th1-sgb  Artifact Content

Artifact 960f480251644318935ff94d4fd85c5777860923:

Wiki page [HowTo] by stephan 2012-07-22 12:13:58.
D 2012-07-22T12:13:58.457
L HowTo
P 378d3e1d63aab1856013cf1f7ecb1fc6a01bba91
U stephan
W 2967
<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 [|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  [|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:

#include "th1.h"
Th1_Vtab vtab = Th1_Vtab_basic;
Th1_Interp * interp = Th1_CreateInterp( &vtab );

int rc;
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).
Z 193da36aa47e5d31c5a67d51b9481d1d