libt3highlight
Data Structures | Macros | Typedefs | Enumerations | Functions
Functions, constants and enums.

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_tt3_highlight_list (int flags, t3_highlight_error_t *error)
 List the known languages. More...
 
t3_highlight_tt3_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_tt3_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_tt3_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_tt3_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_tt3_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_tt3_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...
 

Detailed Description

Macro Definition Documentation

◆ T3_ERR_BAD_ARG

#define T3_ERR_BAD_ARG

Error code: bad argument.

◆ T3_ERR_EMPTY_START_CYCLE

#define T3_ERR_EMPTY_START_CYCLE

Error code: a cycle of empty start states was detected.

◆ T3_ERR_EOF

#define T3_ERR_EOF

Error code: end of file reached.

◆ T3_ERR_ERRNO

#define T3_ERR_ERRNO

Error code: see errno.

◆ T3_ERR_HARDCOPY_TERMINAL

#define T3_ERR_HARDCOPY_TERMINAL

Error code: the file descriptor is a hard-copy terminal.

◆ T3_ERR_INTERNAL

#define T3_ERR_INTERNAL

Error code: internal error in the library.

◆ T3_ERR_INVALID_FORMAT

#define T3_ERR_INVALID_FORMAT

Error code: invalid structure of the syntax highlighting file.

◆ T3_ERR_INVALID_NAME

#define T3_ERR_INVALID_NAME

Error code: an 'extract' directive uses an invalid name.

◆ T3_ERR_INVALID_REGEX

#define T3_ERR_INVALID_REGEX

Error code: invalid regular expression used in syntax highlighting file.

◆ T3_ERR_NO_SYNTAX

#define T3_ERR_NO_SYNTAX

Error code: could not determine appropriate highlighting patterns.

◆ T3_ERR_NO_TERM

#define T3_ERR_NO_TERM

Error code: no terminal given and TERM environment variable not set.

◆ T3_ERR_OUT_OF_MEMORY

#define T3_ERR_OUT_OF_MEMORY

Error code: out of memory.

◆ T3_ERR_TERMINAL_TOO_LIMITED

#define T3_ERR_TERMINAL_TOO_LIMITED

Error code: terminal provides too limited possibilities for the library to function.

◆ T3_ERR_TERMINFODB_NOT_FOUND

#define T3_ERR_TERMINFODB_NOT_FOUND

Error code: no information found for the terminal in the terminfo database.

◆ T3_ERR_UNDEFINED_USE

#define T3_ERR_UNDEFINED_USE

Error code: a 'use' directive references a non-existing define.

◆ T3_ERR_UNKNOWN

#define T3_ERR_UNKNOWN

Error code: unkown error.

◆ T3_ERR_USE_CYCLE

#define T3_ERR_USE_CYCLE

Error code: a cycle of empty start states was detected.

◆ T3_HIGHLIGHT_USE_PATH

#define T3_HIGHLIGHT_USE_PATH

Use the default include path to lookup the file.

◆ T3_HIGHLIGHT_USE_SCOPE

#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.

◆ T3_HIGHLIGHT_UTF8

#define T3_HIGHLIGHT_UTF8

Treat input as UTF-8 encoded text, instead of assuming the C locale.

◆ T3_HIGHLIGHT_UTF8_NOCHECK

#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.

◆ T3_HIGHLIGHT_VERBOSE_ERROR

#define T3_HIGHLIGHT_VERBOSE_ERROR

Use verbose error reporting.

◆ T3_HIGHLIGHT_VERSION

#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.

◆ T3_WARN_MIN

#define T3_WARN_MIN

Warning code: the smallest value returned as warning.

Typedef Documentation

◆ t3_bool

typedef char t3_bool

A boolean type that does not clash with C++ or C99 bool.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Values for t3_bool, a boolean type that does not clash with C++ or C99 bool.

Enumerator
t3_false 

False.

t3_true 

True.

Function Documentation

◆ t3_highlight_detect()

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.

Parameters
lineThe line to use for auto-detection.
line_lengthThe length in bytes of the data in line.
firstBoolean indicating whether the first-line-regex patterns should be applied.
flagsFlags for loading of the map file.
langThe location to store the t3_highlight_lang_t (use t3_highlight_free_lang to free data).
errorLocation 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.

◆ t3_highlight_free()

void t3_highlight_free ( t3_highlight_t highlight)

Free all memory associated with a highlighting pattern.

It is acceptable to pass a NULL pointer.

◆ t3_highlight_free_lang()

void t3_highlight_free_lang ( t3_highlight_lang_t  lang)

Free the data allocated for a single t3_highlight_lang_t.

Parameters
langThe t3_highlight_lang_t to release.

The lang parameter is deliberatly passed by value, to prevent confusion with t3_highlight_free_list.

◆ 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.

◆ t3_highlight_free_match()

void t3_highlight_free_match ( t3_highlight_match_t match)

Free t3_highlight_match_t structure.

It is acceptable to pass a NULL pointer.

◆ t3_highlight_get_begin_attr()

int t3_highlight_get_begin_attr ( t3_highlight_match_t match)

Get the attribute for the pre-match section of the result.

