Fossil SCM

Initial work on documenting all the Fossil specific TH1 commands.

mistachkin 2015-04-05 04:28 trunk
Commit 1e5548ae7cf91d1d4e20ef4efa708990c771fd22
Parent 4aba7584f7568b8…
2 files changed +4 -2 +396 -4
~ src/th_main.c ~ www/th1.md
M src/th_main.c
+4 -2
--- src/th_main.c
+++ src/th_main.c
@@ -174,11 +174,11 @@
174174
 static int enableOutput = 1;
175175
176176
 /*
177177
 ** TH1 command: enable_output BOOLEAN
178178
 **
179
-** Enable or disable the puts and hputs commands.
179
+** Enable or disable the puts and wiki commands.
180180
 */
181181
 static int enableOutputCmd(
182182
 Th_Interp *interp,
183183
 void *p,
184184
 int argc,
@@ -339,13 +339,15 @@
339339
 sendText((char*)argv[1], argl[1], *(unsigned int*)pConvert);
340340
 return TH_OK;
341341
 }
342342
343343
 /*
344
+** TH1 command: decorate STRING
344345
 ** TH1 command: wiki STRING
345346
 **
346
-** Render the input string as wiki.
347
+** Render the input string as wiki. For the decorate command, only links
348
+** are handled.
347349
 */
