Liblouis User's and Programmer's Manual

7.1 Overview ¶

You use the liblouis library by calling the following functions, lou_translateString, lou_backTranslateString, lou_translate, lou_backTranslate, lou_registerLogCallback, lou_setLogLevel, lou_logFile, lou_logPrint, lou_logEnd, lou_getTable, lou_findTable, lou_indexTables, lou_checkTable, lou_hyphenate, lou_charToDots, lou_dotsToChar, lou_compileString, lou_getTypeformForEmphClass, lou_readCharFromFile, lou_version, lou_free and lou_charSize. These are described below. The header file, liblouis.h, also contains brief descriptions. Liblouis is written in straight C. It has four code modules, compileTranslationTable.c, logging.c, lou_translateString.c and lou_backTranslateString.c. In addition, there are two header files, liblouis.h, which defines the API, and louis.h, used only internally and by liblouisutdml. The latter includes liblouis.h.

Persons who wish to use liblouis from Python may want to skip ahead to Python bindings.

compileTranslationTable.c keeps track of all translation tables which an application has used. It is called by the translation, hyphenation and checking functions when they start. If a table has not yet been compiled compileTranslationTable.c checks it for correctness and compiles it into an efficient internal representation. The main entry point is lou_getTable. Since it is the module that keeps track of memory usage, it also contains the lou_free function. In addition, it contains the lou_checkTable function, plus some utility functions which are used by the other modules.

By default, liblouis handles all characters internally as 16-bit unsigned integers. It can be compiled for 32-bit characters as explained below. The meanings of these integers are not hard-coded. Rather they are defined by the character-definition opcodes. However, the standard printable characters, from decimal 32 to 126 are recognized for the purpose of processing the opcodes. Hence, the following definition is included in liblouis.h. It is correct for computers with at least 32-bit processors.

typedef unsigned short int widechar

To make liblouis handle 32-bit Unicode simply remove the word short in the above typedef. This will cause the translate and back-translate functions to expect input in 32-bit form and to deliver their output in this form. The input to the compiler (tables) is unaffected except that two new escape sequences for 20-bit and 32-bit characters are recognized.

At run time, the width of a character specified during compilation may be obtained using lou_charSize.

Here are the definitions of the eleven liblouis functions and their parameters. They are given in terms of Unicode characters, either 16-bit or 32-bit, depending on how liblouis has been compiled.