Liblouis User's and Programmer's Manual
7.6 lou_translateString ¶
int lou_translateString( const char *tableList, const widechar *inbuf, int *inlen, widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int mode);
This function takes a string of Unicode characters in
inbuf
and translates it into a string of characters in
outbuf
. Each character produces a particular dot pattern
in one braille cell when sent to an embosser or braille display or to
a screen type font. Which character represents which dot pattern
is indicated by the character-definition and display opcodes in the
translation table.
The tableList
parameter points to a list of translation tables
separated by commas. See How tables are found, for a description on
how the tables are located in the file system. If only one table is
given, no comma should be used after it. It is these tables which
control just how the translation is made, whether in Grade 2, Grade 1,
or something else.
The tables in a list are all compiled into the same internal table.
The list is then regarded as the name of this table. As explained in
How to Write Translation Tables, each table is a file which may
be plain text, big-endian Unicode or little-endian Unicode. A table
(or list of tables) is compiled into an internal representation the
first time it is used. Liblouis keeps track of which tables have been
compiled. For this reason, it is essential to call the lou_free
function at the end of your application to avoid memory leaks. Do
NOT call lou_free
after each translation. This will
force liblouis to compile the translation tables each time they are
used, leading to great inefficiency.
Note that both the *inlen
and *outlen
parameters are
pointers to integers. When the function is called, these integers
contain the maximum input and output lengths, respectively. When it
returns, they are set to the actual lengths used.
The typeform
parameter is used to indicate italic type,
boldface type, computer braille, etc. It is an array of formtype
with the same length as the input buffer pointed to by *inbuf
.
However, it is used to pass back character-by-character results, so
enough space must be provided to match the *outlen
parameter.
Each element indicates the typeform of the corresponding character
in the input buffer. The values and their meaning can be consulted in the
typeforms
enum in liblouis.h. These values can be
added for multiple emphasis. If this parameter is NULL
, no
checking for type forms is done. In addition, if this parameter is not
NULL
, it is set on return to have an 8 at every position
corresponding to a character in outbuf
which was defined to
have a dot representation containing dot 7, dot 8 or both, and to 0
otherwise.
The spacing
parameter is used to indicate differences in
spacing between the input string and the translated output string. It
is also of the same length as the string pointed to by *inbuf
.
If this parameter is NULL
, no spacing information is computed.
The mode
parameter specifies how the translation should be
done. The valid values of mode are defined in liblouis.h. They
are all powers of 2, so that a combined mode can be specified by
adding up different values.
Note that the mode
parameter is an integer, not a pointer to
an integer.
A combination of the following mode flags can be used with the
lou_translateString
function:
compbrlAtCursor
If this bit is set in the
mode
parameter the space-bounded characters containing the cursor will be translated in computer braille.compbrlLeftCursor
If this bit is set, only the characters to the left of the cursor will be in computer braille. This bit overrides
compbrlAtCursor
.dotsIO
When this bit is set, during forward translation, Liblouis will produce output as dot patterns. During back-translation Liblouis accepts input as dot patterns. Note that the produced dot patterns are affected if you have any
display
opcode (seedisplay
) defined in any of your tables.ucBrl
The
ucBrl
(Unicode Braille) bit is used by the functionslou_charToDots
andlou_translate
. It causes the dot patterns to be Unicode Braille rather than the liblouis representation. Note that you will not notice any change when settingucBrl
unlessdotsIO
is also set.lou_dotsToChar
andlou_backTranslate
recognize Unicode braille automatically.partialTrans
This flag specifies that back-translation input should be treated as an incomplete word. Rules that apply only for complete words or at the end of a word will not take effect. This is intended to be used when translating input typed on a braille keyboard to provide a rough idea to the user of the characters they are typing before the word is complete.
noUndefined
Setting this bit disables the output of hexadecimal values when forward-translating undefined characters (characters that are not matched by any rule), and dot numbers when back-translating undefined braille patterns (braille patterns that are not matched by any rule). The default is for liblouis to output the hexadecimal value (as ’\xhhhh’) of an undefined character when forward-translating and the dot numbers (as \ddd/) of an undefined braille pattern when back-translating.
When back translating input from a braille keyboard cell by cell, it is desirable to output characters as soon as they are produced. Similarly, when back translating contracted braille, it is desirable to provide a "guess" to the user of the characters they typed. To achieve this, liblouis needs to have the ability to produce no text when indicators (which don’t produce a character by themselves) are not followed by another cell. This works automatically for indicators liblouis knows about such as capital sign, number sign, etc., but it does not work for indicators which are not (and cannot be) specifically defined as indicators. For example, in UEB, dots 4 5 6 alone produces the text "\456/". Setting the noUndefined mode suppresses this dot number output.
The function returns 1 if no errors were encountered2 and 0 otherwise.
Footnotes
(2)
When the
output buffer is not big enough, lou_translateString
returns a
partial translation that is more or less accurate up until the
returned inlen
/outlen
, and treats it as a successful
translation, i.e. also returns 1.