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...
Defines
#define	T3_HIGHLIGHT_VERSION
	The version of libt3highlight encoded as a single integer.
Functions
char *	t3_highlight_detect (const char line, size_t line_length, t3_bool first, int flags, t3_highlight_error_t error)
	Detect the language of a file from line data.
void	t3_highlight_free (t3_highlight_t *highlight)
	Free all memory associated with a highlighting pattern.
void	t3_highlight_free_list (t3_highlight_lang_t *list)
	Free a list returned by t3_highlight_list.
void	t3_highlight_free_match (t3_highlight_match_t *match)
	Free t3_highlight_match_t structure.
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.
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.
t3_highlight_lang_t *	t3_highlight_list (int flags, t3_highlight_error_t *error)
	List the known languages.
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.
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.
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.
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.
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.
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.
t3_highlight_match_t *	t3_highlight_new_match (const t3_highlight_t *highlight)
	Allocate and initialize a new t3_highlight_match_t structure.
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.
const char *	t3_highlight_strerror (int error)
	Get a string description for an error code.
t3_bool	t3_highlight_utf8check (const char *line, size_t size)
	Check that a string is valid UTF8.
Error codes (libt3highlight specific)
#define	T3_ERR_INVALID_FORMAT
	Error code: invalid structure of the syntax highlighting file.
#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_UNDEFINED_USE
	Error code: a 'use' directive references a non-existing define.
#define	T3_ERR_INVALID_NAME
	Error code: an 'extract' directive uses an invalid name.
Flags for ::t3_highlight_load.
#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.
#define	T3_HIGHLIGHT_USE_PATH
	Use the default include path to lookup the file.
#define	T3_HIGHLIGHT_VERBOSE_ERROR
	Use verbose error reporting.

Define Documentation

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

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

#define T3_HIGHLIGHT_USE_PATH

Use the default include path to lookup the file.

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

Function Documentation

char* t3_highlight_detect	(	const char *	line,
		size_t	line_length,
		t3_bool	first,
		int	flags,
		t3_highlight_error_t *	error
	)

Detect the language of a file from line data.

Parameters:

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.
error	Location to store an error code, or `NULL`.

Returns:: A newly allocated string with the name of the language, or NULL when no language was detected.

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

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_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_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:

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

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_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:

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.

Parameters:

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.

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:

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.

Parameters:

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.

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;

        t3_highlight_next_line(match);
        do {
            match_result = t3_highlight_match(match, line, line_length);
            size_t begin = t3_highlight_get_start(match),
                start = t3_highlight_get_match_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_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:

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.

Parameters:

highlight The t3_highlight_t structure this t3_highlight_match_t structure will be used for.

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.

Parameters:

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.

Parameters:

error The error code returned by a function in libt3highlight.

Returns:: An internationalized string description for the error code.

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

Data Structures

Defines

Functions

Error codes (libt3highlight specific)

Flags for ::t3_highlight_load.

Define Documentation

Function Documentation