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}
  64         add filter term ``TERM`` as if it had been passed as a ``B`` CGI
  65         parameter.  You must use ``$addfilter`` before any command which
  66         requires the query to have been parsed - see ``$setmap`` for a list
  67         of these commands.
  68
  69 $allterms{docid}
  70         list of all terms matching document
  71
  72 $cgi{CGI}
  73         lookup the value of a CGI parameter.  If the same parameter has
  74         multiple values, ``$cgi`` will pick one arbitrarily - use ``$cgilist``
  75         if you want all the values.
  76
  77 $cgilist{CGI}
  78         return a list of all values of a CGI parameter
  79
  80 $chr{CODEPOINT}
  81         return UTF-8 for the given Unicode codepoint, e.g. ``$chr{127866}``
  82         should display as a beer mug if the font has a suitable glyph.
  83
  84         Since ASCII is a subset of Unicode, you can also produce control
  85         characters, e.g. ``$chr{13}`` gives a carriage return character.
  86
  87         To convert a UTF-8 character to a Unicode codepoint, see ``$ord``.
  88
  89         Added in Omega 1.3.4.
  90
  91 $collapsed
  92         number of other documents collapsed into current hit inside
  93         ``$hitlist``, which might be used like so::
  94
  95              $if{$ne{$collapsed,0},at least $collapsed hidden results ($value{$cgi{COLLAPSE}})}
  96
  97 $csv{STRING[,ALWAYS_ESCAPE]}
  98         encode STRING for use as a field in a CSV file.  By default, escaping
  99         is done as described in RFC4180, except that we treat any byte value
 100         not otherwise mentioned as being 'TEXTDATA' (so %x00-%x09, %x0B-%x0C,
 101         %x0E-%x1F, %x7F-%xFF are also permitted there).  Examples:
 102
 103         ``$csv{Safe in CSV!}`` gives ``Safe in CSV!``
 104
 105         ``$csv{Not "safe"}`` gives ``"Not ""safe"""``
 106
 107         ``$csv{3$. 2$. 1}`` gives ``"3, 2, 1"``
 108
 109         Some CSV consumers don't follow the RFC, in which case you may need
 110         to encode additional values.  For this reason, ``$csv`` provides an
 111         highly conservative alternative mode in which any double quote
 112         characters in the string are doubled, and the result always wrapped in
 113         double quotes.  To select this mode, pass a second non-empty argument.
 114         Examples:
 115
 116         ``$csv{Quote anyway,1}`` gives ``"Quote anyway"``
 117
 118         ``$csv{Not "safe",1}`` gives ``"Not ""safe"""``
 119
 120         Added in Omega 1.3.4.
 121
 122 $date{TIME_T[,FMT]}
 123         convert a time_t to strftime ``FMT`` (default: ``YYYY-MM-DD``).  The
 124         conversion is done in timezone UTC.
 125
 126 $dbname
 127         database name (multiple names are returned separated by "/").
 128
 129 $dbsize
 130         number of documents in the database (if multiple databases are being
 131         searched, this gives the total number).
 132
 133 $def{MACRONAME,VALUE}
 134         define a macro which can take 0 to 9 arguments.  You can call it with
 135         ``$MACRONAME`` (if it take 0 arguments) or
 136         ``$MACRONAME{ARG1,ARG2,ARG3}`` is it takes arguments.  In value,
 137         arguments are available as ``$1``, ``$2``, ...  ``$9``.  In the current
 138         implementation, macros can override OmegaScript commands, but this
 139         shouldn't be relied on.  It's recommended to use capitalised names for
 140         macros to avoid collision with future OmegaScript commands.
 141
 142 $defaultop
 143         "and" or "or" (set from CGI variable DEFAULTOP).
 144
 145 $emptydocs[{TERM}]
 146         returns a list of docids of any documents with document length zero
 147         (such documents probably only contain scanned images, rather than
 148         machine readable text, or suggest the input filter isn't working well).
 149         If TERM is specified, only consider documents matching TERM, otherwise
 150         all documents are considered (so Tapplication/pdf reports all PDF files
 151         for which no text was found).
 152
 153         If you're using omindex, note that it skips files with zero size, so
 154         these won't get reported here as they aren't present in the database.
 155
 156 $env{VAR}
 157         lookup variable ``VAR`` in the environment.
 158
 159 $error
 160         error message (e.g. if a database wouldn't open, or the query couldn't
 161         be parsed, or a Xapian exception has been thrown) or empty if there
 162         wasn't an error.
 163
 164 $field{NAME[,DOCID]}
 165         lookup field ``NAME`` in document ``DOCID``.  If ``DOCID`` is omitted
 166         then the current hit is used (which only works inside ``$hitlist``).
 167
 168         If multiple instances of field exist the field values are returned tab
 169         separated, which means you can pass the results to ``$map``, e.g.::
 170
 171             $map{$field{keywords},<b>$html{$_}</b><br>}
 172
 173 $filesize{SIZE}
 174         pretty printed filesize (e.g. ``1 byte``, ``100 bytes``, ``2.1K``,
 175         ``4.0M``, ``1.3G``).  If ``SIZE`` is negative, expands to nothing.
 176
 177 $filters
 178         serialised version of filter-like settings (currently ``B``, ``N``,
 179         ``START``, ``END``, ``SPAN``, ``COLLAPSE``, ``DOCIDORDER``, ``SORT``,
 180         ``SORTREVERSE``, ``SORTAFTER``, and ``DEFAULTOP``) - set ``xFILTERS``
 181         to this so that Omega can detect when the filters have changed and
 182         force the first page.
 183
 184 $filterterms{PREFIX}
 185         list of all terms in the database with prefix ``PREFIX``, intended to
 186         be used to allow drop-down lists and sets of radio buttons to be
 187         dynamically generated, e.g.::
 188
 189              Hostname:
 190              <SELECT NAME="B">
 191              <OPTION VALUE=""
 192              $if{$map{$cgilist{B},$eq{$substr{$_,0,1},H}},,SELECTED}> Any
 193              $map{$filterterms{H},
 194              <OPTION VALUE="$html{$_}" $if{$find{$cgilist{B},$html{$_}},SELECTED}>
 195              $html{$substr{$_,1}}
 196              </OPTION>
 197              }
 198              </SELECT>
 199
 200 $find{LIST,STRING}
 201         returns the number of the first entry in ``LIST`` which is equal to
 202         ``STRING`` (starting from 0) or the empty string if no entry matches.
 203
 204 $fmt
 205         name of current format (as set by CGI parameter``FMT``, or the default)
 206
 207 $freq{term}
 208         frequency of a term
 209
 210 $highlight{TEXT,LIST,[OPEN,[CLOSE]]}
 211         html escape string (<>&, etc) and highlight any terms from ``LIST``
 212         that appear in ``TEXT`` by enclosing them in ``OPEN`` and ``CLOSE``.
 213         If ``OPEN`` is specified, but close is omitted, ``CLOSE`` defaults to
 214         the appropriate closing tag for ``OPEN`` (i.e. with a "/" in front and
 215         any parameters removed).  If both are omitted, then ``OPEN`` is set to:
 216         ``<b style="color:XXXXX;background-color:#YYYYYY">`` (where ``YYYYYY``
 217         cycles through ``ffff66`` ``99ff99`` ``99ffff`` ``ff66ff`` ``ff9999``
 218         ``990000`` ``009900`` ``996600`` ``006699`` ``990099`` and ``XXXXX``
 219         is ``black`` is ``YYYYYY`` contains an ``f``, and otherwise ``white``)
 220         and ``CLOSE`` is ``</b>``.
 221
 222 $hit
 223         MSet index of current doc (first document in MSet is 0, so if
 224         you want to number the hits 1, 2, 3, ... use ``$add{$hit,1}``).
 225
 226 $hitlist{FMT}
 227         display hitlist using format ``FMT``.
 228
 229 $hitsperpage
 230         hits per page (as set by ``HITSPERPAGE``, or the default)
 231
 232 $hostname{URL}
 233         return the hostname from url ``URL``
 234
 235 $html{TEXT}
 236         html escape string (``<>&"`` are escaped to ``&lt;``, etc).
 237
 238 $htmlstrip{TEXT}
 239         html strip tags from string (``<...>``, etc).
 240
 241 $httpheader{NAME,VALUE}
 242         specify an additional HTTP header to be generated by Omega.
 243         For example::
 244
 245          $httpheader{Cache-Control,max-age=0$.private}
 246
 247         If ``Content-Type`` is not specified by the template, it defaults
 248         to ``text/html``.  Headers must be specified before any other
 249         output from the OmegaScript template - any ``$httpheader{}``
 250         commands found later in the template will be silently ignored.
 251
 252 $id
 253         document id of current document
 254
 255 $json{STRING}
 256         encode STRING as a JSON string (not including the enclosing quotes), e.g.
 257         ``$json{The path is "C:\"}`` gives ``The path is \"C:\\\"``
 258
 259         Added in Omega 1.3.1.
 260
 261 $jsonarray{LIST}
 262         encodes LIST (a string of tab-separated values) as a JSON array, e.g.
 263         ``$jsonarray{$split{a "b" c:\}}`` gives ``["a","\"b\"","c:\\"]``
 264
 265         Added in Omega 1.3.1, but buggy until 1.3.4.
 266
 267 $last
 268         MSet index one beyond the end of the current page (so ``$hit`` runs
 269         from ``0`` to ``$sub{$last,1}``).
 270
 271 $lastpage
 272         number of last page of hits (may be an underestimate unless
 273         ``$thispage`` == ``$lastpage``).
 274
 275 $length{LIST}
 276         number of entries in ``LIST``.
 277
 278 $list{LIST,...}
 279         pretty print list. If ``LIST`` contains 1, 2, 3, 4 then::
 280
 281          "$list{LIST,$. }" = "1, 2, 3, 4"
 282          "$list{LIST,$. , and }" = "1, 2, 3 and 4"
 283          "$list{LIST,List ,$. ,.}" = "List 1, 2, 3, 4."
 284          "$list{LIST,List ,$. , and ,.}" = "List 1, 2, 3 and 4."
 285
 286         NB ``$list`` returns an empty string for an empty list (so the
 287         last two forms aren't redundant as it may at first appear).
 288
 289 $log{LOGFILE[,ENTRY]}
 290         write to the log file ``LOGFILE`` in directory ``log_dir`` (set in
 291         ``omega.conf``).  ``ENTRY`` is the OmegaScript for the log entry, and a
 292         linefeed is appended.  If ``LOGFILE`` cannot be opened for writing,
 293         nothing is done (and ``ENTRY`` isn't evaluated).  ``ENTRY`` defaults to
 294         a format similar to the Common Log Format used by webservers.
 295
 296 $lookup{CDBFILE,KEY}
 297         Return the tag corresponding to key ``KEY`` in the CDB file
 298         ``CDBFILE``.  If the file doesn't exist, or ``KEY`` isn't a key in it,
 299         then ``$lookup`` expands to nothing.  CDB files are compact disk based
 300         hashtables.  For more information and public domain software which can
 301         create CDB files, please visit: http://www.corpit.ru/mjt/tinycdb.html
 302
 303         An example of how this might be used is to map top-level domains to
 304         country names.  Create a CDB file tld_en which maps "fr" to "France",
 305         "de" to "Germany", etc and then you can translate a country code to
 306         the English country name like so::
 307
 308          "$or{$lookup{tld_en,$field{tld}},.$field{tld}}"
 309
 310         If a tld isn't in the CDB (e.g. "com"), this will expand to ".com".
 311
 312         You can take this further and prepare a set of CDBs mapping tld codes
 313         to names in other languages - tld_fr for French, tld_de for German.
 314         Then if you have the ISO language code in ``$opt{lang}`` you can
 315         replace ``tld_en`` with ``tld_$or{$opt{lang},en}`` and automatically
 316         translate into the currently set language, or English if no language is
 317         set.
 318
 319 $lower{TEXT}
 320         return UTF-8 text ``TEXT`` converted to lower case.
 321
 322 $map{LIST,STUFF)
 323         map a list into the evaluated argument. If ``LIST`` is
 324         1, 2 then::
 325
 326          "$map{LIST,x$_ = $_; }" = "x1 = 1;     x2 = 2; "
 327
 328         Note that $map{} returns a list (this is a change from older
 329         versions). If the tabs are a problem, use $list{$map{...},}
 330         to get rid of them.
 331
 332 $msize
 333         estimated number of matches.
 334
 335 $msizeexact
 336         return ``true`` if ``$msize`` is exact (or "" if it is estimated).
 337
 338 $nice{number}
 339         pretty print integer (with thousands separator).
 340
 341 $now
 342         number of seconds since the epoch (suitable for feeding to ``$date``).
 343         Whether ``$now`` returns the same value for repeated calls in the same
 344         Omega search session is unspecified.
 345
 346 $opt{OPT}
 347         lookup an option value (as set by ``$set``).
 348
 349 $opt{MAP,OPT}
 350         lookup an option within a map (as set by ``$setmap``).
 351
 352 $ord{STRING}
 353         return codepoint for first character of UTF-8 string.  If the argument
 354         is an empty string, then an empty string is returned.
 355
 356         For example, ``$ord{One more time}`` gives ``79``.
 357
 358         To convert a Unicode code point into a UTF-8 string, see ``$chr``.
 359
 360         Added in Omega 1.3.4.
 361
 362 $pack{NUMBER}
 363         converts a number to a 4 byte big-endian binary string
 364
 365 $percentage
 366         percentage score of current hit (in range 1-100).
 367
 368         You probably don't want to show these percentage scores to end
 369         users in new applications - they're not really a percentage of
 370         anything meaningful, and research seems to suggest that users
 371         don't find numeric scores in search results useful.
 372
 373 $prettyterm{TERM}
 374         convert a term to "user form", as it might be entered in a query.  If
 375         a matching term was entered in the query, just use that (the first
 376         occurrence if a term was generated multiple times from a query).
 377         Otherwise term prefixes are converted back to user forms as specified
 378         by ``$setmap{prefix,...}`` and ``$setmap{boolprefix,...}``.
 379
 380 $prettyurl{URL}
 381         Prettify URL.  This command undoes RFC3986 URL escaping which doesn't
 382         affect semantics in practice, in order to make a prettier version of a
 383         URL for displaying to the user (rather than in links), but which should
 384         still work if copied and pasted.
 385
 386 $query[{PREFIX}]
 387         list of query strings for prefix PREFIX.  Any tab characters in the
 388         query strings are converted to spaces before adding them to the list
 389         (since an OmegaScript list is a string with tabs in).
 390
 391         If PREFIX is omitted or empty, this is built from CGI ``P`` variable(s)
 392         plus possible added terms from ``ADD`` and ``X``.
 393
 394         If PREFIX is non-empty, this is built from CGI ``P.PREFIX`` variables.
 395
 396         Note: In Omega < 1.3.3, $query simply joins together the query strings
 397         with spaces rather than returning a list.
 398
 399 $querydescription
 400         a human readable description of the ``Xapian::Query`` object which
 401         omega builds.  Mostly useful for debugging omega itself.
 402
 403 $queryterms
 404         list of probabilistic query terms.
 405
 406 $range{START,END}
 407         return list of values between ``START`` and ``END``.
 408
 409 $record[{ID}]
 410         raw record contents of document ``ID``.
 411
 412 $relevant[{ID}]
 413         document id ``ID`` if document is relevant, "" otherwise
 414         (side-effect: removes id from list of relevant documents
 415         returned by ``$relevants``).
 416
 417 $relevants
 418         return list of relevant documents
 419
 420 $score
 421         score (0-10) of current hit (equivalent to ``$div{$percentage,10}``).
 422
 423 $set{OPT,VALUE}
 424         set option value which may be looked up using ``$opt``.  You can use
 425         options as variables (for example, to store values you want to reuse
 426         without recomputing).  There are also several which Omega looks at
 427         and which you can set or use:
 428
 429         * decimal - the decimal separator ("." by default - localised query
 430           templates may want to set this to ",").
 431         * thousand - the thousands separator ("," by default - localised query
 432           templates may want to set this to ".", " ", or "").
 433         * stemmer - which stemming language to use ("english" by default, other
 434           values are as understood by ``Xapian::Stem``, so "none" means no
 435           stemming).
 436         * stem_all - if "true", then tell the query parser to stem all words,
 437           even capitalised ones.
 438         * spelling - if "true", then the query parser spelling correction
 439           feature is enabled and ``$suggestion`` can be used.  Deprecated -
 440           use flag_spelling_correction instead (which was added in version
 441           1.2.5).
 442         * fieldnames - if set to a non-empty value then the document data is
 443           parsed with each line being the value of a field, and the names
 444           are taken from entries in the list in fieldnames.  So
 445           ``$set{fieldnames,$split{title sample url}}`` will take the first
 446           line as the "title" field, the second as the "sample" field and the
 447           third as the "url" field.  Any lines without a corresponding field
 448           name will be ignored.  If unset or empty then the document data is
 449           parsed as one field per line in the format NAME=VALUE (where NAME is
 450           assumed not to contain '=').
 451         * weighting - set the weighting scheme to use, and (optionally) the
 452           parameters to use if the weighting scheme supports them.  The syntax
 453           is a string consisting of the scheme name followed by any parameters,
 454           all separated by whitespace.  Any parameters not specified will use
 455           their default values.  Valid scheme names are
 456           ``bb2`` (in Omega >= 1.3.2), ``bm25``, ``bool``,
 457           ``dlh`` (in Omega >= 1.3.2), ``dph`` (in Omega >= 1.3.2),
 458           ``ifb2`` (in Omega >= 1.3.2), ``ineb2`` (in Omega >= 1.3.2),
 459           ``inl2`` (in Omega >= 1.3.2), ``lm`` (in Omega >= 1.3.2),
 460           ``pl2`` (in Omega >= 1.3.2), ``tfidf`` (in Omega >= 1.3.1),
 461           and ``trad``.  e.g.  ``$set{weighting,bm25 1 0.8}``
 462
 463         * expansion - set the query expansion scheme to use, and (optionally)
 464           the parameters to use if the expansion scheme supports them. The syntax
 465           is a string consisting of the scheme name followed by any parameters,
 466           all separated by whitespace.  Any parameters not specified will use
 467           their default values.  Valid expansion schemes names are
 468           ``trad`` and ``bo1``.  e.g.
 469           ``$set{expansion,trad 2.0}``
 470
 471         Omega 1.2.5 and later support the following options, which can be set
 472         to a non-empty value to enable the corresponding ``QueryParser`` flag.
 473         Omega sets ``flag_default`` to ``true`` by default - you can set it to
 474         an empty value to turn it off (``$set{flag_default,}``):
 475
 476         * flag_auto_multiword_synonyms
 477         * flag_auto_synonyms
 478         * flag_boolean
 479         * flag_boolean_any_case
 480         * flag_cjk_ngram (new in 1.2.22 and 1.3.4)
 481         * flag_default
 482         * flag_lovehate
 483         * flag_partial
 484         * flag_phrase
 485         * flag_pure_not
 486         * flag_spelling_correction
 487         * flag_synonym
 488         * flag_wildcard
 489
 490         Omega 1.2.7 added support for search fields with a probabilistic
 491         prefix, and you can set different QueryParser flags for each prefix -
 492         for example, for the ``XFOO`` prefix use ``XFOO:flag_pure_not``, etc.
 493         The unprefixed constants provide a default value for these.  If a flag
 494         is set in the default, the prefix specific flag can unset it if it
 495         is set to the empty value (e.g.
 496         ``$set{flag_pure_not,1}$set{XFOO:flag_pure_not,}``).
 497
 498         You can use ``:flag_partial``, etc to set or unset a flag just for
 499         unprefixed fields.
 500
 501         Similarly, ``XFOO:stemmer`` specifies the stemmer to use for field
 502         ``XFOO``, with ``stemmer`` providing a default.
 503
 504 $setrelevant{docids}
 505         add documents into the RSet
 506
 507 $setmap{MAP,NAME1,VALUE1,...}
 508         set a map of option values which may be looked up against using
 509         ``$opt{MAP,NAME}`` (maps with the same name are merged rather than
 510         the old map being completely replaced).
 511
 512         You can create and use of maps in your own templates, but Omega also
 513         has several standard maps used to control building the query:
 514
 515         Omega uses the "prefix" map to set the prefixes understood by the query
 516         parser.  So if you wish to translate a prefix of "author:" to A and
 517         "title:" to "S" you would use::
 518
 519          $setmap{prefix,author,A,title,S}
 520
 521         In Omega 1.3.0 and later, you can map a prefix in the query string to
 522         more than one term prefix by specifying an OmegaScript list, for
 523         example to search unprefixed and S prefix by default use this
 524         (this also shows how you can map from an empty query string prefix, and
 525         also that you can map to an empty term prefix - these don't require
 526         Omega 1.3.0, but become much more useful in combination with this new
 527         feature)::
 528
 529          $setmap{prefix,,$split{ S}}
 530
 531         Similarly, if you want to be able to restrict a search with a
 532         boolean filter from the text query (e.g. "group:" to "G") you
 533         would use::
 534
 535          $setmap{boolprefix,group,G}
 536
 537         Don't be tempted to add whitespace around the commas, unless you want
 538         it to be included in the names and values!
 539
 540         Another map (added in Omega 1.3.4) allows specifying any boolean
 541         prefixes which are non-exclusive, i.e. multiple filters of that
 542         type should be combined with ``OP_AND`` rather than ``OP_OR``.
 543         For example, if you have have a boolean filter on "material" using
 544         the ``XM``` prefix, and the items being searched are made of multiple
 545         materials, you likely want multiple material filters to restrict to
 546         items matching all the materials (the default it to restrict to any
 547         of the materials).  To specify this use
 548         ``$setmap{nonexclusiveprefix,XM,true}`` (any non-empty value can
 549         be used in place of ``true``) - this feature affect both filters
 550         from ``B`` CGI parameters (e.g. ``B=XMglass&B=XMwood``` and those
 551         from parsing the query (e.g. ``material:glass material:wood`` if
 552         ``$setmap{boolprefix,material,XM}`` is also in effect).
 553
 554         Note: you must set the prefix-related maps before the query is parsed.
 555         This is done as late as possible - the following commands require the
 556         query to be parsed: $prettyterm, $query, $querydescription, $queryterms,
 557         $relevant, $relevants, $setrelevant, $unstem, and also these commands
 558         require the match to be run which requires the query to be parsed:
 559         $freqs, $hitlist, $last, $lastpage, $msize, $msizeexact, $terms,
 560         $thispage, $time, $topdoc, $topterms.
 561
 562 $slice{LIST,POSITIONS}
 563         returns the elements from ``LIST`` at the positions listed in the
 564         second list ``POSITIONS``.  The first item is at position 0.
 565         Any positions which are out of range will be ignored.
 566
 567         For example, if ``LIST`` contains a, b, c, d then::
 568
 569          "$slice{LIST,2}" = "c"
 570          "$slice{LIST,1 3}" = "b        d"
 571          "$slice{LIST,$range{1,3}}" = "b        c       d"
 572          "$slice{LIST,$range{-10,10}}" = "a     b       c       d"
 573
 574 $snippet{TEXT[,LENGTH]}
 575         Generate a context-sensitive snippet from ``TEXT`` using
 576         ``Xapian::MSet::get_snippet()``.  The snippet will be at most
 577         ``LENGTH`` bytes long (default: 200).
 578
 579 $split{STRING}
 580
 581 $split{SPLIT,STRING}
 582         returns a list by splitting the string ``STRING`` into elements at each
 583         occurrence of the substring ``SPLIT``.  If ``SPLIT`` isn't specified,
 584         it defaults to a single space.  If ``SPLIT`` is empty, ``STRING`` is
 585         split into individual bytes.
 586
 587         For example::
 588
 589          "$split{one two three}" = "one two     three"
 590
 591 $stoplist
 592         returns a list of any terms in the query which were ignored as
 593         stopwords.
 594
 595 $substr{STRING,START[,LENGTH]}
 596         returns the substring of ``STRING`` which starts at byte position
 597         ``START`` (the start of the string being 0) and is ``LENGTH`` bytes
 598         long (or to the end of ``STRING`` if ``STRING`` is less than
 599         ``START``+``LENGTH`` bytes long).  If ``LENGTH`` is omitted, the
 600         substring from ``START`` to the end of ``STRING`` is returned.
 601
 602         If ``START`` is negative, it counts back from the end of ``STRING`` (so
 603         ``$substr{hello,-1}`` is ``o``).
 604
 605         If LENGTH is negative, it instead specifies the number of bytes
 606         to omit from the end of STRING (so "$substr{example,2,-2}" is "amp").
 607         Note that this means that "$substr{STRING,0,N}$substr{STRING,N}" is
 608         "STRING" whether N is positive, negative or zero.
 609
 610 $suggestion
 611         if ``$set{spelling,true}`` was done before the query was parsed, then
 612         ``$suggestion`` will return any suggested spelling corrected version
 613         of the query string.  If there are no spelling corrections, it will
 614         return an empty string.
 615
 616 $terms
 617         list of matching terms for current hit.
 618
 619 $thispage
 620         page number of current page.
 621
 622 $time
 623         how long the match took (in seconds) e.g. ``0.078534``.  If no timing
 624         information was available, returns an empty value.
 625
 626 $topdoc
 627         first document on current page of hit list (counting from 0)
 628
 629 $topterms[{N}]
 630         list of up to ``N`` top relevance feedback terms (default 16)
 631
 632 $transform{REGEXP,SUBST,STRING[,OPTIONS]}
 633         transform string using Perl-compatible regular expressions.  This
 634         command is sort of like the Perl code::
 635
 636          my $string = STRING;
 637          $string =~ s/REGEXP/SUBST/;
 638          print $string;
 639
 640         In SUBST, ``\1`` to ``\9`` are substituted by the 1st to 9th bracket
 641         grouping (or are empty if there is no such bracket grouping).  ``\\``
 642         is a literal backslash.
 643
 644         The optional OPTIONS argument is supported by Omega 1.3.4 and later.
 645         It can contain zero or more of the letters ``gimsx``, which have the
 646         same meanings as the corresponding Perl regexp modifiers:
 647
 648          * ``g`` - replace all occurrences of the pattern in the string
 649          * ``i`` - make the pattern matching case-insensitive
 650          * ``m`` - make ``^``/``$`` match after/before embedded newlines
 651          * ``s`` - allows ``.`` in the pattern to match a linefeed
 652          * ``x`` - allow whitespace and ``#``-comments in the pattern
 653
 654 $truncate{STRING,LEN[,IND[,IND2]]}
 655         truncate STRING to LEN bytes, but try to break after a word (unless
 656         that would mean truncating to much less than LEN).  If we have to
 657         split a word, then IND is appended (if specified).  If we have to
 658         truncate (but don't split a word) then IND2 is appended (if specified).
 659         For example::
 660
 661          $truncate{$field{text},500,..., ...}
 662
 663 $uniq{LIST}
 664         remove duplicates from a sorted list
 665
 666 $unpack{BINARYSTRING}
 667         converts a 4 byte big-endian binary string to a number, for example::
 668
 669          $date{$unpack{$value{0}}}
 670
 671 $unstem{TERM}
 672         maps a stemmed term to a list of the unstemmed forms of it used in
 673         the query
 674
 675 $upper{TEXT}
 676         return UTF-8 text ``TEXT`` converted to upper case.
 677
 678 $url{TEXT}
 679         url encode argument
 680
 681 $value{VALUENO[,DOCID]}
 682         returns value number ``VALUENO`` for document ``DOCID``.  If ``DOCID``
 683         is omitted then the current hit is used (which only works inside
 684         ``$hitlist``).
 685
 686 $version
 687         omega version string - e.g. "xapian-omega 1.2.6"
 688
 689 $weight
 690         raw document weight of the current hit, as a floating point value
 691         (mostly useful for debugging purposes).
 692
 693 Numeric Operators:
 694 ==================
 695
 696 $add{...}
 697         add arguments together (if called with one argument, this will convert
 698         it to a string and back, which ensures it is an integer).
 699
 700 $div{A,B}
 701         returns int(A / B) (or the text "divide by 0" if B is zero)
 702
 703 $mod{A,B}
 704         returns int(A % B) (or the text "divide by 0" if B is zero)
 705
 706 $max{A,...}
 707         maximum of the arguments
 708
 709 $min{A,...}
 710         minimum of the arguments
 711
 712 $mul{A,B,...}
 713 multiply arguments together
 714
 715 $muldiv{A,B,C}
 716         returns int((A * B) / C) (or the text "divide by 0" if C is zero)
 717
 718 $sub{A,B}
 719         returns (A - B)
 720
 721 Logical Operators:
 722 ==================
 723
 724 $and{...}
 725         logical short-cutting "and" of its arguments - evaluates
 726         arguments until it finds an empty one (and returns "") or
 727         has evaluated them all (returns "true")
 728
 729 $eq{A,B}
 730         returns "true" if A and B are the same, "" otherwise.
 731
 732 $ge{A,B}
 733         returns "true" if A is numerically >= B.
 734
 735 $gt{A,B}
 736         returns "true" if A is numerically > B.
 737
 738 $le{A,B}
 739         returns "true" if A is numerically <= B.
 740
 741 $lt{A,B}
 742         returns "true" if A is numerically < B.
 743
 744 $ne{A,B}
 745         returns "true" if A and B are not the same, "" if they are.
 746
 747 $not{A}
 748         returns "true" for the empty string, "" otherwise.
 749
 750 $or{...}
 751         logical short-cutting "or" of its arguments - returns first
 752         non-empty argument
 753
 754 Control:
 755 ========
 756
 757 $if{COND,THEN[,ELSE]}
 758         if ``COND`` is non-empty, evaluate ``THEN``, otherwise evaluate else
 759         (if present)
 760
 761 $include{FILE}
 762         include another OmegaScript file