1TH1 Scripts 2=========== 3 4TH1 is a very small scripting language used to help generate web-page 5content in Fossil. 6 7Origins 8------- 9 10TH1 began as a minimalist re-implementation of the Tcl scripting language. 11There was a need to test the SQLite library on Symbian phones, but at that 12time all of the test cases for SQLite were written in Tcl and Tcl could not 13be easily compiled on the SymbianOS. So TH1 was developed as a cut-down 14version of Tcl that would facilitate running the SQLite test scripts on 15SymbianOS. 16 17Fossil was first being designed at about the same time that TH1 was 18being developed for testing SQLite on SymbianOS. 19Early prototypes of Fossil were written in pure Tcl. But as the development 20shifted toward the use of C-code, the need arose to have a Tcl-like 21scripting language to help with code generation. TH1 was small and 22light-weight and used minimal resources and seemed ideally suited for the 23task. 24 25The name "TH1" stands "Test Harness 1", since that was its original purpose. 26 27Overview 28-------- 29 30TH1 is a string-processing language. All values are strings. Any numerical 31operations are accomplished by converting from string to numeric, performing 32the computation, then converting the result back into a string. (This might 33seem inefficient, but it is faster than people imagine, and numeric 34computations do not come up very often for the kinds of work that TH1 does, 35so it has never been a factor.) 36 37A TH1 script consist of a sequence of commands. 38Each command is terminated by the first *unescaped* newline or ";" character. 39The text of the command (excluding the newline or semicolon terminator) 40is broken into space-separated tokens. The first token is the command 41name and subsequent tokens are the arguments. In this sense, TH1 syntax 42is similar to the familiar command-line shell syntax. 43 44A token is any sequence of characters other than whitespace and semicolons. 45Text inside double-quotes is a single token even if it includes 46whitespace and semicolons. Text within {...} pairs is also a 47single token, which is useful because curly braces are easier to “pair” 48and nest properly than double-quotes. 49 50The nested {...} form of tokens is important because it allows TH1 commands 51to have an appearance similar to C/C++. It is important to remember, though, 52that a TH1 script is really just a list of text commands, not a context-free 53language with a grammar like C/C++. This can be confusing to long-time 54C/C++ programmers because TH1 does look a lot like C/C++, but the semantics 55of TH1 are closer to FORTH or Lisp than they are to C. 56 57Consider the `if` command in TH1. 58 59 if {$current eq "dev"} { 60 puts "hello" 61 } else { 62 puts "world" 63 } 64 65The example above is a single command. The first token, and the name 66of the command, is `if`. 67The second token is `$current eq "dev"` - an expression. (The outer {...} 68are removed from each token by the command parser.) The third token 69is the `puts "hello"`, with its whitespace and newlines. The fourth token 70is `else` and the fifth and last token is `puts "world"`. 71 72The `if` command evaluates its first argument (the second token) 73as an expression, and if that expression is true, evaluates its 74second argument (the third token) as a TH1 script. 75If the expression is false and the third argument is `else`, then 76the fourth argument is evaluated as a TH1 expression. 77 78So, you see, even though the example above spans five lines, it is really 79just a single command. 80 81All of this also explains the emphasis on *unescaped* characters above: 82the curly braces `{ }` are string quoting characters in Tcl/TH1, not 83block delimiters as in C. This is how we can have a command that extends 84over multiple lines. It is also why the `else` keyword must be cuddled 85up with the closing brace for the `if` clause's scriptlet. The following 86is invalid Tcl/TH1: 87 88 if {$current eq "dev"} { 89 puts "hello" 90 } 91 else { 92 puts "world" 93 } 94 95If you try to run this under either Tcl or TH1, the interpreter will 96tell you that there is no `else` command, because with the newline on 97the third line, you terminated the `if` command. 98 99Occasionally in Tcl/TH1 scripts, you may need to use a backslash at the 100end of a line to allow a command to extend over multiple lines without 101being considered two separate commands. Here's an example from one of 102Fossil's test scripts: 103 104 return [lindex [regexp -line -inline -nocase -- \ 105 {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ 106 $repository "" info trunk]]] end] 107 108Those backslashes allow the command to wrap nicely within a standard 109terminal width while telling the interpreter to consider those three 110lines as a single command. 111 112 113Summary of Core TH1 Commands 114---------------------------- 115 116The original Tcl language (after which TH1 is modeled) has a very rich 117repertoire of commands. TH1, as it is designed to be minimalist and 118embedded has a greatly reduced command set. The following bullets 119summarize the commands available in TH1: 120 121 * array exists VARNAME 122 * array names VARNAME 123 * break 124 * catch SCRIPT ?VARIABLE? 125 * continue 126 * error ?STRING? 127 * expr EXPR 128 * for INIT-SCRIPT TEST-EXPR NEXT-SCRIPT BODY-SCRIPT 129 * foreach VARIABLE-LIST VALUE-LIST BODY-SCRIPT 130 * if EXPR SCRIPT (elseif EXPR SCRIPT)* ?else SCRIPT? 131 * info commands 132 * info exists VARNAME 133 * info vars 134 * lappend VARIABLE TERM ... 135 * lindex LIST INDEX 136 * list ARG ... 137 * llength LIST 138 * lsearch LIST STRING 139 * proc NAME ARG-LIST BODY-SCRIPT 140 * rename OLD NEW 141 * return ?-code CODE? ?VALUE? 142 * set VARNAME VALUE 143 * string compare STR1 STR2 144 * string first NEEDLE HAYSTACK ?START-INDEX? 145 * string index STRING INDEX 146 * string is CLASS STRING 147 * string last NEEDLE HAYSTACK ?START-INDEX? 148 * string match PATTERN STRING 149 * string length STRING 150 * string range STRING FIRST LAST 151 * string repeat STRING COUNT 152 * unset VARNAME 153 * uplevel ?LEVEL? SCRIPT 154 * upvar ?FRAME? OTHERVAR MYVAR ?OTHERVAR MYVAR? 155 156All of the above commands work as in the original Tcl. Refer to the 157<a href="https://www.tcl-lang.org/man/tcl/contents.htm">Tcl documentation</a> 158for details. 159 160Summary of Core TH1 Variables 161----------------------------- 162 163 * tcl\_platform(engine) -- _This will always have the value "TH1"._ 164 * tcl\_platform(platform) -- _This will have the value "windows" or "unix"._ 165 * th\_stack\_trace -- _This will contain error stack information._ 166 167TH1 Extended Commands 168--------------------- 169 170There are many new commands added to TH1 and used to access the special 171features of Fossil. The following is a summary of the extended commands: 172 173 * [anoncap](#anoncap) 174 * [anycap](#anycap) 175 * [artifact](#artifact) 176 * [builtin_request_js](#bireqjs) 177 * [capexpr](#capexpr) 178 * [captureTh1](#captureTh1) 179 * [cgiHeaderLine](#cgiHeaderLine) 180 * [checkout](#checkout) 181 * [combobox](#combobox) 182 * [copybtn](#copybtn) 183 * [date](#date) 184 * [decorate](#decorate) 185 * [defHeader](#defHeader) 186 * [dir](#dir) 187 * [enable\_htmlify](#enable_htmlify) 188 * [enable\_output](#enable_output) 189 * [encode64](#encode64) 190 * [getParameter](#getParameter) 191 * [glob\_match](#glob_match) 192 * [globalState](#globalState) 193 * [hascap](#hascap) 194 * [hasfeature](#hasfeature) 195 * [html](#html) 196 * [htmlize](#htmlize) 197 * [http](#http) 198 * [httpize](#httpize) 199 * [insertCsrf](#insertCsrf) 200 * [linecount](#linecount) 201 * [markdown](#markdown) 202 * [nonce](#nonce) 203 * [puts](#puts) 204 * [query](#query) 205 * [randhex](#randhex) 206 * [redirect](#redirect) 207 * [regexp](#regexp) 208 * [reinitialize](#reinitialize) 209 * [render](#render) 210 * [repository](#repository) 211 * [searchable](#searchable) 212 * [setParameter](#setParameter) 213 * [setting](#setting) 214 * [stime](#stime) 215 * [styleHeader](#styleHeader) 216 * [styleFooter](#styleFooter) 217 * [styleScript](#styleScript) 218 * [tclEval](#tclEval) 219 * [tclExpr](#tclExpr) 220 * [tclInvoke](#tclInvoke) 221 * [tclIsSafe](#tclIsSafe) 222 * [tclMakeSafe](#tclMakeSafe) 223 * [tclReady](#tclReady) 224 * [trace](#trace) 225 * [unversioned content](#unversioned_content) 226 * [unversioned list](#unversioned_list) 227 * [utime](#utime) 228 * [verifyCsrf](#verifyCsrf) 229 * [verifyLogin](#verifyLogin) 230 * [wiki](#wiki) 231 232Each of the commands above is documented by a block comment above their 233implementation in the th\_main.c or th\_tcl.c source files. 234 235All commands starting with "tcl", with the exception of "tclReady", 236require the Tcl integration subsystem be included at compile-time. 237Additionally, the "tcl" repository setting must be enabled at runtime 238in order to successfully make use of these commands. 239 240<a id="anoncap"></a>TH1 anoncap Command 241----------------------------------------- 242 243Deprecated: prefer [capexpr](#capexpr) instead. 244 245 * anoncap STRING... 246 247Returns true if the anonymous user has all of the capabilities listed 248in STRING. 249 250<a id="anycap"></a>TH1 anycap Command 251--------------------------------------- 252 253Deprecated: prefer [capexpr](#capexpr) instead. 254 255 * anycap STRING 256 257Returns true if the current user user has any one of the capabilities 258listed in STRING. 259 260<a id="artifact"></a>TH1 artifact Command 261------------------------------------------- 262 263 * artifact ID ?FILENAME? 264 265Attempts to locate the specified artifact and return its contents. An 266error is generated if the repository is not open or the artifact cannot 267be found. 268 269 270<a id="bireqjs"></a>TH1 builtin_request_js Command 271-------------------------------------------------- 272 273 * builtin_request_js NAME 274 275NAME must be the name of one of the 276[built-in javascript source files](/dir?ci=trunk&type=flat&name=src&re=js$). 277This command causes that javascript file to be appended to the delivered 278document. 279 280 281 282<a id="capexpr"></a>TH1 capexpr Command 283----------------------------------------------------- 284 285Added in Fossil 2.15. 286 287 * capexpr CAPABILITY-EXPR 288 289The capability expression is a list. Each term of the list is a 290cluster of [capability letters](./caps/ref.html). 291The overall expression is true if any 292one term is true. A single term is true if all letters within that 293term are true. Or, if the term begins with "!", then the term is true 294if none of the terms or true. Or, if the term begins with "@" then 295the term is true if all of the capability letters in that term are 296available to the "anonymous" user. Or, if the term is "*" then it is 297always true. 298 299Examples: 300 301``` 302 capexpr {j o r} True if any one of j, o, or r are available 303 capexpr {oh} True if both o and h are available 304 capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of 305 4, 5 or 6 is available for the user 306 capexpr L True if the user is logged in 307 capexpr !L True if the user is not logged in 308``` 309 310The `L` pseudo-capability is intended only to be used on its own or with 311the `!` prefix for implementing login/logout menus via the `mainmenu` 312site configuration option: 313 314``` 315Login /login !L {} 316Logout /logout L {} 317``` 318 319i.e. if the user is logged in, show the "Logout" link, else show the 320"Login" link. 321 322<a id="captureTh1"></a>TH1 captureTh1 Command 323----------------------------------------------------- 324 325 * captureTh1 STRING 326 327Executes its single argument as TH1 code and captures any 328TH1-generated output as a string, which becomes the result of the 329function call. e.g. any `puts` calls made from that block will not 330generate any output, and instead their output will become part of the 331result string. 332 333 334<a id="cgiHeaderLine"></a>TH1 cgiHeaderLine Command 335----------------------------------------------------- 336 337 * cgiHeaderLine line 338 339Adds the specified line to the CGI header. 340 341<a id="checkout"></a>TH1 checkout Command 342------------------------------------------- 343 344 * checkout ?BOOLEAN? 345 346Return the fully qualified directory name of the current checkout or an 347empty string if it is not available. Optionally, it will attempt to find 348the current checkout, opening the configuration ("user") database and the 349repository as necessary, if the boolean argument is non-zero. 350 351<a id="combobox"></a>TH1 combobox Command 352------------------------------------------- 353 354 * combobox NAME TEXT-LIST NUMLINES 355 356Generates and emits an HTML combobox. NAME is both the name of the 357CGI parameter and the name of a variable that contains the currently 358selected value. TEXT-LIST is a list of possible values for the 359combobox. NUMLINES is 1 for a true combobox. If NUMLINES is greater 360than one then the display is a listbox with the number of lines given. 361 362<a id="copybtn"></a>TH1 copybtn Command 363----------------------------------------- 364 365 * copybtn TARGETID FLIPPED TEXT ?COPYLENGTH? 366 367Output TEXT with a click-to-copy button next to it. Loads the copybtn.js 368Javascript module, and generates HTML elements with the following IDs: 369 370 * TARGETID: The `<span>` wrapper around TEXT. 371 * copy-TARGETID: The `<span>` for the copy button. 372 373If the FLIPPED argument is non-zero, the copy button is displayed after TEXT. 374 375The optional COPYLENGTH argument defines the length of the substring of TEXT 376copied to clipboard: 377 378 * <= 0: No limit (default if the argument is omitted). 379 * >= 3: Truncate TEXT after COPYLENGTH (single-byte) characters. 380 * 1: Use the "hash-digits" setting as the limit. 381 * 2: Use the length appropriate for URLs as the limit (defined at 382 compile-time by `FOSSIL_HASH_DIGITS_URL`, defaults to 16). 383 384<a id="date"></a>TH1 date Command 385----------------------------------- 386 387 * date ?-local? 388 389Return a strings which is the current time and date. If the -local 390option is used, the date appears using localtime instead of UTC. 391 392<a id="decorate"></a>TH1 decorate Command 393------------------------------------------- 394 395 * decorate STRING 396 397Renders STRING as wiki content; however, only links are handled. No 398other markup is processed. 399 400<a id="defHeader"></a>TH1 defHeader Command 401--------------------------------------------- 402 403 * defHeader 404 405Returns the default page header. 406 407<a id="dir"></a>TH1 dir Command 408--------------------------------- 409 410 * dir CHECKIN ?GLOB? ?DETAILS? 411 412Returns a list containing all files in CHECKIN. If GLOB is given only 413the files matching the pattern GLOB within CHECKIN will be returned. 414If DETAILS is non-zero, the result will be a list-of-lists, with each 415element containing at least three elements: the file name, the file 416size (in bytes), and the file last modification time (relative to the 417time zone configured for the repository). 418 419<a id="enable_htmlify"></a>TH1 enable\_htmlify Command 420------------------------------------------------------ 421 422 * enable\_htmlify 423 * enable\_htmlify ?TRACE-LABEL? BOOLEAN 424 425By default, certain output from `puts` and similar commands is escaped 426for HTML. The first call form returns the current state of that 427feature: `1` for on and `0` for off. The second call form enables 428(non-0) or disables (0) that feature and returns the *pre-call* state 429of that feature (so that a second call can pass that value to restore 430it to its previous state). The optional `TRACE-LABEL` argument causes 431the TH1 tracing output (if enabled) to add a marker when the second 432form of this command is invoked, and includes that label and the 433boolean argument's value in the trace. If tracing is disabled, that 434argument has no effect. 435 436 437<a id="enable_output"></a>TH1 enable\_output Command 438------------------------------------------------------ 439 440 * enable\_output BOOLEAN 441 442Enable or disable sending output when the combobox, copybtn, puts, or wiki 443commands are used. 444 445<a id="encode64"></a>TH1 encode64 Command 446------------------------------------------- 447 448 * encode64 STRING 449 450Encode the specified string using Base64 and return the result. 451 452<a id="getParameter"></a>TH1 getParameter Command 453--------------------------------------------------- 454 455 * getParameter NAME ?DEFAULT? 456 457Returns the value of the specified query parameter or the specified 458default value when there is no matching query parameter. 459 460<a id="glob_match"></a>TH1 glob\_match Command 461------------------------------------------------ 462 463 * glob\_match ?-one? ?--? patternList string 464 465Checks the string against the specified glob pattern -OR- list of glob 466patterns and returns non-zero if there is a match. 467 468<a id="globalState"></a>TH1 globalState Command 469------------------------------------------------- 470 471 * globalState NAME ?DEFAULT? 472 473Returns a string containing the value of the specified global state 474variable -OR- the specified default value. The supported items are: 475 476 1. **checkout** -- _Active local checkout directory, if any._ 477 1. **configuration** -- _Active configuration database file name, if any._ 478 1. **executable** -- _Fully qualified executable file name._ 479 1. **flags** -- _TH1 initialization flags._ 480 1. **log** -- _Error log file name, if any._ 481 1. **repository** -- _Active local repository file name, if any._ 482 1. **top** -- _Base path for the active server instance, if applicable._ 483 1. **user** -- _Active user name, if any._ 484 1. **vfs** -- _SQLite VFS in use, if overridden._ 485 486Attempts to query for unsupported global state variables will result 487in a script error. Additional global state variables may be exposed 488in the future. 489 490<a id="hascap"></a>TH1 hascap Command 491--------------------------------------- 492 493Deprecated: prefer [capexpr](#capexpr) instead. 494 495 * hascap STRING... 496 497Returns true if the current user has all of the capabilities listed 498in STRING. 499 500<a id="hasfeature"></a>TH1 hasfeature Command 501----------------------------------------------- 502 503 * hasfeature STRING 504 505Returns true if the binary has the given compile-time feature enabled. 506The possible features are: 507 508 1. **ssl** -- _Support for the HTTPS transport._ 509 1. **legacyMvRm** -- _Support for legacy mv/rm command behavior._ 510 1. **execRelPaths** -- _Use relative paths with external diff/gdiff._ 511 1. **th1Docs** -- _Support for TH1 in embedded documentation._ 512 1. **th1Hooks** -- _Support for TH1 command and web page hooks._ 513 1. **tcl** -- _Support for Tcl integration._ 514 1. **useTclStubs** -- _Tcl stubs enabled in the Tcl headers._ 515 1. **tclStubs** -- _Uses Tcl stubs (i.e. linking with stubs library)._ 516 1. **tclPrivateStubs** -- _Uses Tcl private stubs (i.e. header-only)._ 517 1. **json** -- _Support for the JSON APIs._ 518 1. **markdown** -- _Support for Markdown documentation format._ 519 1. **unicodeCmdLine** -- _The command line arguments are Unicode._ 520 1. **dynamicBuild** -- _Dynamically linked to libraries._ 521 1. **mman** -- _Uses POSIX memory APIs from "sys/mman.h"._ 522 1. **see** -- _Uses the SQLite Encryption Extension._ 523 524Specifying an unknown feature will return a value of false, it will not 525raise a script error. 526 527<a id="html"></a>TH1 html Command 528----------------------------------- 529 530 * html STRING 531 532Outputs the STRING escaped for HTML. 533 534<a id="htmlize"></a>TH1 htmlize Command 535----------------------------------------- 536 537 * htmlize STRING 538 539Escape all characters of STRING which have special meaning in HTML. 540Returns the escaped string. 541 542<a id="http"></a>TH1 http Command 543----------------------------------- 544 545 * http ?-asynchronous? ?--? url ?payload? 546 547Performs an HTTP or HTTPS request for the specified URL. If a 548payload is present, it will be interpreted as text/plain and 549the POST method will be used; otherwise, the GET method will 550be used. Upon success, if the -asynchronous option is used, an 551empty string is returned as the result; otherwise, the response 552from the server is returned as the result. Synchronous requests 553are not currently implemented. 554 555<a id="httpize"></a>TH1 httpize Command 556----------------------------------------- 557 558 * httpize STRING 559 560Escape all characters of STRING which have special meaning in URI 561components. Returns the escaped string. 562 563<a id="insertCsrf"></a>TH1 insertCsrf Command 564----------------------------------------------- 565 566 * insertCsrf 567 568While rendering a form, call this command to add the Anti-CSRF token 569as a hidden element of the form. 570 571<a id="linecount"></a>TH1 linecount Command 572--------------------------------------------- 573 574 * linecount STRING MAX MIN 575 576Returns one more than the number of \n characters in STRING. But 577never returns less than MIN or more than MAX. 578 579<a id="markdown"></a>TH1 markdown Command 580------------------------------------------- 581 582 * markdown STRING 583 584Renders the input string as markdown. The result is a two-element list. 585The first element contains the body, rendered as HTML. The second element 586is the text-only title string. 587 588<a id="nonce"></a>TH1 nonce Command 589------------------------------------- 590 591 * nonce 592 593Returns the value of the cryptographic nonce for the request being processed. 594 595<a id="puts"></a>TH1 puts Command 596----------------------------------- 597 598 * puts STRING 599 600Outputs the STRING unchanged, where "unchanged" might, depending on 601the context, mean "with some characters escaped for HTML." 602 603<a id="query"></a>TH1 query Command 604------------------------------------- 605 606 * query ?-nocomplain? SQL CODE 607 608Runs the SQL query given by the SQL argument. For each row in the result 609set, run CODE. 610 611In SQL, parameters such as $var are filled in using the value of variable 612"var". Result values are stored in variables with the column name prior 613to each invocation of CODE. 614 615<a id="randhex"></a>TH1 randhex Command 616----------------------------------------- 617 618 * randhex N 619 620Returns a string of N*2 random hexadecimal digits with N<50. If N is 621omitted, use a value of 10. 622 623<a id="redirect"></a>TH1 redirect Command 624------------------------------------------- 625 626 * redirect URL ?withMethod? 627 628Issues an HTTP redirect to the specified URL and then exits the process. 629By default, an HTTP status code of 302 is used. If the optional withMethod 630argument is present and non-zero, an HTTP status code of 307 is used, which 631should force the user agent to preserve the original method for the request 632(e.g. GET, POST) instead of (possibly) forcing the user agent to change the 633method to GET. 634 635<a id="regexp"></a>TH1 regexp Command 636--------------------------------------- 637 638 * regexp ?-nocase? ?--? exp string 639 640Checks the string against the specified regular expression and returns 641non-zero if it matches. If the regular expression is invalid or cannot 642be compiled, an error will be generated. 643 644<a id="reinitialize"></a>TH1 reinitialize Command 645--------------------------------------------------- 646 647 * reinitialize ?FLAGS? 648 649Reinitializes the TH1 interpreter using the specified flags. 650 651<a id="render"></a>TH1 render Command 652--------------------------------------- 653 654 * render STRING 655 656Renders the TH1 template and writes the results. 657 658<a id="repository"></a>TH1 repository Command 659----------------------------------------------- 660 661 * repository ?BOOLEAN? 662 663Returns the fully qualified file name of the open repository or an empty 664string if one is not currently open. Optionally, it will attempt to open 665the repository if the boolean argument is non-zero. 666 667<a id="searchable"></a>TH1 searchable Command 668----------------------------------------------- 669 670 * searchable STRING... 671 672Return true if searching in any of the document classes identified 673by STRING is enabled for the repository and user has the necessary 674capabilities to perform the search. The possible document classes 675are: 676 677 1. **c** -- _Check-in comments_ 678 1. **d** -- _Embedded documentation_ 679 1. **t** -- _Tickets_ 680 1. **w** -- _Wiki_ 681 682To be clear, only one of the document classes identified by each STRING 683needs to be searchable in order for that argument to be true. But all 684arguments must be true for this routine to return true. Hence, to see 685if ALL document classes are searchable: 686 687 if {[searchable c d t w]} {...} 688 689But to see if ANY document class is searchable: 690 691 if {[searchable cdtw]} {...} 692 693This command is useful for enabling or disabling a "Search" entry on the 694menu bar. 695 696<a id="setParameter"></a>TH1 setParameter Command 697--------------------------------------------------- 698 699 * setParameter NAME VALUE 700 701Sets the value of the specified query parameter. 702 703<a id="setting"></a>TH1 setting Command 704----------------------------------------- 705 706 * setting name 707 708Gets and returns the value of the specified setting. 709 710<a id="stime"></a>TH1 stime Command 711------------------------------------- 712 713 * stime 714 715Returns the number of microseconds of CPU time consumed by the current 716process in system space. 717 718<a id="styleHeader"></a>TH1 styleHeader Command 719------------------------------------------------- 720 721 * styleHeader TITLE 722 723Render the configured style header for the selected skin. 724 725<a id="styleFooter"></a>TH1 styleFooter Command 726------------------------------------------------- 727 728 * styleFooter 729 730Render the configured style footer for the selected skin. 731 732<a id="styleScript"></a>TH1 styleScript Command 733------------------------------------------------- 734 735 * styleScript 736 737Render the configured JavaScript for the selected skin. 738 739<a id="tclEval"></a>TH1 tclEval Command 740----------------------------------------- 741 742**This command requires the Tcl integration feature.** 743 744 * tclEval arg ?arg ...? 745 746Evaluates the Tcl script and returns its result verbatim. If a Tcl script 747error is generated, it will be transformed into a TH1 script error. The 748Tcl interpreter will be created automatically if it has not been already. 749 750<a id="tclExpr"></a>TH1 tclExpr Command 751----------------------------------------- 752 753**This command requires the Tcl integration feature.** 754 755 * tclExpr arg ?arg ...? 756 757Evaluates the Tcl expression and returns its result verbatim. If a Tcl 758script error is generated, it will be transformed into a TH1 script 759error. The Tcl interpreter will be created automatically if it has not 760been already. 761 762<a id="tclInvoke"></a>TH1 tclInvoke Command 763--------------------------------------------- 764 765**This command requires the Tcl integration feature.** 766 767 * tclInvoke command ?arg ...? 768 769Invokes the Tcl command using the supplied arguments. No additional 770substitutions are performed on the arguments. The Tcl interpreter 771will be created automatically if it has not been already. 772 773<a id="tclIsSafe"></a>TH1 tclIsSafe Command 774--------------------------------------------- 775 776**This command requires the Tcl integration feature.** 777 778 * tclIsSafe 779 780Returns non-zero if the Tcl interpreter is "safe". The Tcl interpreter 781will be created automatically if it has not been already. 782 783<a id="tclMakeSafe"></a>TH1 tclMakeSafe Command 784------------------------------------------------- 785 786**This command requires the Tcl integration feature.** 787 788 * tclMakeSafe 789 790Forces the Tcl interpreter into "safe" mode by removing all "unsafe" 791commands and variables. This operation cannot be undone. The Tcl 792interpreter will remain "safe" until the process terminates. The Tcl 793interpreter will be created automatically if it has not been already. 794 795<a id="tclReady"></a>TH1 tclReady Command 796------------------------------------------- 797 798 * tclReady 799 800Returns true if the binary has the Tcl integration feature enabled and it 801is currently available for use by TH1 scripts. 802 803<a id="trace"></a>TH1 trace Command 804------------------------------------- 805 806 * trace STRING 807 808Generates a TH1 trace message if TH1 tracing is enabled. 809 810<a id="unversioned_content"></a>TH1 unversioned content Command 811----------------------------------------------------------------- 812 813 * unversioned content FILENAME 814 815Attempts to locate the specified unversioned file and return its contents. 816An error is generated if the repository is not open or the unversioned file 817cannot be found. 818 819<a id="unversioned_list"></a>TH1 unversioned list Command 820----------------------------------------------------------- 821 822 * unversioned list 823 824Returns a list of the names of all unversioned files held in the local 825repository. An error is generated if the repository is not open. 826 827<a id="utime"></a>TH1 utime Command 828------------------------------------- 829 830 * utime 831 832Returns the number of microseconds of CPU time consumed by the current 833process in user space. 834 835<a id="verifyCsrf"></a>TH1 verifyCsrf Command 836----------------------------------------------- 837 838 * verifyCsrf 839 840Before using the results of a form, first call this command to verify 841that this Anti-CSRF token is present and is valid. If the Anti-CSRF token 842is missing or is incorrect, that indicates a cross-site scripting attack. 843If the event of an attack is detected, an error message is generated and 844all further processing is aborted. 845 846<a id="verifyLogin"></a>TH1 verifyLogin Command 847------------------------------------------------- 848 849 * verifyLogin 850 851Returns non-zero if the specified user name and password represent a 852valid login for the repository. 853 854<a id="wiki"></a>TH1 wiki Command 855----------------------------------- 856 857 * wiki STRING 858 859Renders STRING as wiki content. 860 861Tcl Integration Commands 862------------------------ 863 864When the Tcl integration subsystem is enabled, several commands are added 865to the Tcl interpreter. They are used to allow Tcl scripts access to the 866Fossil functionality provided via TH1. The following is a summary of the 867Tcl commands: 868 869 * th1Eval 870 * th1Expr 871 872<a id="th1Eval"></a>Tcl th1Eval Command 873----------------------------------------- 874 875**This command requires the Tcl integration feature.** 876 877 * th1Eval arg 878 879Evaluates the TH1 script and returns its result verbatim. If a TH1 script 880error is generated, it will be transformed into a Tcl script error. 881 882<a id="th1Expr"></a>Tcl th1Expr Command 883----------------------------------------- 884 885**This command requires the Tcl integration feature.** 886 887 * th1Expr arg 888 889Evaluates the TH1 expression and returns its result verbatim. If a TH1 890script error is generated, it will be transformed into a Tcl script error. 891