D 2015-02-12T09:00:07.325
L TH1
N text/x-markdown
P 44de7e2b84fef0d6ebb537d5c6b00896661aeecb
U mario
W 12878
TH1 is the built-in scripting/templating language in Fossil.
It can be used in the header or footer within `<th1>...</th1>` sections, or in the `th1-setup` settings textbox.
It's a slim TCL variant (but a full TCL interpreter may be compiled in too).
See the [Cookbook on TH1](https://www.fossil-scm.org/xfer/wiki/Cookbook#th1-usage) or the
[**TH Manual.pdf**](http://www.sqliteconcepts.org/THManual.pdf) for a proper overview.
The following is just a crude summary.
## Basic syntax
Everything is a string. No really. The string is the fundamental datatype in TH1 / TCL.
* Variables are often passed just by their literal varname.
With a `$` prefix their value gets substituted or interpolated.
set varname "something something"
puts $varname
* Literals are also strings. For instance `1` is a string, `"text text"` is a string and `,&=asdf!` is a string.
* There are three ways to group things for substitution.
* In `"` double `"` quotes any literal text can be grouped into a string, and `$vars` will be interpolated.
Double quotes can be escaped by `\"` within. They cannot nest themselves, but within `{}` or `[]` subgroups.
* Square brackets `[proc calls]` interpolate procedure call results. They also do so within `"` double quoted strings.
And of course they can be nested `[expr 5*[expr [expr $x]+2]]`
* Whereas `{...}` curly blocks are unparsed sections, can be nested with `{}` themselves or `[]` and `""`.
They're often used to defer literal code sections for later evaluation.
* Statements are interpreted *line by line*. The first string literal is the procedure to call.
funcname arg1 arg2 ...
Arguments can be literals, strings, variables, [proc ..] calls, etc. Trailing semicolons are optional.
Some functions provide prefix arguments `-xyz` and `--` flag separators, or `?optional?` parameters.
* Expressions are only interpreted in the <kbd>if {expr}</kbd> block, or with `[expr 2*$x+1]` calls.
They can't be used as statements all alone.
* Lists are a special variant of strings. Any string with spaces can be e.g. split-accessed via <kbd>lindex</kbd>.
Curly braces can group further substrings/lists within. (Lists are actually pretty central to the TH1/TCL
syntax. Command statements and their arguments are basically seen as lists too.)
* Variable names of the form `$varname(xyzname)` are treated as arrays. You need to know/keep the array
keys to utilize them in TH1.
Most control structures (e.g. <kbd>if</kbd> and <kbd>proc</kbd>) are implemented as procedure calls. To wrap code blocks
over multiple lines, the opening `{` curly quote must be in the same statement line, and subsequent blocks
be chained with `} {` thereafter.
## Built-in TH1 functions
<style>
main table td:nth-child(1) { width: 30% }
main table tr:nth-child(2n) { background: #f7f7f7; }
main table kbd { color: #311; font-weight: 500; }
</style>
| <kbd>set</kbd> VARNAME value | Defines a variable. The varname is noted without leading `$`, but creates a `$varname` afterwards. The value can be a literal `123` number, or a `"string"`, or an `[expr ...]` or any other `[ProcCall ...]` of course. |
| <kbd>unset</kbd> VARNAME | Undefines a variable by name. |
| <kbd>info exists</kbd> VARNAME| Probes if a variable was defined. |
| <kbd>expr</kbd> $x +-*/ <>!=< | Runs an expression, returns its result. This can be any combination of arithmetics, or comparisons, with variable names or literal strings. Usually used within `[...]` square brackets for interpolation. |
| <kbd>proc</kbd> {args} {cmd} | Defines a new function. {args} is a space-separated list of parameter names, and {code} just a code block. |
| <kbd>catch</kbd> {code} rc? | Runs a code block, but ignores any runtime errors. An optional varname parameter captures TH1_ERROR codes etc. |
| <kbd>if</kbd> {expr} {body} <i><kbd>elseif</kbd> expr2 body2 <kbd>else</kbd> bodyN?</i> | Tests an expression, and runs the code {body}. Can optionally list multiple `elseif` expressions and blocks, and a final `else` of course. Each expression can be a literal `{$x >= 2}` or a function result interpolation `{[string length $var] >= 2}` for example. |
| <kbd>for</kbd> {init} {condition} {incr} {code-block} | Runs a code block multiple times. The {init} can be empty, the {condition} is usually a boolean comparison, and {incr} often `{set cnt [expr $cnt+1]}`. |
| <kbd>list</kbd> a b c ... | Compacts multiple arguments into a list-string. A list is simply a space-separated string, or entries quoted with unparsed `{...}` curly sections. |
| <kbd>lindex</kbd> list index | Returns an entry from a list-string. |
| <kbd>llength</kbd> list | Counts the number of elements in a list-string. |
| <kbd>proc</kbd> name {args} {code} | Declares a new function. The name is the literal procedure name. Args can be a space-separated list of argument varnames. And the {code} block... is the code block. |
| <kbd>rename</kbd> oldcmd newcmd | Renames a declared function. |
| <kbd>break</kbd> | Break statement. |
| <kbd>continue | Continue statement. |
| <kbd>ok</kbd> | Ok statement. |
| <kbd>error</kbd> | Error statement. |
| <kbd>return</kbd> value? | Plain value return. Used in procedures of course. Can list an optional -code state (break, continue, ok, error) before the value. |
| <kbd>string compare</kbd> $str1 $str2 | Compares strings (strcmp) for alpha-/numeric sorting. |
| <kbd>string first</kbd> $needle $haystack | Finds first position of one string in another. Optional startindex as third param. |
| <kbd>string is alnum</kbd> $string | Checks if string is completely alphanumeric, no special chars. |
| <kbd>string last</kbd> $needle $haystack | Finds last position of needle in haystack string. |
| <kbd>string length</kbd> $string | Returns length of string/variable. |
| <kbd>string range</kbd> $str first end | Returns a substring of its input. String indicies start at 1. The END parameter can be larger than the actual string length. |
| <kbd>string repeat</kbd> $str COUNT | Duplicates a string CNT times, returns the concatenated result string. |
| <kbd>string trim</kbd> $str | Removes whitespace from string. |
| <kbd>string trimleft</kbd> $str | Removes whitespace from string. |
| <kbd>string trimright</kbd> $str | Removes whitespace from string. |
| <kbd>uplevel</kbd> LEVEL {code} | Runs given code block in a different variable scope. Usually `uplevel 1 {...}` to run things in the global scope / prior function call in the chain. |
| <kbd>upvar</kbd> LEVEL extvar local | Imports/aliases a variable name from a different variable scope, and can attach a new local name to it. |
| <kbd>breakpoint</kbd> | Does nothing. Only used for debugging Fossil/TH1. |
## Fossil functions
| <kbd>httpize</kbd> "string" | Escapes a string for URL context. |
| <kbd>enable_output</kbd> 1/0 | Allows to suppress further output. |
| <kbd>puts</kbd> string | Prints a string to the page, pre-escapes HTML special characters. |
| <kbd>html</kbd> string | Prints a raw string, so may contain actual HTML for display. |
| <kbd>wiki</kbd> string | Uses the Wiki renderer to output a string. Thus fossil wiki markup will be converted to HTML. |
| <kbd>htmlize</kbd> string | Escapes a string for HTML context. |
| <kbd>date</kbd> | Returns current date and time string in UTC. With `-local` in current timezone. |
| <kbd>hascap</kbd> letters | Probes permissions for currently logged in user. Argument can be a string of letter-wise capabilities (from Admin>User). |
| <kbd>anycap</kbd> letters | Probes if any of the listed permission letters is allowed for current user. |
| <kbd>hasfeature</kbd> setting | Checks which Fossil features were compiled in (can be one of: <kbd>ssl</kbd>, <kbd>tcl</kbd>, <kbd>json</kbd>, <kbd>markdown</kbd>, <kbd>th1Docs</kbd>, <kbd>th1Hooks</kbd>, <kbd>tclStubs</kbd>, <kbd>useTclStubs</kbd>). |
| <kbd>combobox</kbd> name list lines | Prints a HTML combobox. |
| <kbd>linecount</kbd> string max min | Counts linebreaks in string. |
| <kbd>repository</kbd> | Return full path name to currently open fossil repository. |
| <kbd>checkout</kbd> | Return full path name to opened checkout directory. |
| <kbd>trace</kbd> message | Outputs/logs a debug message, if tracing is enabled. |
| <kbd>globalState</kbd> setting | Returns other runtime states/paths/flags (can be one of: <kbd>checkout</kbd>, <kbd>configuration</kbd>, <kbd>executable</kbd>, <kbd>flags</kbd>, <kbd>log</kbd>, <kbd>repository</kbd>, <kbd>top</kbd>, <kbd>user</kbd>, <kbd>vfs</kbd>) |
| <kbd>getParameter</kbd> name default? | Returns URL parameter with given name or position, or CLI parameter for th1-cmd-hooks. |
| <kbd>setParameter</kbd> name value | Overwrites an URL parameter. |
| <kbd>reinitialize</kbd> flags? | Restarts TH1 interpreter with initialization flags (bitmask of 1=need_config, 2=force_tcl, 4=force_reset, 8=force_setup). |
| <kbd>render</kbd> string | Outputs rendered string. Templates can themselves contain TH1 code. |
| <kbd>styleHeader</kbd> title | Outputs style header. (No idea what that is.) |
| <kbd>styleFooter | Outputs footer. |
| <kbd>artifact</kbd> UUID filename? | Prints the raw artificat content by UUID or filename. |
| <kbd>utime</kbd> | Elapsed CPU time for current fossil userland process in microseconds. |
| <kbd>stime</kbd> | Elapsed CPU time for system calls. |
| <kbd>randhex</kbd> N | Creates a string of random hexdigit pairs. |
| <kbd>query</kbd> {SQL} {code} | Yay! Query Fossil SQL database. The SQL code can be put in curly braces {SELECT $varname} for implicit variable→parameter binding. The {CODE} automatically receives column names and values as $vars for each row. |
| <kbd>setting</kbd> name | Returns Fossil configuration setting string. Preface with -strict to avoid ambigous setting name matches. |
| <kbd>regexp</kbd> -nocase? exp string | Matches a string agains an extended regular expression (no regex delimiters). The -nocase flag an be noted before the regex string. Prefer {curly*} quoting for the regex. |
| <kbd>http</kbd> url payload? | Sends a HTTP query. Target must be whitelisted by `url-regexp` in the settings. The optional payload would become a plain text POST body. Should return the HTTP response body as string. |
## TCL Binding
| <kbd>tclReady</kbd> | Tests if TCL was enabled and can be called from TH1 scripts. Only returns true after first `tclInvoke` seemingly. |
| <kbd>tclInvoke</kbd> CMD args..| Runs a TCL procedure from within TH1. |
| <kbd>tclExpr</kbd> {expr} | Evaluates an expression via TCL, returns its result. |
| <kbd>tclEval</kbd> args.. | Runs some TCL code. |
| <kbd>th1Expr</kbd> args.. | Fetch TH1 value/expression from within TCL code. |
| <kbd>th1Eval</kbd> args.. | Run TH1 from TCL context. |
## [TH1 Hooks](wiki/TH1-Hooks)
| <kbd>webpage_hook</kbd> | Run prior rendering built-in webpages. Allows to render custom pages. |
| <kbd>webpage_notify</kbd> | Run after successful page rendering. |
| <kbd>command_hook</kbd> | Run prior command line actions. Allows to declare new fossil commands. |
| <kbd>command_notify</kbd> | Run after normal CLI commands. |
## Default variables
| $project_name | Proj Name |
| $title | Homepage |
| $baseurl | http://fsl.example.org/repo/ |
| $secureurl | http://fsl.example.org/repo/ |
| $home | home |
| $index_page | /home |
| $current_page | /wiki/index |
| $csrf_token | localhost |
| $release_version | 1.31 |
| $manifest_version | 4932465ecc |
| $manifest_date | 2015-02-02 20:00:00 |
| $compiler_name | gcc-4.9.0 |
| $stylesheet_url | /style.css/142257204849324 |
| `$logo_image_url` | /logo/130387012349324 |
| `$background_image_url` | /background/133320697349324 |
| $login | username |
| $::cmd_name | co |
| $::cmd_args | filename |
| $::cmd_flags | |
| $::web_name | home |
| $::web_args | fossil ui |
| $::web_flags | 1 |
Z 3754cb5a6fe6a0202118fdc8d2e30a5e