redrafted the design

diff --git a/README.md b/README.md
index 418443cd90cdac226a83b3695bb1b38483586339..91086fbd32b5ec902523b71738873a9671006483 100644 (file)
--- a/README.md
+++ b/README.md
@@ -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.