D 2015-02-09T02:01:40.488
L th1x
N text/x-markdown
P 7c7383b1ec035b524f81e48cd1251af72bbe5c27
U mario
W 3767
<h3> TH1 extension functions </h3>
Fossil comes with a neat but limited TCL-like language. It can be utilized for other things, but in the [GitHub](wiki/GitHub) or [Stackoverflow](wiki/Stackoverflow) themes it's used for pretty interfaces.
The [features/*.th1](wiki/features) collections provide a few basic extensions.
* <kbd>basic.th1</kbd> implements some control structures, `foreach`, `switch` and `while`, or aliases `++`, `eq`, `isset` and `?:`
* <kbd>github.th1</kbd> is used by the github template. It's too large to be crammed into the header.
* <kbd>hooks.th1</kbd> provides a few [TH1-Hooks](wiki/TH1-Hooks) like `/changelog`, `/cat` and `/uri-list`
* <kbd>sql.th1</kbd> a few convenience functions for checking file/dir or wiki page existence.
* <kbd>str.th1</kbd> adds some string functions.
<h3> Control structures (basic.th1) </h3>
Increment a variable
++ varname
Shorthand if-else:
?: {$x<5} "true" {puts "false"}
Shorthand info exists
isset varname
While-loop
while {$x < 7} {
++ x
}
Foreach over lists
set list "aa bb cc dd ee"
foreach var $list {
puts $var
}
And a switch statement:
switch $x {
{1} {
puts "value was 1."
}
{zzz} {
puts "Sleepy value."
}
{{default}} {
puts "Something else."
}
}
<h3> String functions (str.th1) </h3>
Shorthand string search (returns either just 1 or 0):
str::contains "/" "dirname/filename"
Return substring position after startindex (the TH1 builtin string first function doesn't yet do that, contrary to its documentation).
str::next "/" "http://example.org/this" 10
Wrap HTML tags around search terms in a string:
str::wrap $html "findme" "<b>" "</b>"
Get directory name from path
str::dirname "/etc/passwd" # returns just /etc
<h3> Database functions (sql.th1) </h3>
To further simplify some of the template features, some basic database functions are included. They're all `sql::` prefixed:
* `sql::allowed $str` tests for whitelisted characters. <s>Because the new prepared statements query API is not yet in Fossil mainline, we have to resort to escaping or whitelisting in this case</s>. Actually, Fossils TH1 automatically binds literal `$varnames` as parameters. Either enclose the query in unparsed `{..}` curly braces, or escape `\$varnames` to be parameterized. (So this function is redundant now.)
* `sql::page_exists $Wiki` tests for existence of a wiki page.
* `sql::file_exists $pathname` tests if the filename exists in the repository (must include complete path).
* While `sql::find_file $basename` allows a file to be located anywhere in the directory tree, and then returns its complete path.
<h3> User interface / template code (github.th1) </h3>
* `ui::search` is invoked by `ui::search_on_wiki` for non-existent wiki pages. It then scans the [fx_search](wiki/fx_search) table for given words, and outputs a link summary.
* `ui::stats` returns some variables: $stats_checkins, $stats_files, $stats_tickets, $stats_branches, $stats_developers, $stats_tags, , $stats_releases
* `u::lang_stats` outputs the language bar from [fx_stats](wiki/fx_stats) percentages.
* `ui::last_commit` outputs two table rows, used by the [GitHub](wiki/GitHub) template file box.
* `ui::recent_files ""` outputs table rows containing the top-level filenames and subdirectories. If a subdirectory name is passed, it will constrain the output to thats contents.
* `ui::social_links $baseurl` outputs facebook/google+/reddit/twitter/etc. links.
Z 24cf1bfb5fdc65ca85e6544094fa508c