## API
```C
- int hl_init(void);
- int hl_deinit(void);
+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.
```C
- void render_string(const char * const string, const char * const mode);
+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_.
```C
- #define HLPATH //?!
+#define HLPATH //?!
```
Coma separated list of directories to be searched for syntax scripts. `#undef` to disable it entirely.
```C
- typedef void (*attribute_callback_t)(const char * const string, const int length, void * const attributes);
+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
This is how you append a display mode that render_string() will search based on _.key_.
```C
- typedef enum {
- KEYSYMBOL,
- KEYWORD,
- MATCH,
- REGION
- } token_type_t;
+typedef enum {
+ KEYSYMBOL,
+ KEYWORD,
+ MATCH,
+ REGION
+} token_type_t;
```
These are the valid type of distinct token types.
The universal way to add a new pattern to be recognized is with:
```C
- token * new_token(const char * const syntax, const token_type_t t, const hl_group_t * const g);
+token * new_token(const char * const syntax, const token_type_t t, const hl_group_t * const g);
```
There are also convinience functions:
```C
- // 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);
-
+// 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:
## Usage
hl will read from stdin and write to stdout.
```bash
- hl < source/main.c
+hl < source/main.c
```
### Cli Options
```bash
- -h : display help message
- -I <dir> : syntax file look up directory
- -s <syntax> : specify syntax to load
+-h : display help message
+-I <dir> : syntax file look up directory
+-s <syntax> : specify syntax to load
```
### Environment variables
```bash
- $HLPATH : colon separated list of directories searched for syntax script files;
- overriddes the value of the HLPATH macro
+$HLPATH : colon separated list of directories searched for syntax script files;
+ overriddes the value of the HLPATH macro
```
---
The instrunctions in particular are:
```vimscript
- 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>+
+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:
```vimscript
- syn[ntax] keysymbol <char>+
+syn[ntax] keysymbol <char>+
```