README draft

diff --git a/README b/README
deleted file mode 100644 (file)
index e69de29..0000000

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..69d8a25
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# 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>+