|
|
@@ -2,25 +2,25 @@ |
|
|
|
|
|
|
|
## 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 |
|
|
@@ -39,12 +39,12 @@ The type for defining display modes. |
|
|
|
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. |
|
|
|
|
|
|
@@ -59,14 +59,13 @@ 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: |
|
|
@@ -82,20 +81,20 @@ General purpose highlighter (and demo program for libhl). |
|
|
|
## 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 |
|
|
|
``` |
|
|
|
|
|
|
|
--- |
|
|
@@ -106,15 +105,15 @@ All Vim highlighing scripts should be valid hl scripts. |
|
|
|
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>+ |
|
|
|
``` |