Mercurial > hg > tema
view doc/manual/manual.tema @ 7:dd4dce98151d
Added tag release_0_1 for changeset 1d2fe61a3a62
author | Mikhail Kryshen <mikhail@kryshen.net> |
---|---|
date | Fri, 07 Nov 2008 03:35:15 +0300 |
parents | a20217d78068 |
children | 5ebf123f3486 |
line wrap: on
line source
[%!\ Tema User Manual. %]\\ <%silent include:document.tema%>\\ <%document: title <%:Tema -- template macro processor%> author <%:Mikhail Kryshen%> content <%section:Introduction%> <%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:%> <%itemize: <%: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{:|#|\|`}[escape]text%>[escape]%]%> <%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:%> <%itemize: <%\':' -- 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 '\\':%> <%itemize: <%:<%:\%> -- 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.%> <%function:tema output <%:Tema version%> %> <%function:echo output <%:function data%> %> <%function:! output nothing description <%:Ignores the input text (':' separator works as '#'). Use for commenting (e.g. <%code\[%!\ comment %]%>).%> %> <%function:silent output nothing %> <%function:set arguments <%:definition name%> input_data <%:variable value%> output <%:function data%> description <%:Defines new function as a static variable.%> %> <%function:define arguments <%:name%> input_data <%: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 %]\\ <%function:export arguments <%:definition name%> input_data <%:static variable value (optional)%> output <%:function data%> description <%:Exports the definition to the global (outermost) context.%> %> <%function:unset arguments <%:def1, def2, ...%> output <%:nothing%> description <%:Unsets the definitions.%> %> <%function:invoke arguments <%:function, arg1, arg2, ..., data%> output <%:function output%> description <%:Invokes function.%> %> <%function:load arguments <%:name, class, url1, url2, ...%> output <%:name%> description <%:Instantiate specified class as a Tema function definition. URL arguments are optional.%> %> <%function:super 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).%> %> <%function:replace 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%> <%function:copy arguments <%:src, dest%> description <%:Copies file <%code:src%> to <%code:dest%>.%> output <%:dest%> %> <%function:write arguments <%:name%> input_data <%:text%> description <%:Writes text to file.%> output <%:name%> %> <%function:read arguments <%:name%> description <%:Reads file.%> output <%:File contents.%> %> <%function:include arguments <%:name%> description <%:Includes template.%> output <%:Result of processing the template.%> %> <%function:file arguments <%:base, name%> output <%:Path constructed from the base directory and file name.%> %> <%subsection:Conditionals%> <%function:optional input_data <%:text%> output <%:Function data if it's value is non-zero or empty text.%> %> <%function:while input_data <%:code%> description <%:Repeatedly outputs it's evaluated data while it has non-zero value.%> %> [%!\ TODO: all functions defined in Control.java %]\\ <%subsection:Database%> <%function:db_connect 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%>%]).%> %> <%function:db_prepare arguments <%:query name, connection name%> input_data <%:SQL statement%> %> <%function:db_query arguments <%:query, template, arg1, arg2, ...%> description <%:Executes query, evaluating the template for each result row.%> %> <%function:db input_data <%:column name%> output <%:value from the query result.%> description <%:Available in the template for the <%code:db_query%> function.%> %> <%function:db_row 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:%> <%itemize: <%:<%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.%> %> <%if:<%not embedded:%> <%section:Homepage%> <%par link:http://kryshen.net/tema/%> %>