xapian-applications/omega/docs/omegascript.rst

   1 ===========
   2 OmegaScript
   3 ===========
   4
   5 OmegaScript adds processed text-generation commands to text templates
   6 (which will usually be HTML, but can be XML or another textual format).
   7 Commands take the form ``$command{comma,separated,arguments}`` or
   8 ``$simplecommand``, for example::
   9
  10     <html>
  11     <head><title>Sample</title></head>
  12     <body>
  13
  14     <p>
  15     You searched for '$html{$query}'.
  16     </p>
  17
  18     </body>
  19     </html>
  20
  21 Where appropriate, arguments themselves can contain OmegaScript commands.
  22 Where an argument is treated as a string, the string is precisely the contents
  23 of that argument - there is no string delimiter (such as the double-quote
  24 character '"' in C and similar languages).  This can make complex OmegaScript
  25 slightly difficult to read at times.
  26
  27 When a command takes no arguments, the braces must be omitted (i.e.
  28 `$msize` rather than `$msize{}` - the latter is a command with a single empty
  29 argument).  If you want to have the value of `$msize` immediately
  30 followed by a letter, digit, or "_", you can use an empty comment (`${}`) to
  31 prevent the parser treating the following character as part of a command name.
  32 E.g. `_$msize${}_` rather than `_$msize_`
  33
  34 It is important to realise that all whitespace is significant in OmegaScript
  35 - e.g. if you put whitespace around a "," which separates two command arguments
  36 then the whitespace will be part of the respective arguments.
  37
  38 Note that (by design) OmegaScript has no unbounded looping constructs.  You
  39 can loop over entries in a list, but you can't loop until some arbitrary
  40 condition is met.  This means that it's not possible to accidentally (or
  41 deliberately!) write an OmegaScript template which contains an infinite loop.
  42
  43 OmegaScript literals
  44 ====================
  45
  46 ::
  47
  48     $$ - literal '$'
  49     $( - literal '{'
  50     $) - literal '}'
  51     $. - literal ','
  52
  53
  54 OmegaScript commands
  55 ====================
  56
  57 In the following descriptions, a LIST is a string of tab-separated
  58 values.
  59
  60 ${...}
  61         commented-out code
  62
  63 $addfilter{TERM[,TYPE]}
  64         add filter term ``TERM`` as if it had been passed as a ``B`` CGI
  65         parameter (if ``TYPE`` is not-specified, empty or ``B``), or as a
  66         negated filter as if passed as an ``N`` CGI parameter (if ``TYPE`` is
  67         ``N``).  Invalid types result in an error.
  68
  69         Support for the second parameter was added in Omega 1.4.12 - in older
  70         versions only ``$addfilter{TERM}`` was supported and added ``B``-style
  71         filters.
  72
  73         You must use ``$addfilter`` before any command which requires the query
  74         to have been parsed - see ``$setmap`` for a list of these commands.
  75
  76 $allterms[{DOCID}]
  77         list of all terms indexing the document with docid `DOCID` - if used
  78         without a parameter list, them the docid of the current hit is
  79         implicitly used.
  80
  81 $base64{DATA}
  82         encodes DATA using base64.
  83
  84         Added in Omega 1.4.19.
  85
  86 $cgi{CGI}
  87         lookup the value of a CGI parameter.  If the same parameter has
  88         multiple values, ``$cgi`` will pick one arbitrarily - use ``$cgilist``
  89         if you want all the values.
  90
  91 $cgilist{CGI}
  92         return a list of all values of a CGI parameter
  93
  94 $cgiparams
  95         return a list of all the unique CGI parameter names, sorted in
  96         ascending order by raw byte values.
  97
  98 $chr{CODEPOINT}
  99         return UTF-8 for the given Unicode codepoint, e.g. ``$chr{127866}``
 100         should display as a beer mug if the font has a suitable glyph.
 101
 102         Since ASCII is a subset of Unicode, you can also produce control
 103         characters, e.g. ``$chr{13}`` gives a carriage return character.
 104
 105         To convert a UTF-8 character to a Unicode codepoint, see ``$ord``.
 106
 107         Added in Omega 1.3.4.
 108
 109 $collapsed
 110         number of other documents collapsed into current hit inside
 111         ``$hitlist``, which might be used like so::
 112
 113              $if{$ne{$collapsed,0},at least $collapsed hidden results ($value{$cgi{COLLAPSE}})}
 114
 115 $contains{STRING1,STRING2}
 116         return position of first occurrence of STRING1 in STRING2, if present. Else return an empty string.
 117         Examples:
 118
 119         ``$contains{fish,goldfish}`` gives ``"4"``
 120
 121         ``$contains{fish,shark}`` gives ``""``
 122
 123 $csv{STRING[,ALWAYS_ESCAPE]}
 124         encode STRING for use as a field in a CSV file.  By default, escaping
 125         is done as described in RFC4180, except that we treat any byte value
 126         not otherwise mentioned as being 'TEXTDATA' (so %x00-%x09, %x0B-%x0C,
 127         %x0E-%x1F, %x7F-%xFF are also permitted there).  Examples:
 128
 129         ``$csv{Safe in CSV!}`` gives ``Safe in CSV!``
 130
 131         ``$csv{Not "safe"}`` gives ``"Not ""safe"""``
 132
 133         ``$csv{3$. 2$. 1}`` gives ``"3, 2, 1"``
 134
 135         Some CSV consumers don't follow the RFC, in which case you may need
 136         to encode additional values.  For this reason, ``$csv`` provides an
 137         highly conservative alternative mode in which any double quote
 138         characters in the string are doubled, and the result always wrapped in
 139         double quotes.  To select this mode, pass a second non-empty argument.
 140         Examples:
 141
 142         ``$csv{Quote anyway,1}`` gives ``"Quote anyway"``
 143
 144         ``$csv{Not "safe",1}`` gives ``"Not ""safe"""``
 145
 146         Added in Omega 1.3.4.
 147
 148 $date{TIME_T[,FMT]}
 149         convert a time_t to strftime ``FMT`` (default: ``YYYY-MM-DD``).  The
 150         conversion is done in timezone UTC.
 151
 152 $dbname
 153         database name (multiple names are returned separated by "/").
 154
 155 $dbsize
 156         number of documents in the database (if multiple databases are being
 157         searched, this gives the total number).
 158
 159 $def{MACRONAME,VALUE}
 160         define a macro which can take 0 to 9 arguments.  You can call it with
 161         ``$MACRONAME`` (if it take 0 arguments) or
 162         ``$MACRONAME{ARG1,ARG2,ARG3}`` is it takes arguments.  In value,
 163         arguments are available as ``$1``, ``$2``, ...  ``$9``.  In the current
 164         implementation, macros can override OmegaScript commands, but this
 165         shouldn't be relied on.  It's recommended to use capitalised names for
 166         macros to avoid collision with future OmegaScript commands.
 167
 168 $defaultop
 169         "and" or "or" (set from CGI variable DEFAULTOP).
 170
 171 $emptydocs[{TERM}]
 172         returns a list of docids of any documents with document length zero
 173         (such documents probably only contain scanned images, rather than
 174         machine readable text, or suggest the input filter isn't working well).
 175         If TERM is specified, only consider documents matching TERM, otherwise
 176         all documents are considered (so Tapplication/pdf reports all PDF files
 177         for which no text was found).
 178
 179         If you're using omindex, note that it skips files with zero size, so
 180         these won't get reported here as they aren't present in the database.
 181
 182 $env{VAR}
 183         lookup variable ``VAR`` in the environment.
 184
 185 $error
 186         error message (e.g. if a database wouldn't open, or the query couldn't
 187         be parsed, or a Xapian exception has been thrown) or empty if there
 188         wasn't an error.  You can set the error message yourself by using
 189         ``$seterror``.
 190
 191 $field{NAME[,DOCID]}
 192         lookup field ``NAME`` in document ``DOCID``.  If ``DOCID`` is omitted
 193         then the field is looked up in the current hit (which only works inside
 194         ``$hitlist``).
 195
 196         If multiple instances of field exist the field values are returned as
 197         an OmegaScript list (i.e. tab separated), which means you can pass the
 198         results to other commands which take a list, such as ``$foreach``, e.g.
 199         ::
 200
 201             $foreach{$field{keywords},<b>$html{$_}</b><br>}
 202
 203 $filesize{SIZE}
 204         pretty printed filesize (e.g. ``1 byte``, ``100 bytes``, ``2.1K``,
 205         ``4.0M``, ``1.3G``).  If ``SIZE`` is empty or a negative integer,
 206         expands to nothing.  Omega 1.4.x and earlier instead gave ``0 bytes``
 207         for empty ``SIZE``.
 208
 209         If ``SIZE`` is not empty or an integer value, ``$error`` is set.
 210         Omega 1.4.x and earlier instead ignored anything after the initial part
 211         of ``SIZE`` which could be parsed as an integer value.
 212
 213 $filters[{WANTOLDFORMAT}]
 214         compact serialisation of filter-like settings (currently ``B``, ``N``,
 215         ``DATEVALUE``, ``START``, ``END``, ``SPAN``, ``START.``\ *SLOT*,
 216         ``END.``\ *SLOT*, ``SPAN.``\ *SLOT*, ``COLLAPSE``,
 217         ``DOCIDORDER``, ``SORT``, ``SORTREVERSE``, ``SORTAFTER``, and
 218         ``DEFAULTOP``) - set ``xFILTERS`` to this so that Omega can detect when
 219         the filters have changed and display the first page of results.
 220
 221         If an argument is supplied and non-empty, an older version of the filter
 222         encoding is used instead.  Omega checks for either format in ``xFILTERS``
 223         to allow the encoding to be improved over time, while keeping
 224         compatibility with the previous release series.  This ability to get
 225         the older format encoding is only intended for use in Omega's testsuite
 226         and probably isn't useful otherwise.
 227
 228 $filterterms{PREFIX}
 229         list of all terms in the database with prefix ``PREFIX``, intended to
 230         be used to allow drop-down lists and sets of radio buttons to be
 231         dynamically generated, e.g.::
 232
 233              Hostname:
 234              <SELECT NAME="B">
 235              <OPTION VALUE=""
 236              $if{$map{$cgilist{B},$eq{$substr{$_,0,1},H}},,SELECTED}> Any
 237              $foreach{$filterterms{H},
 238              <OPTION VALUE="$html{$_}" $if{$find{$cgilist{B},$_},SELECTED}>
 239              $html{$substr{$_,1}}
 240              </OPTION>
 241              }
 242              </SELECT>
 243
 244 $find{LIST,STRING}
 245         returns the number of the first entry in ``LIST`` which is equal to
 246         ``STRING`` (starting from 0) or the empty string if no entry matches.
 247
 248 $fmt
 249         name of current format (as set by CGI parameter ``FMT``, or the default)
 250
 251 $foreach{LIST,STUFF)
 252         evaluated argument ``STUFF`` for each entry in list ``LIST``. If
 253         ``LIST`` contains the entries ``15``, ``13``, ``5``, ``7``, ``1``
 254         then::
 255
 256             "$foreach{LIST,$chr{$add{$_,64}}}" = "OMEGA"
 257
 258         If you want a list as output instead then see ``$map``.
 259
 260         Added in Omega 1.4.18.
 261
 262 $freq{term}
 263         frequency of a term
 264
 265 $hash{TEXT,HASH}
 266         unique ID for ``TEXT`` string using the hashing algorithm specified by
 267         ``HASH`` which must be a lowercase string. Currently, this command only
 268         supports MD5 which yields a 128-bit hash sequence serialised as 32
 269         hexadecimal characters.
 270
 271 $highlight{TEXT,LIST[,OPEN[,CLOSE]]}
 272         html escape string (<>&, etc) and highlight any terms from ``LIST``
 273         that appear in ``TEXT`` by enclosing them in ``OPEN`` and ``CLOSE``.
 274         If ``OPEN`` is specified, but close is omitted, ``CLOSE`` defaults to
 275         the appropriate closing tag for ``OPEN`` (i.e. with a "/" in front and
 276         any parameters removed).  If both are omitted, then ``OPEN`` is set to:
 277         ``<b style="color:XXXXX;background-color:#YYYYYY">`` (where ``YYYYYY``
 278         cycles through ``ffff66`` ``99ff99`` ``99ffff`` ``ff66ff`` ``ff9999``
 279         ``990000`` ``009900`` ``996600`` ``006699`` ``990099`` and ``XXXXX``
 280         is ``black`` if ``YYYYYY`` contains an ``f``, and otherwise ``white``)
 281         and ``CLOSE`` is set to ``</b>``.
 282
 283 $hit
 284         MSet index of current doc (first document in MSet is 0, so if
 285         you want to number the hits 1, 2, 3, ... use ``$add{$hit,1}``).
 286
 287 $hitlist{STUFF}
 288         evaluate ``STUFF`` once for each match in the result list.  During
 289         each evaluation ``$field``, ``$id``, ``$percentage``, ``$score``,
 290         ``$terms``, ``$weight``, etc will report values for the current hit.
 291
 292 $hitsperpage
 293         hits per page (as set by ``HITSPERPAGE``, or the default)
 294
 295 $hostname{URL}
 296         return the hostname from url ``URL``
 297
 298 $html{TEXT}
 299         html escape string (``<>&"`` are escaped to ``&lt;``, etc).
 300
 301 $htmlstrip{TEXT}
 302         html strip tags from string (``<...>``, etc).
 303
 304 $httpheader{NAME,VALUE}
 305         specify an additional HTTP header to be generated by Omega.
 306         For example::
 307
 308          $httpheader{Cache-Control,max-age=0$.private}
 309
 310         If ``Content-Type`` is not specified by the template, it defaults
 311         to ``text/html``.  Headers must be specified before any other
 312         output from the OmegaScript template - any ``$httpheader{}``
 313         commands found later in the template will be silently ignored.
 314
 315 $id
 316         document id of current document
 317
 318 $json{STRING}
 319         encode STRING as a JSON string (not including the enclosing quotes), e.g.
 320         ``$json{The path is "C:\"}`` gives ``The path is \"C:\\\"``
 321
 322         Added in Omega 1.3.1.
 323
 324 $jsonarray{LIST[,FORMAT]}
 325         encodes LIST (a string of tab-separated values) as a JSON array.  By
 326         default the elements of the array are encoded as JSON strings, but
 327         if ``FORMAT`` is specified it's evaluated for each element in turn
 328         with ``$_`` set to the element value and the result used instead.
 329
 330         The default ``FORMAT`` is equivalent to ``"$json{$_}"``.
 331
 332         Examples:
 333
 334         ``$jsonarray{$split{a "b" c:\}}`` gives ``["a","\"b\"","c:\\"]``
 335
 336         ``$jsonarray{$split{2 3 5 7},$mul{$_,$_}}`` gives ``[4,9,25,49]``
 337
 338         Added in Omega 1.3.1, but buggy until 1.3.4.
 339
 340         Support for the second argument added in Omega 1.4.15.
 341
 342 $jsonbool{COND}
 343         returns a JSON bool value (i.e. ``true`` or ``false``) for OmegaScript
 344         value ``COND``.
 345
 346         This is exactly equivalent to ``$if{COND,true,false}`` and is provided
 347         just to allow more readable JSON-producing templates.  This means that
 348         ``COND`` being empty is false and all non-empty values are true (so
 349         note that ``$jsonbool{0}`` gives ``true`` - if you want a numeric test,
 350         you can use ``$jsonbool{$ne{VALUE,0}}``
 351
 352         Added in Omega 1.4.15.
 353
 354 $jsonobject{MAP[,KEYFORMAT[,VALUEFORMAT]]}
 355         encodes OmegaScript map ``MAP`` (as set by ``$setmap``) as a JSON object.
 356
 357         ``KEYFORMAT`` provides a way to modify key values.  It's evaluated for
 358         each key with ``$_`` set to the OmegaScript map key.  If omitted or
 359         empty then the keys are used as-is (so it effectively defaults to
 360         ``$_``).  For example ``$jsonobject{foo,$lower{$_}}`` forces keys to
 361         lower case.
 362
 363         You probably want to avoid creating duplicate keys (RFC 2119 says they
 364         ``SHOULD be unique``).  Note that the resulting value should be an
 365         OmegaScript string - don't pass it though ``$json{}`` or wrap it in
 366         double quotes.
 367
 368         ``VALUEFORMAT`` provides a way to specify how to encode values.  It's
 369         evaluated for each value with ``$_`` set to the OmegaScript map value
 370         and the result should be JSON to use as the JSON object value.  If
 371         omitted or empty the value is encoded as a JSON string (so effectively
 372         the default is ``"$json{$_}"``).  Note that (unlike ``KEYFORMAT``) this
 373         does need to include ``$json{}`` and double quotes, because the value
 374         doesn't have to be a JSON string.
 375
 376         Simple example::
 377
 378           $jsonobject{foo}
 379
 380         More complex example which upper-cases the keys and uses JSON integers
 381         for the values::
 382
 383           $jsonobject{foo,$upper{$_},$_}
 384
 385         Added in Omega 1.4.15.  Since 1.4.19 the returned JSON no longer
 386         contains newlines, which makes it usable as a single line serialisation
 387         format without post-processing.
 388
 389 $jsonobject2{KEYLIST,VALUELIST[,KEYFORMAT[,VALUEFORMAT]]}
 390         encodes OmegaScript lists ``KEYLIST`` and ``VALUELIST`` as a JSON
 391         object.
 392
 393         An error is raised if the number of elements in ``KEYS`` and ``VALUES``
 394         is not the same (except that it's OK for ``VALUES`` to be empty if
 395         ``KEYS`` has a single element, because an OmegaScript list can't
 396         represent a list with a single empty entry distinct from a list with
 397         no entries).
 398
 399         ``KEYFORMAT`` and ``VALUEFORMAT`` work identically to how they do for
 400         ``$jsonobject``.
 401
 402         Simple example::
 403
 404           $jsonobject2{$split{k1 k2 k3},$split{v1 v2 v3}}
 405
 406         More complex example which upper-cases the keys and uses JSON integers
 407         for the values::
 408
 409           $jsonobject2{$split{k1 k2 k3},$split{1 2 3},$upper{$_},$_}
 410
 411         Added in Omega 1.5.0.
 412
 413 $keys{MAP}
 414         returns a list containing the keys of MAP (as set by ``$setmap``).
 415         The keys are in sorted order (by raw byte comparison).
 416
 417         Added in Omega 1.4.15.
 418
 419 $last
 420         MSet index one beyond the end of the current page (so ``$hit`` runs
 421         from ``0`` to ``$sub{$last,1}``).
 422
 423 $lastpage
 424         number of last page of hits (may be an underestimate unless
 425         ``$thispage`` == ``$lastpage``).
 426
 427 $length{LIST}
 428         number of entries in ``LIST``.
 429
 430 $list{LIST,...}
 431         pretty print list. If ``LIST`` contains 1, 2, 3, 4 then::
 432
 433          "$list{LIST,$. }" = "1, 2, 3, 4"
 434          "$list{LIST,$. , and }" = "1, 2, 3 and 4"
 435          "$list{LIST,List ,$. ,.}" = "List 1, 2, 3, 4."
 436          "$list{LIST,List ,$. , and ,.}" = "List 1, 2, 3 and 4."
 437
 438         NB ``$list`` returns an empty string for an empty list (so the
 439         last two forms aren't redundant as it may at first appear).
 440
 441 $log{LOGFILE[,ENTRY]}
 442         append to the log file ``LOGFILE``.  ``LOGFILE`` will be resolved as a
 443         relative path starting from directory ``log_dir`` (as specified in
 444         ``omega.conf``).  ``LOGFILE`` may not contain the substring ``..``.
 445
 446         ``ENTRY`` is the OmegaScript for the log entry, which is evaluated and
 447         a linefeed appended.  ``ENTRY`` defaults to a format similar to the
 448         Common Log Format used by webservers.  If an error occurs when trying
 449         to open the log file then ``ENTRY`` won't be evaluated.
 450
 451         If the logfile can't be opened or writing to it fails then ``$log``
 452         returns an error message (since Omega 1.5.0), otherwise it returns
 453         nothing.  If you want to ignore logging errors, you can ignore the
 454         return value using ``$if`` with no action like so::
 455
 456          $if{$log{example.log}}
 457
 458 $lookup{CDBFILE,KEY}
 459         Return the tag corresponding to key ``KEY`` in the CDB file
 460         ``CDBFILE``.  If the file doesn't exist, or ``KEY`` isn't a key in it,
 461         then ``$lookup`` expands to nothing.  CDB files are compact disk based
 462         hashtables.  For more information and public domain software which can
 463         create CDB files, please visit: http://www.corpit.ru/mjt/tinycdb.html
 464
 465         An example of how this might be used is to map top-level domains to
 466         country names.  Create a CDB file tld_en which maps "fr" to "France",
 467         "de" to "Germany", etc and then you can translate a country code to
 468         the English country name like so::
 469
 470          "$or{$lookup{tld_en,$field{tld}},.$field{tld}}"
 471
 472         If a tld isn't in the CDB (e.g. "com"), this will expand to ".com".
 473
 474         You can take this further and prepare a set of CDBs mapping tld codes
 475         to names in other languages - tld_fr for French, tld_de for German.
 476         Then if you have the ISO language code in ``$opt{lang}`` you can
 477         replace ``tld_en`` with ``tld_$or{$opt{lang},en}`` and automatically
 478         translate into the currently set language, or English if no language is
 479         set.
 480
 481 $lower{TEXT}
 482         return UTF-8 text ``TEXT`` converted to lower case.
 483
 484 $map{LIST,STUFF)
 485         map a list into the evaluated argument. If ``LIST`` contains ``1``,
 486         ``2`` then::
 487
 488             "$map{LIST,x$_=$_;}" = "x1=1;       x2=2;"
 489
 490         Note that $map{} returns a list (since Omega 0.5.0). If the tabs are a
 491         problem, then ``$foreach{LIST,STUFF}`` does the same thing but just
 492         concatenates the results directly rather than adding tabs to make a
 493         list.
 494
 495 $match{REGEX,STRING[,OPTIONS]}
 496         perform a regex match using Perl-compatible regular expressions. Returns
 497         true if a match is found, else it returns an empty string.
 498
 499         The optional OPTIONS argument can contain zero or more of the letters
 500         ``imsx``, which have the same meanings as the corresponding Perl regexp
 501         modifiers:
 502
 503         * ``i`` - make the pattern matching case-insensitive
 504         * ``m`` - make ``^``/``$`` match after/before embedded newlines
 505         * ``s`` - allows ``.`` in the pattern to match a linefeed
 506         * ``x`` - allow whitespace and ``#``-comments in the pattern
 507
 508 $msize
 509         estimated number of matches.
 510
 511 $msizeexact
 512         return ``true`` if ``$msize`` is exact (or "" if it is estimated).
 513         Exactly equivalent to: ``$eq{$msizelower,$msizeupper}``
 514
 515 $msizelower
 516         lower bound on number of matches.
 517
 518 $msizeupper
 519         upper bound on number of matches.
 520
 521 $nice{number}
 522         pretty print integer (with thousands separator).
 523
 524 $now
 525         number of seconds since the epoch (suitable for feeding to ``$date``).
 526         Whether ``$now`` returns the same value for repeated calls in the same
 527         Omega search session is unspecified.
 528
 529 $opt{OPT}
 530         lookup an option value (as set by ``$set``).
 531
 532 $opt{MAP,OPT}
 533         lookup an option within a map (as set by ``$setmap``).
 534
 535 $ord{STRING}
 536         return codepoint for first character of UTF-8 string.  If the argument
 537         is an empty string, then an empty string is returned.
 538
 539         For example, ``$ord{One more time}`` gives ``79``.
 540
 541         To convert a Unicode code point into a UTF-8 string, see ``$chr``.
 542
 543         Added in Omega 1.3.4.
 544
 545 $pack{NUMBER}
 546         converts a number to a 4 byte big-endian binary string
 547
 548 $percentage
 549         percentage score of current hit (in range 1-100).
 550
 551         You probably don't want to show these percentage scores to end
 552         users in new applications - they're not really a percentage of
 553         anything meaningful, and research seems to suggest that users
 554         don't find numeric scores in search results useful.
 555
 556 $prettyterm{TERM}
 557         convert a term to "user form", as it might be entered in a query.  If
 558         a matching term was entered in the query, just use that (the first
 559         occurrence if a term was generated multiple times from a query).
 560         Otherwise term prefixes are converted back to user forms as specified
 561         by ``$setmap{prefix,...}`` and ``$setmap{boolprefix,...}``.
 562
 563 $prettyurl{URL}
 564         Prettify URL.  This command undoes RFC3986 URL escaping which doesn't
 565         affect semantics in practice, in order to make a prettier version of a
 566         URL for displaying to the user (rather than in links), but which should
 567         still work if copied and pasted.
 568
 569 $query[{PREFIX}]
 570         list of query strings for prefix PREFIX.  Any tab characters in the
 571         query strings are converted to spaces before adding them to the list
 572         (since an OmegaScript list is a string with tabs in).
 573
 574         If PREFIX is omitted or empty, this is built from CGI ``P`` variable(s)
 575         plus possible added terms from ``ADD`` and ``X``.
 576
 577         If PREFIX is non-empty, this is built from CGI ``P.PREFIX`` variables.
 578
 579         Note: In Omega < 1.3.3, $query simply joins together the query strings
 580         with spaces rather than returning a list.
 581
 582 $querydescription
 583         a human readable description of the ``Xapian::Query`` object which
 584         omega builds.  Mostly useful for debugging omega itself.
 585
 586 $queryterms
 587         list of parsed query terms.
 588
 589 $range{START,END}
 590         return list of values between ``START`` and ``END``.
 591
 592 $random{HIGH}
 593         return a random value in the range [0, ``HIGH``].
 594
 595 $record[{ID}]
 596         raw record contents of document ``ID``.
 597
 598 $relevant[{ID}]
 599         document id ``ID`` if document is relevant, "" otherwise
 600         (side-effect: removes id from list of relevant documents
 601         returned by ``$relevants``).
 602
 603 $relevants
 604         return list of relevant documents
 605
 606 $score
 607         score (0-10) of current hit (equivalent to ``$div{$percentage,10}``).
 608
 609 $set{OPT,VALUE}
 610         set option value which may be looked up using ``$opt``.  You can use
 611         options as variables (for example, to store values you want to reuse
 612         without recomputing).  There are also several which Omega looks at
 613         and which you can set or use:
 614
 615         * decimal - the decimal separator ("." by default - localised query
 616           templates may want to set this to ",").
 617         * thousand - the thousands separator ("," by default - localised query
 618           templates may want to set this to ".", " ", or "").
 619         * stemmer - which stemming language to use ("english" by default, other
 620           values are as understood by ``Xapian::Stem``, so "none" means no
 621           stemming).
 622         * stem_strategy - tell the query parser how to apply the stemmer - can
 623           be one of:
 624
 625           + ``all``: stem all terms
 626           + ``all_z``: stem all terms and add a Z prefix
 627           + ``none``: don't stem any terms (ignoring any stemmer set)
 628           + ``some``: the default
 629           + ``some_full_pos``: like ``some`` but assume positional data has
 630             been stored for stemmed terms too.
 631
 632           Unknown values are ignored.  Added in Omega 1.4.8.
 633         * stem_all - if "true", then tell the query parser to stem all words,
 634           even capitalised ones.  Now deprecated in favour of setting
 635           ``stem_strategy`` to ``all``, and ignored if ``stem_strategy`` is
 636           also set.
 637         * fieldnames - if set to a non-empty value then the document data is
 638           parsed with each line being the value of a field, and the names
 639           are taken from entries in the list in fieldnames.  So
 640           ``$set{fieldnames,$split{title sample url}}`` will take the first
 641           line as the "title" field, the second as the "sample" field and the
 642           third as the "url" field.  Any lines without a corresponding field
 643           name will be ignored.  If unset or empty then the document data is
 644           parsed as one field per line in the format NAME=VALUE (where NAME is
 645           assumed not to contain '=').
 646         * weighting - set the weighting scheme to use, and (optionally) the
 647           parameters to use if the weighting scheme supports them.  The syntax
 648           is a string consisting of the scheme name followed by any parameters,
 649           all separated by whitespace.  Any parameters not specified will use
 650           their default values.
 651
 652           E.g. ``$set{weighting,bool}`` or ``$set{weighting,bm25 1 0.8}``
 653
 654           Valid scheme names are:
 655
 656           - ``bb2`` (in Omega >= 1.3.2)
 657           - ``bm25``
 658           - ``bm25+`` (in Omega >= 1.4.26)
 659           - ``bool``
 660           - ``coord`` (in Omega >= 1.4.1)
 661           - ``dicecoeff`` (in Omega >= 1.5.0)
 662           - ``dlh`` (in Omega >= 1.3.2)
 663           - ``dph`` (in Omega >= 1.3.2)
 664           - ``ifb2`` (in Omega >= 1.3.2)
 665           - ``ineb2`` (in Omega >= 1.3.2)
 666           - ``inl2`` (in Omega >= 1.3.2)
 667           - ``lm2stage`` (in Omega >= 1.5.0)
 668           - ``lmabsdiscount`` (in Omega >= 1.5.0)
 669           - ``lmdirichlet`` (in Omega >= 1.5.0)
 670           - ``lmjm`` (in Omega >= 1.5.0)
 671           - ``pl2`` (in Omega >= 1.3.2)
 672           - ``pl2+`` (in Omega >= 1.4.26)
 673           - ``tfidf`` (in Omega >= 1.3.1)
 674           - ``trad`` (deprecated since Omega 1.5.0)
 675
 676         * expansion - set the query expansion scheme to use, and (optionally)
 677           the parameters to use if the expansion scheme supports them. The
 678           syntax is the scheme name followed by any parameters, all separated
 679           by whitespace.  Any parameters not specified will use their default
 680           values.  Valid expansion schemes names are ``prob``, ``bo1`` and
 681           ``trad`` (deprecated alias for ``prob``).
 682
 683           E.g. ``$set{expansion,trad 2.0}``.  If not specified, the
 684           default scheme used is equivalent to ``$set{expansion,trad 1.0}``.
 685         * weightingpurefilter - normally a query consisting only of filter
 686           terms won't have relevance weights calculated.  This option allows
 687           you to specify a weighting scheme to use for such queries, with the
 688           same values supported as for ``weighting`` above.  For example,
 689           ``$set{weightingpurefilter,coord}`` will weight such queries by
 690           how many filter terms match each document.
 691
 692         Omega 1.2.5 and later also support the following options, which can be
 693         set to a non-empty value to enable the corresponding ``QueryParser``
 694         flag.  Omega sets ``flag_default`` to ``true`` by default - you can set
 695         it to an empty value to turn it off (``$set{flag_default,}``):
 696
 697         * flag_auto_multiword_synonyms
 698         * flag_auto_synonyms
 699         * flag_boolean
 700         * flag_boolean_any_case
 701         * flag_cjk_ngram (new in 1.2.22 and 1.3.4)
 702         * flag_ngrams (new in 1.4.23)
 703         * flag_default
 704         * flag_fuzzy (new in 1.5.0)
 705         * flag_lovehate
 706         * flag_no_positions (new in 1.4.19)
 707         * flag_partial
 708         * flag_phrase
 709         * flag_pure_not
 710         * flag_spelling_correction (see ``$suggestion`` for suggested
 711           correction)
 712         * flag_synonym
 713         * flag_wildcard
 714         * flag_wildcard_glob (new in 1.5.0)
 715         * flag_wildcard_multi (new in 1.5.0)
 716         * flag_wildcard_single (new in 1.5.0)
 717         * flag_word_breaks (new in 1.5.0)
 718
 719         Note that the ``Xapian::QueryParser::FLAG_ACCUMULATE`` flag is always
 720         enabled by Omega because it's needed for ``$stoplist`` and ``$unstem``
 721         to work correctly, and is deliberately not included in the above list.
 722
 723         Omega 1.2.7 added support for parsing different query fields with
 724         different prefixes and you can specify different QueryParser flags for
 725         each prefix - for example, for the ``XFOO`` prefix use
 726         ``XFOO:flag_pure_not``, etc.  The unprefixed constants provide a
 727         default value for these.  If a flag is set in the default, the prefix
 728         specific flag can unset it if it is set to the empty value (e.g.
 729         ``$set{flag_pure_not,1}$set{XFOO:flag_pure_not,}``).
 730
 731         You can use ``:flag_partial``, etc to set or unset a flag just for
 732         unprefixed fields.
 733
 734         Similarly, ``XFOO:stemmer`` specifies the stemmer to use for field
 735         ``XFOO``, with ``stemmer`` providing a default.
 736
 737         Omega 1.5.0 added support for specifying the operator to use to
 738         combine multiple parsed query strings.  By default this is ``AND``,
 739         but you can specify ``OR`` instead using ``$set{intra_query_op,OR}``
 740         (``or`` also works).  Currently other operators aren't supported.
 741
 742 $seterror{ERROR_MESSAGE}
 743         set error message for the current execution, which can also be looked
 744         up using ``$error``.
 745
 746         Using ``$seterror`` error early in template prevents running the query.
 747
 748         For example, ``$seterror`` can be used when the user enters a wrong
 749         parameter in the search.
 750
 751 $setrelevant{docids}
 752         add documents into the RSet
 753
 754 $setmap{MAP,NAME1,VALUE1,...}
 755         set a map of option values which may be looked up against using
 756         ``$opt{MAP,NAME}`` (maps with the same name are merged rather than
 757         the old map being completely replaced).
 758
 759         You can create and use of maps in your own templates, but Omega also
 760         has several standard maps used to control building the query:
 761
 762         Omega uses the "prefix" map to set the prefixes understood by the query
 763         parser.  So if you wish to translate a prefix of "author:" to A and
 764         "title:" to "S" you would use::
 765
 766          $setmap{prefix,author,A,title,S}
 767
 768         In Omega 1.3.0 and later, you can map a prefix in the query string to
 769         more than one term prefix by specifying an OmegaScript list, for
 770         example to search unprefixed and S prefix by default use this
 771         (this also shows how you can map from an empty query string prefix, and
 772         also that you can map to an empty term prefix - these don't require
 773         Omega 1.3.0, but become much more useful in combination with this new
 774         feature)::
 775
 776          $setmap{prefix,,$split{ S}}
 777
 778         Similarly, if you want to be able to restrict a search with a
 779         boolean filter from the text query (e.g. "group:" to "G") you
 780         would use::
 781
 782          $setmap{boolprefix,group,G}
 783
 784         Don't be tempted to add whitespace around the commas, unless you want
 785         it to be included in the names and values!
 786
 787         Another map (added in Omega 1.3.4) allows specifying any boolean
 788         prefixes which are non-exclusive, i.e. multiple filters of that
 789         type should be combined with ``OP_AND`` rather than ``OP_OR``.
 790         For example, if you have have a boolean filter on "material" using
 791         the ``XM`` prefix, and the items being searched are made of multiple
 792         materials, you likely want multiple material filters to restrict to
 793         items matching all the materials (the default it to restrict to any
 794         of the materials).  To specify this use
 795         ``$setmap{nonexclusiveprefix,XM,true}`` (any non-empty value can
 796         be used in place of ``true``) - this feature affect both filters
 797         from ``B`` CGI parameters (e.g. ``B=XMglass&B=XMwood`` and those
 798         from parsing the query (e.g. ``material:glass material:wood`` if
 799         ``$setmap{boolprefix,material,XM}`` is also in effect).
 800
 801         Note: you must set the prefix-related maps before the query is parsed.
 802         This is done as late as possible - the following commands require the
 803         query to be parsed: $prettyterm, $query, $querydescription, $queryterms,
 804         $relevant, $relevants, $setrelevant, $unstem, and also these commands
 805         require the match to be run which requires the query to be parsed:
 806         $freqs, $hitlist, $last, $lastpage, $msize, $msizeexact, $terms,
 807         $thispage, $time, $topdoc, $topterms.
 808
 809 $slice{LIST,POSITIONS}
 810         returns the elements from ``LIST`` at the positions listed in the
 811         second list ``POSITIONS``.  The first item is at position 0.
 812         Any positions which are out of range will be ignored.
 813
 814         For example, if ``LIST`` contains a, b, c, d then::
 815
 816          "$slice{LIST,2}" = "c"
 817          "$slice{LIST,1 3}" = "b        d"
 818          "$slice{LIST,$range{1,3}}" = "b        c       d"
 819          "$slice{LIST,$range{-10,10}}" = "a     b       c       d"
 820
 821 $snippet{TEXT[,LENGTH[,FLAGS[,BRA[,KET[,GAP]]]]]}
 822         Generate a context-sensitive snippet from ``TEXT`` using the C++ API
 823         ``Xapian::MSet::snippet()`` suitable for inserting into an HTML or XML
 824         document.
 825
 826         The snippet will be at most ``LENGTH`` bytes long (default: 200 if not
 827         specified or ``LENGTH`` is an empty string).  ``BRA`` and ``KET`` are
 828         added around matching terms in the sample (defaults: ``<strong>`` and
 829         ``</strong>``) and ``GAP`` is used to mark omitted parts of ``TEXT``
 830         (default: ``...``).
 831
 832         ``FLAGS`` contains zero or more of the flags that are supported by the
 833         C++ API separated by ``|`` - here they are specified as
 834         case-insensitive strings, and the leading ``SNIPPET_`` is optional.
 835
 836         For example::
 837
 838         $snippet{$field{sample},,background_model|empty_without_match,<b>,</b>}
 839
 840 $sort{LIST[,OPTIONS]}
 841         sort the entries in a list.  The sort order is an ascending string sort
 842         by byte value by default.  ``OPTIONS`` is zero or more of the following
 843         characters which control the sort operation:
 844
 845         * ``#`` : "natural number" sort suitable for use when generating
 846           drop-down lists.  Embedded digit sequences are handled specially:
 847           they are compared numerically, and sort before non-digits at the same
 848           point.  Digit sequences with the same numeric value are sorted
 849           such that the sequence with more leading zeros comes first (so when
 850           used with ``u`` only identical entries are removed).
 851         * ``r`` : reverse the sort order
 852         * ``u`` : output only the first (in input order) of an equal run
 853         * ``n`` : sort by string numerical value - the start of each entry is
 854           parsed as zero or more whitespace characters, an optional ``-``, zero
 855           or more digits, optionally followed by ``$opt{decimal}`` then zero or
 856           more digits.  Entries are regarded as equal if the numbers are equal
 857           and so only the first is kept with ``u``.  When ``u`` is not used,
 858           the order within groups of equal entries is resolved with a string
 859           sort.
 860
 861         Options ``#`` and ``n`` aren't valid together.
 862
 863 $sortableunserialise{STRING}
 864         Decodes ``STRING`` with ``Xapian::sortable_unserialise()`` and returns
 865         the resulting floating point value.  For example, this provides a way
 866         to decode values stored using the scriptindex ``valuenumeric`` action.
 867
 868         Added in Xapian 1.4.22.
 869
 870 $split{STRING}
 871
 872 $split{SPLIT,STRING}
 873         returns a list by splitting the string ``STRING`` into elements at each
 874         occurrence of the substring ``SPLIT``.  If ``SPLIT`` isn't specified,
 875         it defaults to a single space.  If ``SPLIT`` is empty, ``STRING`` is
 876         split into individual bytes.
 877
 878         For example::
 879
 880          "$split{one two three}" = "one two     three"
 881
 882 $srandom{SEED}
 883         ``SEED`` specifies a seed for random number generation.
 884
 885 $stoplist
 886         returns a list of any terms in the query which were ignored as
 887         stopwords.  Since Omega 1.4.18 ``$stoplist`` reports such terms for
 888         all query strings parsed as part of the current query - in previous
 889         versions only this only reported stopwords for the query string
 890         which was parsed last (which would be the one with the prefix sorting
 891         last in byte sort order, and if there were multiple such query strings
 892         then the one specified last).
 893
 894 $subdb[{DOCID}]
 895         return the name from a ``DB`` parameter for the sub-database containing
 896         ``DOCID``.
 897
 898         If ``DOCID`` is omitted it defaults to the current document in the
 899         hitlist.
 900
 901         Prior to Xapian 1.4.12 the implementation assumed that each omega
 902         database name corresponded to a single Xapian database and if a
 903         database name referred to a stub database file expanding to multiple
 904         Xapian databases then this command would misbehave.  In 1.4.12 and
 905         later this case is taken into account.
 906
 907 $subid[{DOCID}]
 908         return the docid in ``$subdb{DOCID}`` corresponding to ``DOCID`` in the
 909         combined database.
 910
 911         If ``DOCID`` is omitted it defaults to the current document in the
 912         hitlist.
 913
 914         Prior to Xapian 1.4.12 the implementation assumed that each omega
 915         database name corresponded to a single Xapian database and if a
 916         database name referred to a stub database file expanding to multiple
 917         Xapian databases then this command would misbehave.  In 1.4.12 and
 918         later this case is taken into account.
 919
 920 $substr{STRING,START[,LENGTH]}
 921         returns the substring of ``STRING`` which starts at byte position
 922         ``START`` (the start of the string being 0) and is ``LENGTH`` bytes
 923         long (or to the end of ``STRING`` if ``STRING`` is less than
 924         ``START``+``LENGTH`` bytes long).  If ``LENGTH`` is omitted, the
 925         substring from ``START`` to the end of ``STRING`` is returned.
 926
 927         If ``START`` is negative, it counts back from the end of ``STRING`` (so
 928         ``$substr{hello,-1}`` is ``o``).
 929
 930         If LENGTH is negative, it instead specifies the number of bytes
 931         to omit from the end of STRING (so "$substr{example,2,-2}" is "amp").
 932         Note that this means that "$substr{STRING,0,N}$substr{STRING,N}" is
 933         "STRING" whether N is positive, negative or zero.
 934
 935 $suggestion
 936         if ``$set{flag_spelling_correction,true}`` was done before the query
 937         was parsed, then ``$suggestion`` will return any suggested spelling
 938         corrected version of the query string.  If there are no spelling
 939         corrections, it will return an empty string.
 940
 941 $termprefix{TERM}
 942         return the prefix (if any) from a term.  Added in Omega 1.4.6.
 943
 944 $terms[{PREFIX}]
 945         list of query terms matching the current hit.  The ability to specify a
 946         prefix was added in Omega 1.3.5.  If no prefix is specified (i.e.
 947         ``$terms``), then only terms from the query string(s) are returned.
 948         This is different to an empty prefix (i.e. ``$terms{}``) which returns
 949         all query terms matching the current hit, so also includes filter
 950         terms.
 951
 952 $thispage
 953         page number of current page.
 954
 955 $time
 956         how long the match took (in seconds) e.g. ``0.078534``.  If no timing
 957         information was available, returns an empty value.
 958
 959 $topdoc
 960         first document on current page of hit list (counting from 0)
 961
 962 $topterms[{N}]
 963         list of up to ``N`` top relevance feedback terms (default 16)
 964
 965 $transform{REGEXP,SUBST,STRING[,OPTIONS]}
 966         transform string using Perl-compatible regular expressions.  This
 967         command is sort of like the Perl code::
 968
 969          my $string = STRING;
 970          $string =~ s/REGEXP/SUBST/;
 971          print $string;
 972
 973         In SUBST, ``\1`` to ``\9`` are substituted by the 1st to 9th bracket
 974         grouping (or are empty if there is no such bracket grouping).  ``\\``
 975         is a literal backslash.
 976
 977         The optional OPTIONS argument is supported by Omega 1.3.4 and later.
 978         It can contain zero or more of the letters ``gimsx``, which have the
 979         same meanings as the corresponding Perl regexp modifiers:
 980
 981          * ``g`` - replace all occurrences of the pattern in the string
 982          * ``i`` - make the pattern matching case-insensitive
 983          * ``m`` - make ``^``/``$`` match after/before embedded newlines
 984          * ``s`` - allows ``.`` in the pattern to match a linefeed
 985          * ``x`` - allow whitespace and ``#``-comments in the pattern
 986
 987 $truncate{STRING,LEN[,IND[,IND2]]}
 988         truncate STRING to LEN bytes, but try to break after a word (unless
 989         that would mean truncating to much less than LEN).  If we have to
 990         split a word, then IND is appended (if specified).  If we have to
 991         truncate (but don't split a word) then IND2 is appended (if specified).
 992         For example::
 993
 994          $truncate{$field{text},500,..., ...}
 995
 996 $uniq{LIST}
 997         remove adjacent duplicates, for example from an already sorted list
 998         (similar to the Unix ``uniq`` command line tool).
 999
1000 $unique{LIST}
1001         remove duplicates from a list - unlike ``$uniq``, duplicates don't
1002         need to be adjacent.  The first of each entry is kept, and order is
1003         preserved.  If the input list is already sorted then ``$uniq`` is
1004         more efficient.
1005
1006 $unpack{BINARYSTRING}
1007         converts a 4 byte big-endian binary string to a number, for example::
1008
1009          $date{$unpack{$value{0}}}
1010
1011 $unprefix{TERM}
1012         remove the prefix (if any) from a term.  Added in Omega 1.4.6.
1013
1014 $unstem{TERM}
1015         maps a stemmed term to a list of the unstemmed forms of it used in
1016         the query.  Since Omega 1.4.18 ``$unstem`` reports unstemmed forms in
1017         all query strings parsed as part of the current query - in previous
1018         versions only this only reported unstemmed forms from the query string
1019         which was parsed last (which would be the one with the prefix sorting
1020         last in byte sort order, and if there were multiple such query strings
1021         then the one specified last).
1022
1023 $upper{TEXT}
1024         return UTF-8 text ``TEXT`` converted to upper case.
1025
1026 $url{TEXT}
1027         url encode argument
1028
1029 $value{SLOT[,DOCID]}
1030         returns value from slot ``SLOT`` for document ``DOCID``.  If ``DOCID``
1031         is omitted then the current hit is used (which only works inside
1032         ``$hitlist``).
1033
1034 $valuelowerbound{SLOT}
1035         returns a lower bound on values in slot ``SLOT`` (empty values don't
1036         count towards this bound).  The bound is not necessarily tight - i.e.
1037         it may be lower than the lowest value which actually occurs.
1038
1039         Added in Omega 1.4.22.
1040
1041 $valueupperbound{SLOT}
1042         returns an upper bound on values in slot ``SLOT``. The bound is not
1043         necessarily tight - i.e. it may be higher than the highest value which
1044         actually occurs.
1045
1046         Added in Omega 1.4.22.
1047
1048 $version
1049         omega version string - e.g. "xapian-omega 1.2.6"
1050
1051 $weight
1052         raw document weight of the current hit, as a floating point value
1053         (mostly useful for debugging purposes).
1054
1055 Numeric Operators:
1056 ==================
1057
1058 OmegaScript numeric operators are forgiving in their interpretation of
1059 numeric arguments.  Any characters after an initial span of ASCII digits
1060 are ignored, so ``123abc`` is interpreted the same as ``123`` and values with
1061 no leading digits are interpreted as zero, including an empty string.
1062
1063 A reason for this behaviour is that it gives more robust handling for numeric
1064 values which are specified in CGI parameters - for example, if an Omega URL
1065 is quoted in a text document or email, punctuation after it may get included
1066 in the URL when it's turned into a link or cut and pasted.
1067
1068 $add{...}
1069         add arguments together (if called with one argument, this will convert
1070         it to an integer and back, which ensures it is an integer).
1071
1072 $div{A,B}
1073         returns int(A / B) (or the text "divide by 0" if B is zero)
1074
1075 $mod{A,B}
1076         returns int(A % B) (or the text "divide by 0" if B is zero)
1077
1078 $max{A,...}
1079         maximum of the arguments
1080
1081 $min{A,...}
1082         minimum of the arguments
1083
1084 $mul{A,B,...}
1085         multiply arguments together
1086
1087 $muldiv{A,B,C}
1088         returns int((A * B) / C) (or the text "divide by 0" if C is zero)
1089
1090 $sub{A,B}
1091         returns (A - B)
1092
1093 Logical Operators:
1094 ==================
1095
1096 OmegaScript logical operators treat an empty string as a false logical value
1097 and any non-empty string as true.
1098
1099 $and{...}
1100         logical short-cutting "and" of its arguments - evaluates
1101         arguments until it finds an empty one (and returns "") or
1102         has evaluated them all (returns "true")
1103
1104 $not{A}
1105         returns "true" for the empty string, "" otherwise.
1106
1107 $or{...}
1108         logical short-cutting "or" of its arguments - returns first
1109         non-empty argument
1110
1111 Comparison Operators:
1112 =====================
1113
1114 These return a value suitable for use in ``$if``, ``$and``, ``$or``, etc.
1115
1116 $eq{A,B}
1117         returns "true" if A and B are the same string, "" otherwise.
1118
1119 $ge{A,B}
1120         returns "true" if A is numerically >= B, "" otherwise.
1121
1122 $gt{A,B}
1123         returns "true" if A is numerically > B, "" otherwise.
1124
1125 $le{A,B}
1126         returns "true" if A is numerically <= B, "" otherwise.
1127
1128 $lt{A,B}
1129         returns "true" if A is numerically < B, "" otherwise.
1130
1131 $ne{A,B}
1132         returns "true" if A and B are not the same string, "" if they are.
1133
1134 Control:
1135 ========
1136
1137 $cond{COND1,THEN1[,COND2,THEN2]...[,ELSE]}
1138         evaluates ``COND1``, ``COND2``, ... in turn until a non-empty value is
1139         obtained, and then evaluates and returns the corresponding ``THEN``.
1140         If all ``COND`` values expand to empty values, then evaluates and
1141         returns ``ELSE`` (if present, otherwise returns nothing).
1142
1143         ``$cond`` provides a neater way of writing a cascading series of
1144         ``$if`` checks.  If there's only one condition, ``$cond`` is equivalent
1145         to ``$if``.
1146
1147         Added in Omega 1.4.6.
1148
1149 $if{COND[,THEN[,ELSE]]}
1150         if ``COND`` is non-empty, evaluates and returns ``THEN``; otherwise
1151         evaluates and returns ``ELSE``.  If ``THEN`` and/or ``ELSE`` are omitted
1152         then returns nothing.  You can use ``$if{COND}`` to evaluate ``COND``
1153         but discard the result of that evaluation, which can be useful if
1154         ``COND`` has side-effects.
1155
1156         The ability to omit ``THEN`` was added in Omega 1.4.15.
1157
1158 $include{FILE[,FALLBACK]}
1159         include another OmegaScript file ``FILE``.  If opening ``FILE`` fails, then
1160         ``FALLBACK`` is evaluated and returned.
1161
1162         Support for the ``FALLBACK`` argument was added in Omega 1.4.18.
1163
1164 $switch{EXPR,CASE1,VALUE1,[CASE2,VALUE2]...[,DEFAULT]}
1165         first evaluates ``EXPR``, and then evaluates ``CASE1``, ``CASE2``, ...
1166         in turn until one of them has the same value as ``EXPR`` did, and then
1167         evaluates and returns the corresponding ``VALUE``.  If none of the
1168         ``CASE`` values matches, then evaluates and returns ``DEFAULT`` (if
1169         present, otherwise returns nothing).
1170
1171         Added in Omega 1.4.6.