libhl/README.md

# 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
	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
	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
+ attributes - arbitrary data associated with the matched rule; intended to hold color/font information for example

```C
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_.

```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_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:
```C
	// ?!
```

---

# 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
```

---

# 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>+
```