liblouis-rb 0.1.0

data/vendor/liblouis/liblouis/liblouis.h.in

@@ -0,0 +1,514 @@
+/* liblouis Braille Translation and Back-Translation Library
+
+   Based on the Linux screenreader BRLTTY, copyright (C) 1999-2006 by The
+   BRLTTY Team
+
+   Copyright (C) 2004, 2005, 2006 ViewPlus Technologies, Inc. www.viewplus.com
+   Copyright (C) 2004, 2005, 2006 JJB Software, Inc. www.jjb-software.com
+   Copyright (C) 2016 Mike Gray, American Printing House for the Blind
+   Copyright (C) 2016 Davy Kager, Dedicon
+
+   This file is part of liblouis.
+
+   liblouis is free software: you can redistribute it and/or modify it
+   under the terms of the GNU Lesser General Public License as published
+   by the Free Software Foundation, either version 2.1 of the License, or
+   (at your option) any later version.
+
+   liblouis is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with liblouis. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @file
+ * @brief Public API of liblouis
+ */
+
+#ifndef __LIBLOUIS_H_
+#define __LIBLOUIS_H_
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+// clang-format interacts badly with @foo@
+// clang-format off
+typedef @WIDECHAR_TYPE@ widechar;
+// clang-format on
+typedef unsigned short formtype;
+
+#ifdef _MSC_VER
+#ifdef _EXPORTING
+#define LIBLOUIS_API __declspec(dllexport)
+#else
+#define LIBLOUIS_API __declspec(dllimport)
+#endif
+#else
+#define LIBLOUIS_API
+#endif
+
+#ifdef __EMSCRIPTEN__
+#include "emscripten.h"
+#define EXPORT_CALL EMSCRIPTEN_KEEPALIVE
+#elif defined(_WIN32)
+#define EXPORT_CALL __stdcall
+LIBLOUIS_API
+char *EXPORT_CALL
+lou_getProgramPath(void);
+#else
+#define EXPORT_CALL
+#endif
+
+typedef enum {
+	plain_text = 0x0000,
+	emph_1 = 0x0001,
+	emph_2 = 0x0002,
+	emph_3 = 0x0004,
+	emph_4 = 0x0008,
+	emph_5 = 0x0010,
+	emph_6 = 0x0020,
+	emph_7 = 0x0040,
+	emph_8 = 0x0080,
+	emph_9 = 0x0100,
+	emph_10 = 0x0200,
+	computer_braille = 0x0400,
+	// @deprecated for input. This feature is unreliable and will be removed in a future
+	// release
+	no_translate = 0x0800,
+	no_contract = 0x1000,
+	// SYLLABLE_MARKER_1  0x2000,
+	// SYLLABLE_MARKER_1  0x4000
+	// CAPSEMPH  0x4000
+} typeforms;
+
+#define italic emph_1
+#define underline emph_2
+#define bold emph_3
+
+#define comp_emph_1 emph_1
+#define comp_emph_2 emph_2
+#define comp_emph_3 emph_3
+
+#define EMPH_NAME_BOLD "bold"
+#define EMPH_NAME_ITALIC "italic"
+#define EMPH_NAME_UNDERLINE "underline"
+
+typedef enum {
+	noContractions = 1,
+	compbrlAtCursor = 2,
+	dotsIO = 4,
+	// for historic reasons 8 and 16 are free
+	compbrlLeftCursor = 32,
+	ucBrl = 64,
+	noUndefined = 128,
+	partialTrans = 256
+} translationModes;
+
+#define noUndefinedDots noUndefined
+
+LIBLOUIS_API
+const char *EXPORT_CALL
+lou_version(void);
+
+/**
+ * Return the size of widechar
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_charSize(void);
+
+/**
+ * Translates a string according to the given translation table(s)
+ *
+ * Take a string of wide characters in `inbuf` and translate it to a
+ * string of wide characters in `outbuf`.
+ *
+ * For detailed documentation check the chapter on [Programming with
+ * liblouis](https://liblouis.io/documentation/liblouis.html#Programming-with-liblouis)
+ * of the liblouis manual.
+ *
+ * @return 1 on success, 0 on failure
+ *
+ * @warning BUFFER OVERFLOW RISK: Caller must ensure that:
+ *          - `inlen` does not exceed actual size of `inbuf`
+ *          - `typeform` array is NULL or at least `inlen` elements long
+ *          - `outbuf` can hold at least `outlen` elements
+ *          Passing incorrect lengths will cause buffer overflows
+ *
+ * @note `typeform` may be NULL if no typeform checking is needed
+ * @note `spacing` is deprecated and must be NULL; any other value is
+ * ignored and a warning is logged
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_translateString(const char *tableList, const widechar *inbuf, int *inlen,
+		widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int mode);
+
+/**
+ * Basically the same as [lou_translateString](#lou_translateString) providing additional
+ * cursor position tracking information
+ *
+ * @return 1 on success, 0 on failure
+ *
+ * @warning BUFFER OVERFLOW RISK: Caller must ensure that:
+ *          - `inlen` does not exceed actual size of `inbuf`
+ *          - `typeform` array is NULL or at least `inlen` elements long
+ *          - `outbuf` can hold at least `outlen` elements
+ *          - `outputPos` array is at least `inlen` elements long
+ *          - `inputPos` array is at least `outlen` elements long
+ *          Passing incorrect lengths will cause buffer overflows
+ *
+ * @note `outputPos`, `inputPos`, and `cursorPos` may be NULL if position tracking is not
+ * needed
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_translate(const char *tableList, const widechar *inbuf, int *inlen, widechar *outbuf,
+		int *outlen, formtype *typeform, char *spacing, int *outputPos, int *inputPos,
+		int *cursorPos, int mode);
+
+LIBLOUIS_API
+int EXPORT_CALL
+lou_translatePrehyphenated(const char *tableList, const widechar *inbuf, int *inlen,
+		widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int *outputPos,
+		int *inputPos, int *cursorPos, char *inputHyphens, char *outputHyphens, int mode);
+
+LIBLOUIS_API
+int EXPORT_CALL
+lou_hyphenate(
+		const char *tableList, const widechar *inbuf, int inlen, char *hyphens, int mode);
+
+/**
+ * Convert a string of dot patterns to a string of chars
+ *
+ * @param[in]  tableList comma separated list of braille tables
+ * @param[in]  inbuf widechar string of dot patterns, either in liblouis format or Unicode
+ * braille
+ * @param[out] outbuf widechar string corresponding to the dot patterns in `inbuf`
+ * @param[in,out] length of both `inbuf` and `outbuf`
+ * @param[in] mode (deprecated)
+ *
+ * @return 1 on success and 0 on failure.
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_dotsToChar(
+		const char *tableList, widechar *inbuf, widechar *outbuf, int length, int mode);
+LIBLOUIS_API
+int EXPORT_CALL
+lou_charToDots(const char *tableList, const widechar *inbuf, widechar *outbuf, int length,
+		int mode);
+LIBLOUIS_API
+int EXPORT_CALL
+lou_backTranslateString(const char *tableList, const widechar *inbuf, int *inlen,
+		widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int mode);
+
+LIBLOUIS_API
+int EXPORT_CALL
+lou_backTranslate(const char *tableList, const widechar *inbuf, int *inlen,
+		widechar *outbuf, int *outlen, formtype *typeform, char *spacing, int *outputPos,
+		int *inputPos, int *cursorPos, int mode);
+/**
+ * Print error messages to a file
+ *
+ * @deprecated As of 2.6.0, applications using liblouis should
+ * implement their own logging system.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_logPrint(const char *format, ...);
+
+/**
+ * Specify the name of the file to be used by lou_logPrint.
+ *
+ * If it is not used, this file is stderr
+ *
+ * @deprecated As of 2.6.0, applications using liblouis should
+ * implement their own logging system.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_logFile(const char *filename);
+
+/**
+ * Read a character from a file, whether big-endian, little-endian or ASCII8
+ *
+ * and return it as an integer. EOF at end of file. Mode = 1 on first
+ * call, any other value thereafter
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_readCharFromFile(const char *fileName, int *mode);
+
+/**
+ * Close the log file so it can be read by other functions.
+ *
+ * @deprecated As of 2.6.0, applications using liblouis should
+ * implement their own logging system.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_logEnd(void);
+
+/**
+ * Load and compile a translation table
+ *
+ * Check the table for errors. If none are found load the table into
+ * memory and return a pointer to it. If errors are found return a
+ * null pointer. It is called by lou_translateString() and
+ * lou_backTranslateString() and also by functions in liblouisutdml
+ * and by the tools.
+ */
+LIBLOUIS_API
+const void *EXPORT_CALL
+lou_getTable(const char *tableList);
+
+/**
+ * Check a translation table for errors.
+ *
+ * If no errors are found it load the table into memory and returns a
+ * non-zero value. Else the return value is 0.
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_checkTable(const char *tableList);
+
+/**
+ * Register a new table resolver. Overrides the default resolver. */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_registerTableResolver(
+		char **(EXPORT_CALL *resolver)(const char *table, const char *base));
+
+/**
+ * Compile a table entry on the fly at run-time
+ *
+ * This function enables you to compile a table entry on the fly at
+ * run-time. The new entry is added to tableList and remains in
+ * force until lou_free() is called. If tableList has not
+ * previously been loaded it is loaded and compiled.
+ *
+ * @param inString contains the table entry to be added. It may be
+ * anything valid. Error messages will be produced if it is invalid.
+ *
+ * @return 1 on success and 0 on failure.
+ */
+LIBLOUIS_API
+int EXPORT_CALL
+lou_compileString(const char *tableList, const char *inString);
+
+/**
+ * Get the typeform bit for the named emphasis class.
+ *
+ * If the table defines the specified emphasis class the corresponding
+ * typeform is returned. Else the return value is 0.
+ */
+LIBLOUIS_API
+formtype EXPORT_CALL
+lou_getTypeformForEmphClass(const char *tableList, const char *emphClass);
+
+/**
+ * Return the emphasis class names declared in tableList as a
+ * NULL-terminated array of strings. The array is acquired with malloc()
+ * and should be released with lou_freeEmphClasses(). The strings must
+ * not be released, and are no longer valid after lou_free() has been
+ * called.
+ */
+LIBLOUIS_API
+char const **EXPORT_CALL
+lou_getEmphClasses(const char *tableList);
+
+/**
+ * Free the memory allocated and returned by lou_getEmphClasses.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_freeEmphClasses(char const **);
+
+/**
+ * Set the path used for searching for tables and liblouisutdml files.
+ *
+ * Overrides the installation path. Returns NULL if `path` is NULL or
+ * if the length of `path` is equal or longer than `MAXSTRING`.
+ *
+ * @deprecated Please migrate to one of the other ways to set the
+ * table search path. See the NEWS file for details.
+ */
+
+LIBLOUIS_API
+char *EXPORT_CALL
+lou_setDataPath(const char *path);
+
+/**
+ * Get the path set in the previous function.
+ *
+ * @deprecated Please migrate to one of the other ways to get the
+ * table search path. See the NEWS file for details.
+ */
+LIBLOUIS_API
+char *EXPORT_CALL
+lou_getDataPath(void);
+
+typedef enum {
+	LOU_LOG_ALL = 0,
+	LOU_LOG_DEBUG = 10000,
+	LOU_LOG_INFO = 20000,
+	LOU_LOG_WARN = 30000,
+	LOU_LOG_ERROR = 40000,
+	LOU_LOG_FATAL = 50000,
+	LOU_LOG_OFF = 60000
+} logLevels;
+
+typedef void(EXPORT_CALL *logcallback)(logLevels level, const char *message);
+
+/**
+ * Register logging callbacks
+ * Set to NULL for default callback.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_registerLogCallback(logcallback callback);
+
+/**
+ * Set the level for logging callback to be called at
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_setLogLevel(logLevels level);
+
+typedef enum { LOU_ROW_BRAILLE = 0X2800 } LOU_UnicodeConstants;
+
+/* ========================= Sort-of private API ========================= */
+
+/**
+ * Definitions of braille dots
+ */
+typedef enum BrailleDots {
+	LOU_DOT_1 = 0X01,	 /** dot 1 */
+	LOU_DOT_2 = 0X02,	 /** dot 2 */
+	LOU_DOT_3 = 0X04,	 /** dot 3 */
+	LOU_DOT_4 = 0X08,	 /** dot 4 */
+	LOU_DOT_5 = 0X10,	 /** dot 5 */
+	LOU_DOT_6 = 0X20,	 /** dot 6 */
+	LOU_DOT_7 = 0X40,	 /** dot 7 */
+	LOU_DOT_8 = 0X80,	 /** dot 8 */
+	LOU_DOT_9 = 0X100,	 /** virtual dot 9 */
+	LOU_DOT_10 = 0X200,	 /** virtual dot A */
+	LOU_DOT_11 = 0X400,	 /** virtual dot B */
+	LOU_DOT_12 = 0X800,	 /** virtual dot C */
+	LOU_DOT_13 = 0X1000, /** virtual dot D */
+	LOU_DOT_14 = 0X2000, /** virtual dot E */
+	LOU_DOT_15 = 0X4000, /** virtual dot F */
+	LOU_DOTS = 0X8000	 /** if this bit is true, the widechar represents a dot pattern */
+} BrailleDots;
+
+/**
+ * A sentinel, used in liblouisutdml
+ */
+#define LOU_ENDSEGMENT 0xffff
+
+/**
+ * Parse, analyze and index tables.
+ *
+ * This function must be called prior to lou_findTable() and
+ * lou_listTables(). Table names must be provided as a NULL-terminated
+ * array of strings. Each table should resolve to exactly one file. An
+ * error message is given when a table contains invalid or duplicate
+ * metadata fields.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_indexTables(const char **tables);
+
+/**
+ * Find the best match for a query.
+ *
+ * Returns the name of the table, or NULL when no match can be
+ * found. If lou_indexTables() has not been previously called, the
+ * table search path specified with LOUIS_TABLEPATH will be indexed
+ * first. An error message is given when the query is invalid. The
+ * caller should free the memory of the returned string with
+ * lou_freeTableFile.
+ */
+LIBLOUIS_API
+char *EXPORT_CALL
+lou_findTable(const char *query);
+
+/**
+ * Free the memory allocated and returned by lou_findTable.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_freeTableFile(char *);
+
+/**
+ * Find all matches for a query, best match first.
+ *
+ * Returns the names of the matched table as a NULL-terminated array
+ * of string. If lou_indexTables() has not been previously called, the
+ * table search path specified with LOUIS_TABLEPATH will be indexed
+ * first. An error message is given when the query is invalid. The
+ * caller should free the memory of the returned array and strings
+ * with lou_freeTableFiles.
+ */
+LIBLOUIS_API
+char **EXPORT_CALL
+lou_findTables(const char *query);
+
+/**
+ * Read metadata from a file.
+ *
+ * Returns the value of the first occuring metadata field specified by
+ * `key' in `table', or NULL when the field does not exist. The caller
+ * should free the memory of the returned string with lou_freeTableInfo.
+ */
+LIBLOUIS_API
+char *EXPORT_CALL
+lou_getTableInfo(const char *table, const char *key);
+
+/**
+ * Free the memory allocated and returned by lou_getTableInfo.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_freeTableInfo(char *);
+
+/**
+ * List available tables.
+ *
+ * Returns the names of available tables as a NULL-terminated array of
+ * strings. Only tables that are discoverable, i.e. the have active
+ * metadata, are listed. If lou_indexTables() has not been previously
+ * called, the table search path specified with LOUIS_TABLEPATH will
+ * be indexed first. The caller should free the memory of the returned array with
+ * lou_freeTableFiles.
+ */
+LIBLOUIS_API
+char **EXPORT_CALL
+lou_listTables(void);
+
+/**
+ * Free the memory allocated and returned by lou_findTables or lou_listTables.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_freeTableFiles(char **);
+
+/**
+ * Free all memory allocated by liblouis.
+ *
+ * This function should be called at the end of the application to
+ * free all memory allocated by liblouis.
+ */
+LIBLOUIS_API
+void EXPORT_CALL
+lou_free(void);
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+#endif /* __LIBLOUIS_H_ */