diff options
Diffstat (limited to 'www/th1.md')
| -rw-r--r-- | www/th1.md | 1024 |
1 files changed, 1024 insertions, 0 deletions
diff --git a/www/th1.md b/www/th1.md new file mode 100644 index 0000000..97875cf --- /dev/null +++ b/www/th1.md @@ -0,0 +1,1024 @@ +TH1 Scripts +=========== + +TH1 is a very small scripting language used to help generate web-page +content in Fossil. + +Origins +------- + +TH1 began as a minimalist re-implementation of the Tcl scripting language. +There was a need to test the SQLite library on Symbian phones, but at that +time all of the test cases for SQLite were written in Tcl and Tcl could not +be easily compiled on the SymbianOS. So TH1 was developed as a cut-down +version of Tcl that would facilitate running the SQLite test scripts on +SymbianOS. + +Fossil was first being designed at about the same time. +Early prototypes of Fossil were written in pure Tcl. But as the development +shifted toward the use of C-code, the need arose to have a Tcl-like +scripting language to help with code generation. TH1 was small and +light-weight and used minimal resources and seemed ideally suited for the +task. + +The name "TH1" stands for "Test Harness 1", +since its original purpose was to serve as testing harness +for SQLite. + +Where TH1 Is Used In Fossil +--------------------------- + + * In the header and footer for [skins](./customskin.md) + text within `<th1>...</th1>` is run as a TH1 script. + ([example](/builtin/skins/default/header.txt)) + + * This display of [tickets](./bugtheory.wiki) is controlled by TH1 + scripts, so that the ticket format can be customized for each + project. Administrators can visit the <b>/tktsetup</b> page in + their repositories to view and customize these scripts. + ([example usage](./custom_ticket.wiki)) + +Overview Of The Tcl/TH1 Language +-------------------------------- + +TH1 is a string-processing language. All values are strings. Any numerical +operations are accomplished by converting from string to numeric, performing +the computation, then converting the result back into a string. (This might +seem inefficient, but it is faster than people imagine, and numeric +computations do not come up very often for the kinds of work that TH1 does, +so it has never been an issue.) + +A TH1 script consists of a sequence of commands. +Each command is terminated by the first *unescaped* newline or ";" character. +The text of the command (excluding the newline or semicolon terminator) +is broken into space-separated tokens. The first token is the command +name and subsequent tokens are the arguments. In this sense, TH1 syntax +is similar to the familiar command-line shell syntax. + +A token is any sequence of characters other than whitespace and semicolons. +Text inside double-quotes is a single token even if it includes +whitespace and semicolons. Text within {...} pairs is also a +single token, which is useful because curly braces are easier to “pair” +and nest properly than double-quotes. + +The nested {...} form of tokens is important because it allows TH1 commands +to have an appearance similar to C/C++. It is important to remember, though, +that a TH1 script is really just a list of text commands, not a context-free +language with a grammar like C/C++. This can be confusing to long-time +C/C++ programmers because TH1 does look a lot like C/C++, but the semantics +of TH1 are closer to FORTH or Lisp than they are to C. + +Consider the `if` command in TH1. + + if {$current eq "dev"} { + puts "hello" + } else { + puts "world" + } + +The example above is a single command. The first token, and the name +of the command, is `if`. +The second token is `$current eq "dev"` - an expression. (The outer {...} +are removed from each token by the command parser.) The third token +is the `puts "hello"`, with its whitespace and newlines. The fourth token +is `else` and the fifth and last token is `puts "world"`. + +The `if` command evaluates its first argument (the second token) +as an expression, and if that expression is true, it evaluates its +second argument (the third token) as a TH1 script. +If the expression is false and the third argument is `else`, then +the fourth argument is evaluated as a TH1 expression. + +So, you see, even though the example above spans five lines, it is really +just a single command. + +All of this also explains the emphasis on *unescaped* characters above: +the curly braces `{ }` are string quoting characters in Tcl/TH1, not +block delimiters as in C. This is how we can have a command that extends +over multiple lines. It is also why the `else` keyword must be cuddled +up with the closing brace for the `if` clause's scriptlet. The following +is invalid Tcl/TH1: + + if {$current eq "dev"} { + puts "hello" + } + else { + puts "world" + } + +If you try to run this under either Tcl or TH1, the interpreter will +tell you that there is no `else` command, because with the newline on +the third line, you terminated the `if` command. + +Occasionally in Tcl/TH1 scripts, you may need to use a backslash at the +end of a line to allow a command to extend over multiple lines without +being considered two separate commands. Here's an example from one of +Fossil's test scripts: + + return [lindex [regexp -line -inline -nocase -- \ + {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ + $repository "" info trunk]]] end] + +Those backslashes allow the command to wrap nicely within a standard +terminal width while telling the interpreter to consider those three +lines as a single command. + +<a id="taint"></a>Tainted And Untainted Strings +----------------------------------------------- + +Beginning with Fossil version 2.26 (circa 2025), TH1 distinguishes between +"tainted" and "untainted" strings. Tainted strings are strings that are +derived from user inputs that might contain text that is designed to subvert +the script. Untainted strings are known to come from secure sources and +are assumed to contain no malicious content. + +Beginning with Fossil version 2.26, and depending on the value of the +[vuln-report setting](/help/vuln-report), TH1 will prevent tainted +strings from being used in ways that might lead to XSS or SQL-injection +attacks. This feature helps to ensure that XSS and SQL-injection +vulnerabilities are not *accidentally* added to Fossil when +custom TH1 scripts for headers or footers or tickets are added to a +repository. Note that the tainted/untainted distinction in strings does +not make it impossible to introduce XSS and SQL-injections vulnerabilities +using poorly-written TH1 scripts; it just makes it more difficult and +less likely to happen by accident. Developers must still consider the +security implications of TH1 customizations they add to Fossil, and take +appropriate precautions when writing custom TH1. Peer review of TH1 +script changes is encouraged. + +In Fossil version 2.26, if the vuln-report setting is set to "block" +or "fatal", the [html](#html) and [query](#query) TH1 commands will +fail with an error if their argument is a tainted string. This helps +to prevent XSS and SQL-injection attacks, respectively. Note that +the default value of the vuln-report setting is "log", which allows those +commands to continue working and only writes a warning message into the +error log. <b>Future versions of Fossil may change the default value +of the vuln-report setting to "block" or "fatal".</b> Fossil users +with customized TH1 scripts are encouraged to audit their customizations +and fix any potential vulnerabilities soon, so as to avoid breakage +caused by future upgrades. <b>Future versions of Fossil might also +place additional restrictions on the use of tainted strings.</b> +For example, it is likely that future versions of Fossil will disallow +using tainted strings as script, for example as the body of a "for" +loop or of a "proc". + + +Summary of Core TH1 Commands +---------------------------- + +The original Tcl language (after which TH1 is modeled) has a very rich +repertoire of commands. TH1, as it is designed to be minimalist and +embedded has a greatly reduced command set. The following bullets +summarize the commands available in TH1: + + * array exists VARNAME + * array names VARNAME + * break + * catch SCRIPT ?VARIABLE? + * continue + * error ?STRING? + * expr EXPR + * for INIT-SCRIPT TEST-EXPR NEXT-SCRIPT BODY-SCRIPT + * foreach VARIABLE-LIST VALUE-LIST BODY-SCRIPT + * if EXPR SCRIPT (elseif EXPR SCRIPT)* ?else SCRIPT? + * info commands + * info exists VARNAME + * info vars + * lappend VARIABLE TERM ... + * lindex LIST INDEX + * list ARG ... + * llength LIST + * lsearch LIST STRING + * proc NAME ARG-LIST BODY-SCRIPT + * rename OLD NEW + * return ?-code CODE? ?VALUE? + * set VARNAME VALUE + * string compare STR1 STR2 + * string first NEEDLE HAYSTACK ?START-INDEX? + * string index STRING INDEX + * string is CLASS STRING + * string last NEEDLE HAYSTACK ?START-INDEX? + * string match PATTERN STRING + * string length STRING + * string range STRING FIRST LAST + * string repeat STRING COUNT + * string trim STRING + * string trimleft STRING + * string trimright STRING + * unset VARNAME + * uplevel ?LEVEL? SCRIPT + * upvar ?FRAME? OTHERVAR MYVAR ?OTHERVAR MYVAR? + +All of the above commands work as in the original Tcl. Refer to the +<a href="https://www.tcl-lang.org/man/tcl/contents.htm">Tcl documentation</a> +for details. + +Summary of Core TH1 Variables +----------------------------- + + * tcl\_platform(engine) -- _This will always have the value "TH1"._ + * tcl\_platform(platform) -- _This will have the value "windows" or "unix"._ + * th\_stack\_trace -- _This will contain error stack information._ + +TH1 Extended Commands +--------------------- + +There are many new commands added to TH1 and used to access the special +features of Fossil. The following is a summary of the extended commands: + + * [anoncap](#anoncap) + * [anycap](#anycap) + * [artifact](#artifact) + * [builtin_request_js](#bireqjs) + * [capexpr](#capexpr) + * [captureTh1](#captureTh1) + * [cgiHeaderLine](#cgiHeaderLine) + * [checkout](#checkout) + * [combobox](#combobox) + * [copybtn](#copybtn) + * [date](#date) + * [decorate](#decorate) + * [defHeader](#defHeader) + * [dir](#dir) + * [enable\_output](#enable_output) + * [encode64](#encode64) + * [getParameter](#getParameter) + * [glob\_match](#glob_match) + * [globalState](#globalState) + * [hascap](#hascap) + * [hasfeature](#hasfeature) + * [html](#html) + * [htmlize](#htmlize) + * [http](#http) + * [httpize](#httpize) + * [insertCsrf](#insertCsrf) + * [linecount](#linecount) + * [markdown](#markdown) + * [nonce](#nonce) + * [puts](#puts) + * [query](#query) + * [randhex](#randhex) + * [redirect](#redirect) + * [regexp](#regexp) + * [reinitialize](#reinitialize) + * [render](#render) + * [repository](#repository) + * [searchable](#searchable) + * [setParameter](#setParameter) + * [setting](#setting) + * [stime](#stime) + * [styleHeader](#styleHeader) + * [styleFooter](#styleFooter) + * [styleScript](#styleScript) + * [submenu](#submenu) + * [taint](#taintCmd) + * [tclEval](#tclEval) + * [tclExpr](#tclExpr) + * [tclInvoke](#tclInvoke) + * [tclIsSafe](#tclIsSafe) + * [tclMakeSafe](#tclMakeSafe) + * [tclReady](#tclReady) + * [trace](#trace) + * [untaint](#untaintCmd) + * [unversioned content](#unversioned_content) + * [unversioned list](#unversioned_list) + * [utime](#utime) + * [verifyCsrf](#verifyCsrf) + * [verifyLogin](#verifyLogin) + * [wiki](#wiki) + * [wiki_assoc](#wiki_assoc) + +Each of the commands above is documented by a block comment above their +implementation in the th\_main.c or th\_tcl.c source files. + +All commands starting with "tcl", with the exception of "tclReady", +require the Tcl integration subsystem be included at compile-time. +Additionally, the "tcl" repository setting must be enabled at runtime +in order to successfully make use of these commands. + +<a id="anoncap"></a>TH1 anoncap Command +----------------------------------------- + +Deprecated: prefer [capexpr](#capexpr) instead. + + * anoncap STRING... + +Returns true if the anonymous user has all of the capabilities listed +in STRING. + +<a id="anycap"></a>TH1 anycap Command +--------------------------------------- + +Deprecated: prefer [capexpr](#capexpr) instead. + + * anycap STRING + +Returns true if the current user user has any one of the capabilities +listed in STRING. + +<a id="artifact"></a>TH1 artifact Command +------------------------------------------- + + * artifact ID ?FILENAME? + +Attempts to locate the specified artifact and return its contents. An +error is generated if the repository is not open or the artifact cannot +be found. + + +<a id="bireqjs"></a>TH1 builtin_request_js Command +-------------------------------------------------- + + * builtin_request_js NAME + +NAME must be the name of one of the +[built-in javascript source files](/dir?ci=trunk&type=flat&name=src&re=js$). +This command causes that javascript file to be appended to the delivered +document. + + + +<a id="capexpr"></a>TH1 capexpr Command +----------------------------------------------------- + + * capexpr CAPABILITY-EXPR + +The capability expression is a list. Each term of the list is a +cluster of [capability letters](./caps/ref.html). +The overall expression is true if any +one term is true. A single term is true if all letters within that +term are true. Or, if the term begins with "!", then the term is true +if none of the terms are true. Or, if the term begins with "@" then +the term is true if all of the capability letters in that term are +available to the "anonymous" user. Or, if the term is "*" then it is +always true. + +Examples: + +``` +capexpr {j o r} True if any one of j, o, or r are available +capexpr {oh} True if both o and h are available +capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of + 4, 5 or 6 is available for the user +capexpr L True if the user is logged in +capexpr !L True if the user is not logged in +``` + +The `L` pseudo-capability is intended only to be used on its own or with +the `!` prefix for implementing login/logout menus via the `mainmenu` +site configuration option: + +``` +Login /login !L {} +Logout /logout L {} +``` + +i.e. if the user is logged in, show the "Logout" link, else show the +"Login" link. + +<a id="captureTh1"></a>TH1 captureTh1 Command +----------------------------------------------------- + + * captureTh1 STRING + +Executes its single argument as TH1 code and captures any +TH1-generated output as a string, which becomes the result of the +function call. e.g. any `puts` calls made from that block will not +generate any output, and instead their output will become part of the +result string. + + +<a id="cgiHeaderLine"></a>TH1 cgiHeaderLine Command +----------------------------------------------------- + + * cgiHeaderLine line + +Adds the specified line to the CGI header. + +<a id="checkout"></a>TH1 checkout Command +------------------------------------------- + + * checkout ?BOOLEAN? + +Return the fully qualified directory name of the current checkout or an +empty string if it is not available. Optionally, it will attempt to find +the current checkout, opening the configuration ("user") database and the +repository as necessary, if the boolean argument is non-zero. + +<a id="combobox"></a>TH1 combobox Command +------------------------------------------- + + * combobox NAME TEXT-LIST NUMLINES + +Generates and emits an HTML combobox. NAME is both the name of the +CGI parameter and the name of a variable that contains the currently +selected value. TEXT-LIST is a list of possible values for the +combobox. NUMLINES is 1 for a true combobox. If NUMLINES is greater +than one then the display is a listbox with the number of lines given. + +<a id="copybtn"></a>TH1 copybtn Command +----------------------------------------- + + * copybtn TARGETID FLIPPED TEXT ?COPYLENGTH? + +Output TEXT with a click-to-copy button next to it. Loads the copybtn.js +Javascript module, and generates HTML elements with the following IDs: + + * TARGETID: The `<span>` wrapper around TEXT. + * copy-TARGETID: The `<span>` for the copy button. + +If the FLIPPED argument is non-zero, the copy button is displayed after TEXT. + +The optional COPYLENGTH argument defines the length of the substring of TEXT +copied to clipboard: + + * <= 0: No limit (default if the argument is omitted). + * >= 3: Truncate TEXT after COPYLENGTH (single-byte) characters. + * 1: Use the "hash-digits" setting as the limit. + * 2: Use the length appropriate for URLs as the limit (defined at + compile-time by `FOSSIL_HASH_DIGITS_URL`, defaults to 16). + +<a id="date"></a>TH1 date Command +----------------------------------- + + * date ?-local? + +Return a string which is the current time and date. If the -local +option is used, the date appears using localtime instead of UTC. + +<a id="decorate"></a>TH1 decorate Command +------------------------------------------- + + * decorate STRING + +Renders STRING as wiki content; however, only links are handled. No +other markup is processed. + +<a id="defHeader"></a>TH1 defHeader Command +--------------------------------------------- + + * defHeader + +Returns the default page header. + +<a id="dir"></a>TH1 dir Command +--------------------------------- + + * dir CHECKIN ?GLOB? ?DETAILS? + +Returns a list containing all files in CHECKIN. If GLOB is given only +the files matching the pattern GLOB within CHECKIN will be returned. +If DETAILS is non-zero, the result will be a list-of-lists, with each +element containing at least three elements: the file name, the file +size (in bytes), and the file last modification time (relative to the +time zone configured for the repository). + +<a id="enable_output"></a>TH1 enable\_output Command +------------------------------------------------------ + + * enable\_output BOOLEAN + +Enable or disable sending output when the combobox, copybtn, puts, or wiki +commands are used. + +<a id="encode64"></a>TH1 encode64 Command +------------------------------------------- + + * encode64 STRING + +Encode the specified string using Base64 and return the result. + +<a id="getParameter"></a>TH1 getParameter Command +--------------------------------------------------- + + * getParameter NAME ?DEFAULT? + +Returns the value of the specified query parameter or the specified +default value when there is no matching query parameter. + +<a id="glob_match"></a>TH1 glob\_match Command +------------------------------------------------ + + * glob\_match ?-one? ?--? patternList string + +Checks the string against the specified glob pattern -OR- list of glob +patterns and returns non-zero if there is a match. + +<a id="globalState"></a>TH1 globalState Command +------------------------------------------------- + + * globalState NAME ?DEFAULT? + +Returns a string containing the value of the specified global state +variable -OR- the specified default value. The supported items are: + + 1. **checkout** -- _Active local checkout directory, if any._ + 1. **configuration** -- _Active configuration database file name, if any._ + 1. **executable** -- _Fully qualified executable file name._ + 1. **flags** -- _TH1 initialization flags._ + 1. **log** -- _Error log file name, if any._ + 1. **repository** -- _Active local repository file name, if any._ + 1. **top** -- _Base path for the active server instance, if applicable._ + 1. **user** -- _Active user name, if any._ + 1. **vfs** -- _SQLite VFS in use, if overridden._ + +Attempts to query for unsupported global state variables will result +in a script error. Additional global state variables may be exposed +in the future. + +<a id="hascap"></a>TH1 hascap Command +--------------------------------------- + +Deprecated: prefer [capexpr](#capexpr) instead. + + * hascap STRING... + +Returns true if the current user has all of the capabilities listed +in STRING. + +<a id="hasfeature"></a>TH1 hasfeature Command +----------------------------------------------- + + * hasfeature STRING + +Returns true if the binary has the given compile-time feature enabled. +The possible features are: + + 1. **ssl** -- _Support for the HTTPS transport._ + 1. **legacyMvRm** -- _Support for legacy mv/rm command behavior._ + 1. **execRelPaths** -- _Use relative paths with external diff/gdiff._ + 1. **th1Docs** -- _Support for TH1 in embedded documentation._ + 1. **th1Hooks** -- _Support for TH1 command and web page hooks._ + 1. **tcl** -- _Support for Tcl integration._ + 1. **useTclStubs** -- _Tcl stubs enabled in the Tcl headers._ + 1. **tclStubs** -- _Uses Tcl stubs (i.e. linking with stubs library)._ + 1. **tclPrivateStubs** -- _Uses Tcl private stubs (i.e. header-only)._ + 1. **json** -- _Support for the JSON APIs._ + 1. **markdown** -- _Support for Markdown documentation format._ + 1. **unicodeCmdLine** -- _The command line arguments are Unicode._ + 1. **dynamicBuild** -- _Dynamically linked to libraries._ + 1. **mman** -- _Uses POSIX memory APIs from "sys/mman.h"._ + 1. **see** -- _Uses the SQLite Encryption Extension._ + +Specifying an unknown feature will return a value of false, it will not +raise a script error. + +<a id="html"></a>TH1 html Command +----------------------------------- + + * html STRING + +Outputs the STRING literally. It is assumed that STRING contains +valid HTML, or that if STRING contains any characters that are +significant to HTML (such as `<`, `>`, `'`, or `&`) have already +been escaped, perhaps by the [htmlize](#htmlize) command. Use the +[puts](#puts) command to output text that might contain unescaped +HTML markup. + +**Beware of XSS attacks!** If the STRING value to the html command +can be controlled by a hostile user, then he might be able to sneak +in malicious HTML or Javascript which could result in a +cross-site scripting (XSS) attack. Be careful that all text that +in STRING that might come from user input has been sanitized by the +[htmlize](#htmlize) command or similar. In recent versions of Fossil, +the STRING value must be [untainted](#taint) or else the "html" command +will fail. + +<a id="htmlize"></a>TH1 htmlize Command +----------------------------------------- + + * htmlize STRING + +Escape all characters of STRING which have special meaning in HTML. +Returns the escaped string. + +<a id="http"></a>TH1 http Command +----------------------------------- + + * http ?-asynchronous? ?--? url ?payload? + +Performs an HTTP or HTTPS request for the specified URL. If a +payload is present, it will be interpreted as text/plain and +the POST method will be used; otherwise, the GET method will +be used. Upon success, if the -asynchronous option is used, an +empty string is returned as the result; otherwise, the response +from the server is returned as the result. Synchronous requests +are not currently implemented. + +<a id="httpize"></a>TH1 httpize Command +----------------------------------------- + + * httpize STRING + +Escape all characters of STRING which have special meaning in URI +components. Returns the escaped string. + +<a id="insertCsrf"></a>TH1 insertCsrf Command +----------------------------------------------- + + * insertCsrf + +While rendering a form, call this command to add the Anti-CSRF token +as a hidden element of the form. + +<a id="linecount"></a>TH1 linecount Command +--------------------------------------------- + + * linecount STRING MAX MIN + +Returns one more than the number of `\n` characters in STRING. But +never returns less than MIN or more than MAX. + +<a id="markdown"></a>TH1 markdown Command +------------------------------------------- + + * markdown STRING + +Renders the input string as markdown. The result is a two-element list. +The first element contains the body, rendered as HTML. The second element +is the text-only title string. + +<a id="nonce"></a>TH1 nonce Command +------------------------------------- + + * nonce + +Returns the value of the cryptographic nonce for the request being processed. + +<a id="puts"></a>TH1 puts Command +----------------------------------- + + * puts STRING + +Outputs STRING. Characters within STRING that have special meaning +in HTML are escaped prior to being output. Thus is it safe for STRING +to be derived from user inputs. See also the [html](#html) command +which behaves similarly except does not escape HTML markup. This +command ("puts") is safe to use on [tainted strings](#taint), but the "html" +command is not. + +<a id="query"></a>TH1 query Command +------------------------------------- + + * query ?-nocomplain? SQL CODE + +Runs the SQL query given by the SQL argument. For each row in the result +set, run CODE. + +In SQL, parameters such as $var are filled in using the value of variable +"var". Result values are stored in variables with the column name prior +to each invocation of CODE. The names of the variables in which results +are stored can be controlled using "AS name" clauses in the SQL. As +the database will often contain content that originates from untrusted +users, all result values are marked as [tainted](#taint). + +**Beware of SQL injections in the `query` command!** +The SQL argument to the query command should always be literal SQL +text enclosed in {...}. The SQL argument should never be a double-quoted +string or the value of a \$variable, as those constructs can lead to +an SQL Injection attack. If you need to include the values of one or +more TH1 variables as part of the SQL, then put \$variable inside the +{...}. The \$variable keyword will then get passed down into the SQLite +parser which knows to look up the value of \$variable in the TH1 symbol +table. For example: + +~~~ + query {SELECT res FROM tab1 WHERE key=$mykey} {...} +~~~ + +SQLite will see the \$mykey token in the SQL and will know to resolve it +to the value of the "mykey" TH1 variable, safely and without the possibility +of SQL injection. The following is unsafe: + +~~~ + query "SELECT res FROM tab1 WHERE key='$mykey'" {...} ;# <-- UNSAFE! +~~~ + +In this second example, TH1 does the expansion of `$mykey` prior to passing +the text down into SQLite. So if `$mykey` contains a single-quote character, +followed by additional hostile text, that will result in an SQL injection. + +To help guard against SQL-injections, recent versions of Fossil require +that the SQL argument be [untainted](#taint) or else the "query" command +will fail. + +<a id="randhex"></a>TH1 randhex Command +----------------------------------------- + + * randhex N + +Returns a string of N*2 random hexadecimal digits with N<50. If N is +omitted, use a value of 10. + +<a id="redirect"></a>TH1 redirect Command +------------------------------------------- + + * redirect URL ?withMethod? + +Issues an HTTP redirect to the specified URL and then exits the process. +By default, an HTTP status code of 302 is used. If the optional withMethod +argument is present and non-zero, an HTTP status code of 307 is used, which +should force the user agent to preserve the original method for the request +(e.g. GET, POST) instead of (possibly) forcing the user agent to change the +method to GET. + +<a id="regexp"></a>TH1 regexp Command +--------------------------------------- + + * regexp ?-nocase? ?--? exp string + +Checks the string against the specified regular expression and returns +non-zero if it matches. If the regular expression is invalid or cannot +be compiled, an error will be generated. + +See [fossil grep](./grep.md) for details on the regexp syntax. + +<a id="reinitialize"></a>TH1 reinitialize Command +--------------------------------------------------- + + * reinitialize ?FLAGS? + +Reinitializes the TH1 interpreter using the specified flags. + +<a id="render"></a>TH1 render Command +--------------------------------------- + + * render STRING + +Renders the TH1 template and writes the results. + +<a id="repository"></a>TH1 repository Command +----------------------------------------------- + + * repository ?BOOLEAN? + +Returns the fully qualified file name of the open repository or an empty +string if one is not currently open. Optionally, it will attempt to open +the repository if the boolean argument is non-zero. + +<a id="searchable"></a>TH1 searchable Command +----------------------------------------------- + + * searchable STRING... + +Return true if searching in any of the document classes identified +by STRING is enabled for the repository and user has the necessary +capabilities to perform the search. The possible document classes +are: + + 1. **c** -- _Check-in comments_ + 1. **d** -- _Embedded documentation_ + 1. **t** -- _Tickets_ + 1. **w** -- _Wiki_ + +To be clear, only one of the document classes identified by each STRING +needs to be searchable in order for that argument to be true. But all +arguments must be true for this routine to return true. Hence, to see +if ALL document classes are searchable: + + if {[searchable c d t w]} {...} + +But to see if ANY document class is searchable: + + if {[searchable cdtw]} {...} + +This command is useful for enabling or disabling a "Search" entry on the +menu bar. + +<a id="setParameter"></a>TH1 setParameter Command +--------------------------------------------------- + + * setParameter NAME VALUE + +Sets the value of the specified query parameter. + +<a id="setting"></a>TH1 setting Command +----------------------------------------- + + * setting name + +Gets and returns the value of the specified setting. + +<a id="stime"></a>TH1 stime Command +------------------------------------- + + * stime + +Returns the number of microseconds of CPU time consumed by the current +process in system space. + +<a id="styleHeader"></a>TH1 styleHeader Command +------------------------------------------------- + + * styleHeader TITLE + +Render the configured style header for the selected skin. + +<a id="styleFooter"></a>TH1 styleFooter Command +------------------------------------------------- + + * styleFooter + +Render the configured style footer for the selected skin. + +<a id="styleScript"></a>TH1 styleScript Command +------------------------------------------------- + + * styleScript + +Render the configured JavaScript for the selected skin. + +<a id="submenu"></a>TH1 submenu Command +----------------------------------------- + + * submenu link LABEL URL + +Add hyperlink to the submenu of the current page. + +<a id="taintCmd"></a>TH1 taint Command +----------------------------------------- + + * taint STRING + +This command returns a copy of STRING that has been marked as +[tainted](#taint). Tainted strings are strings which might be +controlled by an attacker and might contain hostile inputs and +are thus unsafe to use in certain contexts. For example, tainted +strings should not be output as part of a webpage as they might +contain rogue HTML or Javascript that could lead to an XSS +vulnerability. Similarly, tainted strings should not be run as +SQL since they might contain an SQL-injection vulerability. + +<a id="tclEval"></a>TH1 tclEval Command +----------------------------------------- + +**This command requires the Tcl integration feature.** + + * tclEval arg ?arg ...? + +Evaluates the Tcl script and returns its result verbatim. If a Tcl script +error is generated, it will be transformed into a TH1 script error. The +Tcl interpreter will be created automatically if it has not been already. + +<a id="tclExpr"></a>TH1 tclExpr Command +----------------------------------------- + +**This command requires the Tcl integration feature.** + + * tclExpr arg ?arg ...? + +Evaluates the Tcl expression and returns its result verbatim. If a Tcl +script error is generated, it will be transformed into a TH1 script +error. The Tcl interpreter will be created automatically if it has not +been already. + +<a id="tclInvoke"></a>TH1 tclInvoke Command +--------------------------------------------- + +**This command requires the Tcl integration feature.** + + * tclInvoke command ?arg ...? + +Invokes the Tcl command using the supplied arguments. No additional +substitutions are performed on the arguments. The Tcl interpreter +will be created automatically if it has not been already. + +<a id="tclIsSafe"></a>TH1 tclIsSafe Command +--------------------------------------------- + +**This command requires the Tcl integration feature.** + + * tclIsSafe + +Returns non-zero if the Tcl interpreter is "safe". The Tcl interpreter +will be created automatically if it has not been already. + +<a id="tclMakeSafe"></a>TH1 tclMakeSafe Command +------------------------------------------------- + +**This command requires the Tcl integration feature.** + + * tclMakeSafe + +Forces the Tcl interpreter into "safe" mode by removing all "unsafe" +commands and variables. This operation cannot be undone. The Tcl +interpreter will remain "safe" until the process terminates. The Tcl +interpreter will be created automatically if it has not been already. + +<a id="tclReady"></a>TH1 tclReady Command +------------------------------------------- + + * tclReady + +Returns true if the binary has the Tcl integration feature enabled and it +is currently available for use by TH1 scripts. + +<a id="trace"></a>TH1 trace Command +------------------------------------- + + * trace STRING + +Generates a TH1 trace message if TH1 tracing is enabled. + +<a id="untaintCmd"></a>TH1 untaint Command +------------------------------------------ + + * untaint STRING + +This command returns a copy of STRING that has been marked as +[untainted](#taint). Untainted strings are strings which are +believed to be free of potentially hostile content. Use this +command with caution, as it overwrites the tainted-string protection +mechanisms that are built into TH1. If you do not understand all +the implications of executing this command, then do not use it. + +<a id="unversioned_content"></a>TH1 unversioned content Command +----------------------------------------------------------------- + + * unversioned content FILENAME + +Attempts to locate the specified unversioned file and return its contents. +An error is generated if the repository is not open or the unversioned file +cannot be found. + +<a id="unversioned_list"></a>TH1 unversioned list Command +----------------------------------------------------------- + + * unversioned list + +Returns a list of the names of all unversioned files held in the local +repository. An error is generated if the repository is not open. + +<a id="utime"></a>TH1 utime Command +------------------------------------- + + * utime + +Returns the number of microseconds of CPU time consumed by the current +process in user space. + +<a id="verifyCsrf"></a>TH1 verifyCsrf Command +----------------------------------------------- + + * verifyCsrf + +Before using the results of a form, first call this command to verify +that the Anti-CSRF token is present and is valid. If the Anti-CSRF token +is missing or is incorrect, that indicates a cross-site scripting attack. +If the event of an attack is detected, an error message is generated and +all further processing is aborted. + +<a id="verifyLogin"></a>TH1 verifyLogin Command +------------------------------------------------- + + * verifyLogin + +Returns non-zero if the specified user name and password represent a +valid login for the repository. + +<a id="wiki"></a>TH1 wiki Command +----------------------------------- + + * wiki STRING + +Renders STRING as wiki content. + +<a id="wiki_assoc"></a>TH1 wiki_assoc Command +----------------------------------- + + * wiki_assoc STRING STRING + +Renders the special wiki. The first string refers to the namespace +(checkin, branch, tag, ticket). The second string specifies the +concrete wiki page to be rendered. + +Tcl Integration Commands +------------------------ + +When the Tcl integration subsystem is enabled, several commands are added +to the Tcl interpreter. They are used to allow Tcl scripts access to the +Fossil functionality provided via TH1. The following is a summary of the +Tcl commands: + + * th1Eval + * th1Expr + +<a id="th1Eval"></a>Tcl th1Eval Command +----------------------------------------- + +**This command requires the Tcl integration feature.** + + * th1Eval arg + +Evaluates the TH1 script and returns its result verbatim. If a TH1 script +error is generated, it will be transformed into a Tcl script error. + +<a id="th1Expr"></a>Tcl th1Expr Command +----------------------------------------- + +**This command requires the Tcl integration feature.** + + * th1Expr arg + +Evaluates the TH1 expression and returns its result verbatim. If a TH1 +script error is generated, it will be transformed into a Tcl script error. |