<h1>Exceedingly Brief HowTo...</h1>
The canonical example program is in <tt>test.c</tt>. It shows what one needs to do to set up an interpreter and execute code through it.
Examples of binding custom functions can be found in <tt>th1*.c</tt>. Search those files for where "Th1_RegisterCommands" is called and follow the nearby function lists. The file <tt>th1.c</tt> holds the core interpreter, <tt>th1_lang.c</tt> holds the language-defined functions and function-like constructs, and <tt>th1_main.c</tt> holds "app-level" functions. The file <tt>th1_client.c</tt> is a stub which clients can use to get started with.
More documentation can be found here:
* Paul Ruizendaal's [http://www.sqliteconcepts.org/THManual.pdf|TH Manual] (PDF) is essentially the only user's guide to Fossil's TH1 language, and is invaluable for anyone wanting to use TH1.
* i have ported Paul's document [https://docs.google.com/document/d/1qBDuO6T4A-KOwZr2WyWTLX9XzWjKZvbiRJYaPaTBE7Y/view|into Google Docs], expanding it a bit to include features specific to this TH1 implementation.
At its simplest, here is how one sets up an interpreter:
Th1_Vtab vtab = Th1_Vtab_basic;
Th1_Interp * interp = Th1_CreateInterp( &vtab );
rc = Th1_Eval_code( interp, "puts \"hi, world\\n\"\n", 0 );
rc = Th1_Eval_filename( interp, "foo.th1", 1 );
Th1_DeleteInterp( interp );
The real value in th1 comes in binding one's own C functions to it, such that they can be called from script code. How to do that is demonstrated in the various <tt>th1*.c</tt> files, and many invaluable details about TH1 can be found via the doc links above.
The <tt>Th1_Eval_xxx()</tt> family of functions evaluate "pure" script code, whereas the <tt>Th1_Render_xxx()</tt> family of functions evaluate code wrapped in TH1 tags in text documents.
The <tt>Th1_Vtab</tt> class shown above holds the "virtual" operations of the interpreter. This includes:
* Memory de/re/allocation. It uses a <tt>realloc(3)</tt>-style interface, rather than a collection of malloc/free functions.
* A generic output interface for use by script routines which want to generate output through a common mechanism. This allows, e.g., integrating [th1_ob|output buffering features] transparently to code which generates output. The function <tt>Th1_Output()</tt> sends all of its data via this output mechanism, so script-bound functions which generate output are encouraged to use <tt>Th1_Output()</tt> to do so.
The Vtab class might be expanded/changed as the engine is tweaked.
Client code must pass a Vtab instance when creating an interpreter, and can use the convenience object <tt>Th1_Vtab_basic</tt> to copy an instance which uses the C-standard memory management routines and sends its output to <tt>stdout</tt> by default (set <tt>vtab.out.pState</tt> to a <tt>FILE</tt> pointer to direct the ouput there).