1/* liblouis Braille Translation and Back-Translation Library 2 3 Based on the Linux screenreader BRLTTY, copyright (C) 1999-2006 by The 4 BRLTTY Team 5 6 Copyright (C) 2004, 2005, 2006 ViewPlus Technologies, Inc. www.viewplus.com 7 Copyright (C) 2004, 2005, 2006 JJB Software, Inc. www.jjb-software.com 8 Copyright (C) 2016 Mike Gray, American Printing House for the Blind 9 Copyright (C) 2016 Davy Kager, Dedicon 10 11 This file is part of liblouis. 12 13 liblouis is free software: you can redistribute it and/or modify it 14 under the terms of the GNU Lesser General Public License as published 15 by the Free Software Foundation, either version 2.1 of the License, or 16 (at your option) any later version. 17 18 liblouis is distributed in the hope that it will be useful, but 19 WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 Lesser General Public License for more details. 22 23 You should have received a copy of the GNU Lesser General Public 24 License along with liblouis. If not, see <http://www.gnu.org/licenses/>. 25*/ 26 27/** 28 * @file 29 * @brief Public API of liblouis 30 */ 31 32#ifndef __LIBLOUIS_H_ 33#define __LIBLOUIS_H_ 34#ifdef __cplusplus 35extern "C" { 36#endif /* __cplusplus */ 37 38// clang-format interacts badly with @foo@ 39// clang-format off 40typedef @WIDECHAR_TYPE@ widechar; 41// clang-format on 42typedef unsigned short formtype; 43 44#ifdef _MSC_VER 45#ifdef _EXPORTING 46#define LIBLOUIS_API __declspec(dllexport) 47#else 48#define LIBLOUIS_API __declspec(dllimport) 49#endif 50#else 51#define LIBLOUIS_API 52#endif 53 54#ifdef __EMSCRIPTEN__ 55#include "emscripten.h" 56#define EXPORT_CALL EMSCRIPTEN_KEEPALIVE 57#elif defined(_WIN32) 58#define EXPORT_CALL __stdcall 59LIBLOUIS_API 60char *EXPORT_CALL 61lou_getProgramPath(void); 62#else 63#define EXPORT_CALL 64#endif 65 66typedef enum { 67 plain_text = 0x0000, 68 emph_1 = 0x0001, 69 emph_2 = 0x0002, 70 emph_3 = 0x0004, 71 emph_4 = 0x0008, 72 emph_5 = 0x0010, 73 emph_6 = 0x0020, 74 emph_7 = 0x0040, 75 emph_8 = 0x0080, 76 emph_9 = 0x0100, 77 emph_10 = 0x0200, 78 computer_braille = 0x0400, 79 no_translate = 0x0800, 80 no_contract = 0x1000, 81 // SYLLABLE_MARKER_1 0x2000, 82 // SYLLABLE_MARKER_1 0x4000 83 // CAPSEMPH 0x4000 84} typeforms; 85 86#define italic emph_1 87#define underline emph_2 88#define bold emph_3 89 90#define comp_emph_1 emph_1 91#define comp_emph_2 emph_2 92#define comp_emph_3 emph_3 93 94#define EMPH_NAME_BOLD "bold" 95#define EMPH_NAME_ITALIC "italic" 96#define EMPH_NAME_UNDERLINE "underline" 97 98typedef enum { 99 noContractions = 1, 100 compbrlAtCursor = 2, 101 dotsIO = 4, 102 // for historic reasons 8 and 16 are free 103 compbrlLeftCursor = 32, 104 ucBrl = 64, 105 noUndefined = 128, 106 partialTrans = 256 107} translationModes; 108 109#define noUndefinedDots noUndefined 110 111LIBLOUIS_API 112const char *EXPORT_CALL 113lou_version(void); 114 115/** 116 * Return the size of widechar 117 */ 118LIBLOUIS_API 119int EXPORT_CALL 120lou_charSize(void); 121 122LIBLOUIS_API 123int EXPORT_CALL 124lou_translateString(const char *tableList, const widechar *inbuf, int *inlen, 125 widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int mode); 126 127LIBLOUIS_API 128int EXPORT_CALL 129lou_translate(const char *tableList, const widechar *inbuf, int *inlen, widechar *outbuf, 130 int *outlen, formtype *typeform, char *spacing, int *outputPos, int *inputPos, 131 int *cursorPos, int mode); 132 133LIBLOUIS_API 134int EXPORT_CALL 135lou_translatePrehyphenated(const char *tableList, const widechar *inbuf, int *inlen, 136 widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int *outputPos, 137 int *inputPos, int *cursorPos, char *inputHyphens, char *outputHyphens, int mode); 138 139LIBLOUIS_API 140int EXPORT_CALL 141lou_hyphenate( 142 const char *tableList, const widechar *inbuf, int inlen, char *hyphens, int mode); 143 144/** 145 * Convert a string of dot patterns to a string of chars 146 * 147 * @param[in] tableList comma separated list of braille tables 148 * @param[in] inbuf widechar string of dot patterns, either in liblouis format or Unicode 149 * braille 150 * @param[out] outbuf widechar string corresponding to the dot patterns in `inbuf` 151 * @param[in,out] length of both `inbuf` and `outbuf` 152 * @param[in] mode (deprecated) 153 * 154 * @return 1 on success and 0 on failure. 155 */ 156LIBLOUIS_API 157int EXPORT_CALL 158lou_dotsToChar( 159 const char *tableList, widechar *inbuf, widechar *outbuf, int length, int mode); 160LIBLOUIS_API 161int EXPORT_CALL 162lou_charToDots(const char *tableList, const widechar *inbuf, widechar *outbuf, int length, 163 int mode); 164LIBLOUIS_API 165int EXPORT_CALL 166lou_backTranslateString(const char *tableList, const widechar *inbuf, int *inlen, 167 widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int mode); 168 169LIBLOUIS_API 170int EXPORT_CALL 171lou_backTranslate(const char *tableList, const widechar *inbuf, int *inlen, 172 widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int *outputPos, 173 int *inputPos, int *cursorPos, int mode); 174/** 175 * Print error messages to a file 176 * 177 * @deprecated As of 2.6.0, applications using liblouis should 178 * implement their own logging system. 179 */ 180LIBLOUIS_API 181void EXPORT_CALL 182lou_logPrint(const char *format, ...); 183 184/** 185 * Specify the name of the file to be used by lou_logPrint. 186 * 187 * If it is not used, this file is stderr 188 * 189 * @deprecated As of 2.6.0, applications using liblouis should 190 * implement their own logging system. 191 */ 192LIBLOUIS_API 193void EXPORT_CALL 194lou_logFile(const char *filename); 195 196/** 197 * Read a character from a file, whether big-endian, little-endian or ASCII8 198 * 199 * and return it as an integer. EOF at end of file. Mode = 1 on first 200 * call, any other value thereafter 201 */ 202LIBLOUIS_API 203int EXPORT_CALL 204lou_readCharFromFile(const char *fileName, int *mode); 205 206/** 207 * Close the log file so it can be read by other functions. 208 * 209 * @deprecated As of 2.6.0, applications using liblouis should 210 * implement their own logging system. 211 */ 212LIBLOUIS_API 213void EXPORT_CALL 214lou_logEnd(void); 215 216/** 217 * Load and compile a translation table 218 * 219 * Check the table for errors. If none are found load the table into 220 * memory and return a pointer to it. If errors are found return a 221 * null pointer. It is called by lou_translateString() and 222 * lou_backTranslateString() and also by functions in liblouisutdml 223 * and by the tools. 224 */ 225LIBLOUIS_API 226const void *EXPORT_CALL 227lou_getTable(const char *tableList); 228 229/** 230 * Check a translation table for errors. 231 * 232 * If no errors are found it load the table into memory and returns a 233 * non-zero value. Else the return value is 0. 234 */ 235LIBLOUIS_API 236int EXPORT_CALL 237lou_checkTable(const char *tableList); 238 239/** 240 * Register a new table resolver. Overrides the default resolver. */ 241LIBLOUIS_API 242void EXPORT_CALL 243lou_registerTableResolver( 244 char **(EXPORT_CALL *resolver)(const char *table, const char *base)); 245 246/** 247 * Compile a table entry on the fly at run-time 248 * 249 * This function enables you to compile a table entry on the fly at 250 * run-time. The new entry is added to tableList and remains in 251 * force until lou_free() is called. If tableList has not 252 * previously been loaded it is loaded and compiled. 253 * 254 * @param inString contains the table entry to be added. It may be 255 * anything valid. Error messages will be produced if it is invalid. 256 * 257 * @return 1 on success and 0 on failure. 258 */ 259LIBLOUIS_API 260int EXPORT_CALL 261lou_compileString(const char *tableList, const char *inString); 262 263/** 264 * Get the typeform bit for the named emphasis class. 265 * 266 * If the table defines the specified emphasis class the corresponding 267 * typeform is returned. Else the return value is 0. 268 */ 269LIBLOUIS_API 270formtype EXPORT_CALL 271lou_getTypeformForEmphClass(const char *tableList, const char *emphClass); 272 273/** 274 * Return the emphasis class names declared in tableList as a 275 * NULL-terminated array of strings. The array is acquired with malloc() 276 * and should be released with free(). The strings must not be released, 277 * and are no longer valid after lou_free() has been called. 278 */ 279LIBLOUIS_API 280char const **EXPORT_CALL 281lou_getEmphClasses(const char *tableList); 282 283/** 284 * Set the path used for searching for tables and liblouisutdml files. 285 * 286 * Overrides the installation path. */ 287LIBLOUIS_API 288char *EXPORT_CALL 289lou_setDataPath(const char *path); 290 291/** 292 * Get the path set in the previous function. */ 293LIBLOUIS_API 294char *EXPORT_CALL 295lou_getDataPath(void); 296 297typedef enum { 298 LOU_LOG_ALL = 0, 299 LOU_LOG_DEBUG = 10000, 300 LOU_LOG_INFO = 20000, 301 LOU_LOG_WARN = 30000, 302 LOU_LOG_ERROR = 40000, 303 LOU_LOG_FATAL = 50000, 304 LOU_LOG_OFF = 60000 305} logLevels; 306 307typedef void(EXPORT_CALL *logcallback)(logLevels level, const char *message); 308 309/** 310 * Register logging callbacks 311 * Set to NULL for default callback. 312 */ 313LIBLOUIS_API 314void EXPORT_CALL 315lou_registerLogCallback(logcallback callback); 316 317/** 318 * Set the level for logging callback to be called at 319 */ 320LIBLOUIS_API 321void EXPORT_CALL 322lou_setLogLevel(logLevels level); 323 324typedef enum { LOU_ROW_BRAILLE = 0X2800 } LOU_UnicodeConstants; 325 326/* ========================= Sort-of private API ========================= */ 327 328/** 329 * Definitions of braille dots 330 */ 331typedef enum BrailleDots { 332 LOU_DOT_1 = 0X01, /** dot 1 */ 333 LOU_DOT_2 = 0X02, /** dot 2 */ 334 LOU_DOT_3 = 0X04, /** dot 3 */ 335 LOU_DOT_4 = 0X08, /** dot 4 */ 336 LOU_DOT_5 = 0X10, /** dot 5 */ 337 LOU_DOT_6 = 0X20, /** dot 6 */ 338 LOU_DOT_7 = 0X40, /** dot 7 */ 339 LOU_DOT_8 = 0X80, /** dot 8 */ 340 LOU_DOT_9 = 0X100, /** virtual dot 9 */ 341 LOU_DOT_10 = 0X200, /** virtual dot A */ 342 LOU_DOT_11 = 0X400, /** virtual dot B */ 343 LOU_DOT_12 = 0X800, /** virtual dot C */ 344 LOU_DOT_13 = 0X1000, /** virtual dot D */ 345 LOU_DOT_14 = 0X2000, /** virtual dot E */ 346 LOU_DOT_15 = 0X4000, /** virtual dot F */ 347 LOU_DOTS = 0X8000 /** if this bit is true, the widechar represents a dot pattern */ 348} BrailleDots; 349 350/** 351 * A sentinel, used in liblouisutdml 352 */ 353#define LOU_ENDSEGMENT 0xffff 354 355/* ========================= BETA API ========================= */ 356 357// Use the following two function with care, API is subject to change! 358 359/** 360 * Parse, analyze and index tables. 361 * 362 * This function must be called prior to lou_findTable() and 363 * lou_listTables(). Table names must be provided as a NULL-terminated 364 * array of strings. Each table should resolve to exactly one file. An 365 * error message is given when a table contains invalid or duplicate 366 * metadata fields. 367 */ 368LIBLOUIS_API 369void EXPORT_CALL 370lou_indexTables(const char **tables); 371 372/** 373 * Find the best match for a query. 374 * 375 * Returns the name of the table, or NULL when no match can be 376 * found. If lou_indexTables() has not been previously called, the 377 * table search path specified with LOUIS_TABLEPATH will be indexed 378 * first. An error message is given when the query is invalid. Freeing 379 * the memory of the returned string is the responsibility of the 380 * caller. 381 */ 382LIBLOUIS_API 383char *EXPORT_CALL 384lou_findTable(const char *query); 385 386/** 387 * Find all matches for a query, best match first. 388 * 389 * Returns the names of the matched table as a NULL-terminated array 390 * of string. If lou_indexTables() has not been previously called, the 391 * table search path specified with LOUIS_TABLEPATH will be indexed 392 * first. An error message is given when the query is invalid. Freeing 393 * the memory of the returned array and strings is the responsibility 394 * of the caller. 395 */ 396LIBLOUIS_API 397char **EXPORT_CALL 398lou_findTables(const char *query); 399 400/** 401 * Read metadata from a file. 402 * 403 * Returns the value of the metadata field specified by `key' in 404 * `table', or NULL when the field does not exist. Freeing the memory 405 * of the returned string is the responsibility of the caller. 406 */ 407LIBLOUIS_API 408char *EXPORT_CALL 409lou_getTableInfo(const char *table, const char *key); 410 411/** 412 * List available tables. 413 * 414 * Returns the names of available tables as a NULL-terminated array of 415 * strings. Only tables that are discoverable, i.e. the have active 416 * metadata, are listed. If lou_indexTables() has not been previously 417 * called, the table search path specified with LOUIS_TABLEPATH will 418 * be indexed first. Freeing the memory of the returned array and 419 * strings is the responsibility of the caller. 420 */ 421LIBLOUIS_API 422char **EXPORT_CALL 423lou_listTables(void); 424 425/* ====================== END OF BETA API ====================== */ 426 427/** 428 * Free all memory allocated by liblouis. 429 * 430 * This function should be called at the end of the application to 431 * free all memory allocated by liblouis. 432 */ 433LIBLOUIS_API 434void EXPORT_CALL 435lou_free(void); 436 437#ifdef __cplusplus 438} 439#endif /* __cplusplus */ 440#endif /* __LIBLOUIS_H_ */ 441