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