1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4uc2l.ctr 12 */ 13 14 #ifndef DK4UC2L_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4UC2L_H_INCLUDED 1 17 18 19 /** @file dk4uc2l.h Text to LaTeX conversion. 20 21 LaTeX sequences to represent a 32 bit character are found in lookup tables 22 in the ${datarootdir}/dktools/charmap directory. The functions in this 23 module read those lookup tables needed, cache the contents and provide 24 LaTeX sequences. 25 26 After finishing output you can write recommendations (i.e. LaTeX packages 27 to include, font encoding to use) as comments to the file. 28 29 The functions in this module use a dk4_er_t structure to report errors 30 to the calling function as good as possible. 31 The functions from the dk4uc2la module use a dk4_app_t structure to 32 report errors immediately. 33 34 Functions from the dk4uc2la and dk4uc2l module can be used combined. 35 A typical scenario is to use the dk4uc2l_open_app_ex1() function with la 36 set to 1 to open a conversion structure. This will read all the data files 37 and store all contained LaTeX encodings in memory when opening the structure. 38 Errors - i.e. failed memory allocations or syntax error in data files - are 39 reported immediately. 40 Later the dk4uc2l_find() function can be used. As problematic errors like 41 failed memory allocations are already reported, a NULL return value can 42 only indicate a missing encoding. 43 */ 44 45 #ifndef DK4CONF_H_INCLUDED 46 #if DK4_BUILDING_DKTOOLS4 47 #include "dk4conf.h" 48 #else 49 #include <dktools-4/dk4conf.h> 50 #endif 51 #endif 52 53 #ifndef DK4ERROR_H_INCLUDED 54 #if DK4_BUILDING_DKTOOLS4 55 #include <libdk4base/dk4error.h> 56 #else 57 #include <dktools-4/dk4error.h> 58 #endif 59 #endif 60 61 #ifndef DK4STO_H_INCLUDED 62 #if DK4_BUILDING_DKTOOLS4 63 #include <libdk4c/dk4sto.h> 64 #else 65 #include <dktools-4/dk4sto.h> 66 #endif 67 #endif 68 69 #ifndef DK4STRM_H_INCLUDED 70 #if DK4_BUILDING_DKTOOLS4 71 #include <libdk4c/dk4strm.h> 72 #else 73 #include <dktools-4/dk4strm.h> 74 #endif 75 #endif 76 77 /** Information about a package. 78 */ 79 typedef struct { 80 char *pn; /**< Package name. */ 81 unsigned char used; /**< Flag: Package used. */ 82 } dk4_uc2l_pkg_t; 83 84 /** Pointer to a package or an array of packages. 85 */ 86 typedef dk4_uc2l_pkg_t *dk4_uc2l_pkg_p; 87 88 /** Pointer to an array of package pointers. 89 */ 90 typedef dk4_uc2l_pkg_p *dk4_uc2l_pkg_pp; 91 92 /** Data for contents of one file. 93 The structure contains information about the character 94 ranges covered by the file. 95 */ 96 typedef struct { 97 dkChar *fn; /**< Short file name. */ 98 unsigned char loaded; /**< Flag: File loaded. */ 99 } dk4_uc2l_file_t; 100 101 102 /** Range of characters. 103 */ 104 typedef struct { 105 dk4_uc2l_file_t *file; /**< File containing data. */ 106 char **both; /**< LaTeX text both modes. */ 107 char **text; /**< LaTeX text text mode. */ 108 char **math; /**< LaTeX text math mode. */ 109 dk4_uc2l_pkg_t ***pkgs; /**< Packages for characters. */ 110 unsigned char *fenc; /**< Required font encodings. */ 111 dk4_um_t *lno; /**< Line numbers. */ 112 dk4_c32_t start; /**< First character of range. */ 113 dk4_c32_t end; /**< Final character of range. */ 114 unsigned char ia; /**< Flag: Initialisation att. */ 115 } dk4_uc2l_range_t; 116 117 118 /** Text to LaTeX conversion structure. 119 */ 120 typedef struct { 121 char buf[16]; /**< Buffer for direct output. */ 122 dkChar *dname; /**< Directory name. */ 123 dk4_sto_t *s_ranges; /**< Ranges container. */ 124 dk4_sto_it_t *i_ranges; /**< Ranges container iterator. */ 125 dk4_sto_t *s_files; /**< Files container. */ 126 dk4_sto_it_t *i_files; /**< Files container iterator. */ 127 dk4_sto_t *s_pkgs; /**< Package information container. */ 128 dk4_sto_it_t *i_pkgs; /**< Package information iterator. */ 129 int had_error; /**< Flag: Errors occured. */ 130 unsigned char utf8allowed; /**< Flag: UTF-8 output allowed. */ 131 unsigned char fallowed; /**< Allowed font encodings. */ 132 } dk4_uc2l_t; 133 134 135 /** Font encodings 136 */ 137 enum { 138 /** OT1 font encoding. 139 */ 140 DK4_UC2L_FONT_ENCODING_OT1 = 1 , 141 142 /** T1 font encoding. 143 */ 144 DK4_UC2L_FONT_ENCODING_T1 = 2 , 145 146 /** T4 font encoding. 147 */ 148 DK4_UC2L_FONT_ENCODING_T4 = 4 , 149 150 /** T5 font encoding. 151 */ 152 DK4_UC2L_FONT_ENCODING_T5 = 8 , 153 154 /** All encodings mentioned above. 155 */ 156 DK4_UC2L_FONT_ENCODING_ALL = ( 157 0 158 | DK4_UC2L_FONT_ENCODING_OT1 159 | DK4_UC2L_FONT_ENCODING_T1 160 | DK4_UC2L_FONT_ENCODING_T4 161 | DK4_UC2L_FONT_ENCODING_T5 162 ) 163 }; 164 165 166 167 /** Errors from this module 168 */ 169 enum { 170 171 /** Memory allocation failed. 172 */ 173 DK4_UC2L_ERROR_MEMORY = 1 , 174 175 /** Syntax error in configuration file. 176 */ 177 DK4_UC2L_ERROR_SYNTAX = 2 , 178 179 /** Decoding error in configuration file. 180 */ 181 DK4_UC2L_ERROR_DECODING = 4 , 182 183 /** Other processing errors while reading data. 184 */ 185 DK4_UC2L_ERROR_PROCESSING = 8 , 186 187 /** Failed to open one of the data files. 188 */ 189 DK4_UC2L_ERROR_FOPEN = 16 , 190 }; 191 192 193 194 #ifdef __cplusplus 195 extern "C" { 196 #endif 197 198 /** Open conversion structure. 199 @param dn Directory containing the data files. 200 @param erp Error report, may be NULL. 201 @return Valid pointer on success, NULL on error. 202 */ 203 dk4_uc2l_t * 204 dk4uc2l_open(const dkChar *dn, dk4_er_t *erp); 205 206 /** Close conversion structure, release memory. 207 @param ulptr Conversion structure to close. 208 */ 209 void 210 dk4uc2l_close(dk4_uc2l_t *ulptr); 211 212 /** Find LaTeX encoding for one 32 bit character. 213 @param ulptr Conversion structure. 214 @param c Character to search encoding for. 215 @param mm Flag: Math mode (1) or text mode (0). 216 @param erp Error report, may be NULL. 217 @return Pointer to encoding string on success, NULL on error. 218 */ 219 const char * 220 dk4uc2l_find(dk4_uc2l_t *ulptr, dk4_c32_t c, int mm, dk4_er_t *erp); 221 222 /** Enable or disable direct UTF-8 output. 223 If you use usepackage[utf-8]{inputenc} you might want to 224 enable UTF-8 output. 225 @param ulptr Conversion structure to set up. 226 @param enabled Flag: Enable UTF-8 output. 227 */ 228 void 229 dk4uc2l_allow_utf8(dk4_uc2l_t *ulptr, int enabled); 230 231 /** Reset information about used packages and allowed and denied 232 font encodings. 233 Typically you want to use this function only after finishing 234 one output file and starting a new one. 235 @param ulptr Conversion structure to reset. 236 */ 237 void 238 dk4uc2l_clean_packages_and_fonts(dk4_uc2l_t *ulptr); 239 240 /** Retrieve or-combination of all allowed font encodings. 241 You should use this function after processing all characters. 242 */ 243 unsigned char 244 dk4uc2l_retrieve_allowed_fe(dk4_uc2l_t *ulptr); 245 246 /** Check whether a character can be written to a LaTeX file directly. 247 @param c32 Character to check. 248 @return 1 for yes, 0 for no. 249 */ 250 int 251 dk4uc2lat_direct(dk4_c32_t c32); 252 253 /** Issue recommendations about font encodings and packages. 254 Use this function after processing all characters. 255 @param ulptr Conversion structure. 256 @param wstrm Destination stream to write to. 257 @param erp Error report, may be NULL. 258 */ 259 void 260 dk4uc2l_recommendations(dk4_uc2l_t *ulptr, dk4_stream_t *wstrm, dk4_er_t *erp); 261 262 /** Retrieve internal error status from conversion structure. 263 @param ulptr Conversion structure. 264 @return Error status, 0 or combination of DK4_UC2L_ERROR_MEMORY, 265 DK4_UC2L_ERROR_SYNTAX, DK4_UC2L_ERROR_DECODING, 266 DK4_UC2L_ERROR_PROCESSING, and DK4_UC2L_ERROR_FOPEN. 267 */ 268 int 269 dk4uc2l_retrieve_errors(dk4_uc2l_t *ulptr); 270 271 /** Retrieve internal error status from conversion structure. 272 @param ulptr Conversion structure. 273 @return Error status, 0 or combination of DK4_UC2L_ERROR_MEMORY, 274 DK4_UC2L_ERROR_SYNTAX, DK4_UC2L_ERROR_DECODING, 275 DK4_UC2L_ERROR_PROCESSING, and DK4_UC2L_ERROR_FOPEN. 276 */ 277 void 278 dk4uc2l_reset_errors(dk4_uc2l_t *ulptr); 279 280 /** Write dkChar string LaTeX encoded to stream. 281 The method is primarily selected by DK4_CHAR_SIZE. 282 Use this function if you want to output a dkChar string. 283 @param wstrm Stream to write to. 284 @param ulptr Conversion structure. 285 @param str String. 286 @param ie Input encoding, only used if dkChar is char. 287 @param erp Error report, may be NULL. 288 @return 1 on success, 0 on error. 289 */ 290 int 291 dk4uc2l_string_dk( 292 dk4_stream_t *wstrm, 293 dk4_uc2l_t *ulptr, 294 const dkChar *str, 295 int ie, 296 dk4_er_t *erp 297 ); 298 299 /** Write encoded string LaTeX encoded to stream. 300 The method is selected by the ie parameter. 301 Use this function if your string is not necessarily a dkChar string 302 but you know the encoding. 303 @param wstrm Stream to write to. 304 @param ulptr Conversion structure. 305 @param str String. 306 @param ie Input encoding, only used if dkChar is char. 307 @param erp Error report, may be NULL. 308 @return 1 on success, 0 on error. 309 */ 310 int 311 dk4uc2l_string_encoded( 312 dk4_stream_t *wstrm, 313 dk4_uc2l_t *ulptr, 314 const void *str, 315 int ie, 316 dk4_er_t *erp 317 ); 318 319 /** Write dk4_c32_t string LaTeX encoded to stream. 320 @param wstrm Stream to write to. 321 @param ulptr Conversion structure. 322 @param str String to write. 323 @param erp Error report, may be NULL. 324 @return 1 on success, 0 on error. 325 */ 326 int 327 dk4uc2l_string_c32( 328 dk4_stream_t *wstrm, 329 dk4_uc2l_t *ulptr, 330 const dk4_c32_t *str, 331 dk4_er_t *erp 332 ); 333 334 /** Write UTF-16 encoded dk_c32_t string LaTeX encoded to stream. 335 @param wstrm Stream to write to. 336 @param ulptr Conversion structure. 337 @param str String to write. 338 @param erp Error report, may be NULL. 339 @return 1 on success, 0 on error. 340 */ 341 int 342 dk4uc2l_string_c16( 343 dk4_stream_t *wstrm, 344 dk4_uc2l_t *ulptr, 345 const dk4_c16_t *str, 346 dk4_er_t *erp 347 ); 348 349 /** Write UTF-8 encoded char string LaTeX encoded to stream. 350 @param wstrm Stream to write to. 351 @param ulptr Conversion structure. 352 @param str String to write. 353 @param erp Error report, may be NULL. 354 @return 1 on success, 0 on error. 355 */ 356 int 357 dk4uc2l_string_utf8( 358 dk4_stream_t *wstrm, 359 dk4_uc2l_t *ulptr, 360 const char *str, 361 dk4_er_t *erp 362 ); 363 364 /** Write ANSI encoded char string LaTeX encoded to stream. 365 @param wstrm Stream to write to. 366 @param ulptr Conversion structure. 367 @param str String to write. 368 @param erp Error report, may be NULL. 369 @return 1 on success, 0 on error. 370 */ 371 int 372 dk4uc2l_string_ansi( 373 dk4_stream_t *wstrm, 374 dk4_uc2l_t *ulptr, 375 const char *str, 376 dk4_er_t *erp 377 ); 378 379 /** Write ASCII encoded char string LaTeX encoded to stream. 380 @param wstrm Stream to write to. 381 @param ulptr Conversion structure. 382 @param str String to write. 383 @param erp Error report, may be NULL. 384 @return 1 on success, 0 on error. 385 */ 386 int 387 dk4uc2l_string_ascii( 388 dk4_stream_t *wstrm, 389 dk4_uc2l_t *ulptr, 390 const char *str, 391 dk4_er_t *erp 392 ); 393 394 /** Write char string LaTeX encoded to stream. 395 @param wstrm Stream to write to. 396 @param ulptr Conversion structure. 397 @param str String to write. 398 @param ie Input encoding. 399 @param erp Error report, may be NULL. 400 @return 1 on success, 0 on error. 401 */ 402 int 403 dk4uc2l_string_c8( 404 dk4_stream_t *wstrm, 405 dk4_uc2l_t *ulptr, 406 const char *str, 407 int ie, 408 dk4_er_t *erp 409 ); 410 411 #ifdef __cplusplus 412 } 413 #endif 414 415 416 417 418 #endif 419