73 lines
3.0 KiB
Markdown
73 lines
3.0 KiB
Markdown
|
# hl
|
||
|
|
General purpose highlighter.
|
||
|
|
|
||
|
|
// it would be lovely to have a different name the "library" part and the cli
|
||
|
|
# 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.
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
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,
|
||
|
|
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
|
||
|
|
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_syntax_character_tokens(const char * const chars, hl_group_t * const g);
|
||
|
|
|
||
|
|
# 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>+
|