libt3highlight
|
Data Structures | |
struct | t3_highlight_error_t |
A struct with error information. More... | |
struct | t3_highlight_lang_t |
A struct representing a display name/language file name tuple. More... | |
struct | t3_highlight_match_t |
An opaque struct representing a match and current state during highlighting. More... | |
struct | t3_highlight_t |
An opaque struct representing a highlighting pattern. More... | |
Macros | |
#define | T3_HIGHLIGHT_VERSION |
The version of libt3highlight encoded as a single integer. More... | |
Typedefs | |
typedef char | t3_bool |
A boolean type that does not clash with C++ or C99 bool. More... | |
Enumerations | |
enum | { t3_false, t3_true } |
Values for t3_bool , a boolean type that does not clash with C++ or C99 bool. More... | |
Functions | |
t3_bool | t3_highlight_detect (const char *line, size_t line_length, t3_bool first, int flags, t3_highlight_lang_t *lang, t3_highlight_error_t *error) |
Detect the language of a file from line data. More... | |
void | t3_highlight_free (t3_highlight_t *highlight) |
Free all memory associated with a highlighting pattern. More... | |
void | t3_highlight_free_lang (t3_highlight_lang_t lang) |
Free the data allocated for a single t3_highlight_lang_t . More... | |
void | t3_highlight_free_list (t3_highlight_lang_t *list) |
Free a list returned by t3_highlight_list. More... | |
void | t3_highlight_free_match (t3_highlight_match_t *match) |
Free t3_highlight_match_t structure. More... | |
int | t3_highlight_get_begin_attr (t3_highlight_match_t *match) |
Get the attribute for the pre-match section of the result. More... | |
size_t | t3_highlight_get_end (t3_highlight_match_t *match) |
Get the end of the match. More... | |
const char * | t3_highlight_get_langfile (const t3_highlight_t *highlight) |
Get the language file associated with this highlighting pattern. More... | |
int | t3_highlight_get_match_attr (t3_highlight_match_t *match) |
Get the attribute for the match section of the result. More... | |
size_t | t3_highlight_get_match_start (t3_highlight_match_t *match) |
Get the start of the match. More... | |
size_t | t3_highlight_get_start (t3_highlight_match_t *match) |
Get the start index of a result. More... | |
int | t3_highlight_get_state (t3_highlight_match_t *match) |
Get the state represented by match . More... | |
long | t3_highlight_get_version (void) |
Get the value of T3_HIGHLIGHT_VERSION corresponding to the actual used library. More... | |
t3_bool | t3_highlight_lang_by_filename (const char *filename, int flags, t3_highlight_lang_t *lang, t3_highlight_error_t *error) |
Detect the language of a file from its name. More... | |
t3_highlight_lang_t * | t3_highlight_list (int flags, t3_highlight_error_t *error) |
List the known languages. More... | |
t3_highlight_t * | t3_highlight_load (const char *name, int(*map_style)(void *, const char *), void *map_style_data, int flags, t3_highlight_error_t *error) |
Load a highlighting pattern, using a language file name. More... | |
t3_highlight_t * | t3_highlight_load_by_detect (const char *line, size_t line_length, t3_bool first, int(*map_style)(void *, const char *), void *map_style_data, int flags, t3_highlight_error_t *error) |
Load a highlighting pattern, based on auto-detection from the line content. More... | |
t3_highlight_t * | t3_highlight_load_by_filename (const char *name, int(*map_style)(void *, const char *), void *map_style_data, int flags, t3_highlight_error_t *error) |
Load a highlighting pattern, using a source file name. More... | |
t3_highlight_t * | t3_highlight_load_by_langname (const char *name, int(*map_style)(void *, const char *), void *map_style_data, int flags, t3_highlight_error_t *error) |
Load a highlighting pattern, using a language name. More... | |
t3_bool | t3_highlight_match (t3_highlight_match_t *match, const char *str, size_t size) |
Find the next highlighting match in a subject string. More... | |
t3_highlight_t * | t3_highlight_new (t3_config_t *syntax, int(*map_style)(void *, const char *), void *map_style_data, int flags, t3_highlight_error_t *error) |
Create a highlighting pattern from a previously created configuration. More... | |
t3_highlight_match_t * | t3_highlight_new_match (const t3_highlight_t *highlight) |
Allocate and initialize a new t3_highlight_match_t structure. More... | |
int | t3_highlight_next_line (t3_highlight_match_t *match) |
Set up match for highlighting the next line of input. More... | |
void | t3_highlight_reset (t3_highlight_match_t *match, int state) |
Reset a t3_highlight_match_t structure. More... | |
const char * | t3_highlight_strerror (int error) |
Get a string description for an error code. More... | |
t3_bool | t3_highlight_utf8check (const char *line, size_t size) |
Check that a string is valid UTF8. More... | |
Error codes (libt3highlight specific) | |
#define | T3_ERR_INVALID_FORMAT |
Error code: invalid structure of the syntax highlighting file. More... | |
#define | T3_ERR_INVALID_REGEX |
Error code: invalid regular expression used in syntax highlighting file. More... | |
#define | T3_ERR_NO_SYNTAX |
Error code: could not determine appropriate highlighting patterns. More... | |
#define | T3_ERR_UNDEFINED_USE |
Error code: a 'use' directive references a non-existing define. More... | |
#define | T3_ERR_INVALID_NAME |
Error code: an 'extract' directive uses an invalid name. More... | |
#define | T3_ERR_EMPTY_START_CYCLE |
Error code: a cycle of empty start states was detected. More... | |
#define | T3_ERR_USE_CYCLE |
Error code: a cycle of empty start states was detected. More... | |
Flags for ::t3_highlight_load. | |
#define | T3_HIGHLIGHT_UTF8 |
Treat input as UTF-8 encoded text, instead of assuming the C locale. More... | |
#define | T3_HIGHLIGHT_UTF8_NOCHECK |
Assume the text to be highlighted is valid UTF-8. More... | |
#define | T3_HIGHLIGHT_USE_PATH |
Use the default include path to lookup the file. More... | |
#define | T3_HIGHLIGHT_VERBOSE_ERROR |
Use verbose error reporting. More... | |
#define | T3_HIGHLIGHT_USE_SCOPE |
Use scopes for mapping styles. More... | |
Error codes (T3 generic) | |
#define | T3_ERR_SUCCESS |
Error code: success. | |
#define | T3_ERR_ERRNO |
Error code: see errno . More... | |
#define | T3_ERR_EOF |
Error code: end of file reached. More... | |
#define | T3_ERR_UNKNOWN |
Error code: unkown error. More... | |
#define | T3_ERR_BAD_ARG |
Error code: bad argument. More... | |
#define | T3_ERR_OUT_OF_MEMORY |
Error code: out of memory. More... | |
#define | T3_ERR_TERMINFODB_NOT_FOUND |
Error code: no information found for the terminal in the terminfo database. More... | |
#define | T3_ERR_HARDCOPY_TERMINAL |
Error code: the file descriptor is a hard-copy terminal. More... | |
#define | T3_ERR_TERMINAL_TOO_LIMITED |
Error code: terminal provides too limited possibilities for the library to function. More... | |
#define | T3_ERR_NO_TERM |
Error code: no terminal given and TERM environment variable not set. More... | |
#define | T3_ERR_INTERNAL |
Error code: internal error in the library. More... | |
#define | T3_WARN_MIN |
Warning code: the smallest value returned as warning. More... | |
#define T3_ERR_BAD_ARG |
Error code: bad argument.
#define T3_ERR_EMPTY_START_CYCLE |
Error code: a cycle of empty start states was detected.
#define T3_ERR_EOF |
Error code: end of file reached.
#define T3_ERR_ERRNO |
Error code: see errno
.
#define T3_ERR_HARDCOPY_TERMINAL |
Error code: the file descriptor is a hard-copy terminal.
#define T3_ERR_INTERNAL |
Error code: internal error in the library.
#define T3_ERR_INVALID_FORMAT |
Error code: invalid structure of the syntax highlighting file.
#define T3_ERR_INVALID_NAME |
Error code: an 'extract' directive uses an invalid name.
#define T3_ERR_INVALID_REGEX |
Error code: invalid regular expression used in syntax highlighting file.
#define T3_ERR_NO_SYNTAX |
Error code: could not determine appropriate highlighting patterns.
#define T3_ERR_NO_TERM |
Error code: no terminal given and TERM
environment variable not set.
#define T3_ERR_OUT_OF_MEMORY |
Error code: out of memory.
#define T3_ERR_TERMINAL_TOO_LIMITED |
Error code: terminal provides too limited possibilities for the library to function.
#define T3_ERR_TERMINFODB_NOT_FOUND |
Error code: no information found for the terminal in the terminfo database.
#define T3_ERR_UNDEFINED_USE |
Error code: a 'use' directive references a non-existing define.
#define T3_ERR_UNKNOWN |
Error code: unkown error.
#define T3_ERR_USE_CYCLE |
Error code: a cycle of empty start states was detected.
#define T3_HIGHLIGHT_USE_PATH |
Use the default include path to lookup the file.
#define T3_HIGHLIGHT_USE_SCOPE |
Use scopes for mapping styles.
When scopes are in use, the map_style
callback to t3_highlight_load will first be called with style@scope
. If that returns 0, map_style
will be called with style
. Otherwise, the result of the first call will be used as the mapped style.
#define T3_HIGHLIGHT_UTF8 |
Treat input as UTF-8 encoded text, instead of assuming the C locale.
#define T3_HIGHLIGHT_UTF8_NOCHECK |
Assume the text to be highlighted is valid UTF-8.
Be very careful using this flag: using this flag when the input is not valid UTF-8 may crash your program! For a definition of what is considered valid UTF-8, see the PCRE documentation. At the time of writing it refers to RFC 3629.
If the input is guaranteed to be valid UTF-8, using this flag will provide a performance benefit.
#define T3_HIGHLIGHT_VERBOSE_ERROR |
Use verbose error reporting.
#define T3_HIGHLIGHT_VERSION |
The version of libt3highlight encoded as a single integer.
The least significant 8 bits represent the patch level. The second 8 bits represent the minor version. The third 8 bits represent the major version.
At runtime, the value of T3_HIGHLIGHT_VERSION can be retrieved by calling t3_highlight_get_version.
#define T3_WARN_MIN |
Warning code: the smallest value returned as warning.
typedef char t3_bool |
A boolean type that does not clash with C++ or C99 bool.
anonymous enum |
t3_bool t3_highlight_detect | ( | const char * | line, |
size_t | line_length, | ||
t3_bool | first, | ||
int | flags, | ||
t3_highlight_lang_t * | lang, | ||
t3_highlight_error_t * | error | ||
) |
Detect the language of a file from line data.
line | The line to use for auto-detection. |
line_length | The length in bytes of the data in line . |
first | Boolean indicating whether the first-line-regex patterns should be applied. |
flags | Flags for loading of the map file. |
lang | The location to store the t3_highlight_lang_t (use t3_highlight_free_lang to free data). |
error | Location to store an error code, or NULL . |
If detection succeeds, t3_highlight_free_lang should be called on lang
when it is no longer necessary.
Auto-detection of the highlighting language is based on vi/Vim modelines, and Emacs major mode tags. Furthermore, when the boolean first
is set, the first-line-regex
patterns from the map file are used. for detection. These regular expressions typically look for interpreters indicated with the #! syntax.
void t3_highlight_free | ( | t3_highlight_t * | highlight | ) |
Free all memory associated with a highlighting pattern.
It is acceptable to pass a NULL
pointer.
void t3_highlight_free_lang | ( | t3_highlight_lang_t | lang | ) |
Free the data allocated for a single t3_highlight_lang_t
.
lang | The t3_highlight_lang_t to release. |
The lang
parameter is deliberatly passed by value, to prevent confusion with t3_highlight_free_list.
void t3_highlight_free_list | ( | t3_highlight_lang_t * | list | ) |
Free a list returned by t3_highlight_list.
It is acceptable to pass a NULL
pointer.
void t3_highlight_free_match | ( | t3_highlight_match_t * | match | ) |
Free t3_highlight_match_t structure.
It is acceptable to pass a NULL
pointer.
int t3_highlight_get_begin_attr | ( | t3_highlight_match_t * | match | ) |
Get the attribute for the pre-match section of the result.
size_t t3_highlight_get_end | ( | t3_highlight_match_t * | match | ) |
Get the end of the match.
const char* t3_highlight_get_langfile | ( | const t3_highlight_t * | highlight | ) |
Get the language file associated with this highlighting pattern.
int t3_highlight_get_match_attr | ( | t3_highlight_match_t * | match | ) |
Get the attribute for the match section of the result.
size_t t3_highlight_get_match_start | ( | t3_highlight_match_t * | match | ) |
Get the start of the match.
size_t t3_highlight_get_start | ( | t3_highlight_match_t * | match | ) |
Get the start index of a result.
This is equal to the end index of the previous result.
int t3_highlight_get_state | ( | t3_highlight_match_t * | match | ) |
Get the state represented by match
.
long t3_highlight_get_version | ( | void | ) |
Get the value of T3_HIGHLIGHT_VERSION corresponding to the actual used library.
This function can be useful to determine at runtime what version of the library was linked to the program. Although currently there are no known uses for this information, future library additions may prompt library users to want to operate differently depending on the available features.
t3_bool t3_highlight_lang_by_filename | ( | const char * | filename, |
int | flags, | ||
t3_highlight_lang_t * | lang, | ||
t3_highlight_error_t * | error | ||
) |
Detect the language of a file from its name.
filename | The file name to use for auto-detection. |
flags | Flags for loading of the map file. |
lang | The location to store the t3_highlight_lang_t (use t3_highlight_free_lang to free data). |
error | Location to store an error code, or NULL . |
If detection succeeds, t3_highlight_free_lang should be called on lang
when it is no longer necessary.
t3_highlight_lang_t* t3_highlight_list | ( | int | flags, |
t3_highlight_error_t * | error | ||
) |
List the known languages.
The returned list is terminated by an entry with two NULL
pointers, and must be freed using t3_highlight_free_list.
t3_highlight_t* t3_highlight_load | ( | const char * | name, |
int(*)(void *, const char *) | map_style, | ||
void * | map_style_data, | ||
int | flags, | ||
t3_highlight_error_t * | error | ||
) |
Load a highlighting pattern, using a language file name.
name | The file name (relative to the search path) to load. |
map_style | Callback function to map symbolic style names to integers. |
map_style_data | Data for the map_style callback. |
flags | Flags for loading of highlighting files and syntax highlighting. |
error | Location to store an error code, or NULL . |
NULL
on error.The map_style
callback is passed map_style_data
as its first argument, and a string describing a style as its second argument. The return value must be an integer, which will be used in the result from t3_highlight_match. Typically any unknown styles should be mapped to the same value as the 'normal' style.
t3_highlight_t* t3_highlight_load_by_detect | ( | const char * | line, |
size_t | line_length, | ||
t3_bool | first, | ||
int(*)(void *, const char *) | map_style, | ||
void * | map_style_data, | ||
int | flags, | ||
t3_highlight_error_t * | error | ||
) |
Load a highlighting pattern, based on auto-detection from the line content.
line | The line to use for auto-detection. |
line_length | The length in bytes of the data in line . |
first | Boolean indicating whether the first-line-regex patterns should be applied. |
map_style | See t3_highlight_load. |
map_style_data | See t3_highlight_load. |
flags | See t3_highlight_load. |
error | See t3_highlight_load. |
For details on the file loading, see t3_highlight_load. For details on the detection, see t3_highlight_detect.
t3_highlight_t* t3_highlight_load_by_filename | ( | const char * | name, |
int(*)(void *, const char *) | map_style, | ||
void * | map_style_data, | ||
int | flags, | ||
t3_highlight_error_t * | error | ||
) |
Load a highlighting pattern, using a source file name.
name | The source file name used to determine the appropriate highlighting pattern. |
map_style | See t3_highlight_load. |
map_style_data | See t3_highlight_load. |
flags | See t3_highlight_load. |
error | See t3_highlight_load. |
Other parameters and return value are equal to t3_highlight_load. The file-regex member in the language definition in the lang.map file is used to determine which highlighting patterns should be loaded. The returned data structure is not modified by any call to the library except t3_highlight_free, and can be used across threads.
t3_highlight_t* t3_highlight_load_by_langname | ( | const char * | name, |
int(*)(void *, const char *) | map_style, | ||
void * | map_style_data, | ||
int | flags, | ||
t3_highlight_error_t * | error | ||
) |
Load a highlighting pattern, using a language name.
name | The source file name used to determine the appropriate highlighting pattern. |
map_style | See t3_highlight_load. |
map_style_data | See t3_highlight_load. |
flags | See t3_highlight_load. |
error | See t3_highlight_load. |
Other parameters and return value are equal to t3_highlight_load. The name-regex member in the language definition in the lang.map file is used to determine which highlighting patterns should be loaded.
t3_bool t3_highlight_match | ( | t3_highlight_match_t * | match, |
const char * | str, | ||
size_t | size | ||
) |
Find the next highlighting match in a subject string.
match | The t3_highlight_match_t structure to store the result. |
str | The string to search in. |
size | The length of the string in bytes. |
This function should be called repeatedly to find all the highlighting matches in the line. The match
parameter should be reset (using either t3_highlight_next_line or :: t3_highlight_reset) before the first call to this function, because it holds the intermediate state information.
The following code demonstrates how to highlight a single line. It assumes that a t3_highlight_match_t struct named match
has been previously created. The line data is assumed to be stored in line
with line_length
bytes.
Note that both the pre-match section from 'begin' to 'start', and the match section from 'start' to 'end' may be empty.
start
, match_start
and end
members of the t3_highlight_match_t are set to -1. t3_highlight_t* t3_highlight_new | ( | t3_config_t * | syntax, |
int(*)(void *, const char *) | map_style, | ||
void * | map_style_data, | ||
int | flags, | ||
t3_highlight_error_t * | error | ||
) |
Create a highlighting pattern from a previously created configuration.
syntax | The t3_config_t to create the highlighting pattern from. |
map_style | See t3_highlight_load. |
map_style_data | See t3_highlight_load. |
flags | See t3_highlight_load. |
error | See t3_highlight_load. |
Other parameters and return value are equal to t3_highlight_load. The highlighting pattern are stored in the format of libt3config
. Any configuration which conforms to the schema of a syntax highlighting pattern can be used to create a highlighting pattern.
t3_highlight_match_t* t3_highlight_new_match | ( | const t3_highlight_t * | highlight | ) |
Allocate and initialize a new t3_highlight_match_t structure.
highlight | The t3_highlight_t structure this t3_highlight_match_t structure will be used for. |
The returned structure will can not be shared across threads.
int t3_highlight_next_line | ( | t3_highlight_match_t * | match | ) |
Set up match
for highlighting the next line of input.
void t3_highlight_reset | ( | t3_highlight_match_t * | match, |
int | state | ||
) |
Reset a t3_highlight_match_t structure.
match | The t3_highlight_match_t structure to reset. |
state | The state to which to initialize match . |
State must be a valid state index. Valid indices are retrieved as the return values of t3_highlight_get_state and t3_highlight_next_line. Furthermore, 0
is the initial state, and is therefore always valid.
const char* t3_highlight_strerror | ( | int | error | ) |
Get a string description for an error code.
error | The error code returned by a function in libt3highlight. |
t3_bool t3_highlight_utf8check | ( | const char * | line, |
size_t | size | ||
) |
Check that a string is valid UTF8.
Passing an invalid UTF-8 string to libt3highlight, when using a t3_highlight_t created with the T3_HIGHLIGHT_UTF8 and T3_HIGHLIGHT_UTF8_NOCHECK flags, may cause undefined behaviour. This function can be used to check the validity of a string. It is used internally when only the T3_HIGHLIGHT_UTF8 flag is passed.
UTF-8 validity is defined as a string consisting of UTF-8 encoded codepoints up to and including U+10FFFF, with the exception of the range U+D800-U+DFFFF (inclusive).