Tema User Manual.

<%silent include:document.tema%>\\

  title    <%:Tema -- template macro processor%>
  author   <%:Mikhail Kryshen%>


<%par:Tema is a macro processor and template engine. It reads the input file 
recursively expanding any macro found in the text.%>

<%par:Distinctive features:%>
  <%:Extensible: implement new functions as Java classes.%>
  <%:Database access.%>
  <%:Processes and outputs data as early as possible (function could start 
     to output data before all it's arguments are read and parsed).%>
  <%:Apache Ant integration.%>

<%par:Tema macro has the following syntax:%>


<%par:<%code:function_list%> is the list of text-processing functions.
Functions will be applied to text in reverse order.%>

<%par:<%code:text%> could contain space-separated list of arguments 
followed by arbitrary data. Number of arguments is determined by the last
function in the <%code:function_list%>.%>

<%par:<%code\[arg1 arg2...] [data]%>%>

<%par:The text is separated from the list of functions by one of the 
following characters:%>

  <%\':' -- process text recursively.%>
  <%\'#' -- parse text but do not replace any embedded macro.%>
  <%\'\', '`' -- do not parse text (ignore any '<%' sequences).%>

<%par:<%code:escape%> is either '\' or '\\':%>

  <%:<%:\%> -- the following newline symbol will be removed;%>
  <%:<%:\\%> -- the following sequence of the whitespace characters will be removed.%>

<%par:You could use <%\'[%' and '%]'%> character sequences to denote macro
as an alternative to [%\'<%' and '%>'%].%>

<%par:Every function returns integer value. The general convention is to 
return non-zero for successful operation. The value of the macro substitution 
is the return value of the first function in the function list. The value of
any Tema text is the sum value of all macro in the text, except the value of
the text without any macro equals -1.%>

<%par:Internally, Tema function could be represented by any Java object.
Instances of kryshen.tema.Function and kryshen.tema.Context are handled
specially. For any other type of object, function output would be the value 
returned by the method <%code:toString()%>.%>

<%section:Built-in functions%>

<%par emph:Notice: some functions are not yet described in this manual.
For the complete list of built-in functions refer to the API documentation
and source code.%>

  output  <%:Tema version%>

  output  <%:function data%>

  output      nothing
  description <%:Ignores the input text (':' separator works as '#').
    Use for commenting (e.g. <%code\[%!\ comment %]%>).%>

  output  nothing

  arguments   <%:definition name%>
  input_data  <%:variable value%>
  output      <%:function data%>
  description <%:Defines new function as a static variable.%>

  arguments   <%:name, code%>
  description <%:\\
    Defines new function. 
    Use <%code:next_arg%>, <%code:data%>, and <%code:has_more_data%> 
    functions to access function arguments.%>
  output      <%:name%> 

[%!\ TODO: next_arg, data, has_more_data %]\\

  arguments   <%:definition name%>
  input_data  <%:static variable value (optional)%>
  output      <%:function data%>
  description <%:Exports the definition to the global (outermost) context.%>

  arguments   <%:def1, def2, ...%>
  output      <%:nothing%>
  description <%:Unsets the definitions.%>

  arguments   <%:function, arg1, arg2, ..., data%>
  output      <%:function output%>
  description <%:Invokes function.%>

  arguments   <%:name, class, url1, url2, ...%>
  output      <%:name%>
  description <%:Instantiate specified class as a Tema function definition.
    URL arguments are optional.%>

  input_data  <%:code%>
  output      <%:output generated by the code%>
  description <%:Evaluates the specified template code in the super-context
    (i.e. context of the calling function or context executing 
    the database query).%>

  arguments   <%:s1, s2, data%>
  description <%:\\
    Replaces all occurrences of <%code:s1%> with <%code:s2%> in data.%>

[%!\ TODO: all functions defined in Strings.java %]\\

<%subsection:Input / output%>

  arguments   <%:src, dest%>
  description <%:Copies file <%code:src%> to <%code:dest%>.%>
  output      <%:dest%> 

  arguments   <%:name%>
  input_data  <%:text%>
  description <%:Writes text to file.%> 
  output      <%:name%>

  arguments   <%:name%>
  description <%:Reads file.%> 
  output      <%:File contents.%>

  arguments   <%:name%>
  description <%:Includes template.%> 
  output      <%:Result of processing the template.%>

  arguments   <%:base, name%>
  output      <%:Path constructed from the base directory and file name.%> 


  input_data  <%:text%>
  output      <%:Function data if it's value is non-zero or empty text.%>

  input_data  <%:code%>
  description <%:Repeatedly outputs it's evaluated data while it has non-zero value.%>

[%!\ TODO: all functions defined in Control.java %]\\


  arguments   <%:connection name%>
  input_data  <%:resource%>
  description <%:Establishes connection with the database.
    Load the appropriate database driver using the <%code:load%> function
    before using <%code:db_connect%> 
    (e.g. [%code\<%load:driver sun.jdbc.odbc.JdbcOdbcDriver%>%]).%>

  arguments   <%:query name, connection name%>
  input_data  <%:SQL statement%>

  arguments   <%:query, template, arg1, arg2, ...%>
  description <%:Executes query, evaluating the template for each result row.%>

  input_data  <%:column name%>
  output      <%:value from the query result.%>
  description <%:Available in the template for the <%code:db_query%> function.%>  

  output      <%:current row number in the result set.%>
  description <%:Available in the template for the <%code:db_query%> function.%>  

[%!\ TODO: all functions defined in ImageConverter.java %]\\

<%section:Running Tema%>

<%par:Change to the dist subdirectory in the distribution package and
issue the following command:%>

<%par:<%code:java -jar tema.jar [options] [files]%>%>

<%par:The following options are recognized:%>
  <%:<%code:--demo%> --- run demo console with a code example;%>
  <%:<%code:-h, --help%> --- print help message;%>
  <%:<%code:--input-encoding <arg>%> --- set the input encoding;%>
  <%:<%code:--log <arg>%> --- log all error messages to the specified file;%>
  <%:<%code:-o, --output <arg>%> --- set the output file;%>
  <%:<%code:--output-encoding <arg>%> --- set the output encoding;%>
  <%:<%code:-v, --version%> --- print the version information and exit.%>


<%par link:http://kryshen.pp.ru/tema/%>