TH1 extension functions

Fossil comes with a neat but limited TCL-like language. It can be utilized for other things, but in the GitHub or Stackoverflow themes it's used for pretty interfaces.

The features/*.th1 collections provide a few basic extensions.

• basic.th1 implements some control structures, foreach, switch and while, or aliases ++, eq, isset and ?:
• github.th1 is used by the github template. It's too large to be crammed into the header.
• hooks.th1 provides a few TH1-Hooks like /changelog, /cat and /uri-list
• sql.th1 a few convenience functions for checking file/dir or wiki page existence.
• str.th1 adds some string functions.

Control structures (basic.th1)

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."
     }
 }

String functions (str.th1)

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

Database functions (sql.th1)

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. Because the new prepared statements query API is not yet in Fossil mainline, we have to resort to escaping or whitelisting in this case. 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.

User interface / template code (github.th1)

• ui::search is invoked by ui::search_on_wiki for non-existent wiki pages. It then scans the 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 percentages.

• ui::last_commit outputs two table rows, used by the 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.