libhl

API

int hl_init(void);
int hl_deinit(void);

These functions are responsible for the library's “life time”. hl_init() must be called before any other library function. hl_deinit() will ensure all occupied memory is freed.

void render_string(const char * const string, const char * const mode);

This function matches string against all known highlighting rules and dispatches the appropriate callback depending on mode.

typedef void (*attribute_callback_t)(const char * const string, const int length, void * const attributes);

The type used for defining appropriate callbacks for render_string().

• string - string to be outputed

• length - number of characters that matched a highlighting rule

• attributes - arbitrary data associated with the matched rule; intended to hold color/font information for example

  typedef struct { char * key; attribute_callback_t callback; } display_t; The type for defining display modes.

  void new_display_mode(display_t * mode); This is how you append a display mode that render_string() will search based on .key.

  typedef enum { KEYSYMBOL, KEYWORD, MATCH, REGION } token_type_t; These are the valid type of distinct token types.

• KEYSYMBOL - a string which is contextless, the surounding text is ignored “mysymbol” will match inside all of these: “something mysymbol something” “somethingmysymbolsomething” it is intended to match such thing as programming language operators

• KEYWORD - a string which is recognized when surounded by word bundaries such as ' ' or ‘\t’

• MATCH - a regular expression to be recognized

• REGION - a regular expression where the starting and ending patters are to be distinguished from the contents

The universal way to add a new pattern to be recognized is with:

token * new_token(const char * const syntax, const token_type_t t, const hl_group_t * const g);

There are also convinience functions:

// NOTE: the return value is the number tokens successfully inserted
int new_keyword_tokens(const char * const * words, hl_group_t * const g);	// _words_ must be NULL terminated
int new_syntax_character_tokens(const char * const chars, hl_group_t * const g);

The regex engine used for MATCHes is Jeger by default, emulating Vim regex. However the regex engine can be overridden:

// ?!

---

#hl General purpose highlighter (and demo program for libhl).

Usage

hl will read from stdin and write to stdout. hl < source/main.c

Cli Options

-h          : display help message
-F <dir>    : syntax file look up directory
-s <syntax> : specify syntax to load

Environment variables

HL_HOME	: default directory to load syntax files from

---

Scripting

hl can parse a small subset of VimScript: the few instructions related to highlighing, and it ignores everything else. All Vim highlighing scripts should be valid hl scripts. The instrunctions in particular are:

sy[ntax] keyword <hl_group> <word>+
sy[ntax] match   <hl_group> <regex>
sy[ntax] region  <hl_group> start=<string|match> end=<string|match>
hi[ghtlight] link <from_group> <to_group>
hi[ghtlight] def  <group> <display_t>=<data>+

Additionally hl recognizes:

syn[ntax] keysymbol <char>+