TH1 extension functions

Fossil comes with a neat but lightweigh 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.

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 query 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::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.