◆ t3_highlight_get_end()

size_t t3_highlight_get_end ( t3_highlight_match_t match)

Get the end of the match.

◆ t3_highlight_get_langfile()

const char* t3_highlight_get_langfile ( const t3_highlight_t highlight)

Get the language file associated with this highlighting pattern.

◆ t3_highlight_get_match_attr()

int t3_highlight_get_match_attr ( t3_highlight_match_t match)

Get the attribute for the match section of the result.

◆ t3_highlight_get_match_start()

size_t t3_highlight_get_match_start ( t3_highlight_match_t match)

Get the start of the match.

◆ t3_highlight_get_start()

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.

◆ t3_highlight_get_state()

int t3_highlight_get_state ( t3_highlight_match_t match)

Get the state represented by match.

◆ t3_highlight_get_version()

long t3_highlight_get_version ( void  )

Get the value of T3_HIGHLIGHT_VERSION corresponding to the actual used library.

Returns
The value of T3_HIGHLIGHT_VERSION.

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_highlight_lang_by_filename()

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.

Parameters
filenameThe file name to use for auto-detection.
flagsFlags for loading of the map file.
langThe location to store the t3_highlight_lang_t (use t3_highlight_free_lang to free data).
errorLocation 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_list()

t3_highlight_lang_t* t3_highlight_list ( int  flags,
t3_highlight_error_t error 
)

List the known languages.

Returns
A list of display name/language file name pairs.

The returned list is terminated by an entry with two NULL pointers, and must be freed using t3_highlight_free_list.

◆ t3_highlight_load()

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.

Parameters
nameThe file name (relative to the search path) to load.
map_styleCallback function to map symbolic style names to integers.
map_style_dataData for the map_style callback.
flagsFlags for loading of highlighting files and syntax highlighting.
errorLocation to store an error code, or NULL.
Returns
An opaque struct representing a highlighting pattern, or 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_load_by_detect()

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.

Parameters
lineThe line to use for auto-detection.
line_lengthThe length in bytes of the data in line.
firstBoolean indicating whether the first-line-regex patterns should be applied.
map_styleSee t3_highlight_load.
map_style_dataSee t3_highlight_load.
flagsSee t3_highlight_load.
errorSee t3_highlight_load.

For details on the file loading, see t3_highlight_load. For details on the detection, see t3_highlight_detect.

◆ t3_highlight_load_by_filename()

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.

Parameters
nameThe source file name used to determine the appropriate highlighting pattern.
map_styleSee t3_highlight_load.
map_style_dataSee t3_highlight_load.
flagsSee t3_highlight_load.
errorSee 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_load_by_langname()

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.

Parameters
nameThe source file name used to determine the appropriate highlighting pattern.
map_styleSee t3_highlight_load.
map_style_dataSee t3_highlight_load.
flagsSee t3_highlight_load.
errorSee 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_highlight_match()

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.

Parameters
matchThe t3_highlight_match_t structure to store the result.
strThe string to search in.
sizeThe length of the string in bytes.
Returns
A boolean indicating whether the end of the line has been reached.

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.

t3_bool match_result;
do {
match_result = t3_highlight_match(match, line, line_length);
size_t begin = t3_highlight_get_start(match),
end = t3_highlight_get_end(match);
// Output bytes from 'begin' up to 'start' using t3_highlight_get_begin_attr(match) as
// attribute
// Output bytes from 'start' up to 'end' using t3_highlight_get_match_attr(match) as
// attribute
} while (match_result);

Note that both the pre-match section from 'begin' to 'start', and the match section from 'start' to 'end' may be empty.

Note
when using a t3_highlight_t created using the T3_HIGHLIGHT_UTF8 flag, the first call to t3_highlight_match will check the passed string for UTF-8 validity (see t3_highlight_utf8check for details). If the test fails, t3_false is returned and the start, match_start and end members of the t3_highlight_match_t are set to -1.

◆ t3_highlight_new()

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.

Parameters
syntaxThe t3_config_t to create the highlighting pattern from.
map_styleSee t3_highlight_load.
map_style_dataSee t3_highlight_load.
flagsSee t3_highlight_load.
errorSee 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_new_match()

t3_highlight_match_t* t3_highlight_new_match ( const t3_highlight_t highlight)

Allocate and initialize a new t3_highlight_match_t structure.

Parameters
highlightThe t3_highlight_t structure this t3_highlight_match_t structure will be used for.

The returned structure will can not be shared across threads.

◆ t3_highlight_next_line()

int t3_highlight_next_line ( t3_highlight_match_t match)

Set up match for highlighting the next line of input.

◆ t3_highlight_reset()

void t3_highlight_reset ( t3_highlight_match_t match,
int  state 
)

Reset a t3_highlight_match_t structure.

Parameters
matchThe t3_highlight_match_t structure to reset.
stateThe 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.

◆ t3_highlight_strerror()

const char* t3_highlight_strerror ( int  error)

Get a string description for an error code.

Parameters
errorThe error code returned by a function in libt3highlight.
Returns
An internationalized string description for the error code.

◆ t3_highlight_utf8check()

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).