|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179 |
- # libhl
-
- ## API
- ```C
- 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
- #define HLPATH ~/.local/hl/:~/.vim/syntax/
- ```
- Coma separated list of directories to be searched for syntax scripts. `#undef` to disable it entirely.
-
-
- ```C
- void render_string(const char * const string, const char * const mode); //XXX: rename
- ```
- This function matches _string_ against all known highlighting rules and dispatches the appropriate callback depending on _mode_.
-
-
- ```C
- int token_fits(const token_t * const token, const char * const to, const int string_offset, const bool is_start_of_line, int * match_offset);
- ```
- Fit a specific token against a string. `render_string()` uses this function internally.
-
-
- ```C
- 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 processed (probably printed)
- + length - number of characters to be processed from _string_
- + attributes - arbitrary data associated with the matched token; intended to hold color/font information for example; if no token was matched NULL will be passed
-
-
- ```C
- struct token_table_t;
- ```
- Holds a group of tokens belonging to the same language.
-
-
- ```C
- typedef struct {
- char * key;
- attribute_callback_t callback;
- } display_t;
- ```
- The type for defining display modes.
-
-
- ```C
- void new_display_mode(display_t * mode);
- ```
- 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;
- ```
- 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:
- ```C
- 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_char_tokens(const char * const chars, hl_group_t * const g);
- token_t * new_symbol_token(const char * const c, hl_group_t * const g);
- int new_symbol_tokens(const char * const * symbols, hl_group_t * const g);
- int new_char_tokens(const char * str, hl_group_t * const g);
- token_t * new_keyword_token(const char * const word, hl_group_t * const g);
- token_t * new_region_token(const char * start, const char * end, hl_group_t * g);
- ```
-
-
- The regex engine used for MATCH-es is Jeger by default, emulating Vim regex.
- However the regex engine can be overridden:
- ```C
- // ?!
- ```
-
-
- ### Default
- There are default of most anything defined for convenience. They can be disable with `#undef`-ing the following macro:
- ```C
- #define HL_DEFAULTS
- ```
-
- ```C
- hl_group_t * normal_hl
- hl_group_t * error_hl
- hl_group_t * warning_hl
- hl_group_t * search_hl
-
- hl_group_t * underlined_hl
- hl_group_t * bold_hl
- hl_group_t * italics_hl
-
- hl_group_t * comment_hl
- hl_group_t * block_hl
- hl_group_t * operator_hl
- hl_group_t * constant_hl
- hl_group_t * special_hl
- hl_group_t * identifier_hl
- hl_group_t * type_hl
-
- // ---
- token_table_t std_token_table;
- ```
-
- ---
-
-
- # hl
- General purpose highlighter (and demo program for libhl).
-
- ## Usage
- hl will read from stdin and write to stdout.
- ```bash
- hl < source/main.c
- ```
-
- ### Cli Options
- ```bash
- -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
- ```
-
- ---
-
- # 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:
-
- ```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>+
- ```
-
- Additionally hl recognizes:
-
- ```vimscript
- syn[ntax] keysymbol <char>+
- ```
|