348350
 static int wikiCmd(
349351
 Th_Interp *interp,
350352
 void *p,
351353
 int argc,
352354
--- src/th_main.c
+++ src/th_main.c
@@ -174,11 +174,11 @@
174 static int enableOutput = 1;
175
176 /*
177 ** TH1 command: enable_output BOOLEAN
178 **
179 ** Enable or disable the puts and hputs commands.
180 */
181 static int enableOutputCmd(
182 Th_Interp *interp,
183 void *p,
184 int argc,
@@ -339,13 +339,15 @@
339 sendText((char*)argv[1], argl[1], *(unsigned int*)pConvert);
340 return TH_OK;
341 }
342
343 /*
 
344 ** TH1 command: wiki STRING
345 **
346 ** Render the input string as wiki.
 
347 */
348 static int wikiCmd(
349 Th_Interp *interp,
350 void *p,
351 int argc,
352
--- src/th_main.c
+++ src/th_main.c
@@ -174,11 +174,11 @@
174 static int enableOutput = 1;
175
176 /*
177 ** TH1 command: enable_output BOOLEAN
178 **
179 ** Enable or disable the puts and wiki commands.
180 */
181 static int enableOutputCmd(
182 Th_Interp *interp,
183 void *p,
184 int argc,
@@ -339,13 +339,15 @@
339 sendText((char*)argv[1], argl[1], *(unsigned int*)pConvert);
340 return TH_OK;
341 }
342
343 /*
344 ** TH1 command: decorate STRING
345 ** TH1 command: wiki STRING
346 **
347 ** Render the input string as wiki. For the decorate command, only links
348 ** are handled.
349 */
350 static int wikiCmd(
351 Th_Interp *interp,
352 void *p,
353 int argc,
354
M www/th1.md
+396 -4
--- www/th1.md
+++ www/th1.md
@@ -13,14 +13,14 @@
1313
 be easily compiled on the SymbianOS. So TH1 was developed as a cut-down
1414
 version of TCL that would facilitate running the SQLite test scripts on
1515
 SymbianOS.
1616
1717
 The testing of SQLite on SymbianOS was eventually accomplished by other
18
-means. But Fossil was first being designed at about the same time.
18
+means. But Fossil was first being designed at about the same time.
1919
 Early prototypes of Fossil were written in pure TCL. But as the development
2020
 shifted toward the use of C-code, the need arose to have a TCL-like
21
-scripting language to help with code generation. TH1 was small and
21
+scripting language to help with code generation. TH1 was small and
2222
 light-weight and used minimal resources and seemed ideally suited for the
2323
 task.
2424
2525
 The name "TH1" stands "Test Harness 1", since that was its original purpose.
2626
@@ -128,16 +128,16 @@
128128
 * date
129129
 * decorate
130130
 * enable_output
131131
 * getParameter
132132
 * globalState
133
- * httpize
134133
 * hascap
135134
 * hasfeature
136135
 * html
137136
 * htmlize
138137
 * http
138
+ * httpize
139139
 * linecount
140140
 * puts
141141
 * query
142142
 * randhex
143143
 * regexp
@@ -157,18 +157,410 @@
157157
 * stime
158158
 * utime
159159
 * wiki
160160
161161
 Each of the commands above is documented by a block comment above their
162
-implementation in the th_main.c or th_tcl.c source files.
162
+implementation in the th\_main.c or th\_tcl.c source files.
163163
164164
 All commands starting with "tcl", with the exception of "tclReady",
165165
 require the Tcl integration subsystem be included at compile-time.
166166
 Additionally, the "tcl" repository setting must be enabled at runtime
167167
 in order to successfully make use of these commands.
168
+
169
+TH1 anoncap Command
170
+-------------------
171
+
172
+ * anoncap STRING...
173
+
174
+Returns true if the anonymous user has all of the capabilities listed
175
+in STRING.
176
+
177
+TH1 anycap Command
178
+------------------
179
+
180
+ * anycap STRING
181
+
182
+Returns true if the current user user has any one of the capabilities
183
+listed in STRING.
184
+
185
+TH1 artifact Command
186
+--------------------
187
+
188
+ * artifact ID ?FILENAME?
189
+
190
+Attempts to locate the specified artifact and return its contents. An
191
+error is generated if the repository is not open or the artifact cannot
192
+be found.
193
+
194
+TH1 checkout Command
195
+--------------------
196
+
197
+ * checkout ?BOOLEAN?
198
+
199
+Return the fully qualified directory name of the current checkout or an
200
+empty string if it is not available. Optionally, it will attempt to find
201
+the current checkout, opening the configuration ("user") database and the
202
+repository as necessary, if the boolean argument is non-zero.
203
+
204
+TH1 combobox Command
205
+--------------------
206
+
207
+ * combobox NAME TEXT-LIST NUMLINES
208
+
209
+Generates and emits an HTML combobox. NAME is both the name of the
210
+CGI parameter and the name of a variable that contains the currently
211
+selected value. TEXT-LIST is a list of possible values for the
212
+combobox. NUMLINES is 1 for a true combobox. If NUMLINES is greater
213
+than one then the display is a listbox with the number of lines given.
214
+
215
+TH1 date Command
216
+----------------
217
+
218
+ * date ?-local?
219
+
220
+Return a strings which is the current time and date. If the -local
221
+option is used, the date appears using localtime instead of UTC.
222
+
223
+TH1 decorate Command
224
+--------------------
225
+
226
+ * decorate STRING
227
+
228
+Renders STRING as wiki content; however, only links are handled. No
229
+other markup is processed.
230
+
231
+TH1 enable_output Command
232
+-------------------------
233
+
234
+ * enable_output BOOLEAN
235
+
236
+Enable or disable sending output when the combobox, puts, or wiki
237
+commands are used.
238
+
239
+TH1 getParameter Command
240
+------------------------
241
+
242
+ * getParameter NAME ?DEFAULT?
243
+
244
+Returns the value of the specified query parameter or the specified
245
+default value when there is no matching query parameter.
246
+
247
+TH1 globalState Command
248
+-----------------------
249
+
250
+ * globalState NAME ?DEFAULT?
251
+
252
+Returns a string containing the value of the specified global state
253
+variable -OR- the specified default value. The supported items are:
254
+
255
+ 1. **checkout** -- _Active local checkout directory, if any._
256
+ 1. **configuration** -- _Active configuration database file name, if any._
257
+ 1. **executable** -- _Fully qualified executable file name._
258
+ 1. **flags** -- _TH1 initialization flags._
259
+ 1. **log** -- _Error log file name, if any._
260
+ 1. **repository** -- _Active local repository file name, if any._
261
+ 1. **top** -- _Base path for the active server instance, if applicable._
262
+ 1. **user** -- _Active user name, if any._
263
+ 1. **vfs** -- _SQLite VFS in use, if overridden._
264
+
265
+Attempts to query for unsupported global state variables will result
266
+in a script error. Additional global state variables may be exposed
267
+in the future.
268
+
269
+TH1 hascap Command
270
+------------------
271
+
272
+ * hascap STRING...
273
+
274
+Returns true if the current user has all of the capabilities listed
275
+in STRING.
276
+
277
+TH1 hasfeature Command
278
+----------------------
279
+
280
+ * hasfeature STRING
281
+
282
+Returns true if the binary has the given compile-time feature enabled.
283
+The possible features are:
284
+
285
+ 1. **ssl** -- _Support for the HTTPS transport._
286
+ 1. **th1Docs** -- _Support for TH1 in embedded documentation._
287
+ 1. **th1Hooks** -- _Support for TH1 command and web page hooks._
288
+ 1. **tcl** -- _Support for Tcl integration._
289
+ 1. **useTclStubs** -- _Tcl stubs enabled in the Tcl headers._
290
+ 1. **tclStubs** -- _Uses Tcl stubs (i.e. linking with stubs library)._
291
+ 1. **tclPrivateStubs** -- _Uses Tcl private stubs (i.e. header-only)._
292
+ 1. **json** -- _Support for the JSON APIs._
293
+ 1. **markdown** -- _Support for Markdown documentation format._
294
+ 1. **unicodeCmdLine** -- _The command line arguments are Unicode._
295
+
296
+TH1 html Command
297
+----------------
298
+
299
+ * html STRING
300
+
301
+Outputs the STRING escaped for HTML.
302
+
303
+TH1 htmlize Command
304
+-------------------
305
+
306
+ * htmlize STRING
307
+
308
+Escape all characters of STRING which have special meaning in HTML.
309
+Returns the escaped string.
310
+
311
+TH1 http Command
312
+----------------
313
+
314
+ * http ?-asynchronous? ?--? url ?payload?
315
+
316
+Performs an HTTP or HTTPS request for the specified URL. If a
317
+payload is present, it will be interpreted as text/plain and
318
+the POST method will be used; otherwise, the GET method will
319
+be used. Upon success, if the -asynchronous option is used, an
320
+empty string is returned as the result; otherwise, the response
321
+from the server is returned as the result. Synchronous requests
322
+are not currently implemented.
323
+
324
+TH1 httpize Command
325
+-------------------
326
+
327
+ * httpize STRING
328
+
329
+Escape all characters of STRING which have special meaning in URI
330
+components. Returns the escaped string.
331
+
332
+TH1 linecount Command
333
+---------------------
334
+
335
+ * linecount STRING MAX MIN
336
+
337
+Returns one more than the number of \n characters in STRING. But
338
+never returns less than MIN or more than MAX.
339
+
340
+TH1 puts Command
341
+----------------
342
+
343
+ * puts STRING
344
+
345
+Outputs the STRING unchanged.
346
+
347
+TH1 query Command
348
+-----------------
349
+
350
+ * query SQL CODE
351
+
352
+Runs the SQL query given by the SQL argument. For each row in the result
353
+set, run CODE.
354
+
355
+In SQL, parameters such as $var are filled in using the value of variable
356
+"var". Result values are stored in variables with the column name prior
357
+to each invocation of CODE.
358
+
359
+TH1 randhex Command
360
+-------------------
361
+
362
+ * randhex N
363
+
364
+Returns a string of N*2 random hexadecimal digits with N<50. If N is
365
+omitted, use a value of 10.
366
+
367
+TH1 regexp Command
368
+------------------
369
+
370
+ * regexp ?-nocase? ?--? exp string
371
+
372
+Checks the string against the specified regular expression and returns
373
+non-zero if it matches. If the regular expression is invalid or cannot
374
+be compiled, an error will be generated.
375
+
376
+TH1 reinitialize Command
377
+------------------------
378
+
379
+ * reinitialize ?FLAGS?
380
+
381
+Reinitializes the TH1 interpreter using the specified flags.
382
+
383
+TH1 render Command
384
+------------------
385
+
386
+ * render STRING
387
+
388
+Renders the TH1 template and writes the results.
389
+
390
+TH1 repository Command
391
+----------------------
392
+
393
+ * repository ?BOOLEAN?
394
+
395
+Returns the fully qualified file name of the open repository or an empty
396
+string if one is not currently open. Optionally, it will attempt to open
397
+the repository if the boolean argument is non-zero.
398
+
399
+TH1 searchable Command
400
+----------------------
401
+
402
+ * searchable STRING...
403
+
404
+Return true if searching in any of the document classes identified
405
+by STRING is enabled for the repository and user has the necessary
406
+capabilities to perform the search. The possible document classes
407
+are:
408
+
409
+ 1. **c** -- _Check-in comments_
410
+ 1. **d** -- _Embedded documentation_
411
+ 1. **t** -- _Tickets_
412
+ 1. **w** -- _Wiki_
413
+
414
+To be clear, only one of the document classes identified by each STRING
415
+needs to be searchable in order for that argument to be true. But all
416
+arguments must be true for this routine to return true. Hence, to see
417
+if ALL document classes are searchable:
418
+
419
+ if {[searchable c d t w]} {...}
420
+
421
+But to see if ANY document class is searchable:
422
+
423
+ if {[searchable cdtw]} {...}
424
+
425
+This command is useful for enabling or disabling a "Search" entry on the
426
+menu bar.
427
+
428
+TH1 setParameter Command
429
+------------------------
430
+
431
+ * setParameter NAME VALUE
432
+
433
+Sets the value of the specified query parameter.
434
+
435
+TH1 setting Command
436
+-------------------
437
+
438
+ * setting name
439
+
440
+Gets and returns the value of the specified setting.
441
+
442
+TH1 styleHeader Command
443
+-----------------------
444
+
445
+ * styleHeader TITLE
446
+
447
+Render the configured style header.
448
+
449
+TH1 styleFooter Command
450
+-----------------------
451
+
452
+ * styleFooter
453
+
454
+Render the configured style footer.
455
+
456
+TH1 tclEval Command
457
+-------------------
458
+
459
+**This command requires the Tcl integration feature.**
460
+
461
+ * tclEval arg ?arg ...?
462
+
463
+Evaluates the Tcl script and returns its result verbatim. If a Tcl script
464
+error is generated, it will be transformed into a TH1 script error. A Tcl
465
+interpreter will be created automatically if it has not been already.
466
+
467
+TH1 tclExpr Command
468
+-------------------
469
+
470
+**This command requires the Tcl integration feature.**
471
+
472
+ * tclExpr arg ?arg ...?
473
+
474
+Evaluates the Tcl expression and returns its result verbatim. If a Tcl
475
+script error is generated, it will be transformed into a TH1 script error.
476
+A Tcl interpreter will be created automatically if it has not been already.
477
+
478
+TH1 tclInvoke Command
479
+---------------------
480
+
481
+**This command requires the Tcl integration feature.**
482
+
483
+ * tclInvoke command ?arg ...?
484
+
485
+Invokes the Tcl command using the supplied arguments. No additional
486
+substitutions are performed on the arguments. A Tcl interpreter will
487
+be created automatically if it has not been already.
488
+
489
+TH1 tclReady Command
490
+--------------------
491
+
492
+ * tclReady
493
+
494
+Returns true if the binary has the Tcl integration feature enabled and it
495
+is currently available for use by TH1 scripts.
496
+
497
+TH1 trace Command
498
+-----------------
499
+
500
+ * trace STRING
501
+
502
+Generates a TH1 trace message if TH1 tracing is enabled.
503
+
504
+TH1 stime Command
505
+-----------------
506
+
507
+ * stime
508
+
509
+Returns the number of microseconds of CPU time consumed by the current
510
+process in system space.
511
+
512
+TH1 utime Command
513
+-----------------
514
+
515
+ * utime
516
+
517
+Returns the number of microseconds of CPU time consumed by the current
518
+process in user space.
519
+
520
+TH1 wiki Command
521
+----------------
522
+
523
+ * wiki STRING
524
+
525
+Renders STRING as wiki content.
526
+
527
+Tcl Integration Commands
528
+------------------------
529
+
530
+When the Tcl integration subsystem is enabled, several commands are added
531
+to the Tcl interpreter. They are used to allow Tcl scripts access to the
532
+Fossil functionality provided via TH1. The following is a summary of the
533
+Tcl commands:
534
+
535
+ * th1Eval
536
+ * th1Expr
537
+
538
+Tcl th1Eval Command
539
+-------------------
540
+
541
+**This command requires the Tcl integration feature.**
542
+
543
+ * th1Eval arg
544
+
545
+Evaluates the TH1 script and returns its result verbatim. If a TH1 script
546
+error is generated, it will be transformed into a Tcl script error.
547
+
548
+Tcl th1Expr Command
549
+-------------------
550
+
551
+**This command requires the Tcl integration feature.**
552
+
553
+ * th1Expr arg
554
+
555
+Evaluates the TH1 expression and returns its result verbatim. If a TH1
556
+script error is generated, it will be transformed into a Tcl script error.
557
+
558
+Further Notes
559
+-------------
168560
169561
 **To Do:** We would like to have a community volunteer go through and
170562
 copy the documentation for each of these commands (with appropriate
171563
 format changes and spelling and grammar corrections) into subsequent
172564
 sections of this document. It is suggested that the list of extension
173565
 commands be left intact - as a quick reference. But it would be really
174566
 nice to also have the details of what each command does.
175567
--- www/th1.md
+++ www/th1.md
@@ -13,14 +13,14 @@
13 be easily compiled on the SymbianOS. So TH1 was developed as a cut-down
14 version of TCL that would facilitate running the SQLite test scripts on
15 SymbianOS.
16
17 The testing of SQLite on SymbianOS was eventually accomplished by other
18 means. But Fossil was first being designed at about the same time.
19 Early prototypes of Fossil were written in pure TCL. But as the development
20 shifted toward the use of C-code, the need arose to have a TCL-like
21 scripting language to help with code generation. TH1 was small and
22 light-weight and used minimal resources and seemed ideally suited for the
23 task.
24
25 The name "TH1" stands "Test Harness 1", since that was its original purpose.
26
@@ -128,16 +128,16 @@
128 * date
129 * decorate
130 * enable_output
131 * getParameter
132 * globalState
133 * httpize
134 * hascap
135 * hasfeature
136 * html
137 * htmlize
138 * http
 
139 * linecount
140 * puts
141 * query
142 * randhex
143 * regexp
@@ -157,18 +157,410 @@
157 * stime
158 * utime
159 * wiki
160
161 Each of the commands above is documented by a block comment above their
162 implementation in the th_main.c or th_tcl.c source files.
163
164 All commands starting with "tcl", with the exception of "tclReady",
165 require the Tcl integration subsystem be included at compile-time.
166 Additionally, the "tcl" repository setting must be enabled at runtime
167 in order to successfully make use of these commands.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
168
169 **To Do:** We would like to have a community volunteer go through and
170 copy the documentation for each of these commands (with appropriate
171 format changes and spelling and grammar corrections) into subsequent
172 sections of this document. It is suggested that the list of extension
173 commands be left intact - as a quick reference. But it would be really
174 nice to also have the details of what each command does.
175
--- www/th1.md
+++ www/th1.md
@@ -13,14 +13,14 @@
13 be easily compiled on the SymbianOS. So TH1 was developed as a cut-down
14 version of TCL that would facilitate running the SQLite test scripts on
15 SymbianOS.
16
17 The testing of SQLite on SymbianOS was eventually accomplished by other
18 means. But Fossil was first being designed at about the same time.
19 Early prototypes of Fossil were written in pure TCL. But as the development
20 shifted toward the use of C-code, the need arose to have a TCL-like
21 scripting language to help with code generation. TH1 was small and
22 light-weight and used minimal resources and seemed ideally suited for the
23 task.
24
25 The name "TH1" stands "Test Harness 1", since that was its original purpose.
26
@@ -128,16 +128,16 @@
128 * date
129 * decorate
130 * enable_output
131 * getParameter
132 * globalState
 
133 * hascap
134 * hasfeature
135 * html
136 * htmlize
137 * http
138 * httpize
139 * linecount
140 * puts
141 * query
142 * randhex
143 * regexp
@@ -157,18 +157,410 @@
157 * stime
158 * utime
159 * wiki
160
161 Each of the commands above is documented by a block comment above their
162 implementation in the th\_main.c or th\_tcl.c source files.
163
164 All commands starting with "tcl", with the exception of "tclReady",
165 require the Tcl integration subsystem be included at compile-time.
166 Additionally, the "tcl" repository setting must be enabled at runtime
167 in order to successfully make use of these commands.
168
169 TH1 anoncap Command
170 -------------------
171
172 * anoncap STRING...
173
174 Returns true if the anonymous user has all of the capabilities listed
175 in STRING.
176
177 TH1 anycap Command
178 ------------------
179
180 * anycap STRING
181
182 Returns true if the current user user has any one of the capabilities
183 listed in STRING.
184
185 TH1 artifact Command
186 --------------------
187
188 * artifact ID ?FILENAME?
189
190 Attempts to locate the specified artifact and return its contents. An
191 error is generated if the repository is not open or the artifact cannot
192 be found.
193
194 TH1 checkout Command
195 --------------------
196
197 * checkout ?BOOLEAN?
198
199 Return the fully qualified directory name of the current checkout or an
200 empty string if it is not available. Optionally, it will attempt to find
201 the current checkout, opening the configuration ("user") database and the
202 repository as necessary, if the boolean argument is non-zero.
203
204 TH1 combobox Command
205 --------------------
206
207 * combobox NAME TEXT-LIST NUMLINES
208
209 Generates and emits an HTML combobox. NAME is both the name of the
210 CGI parameter and the name of a variable that contains the currently
211 selected value. TEXT-LIST is a list of possible values for the
212 combobox. NUMLINES is 1 for a true combobox. If NUMLINES is greater
213 than one then the display is a listbox with the number of lines given.
214
215 TH1 date Command
216 ----------------
217
218 * date ?-local?
219
220 Return a strings which is the current time and date. If the -local
221 option is used, the date appears using localtime instead of UTC.
222
223 TH1 decorate Command
224 --------------------
225
226 * decorate STRING
227
228 Renders STRING as wiki content; however, only links are handled. No
229 other markup is processed.
230
231 TH1 enable_output Command
232 -------------------------
233
234 * enable_output BOOLEAN
235
236 Enable or disable sending output when the combobox, puts, or wiki
237 commands are used.
238
239 TH1 getParameter Command
240 ------------------------
241
242 * getParameter NAME ?DEFAULT?
243
244 Returns the value of the specified query parameter or the specified
245 default value when there is no matching query parameter.
246
247 TH1 globalState Command
248 -----------------------
249
250 * globalState NAME ?DEFAULT?
251
252 Returns a string containing the value of the specified global state
253 variable -OR- the specified default value. The supported items are:
254
255 1. **checkout** -- _Active local checkout directory, if any._
256 1. **configuration** -- _Active configuration database file name, if any._
257 1. **executable** -- _Fully qualified executable file name._
258 1. **flags** -- _TH1 initialization flags._
259 1. **log** -- _Error log file name, if any._
260 1. **repository** -- _Active local repository file name, if any._
261 1. **top** -- _Base path for the active server instance, if applicable._
262 1. **user** -- _Active user name, if any._
263 1. **vfs** -- _SQLite VFS in use, if overridden._
264
265 Attempts to query for unsupported global state variables will result
266 in a script error. Additional global state variables may be exposed
267 in the future.
268
269 TH1 hascap Command
270 ------------------
271
272 * hascap STRING...
273
274 Returns true if the current user has all of the capabilities listed
275 in STRING.
276
277 TH1 hasfeature Command
278 ----------------------
279
280 * hasfeature STRING
281
282 Returns true if the binary has the given compile-time feature enabled.
283 The possible features are:
284
285 1. **ssl** -- _Support for the HTTPS transport._
286 1. **th1Docs** -- _Support for TH1 in embedded documentation._
287 1. **th1Hooks** -- _Support for TH1 command and web page hooks._
288 1. **tcl** -- _Support for Tcl integration._
289 1. **useTclStubs** -- _Tcl stubs enabled in the Tcl headers._
290 1. **tclStubs** -- _Uses Tcl stubs (i.e. linking with stubs library)._
291 1. **tclPrivateStubs** -- _Uses Tcl private stubs (i.e. header-only)._
292 1. **json** -- _Support for the JSON APIs._
293 1. **markdown** -- _Support for Markdown documentation format._
294 1. **unicodeCmdLine** -- _The command line arguments are Unicode._
295
296 TH1 html Command
297 ----------------
298
299 * html STRING
300
301 Outputs the STRING escaped for HTML.
302
303 TH1 htmlize Command
304 -------------------
305
306 * htmlize STRING
307
308 Escape all characters of STRING which have special meaning in HTML.
309 Returns the escaped string.
310
311 TH1 http Command
312 ----------------
313
314 * http ?-asynchronous? ?--? url ?payload?
315
316 Performs an HTTP or HTTPS request for the specified URL. If a
317 payload is present, it will be interpreted as text/plain and
318 the POST method will be used; otherwise, the GET method will
319 be used. Upon success, if the -asynchronous option is used, an
320 empty string is returned as the result; otherwise, the response
321 from the server is returned as the result. Synchronous requests
322 are not currently implemented.
323
324 TH1 httpize Command
325 -------------------
326
327 * httpize STRING
328
329 Escape all characters of STRING which have special meaning in URI
330 components. Returns the escaped string.
331
332 TH1 linecount Command
333 ---------------------
334
335 * linecount STRING MAX MIN
336
337 Returns one more than the number of \n characters in STRING. But
338 never returns less than MIN or more than MAX.
339
340 TH1 puts Command
341 ----------------
342
343 * puts STRING
344
345 Outputs the STRING unchanged.
346
347 TH1 query Command
348 -----------------
349
350 * query SQL CODE
351
352 Runs the SQL query given by the SQL argument. For each row in the result
353 set, run CODE.
354
355 In SQL, parameters such as $var are filled in using the value of variable
356 "var". Result values are stored in variables with the column name prior
357 to each invocation of CODE.
358
359 TH1 randhex Command
360 -------------------
361
362 * randhex N
363
364 Returns a string of N*2 random hexadecimal digits with N<50. If N is
365 omitted, use a value of 10.
366
367 TH1 regexp Command
368 ------------------
369
370 * regexp ?-nocase? ?--? exp string
371
372 Checks the string against the specified regular expression and returns
373 non-zero if it matches. If the regular expression is invalid or cannot
374 be compiled, an error will be generated.
375
376 TH1 reinitialize Command
377 ------------------------
378
379 * reinitialize ?FLAGS?
380
381 Reinitializes the TH1 interpreter using the specified flags.
382
383 TH1 render Command
384 ------------------
385
386 * render STRING
387
388 Renders the TH1 template and writes the results.
389
390 TH1 repository Command
391 ----------------------
392
393 * repository ?BOOLEAN?
394
395 Returns the fully qualified file name of the open repository or an empty
396 string if one is not currently open. Optionally, it will attempt to open
397 the repository if the boolean argument is non-zero.
398
399 TH1 searchable Command
400 ----------------------
401
402 * searchable STRING...
403
404 Return true if searching in any of the document classes identified
405 by STRING is enabled for the repository and user has the necessary
406 capabilities to perform the search. The possible document classes
407 are:
408
409 1. **c** -- _Check-in comments_
410 1. **d** -- _Embedded documentation_
411 1. **t** -- _Tickets_
412 1. **w** -- _Wiki_
413
414 To be clear, only one of the document classes identified by each STRING
415 needs to be searchable in order for that argument to be true. But all
416 arguments must be true for this routine to return true. Hence, to see
417 if ALL document classes are searchable:
418
419 if {[searchable c d t w]} {...}
420
421 But to see if ANY document class is searchable:
422
423 if {[searchable cdtw]} {...}
424
425 This command is useful for enabling or disabling a "Search" entry on the
426 menu bar.
427
428 TH1 setParameter Command
429 ------------------------
430
431 * setParameter NAME VALUE
432
433 Sets the value of the specified query parameter.
434
435 TH1 setting Command
436 -------------------
437
438 * setting name
439
440 Gets and returns the value of the specified setting.
441
442 TH1 styleHeader Command
443 -----------------------
444
445 * styleHeader TITLE
446
447 Render the configured style header.
448
449 TH1 styleFooter Command
450 -----------------------
451
452 * styleFooter
453
454 Render the configured style footer.
455
456 TH1 tclEval Command
457 -------------------
458
459 **This command requires the Tcl integration feature.**
460
461 * tclEval arg ?arg ...?
462
463 Evaluates the Tcl script and returns its result verbatim. If a Tcl script
464 error is generated, it will be transformed into a TH1 script error. A Tcl
465 interpreter will be created automatically if it has not been already.
466
467 TH1 tclExpr Command
468 -------------------
469
470 **This command requires the Tcl integration feature.**
471
472 * tclExpr arg ?arg ...?
473
474 Evaluates the Tcl expression and returns its result verbatim. If a Tcl
475 script error is generated, it will be transformed into a TH1 script error.
476 A Tcl interpreter will be created automatically if it has not been already.
477
478 TH1 tclInvoke Command
479 ---------------------
480
481 **This command requires the Tcl integration feature.**
482
483 * tclInvoke command ?arg ...?
484
485 Invokes the Tcl command using the supplied arguments. No additional
486 substitutions are performed on the arguments. A Tcl interpreter will
487 be created automatically if it has not been already.
488
489 TH1 tclReady Command
490 --------------------
491
492 * tclReady
493
494 Returns true if the binary has the Tcl integration feature enabled and it
495 is currently available for use by TH1 scripts.
496
497 TH1 trace Command
498 -----------------
499
500 * trace STRING
501
502 Generates a TH1 trace message if TH1 tracing is enabled.
503
504 TH1 stime Command
505 -----------------
506
507 * stime
508
509 Returns the number of microseconds of CPU time consumed by the current
510 process in system space.
511
512 TH1 utime Command
513 -----------------
514
515 * utime
516
517 Returns the number of microseconds of CPU time consumed by the current
518 process in user space.
519
520 TH1 wiki Command
521 ----------------
522
523 * wiki STRING
524
525 Renders STRING as wiki content.
526
527 Tcl Integration Commands
528 ------------------------
529
530 When the Tcl integration subsystem is enabled, several commands are added
531 to the Tcl interpreter. They are used to allow Tcl scripts access to the
532 Fossil functionality provided via TH1. The following is a summary of the
533 Tcl commands:
534
535 * th1Eval
536 * th1Expr
537
538 Tcl th1Eval Command
539 -------------------
540
541 **This command requires the Tcl integration feature.**
542
543 * th1Eval arg
544
545 Evaluates the TH1 script and returns its result verbatim. If a TH1 script
546 error is generated, it will be transformed into a Tcl script error.
547
548 Tcl th1Expr Command
549 -------------------
550
551 **This command requires the Tcl integration feature.**
552
553 * th1Expr arg
554
555 Evaluates the TH1 expression and returns its result verbatim. If a TH1
556 script error is generated, it will be transformed into a Tcl script error.
557
558 Further Notes
559 -------------
560
561 **To Do:** We would like to have a community volunteer go through and
562 copy the documentation for each of these commands (with appropriate
563 format changes and spelling and grammar corrections) into subsequent
564 sections of this document. It is suggested that the list of extension
565 commands be left intact - as a quick reference. But it would be really
566 nice to also have the details of what each command does.
567

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button