|
|
@@ -1,30 +1,20 @@ |
|
|
|
# hl |
|
|
|
General purpose highlighter. |
|
|
|
# libhl |
|
|
|
|
|
|
|
// it would be lovely to have a different name the "library" part and the cli |
|
|
|
## 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. |
|
|
|
|
|
|
|
# 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 |
|
|
|
|
|
|
|
# API |
|
|
|
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 defending on 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; |
|
|
|
0 if rule passed, in such a case the user is expected still want 1 character outputed |
|
|
|
attributes - arbitrary data associated with the matched rule; intended to hold color/font information for example |
|
|
|
+ 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; |
|
|
@@ -43,30 +33,49 @@ This is how you append a display mode that render_string() will search based on |
|
|
|
} 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, |
|
|
|
so both "var a = 'a'" and "var a='a'" are recognized |
|
|
|
KEYWORD - a string which is recognized when surounded by word bundaries such as ' ' or '\t' |
|
|
|
MATCH - a Vim style regular expression to be recognized |
|
|
|
REGION - a Vim style regular expression where the starting and ending patters are to be distinguished from the contents |
|
|
|
+ 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); |
|
|
|
|
|
|
|
This wraps one of the following: |
|
|
|
|
|
|
|
// ?! |
|
|
|
|
|
|
|
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); |
|
|
|
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. |
|
|
|