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::
11 <head><title>Sample</title></head>
15 You searched for '$html{$query}'.
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.
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_`
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.
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.
57 In the following descriptions, a LIST is a string of tab-separated
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
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
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.
80 return a list of all values of a CGI parameter
83 return a list of all the unique CGI parameter names, sorted in
84 ascending order by raw byte values.
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.
90 Since ASCII is a subset of Unicode, you can also produce control
91 characters, e.g. ``$chr{13}`` gives a carriage return character.
93 To convert a UTF-8 character to a Unicode codepoint, see ``$ord``.
98 number of other documents collapsed into current hit inside
99 ``$hitlist``, which might be used like so::
101 $if{$ne{$collapsed,0},at least $collapsed hidden results ($value{$cgi{COLLAPSE}})}
103 $contains{STRING1,STRING2}
104 return position of first occurrence of STRING1 in STRING2, if present. Else return an empty string.
107 ``$contains{fish,goldfish}`` gives ``"4"``
109 ``$contains{fish,shark}`` gives ``""``
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:
117 ``$csv{Safe in CSV!}`` gives ``Safe in CSV!``
119 ``$csv{Not "safe"}`` gives ``"Not ""safe"""``
121 ``$csv{3$. 2$. 1}`` gives ``"3, 2, 1"``
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.
130 ``$csv{Quote anyway,1}`` gives ``"Quote anyway"``
132 ``$csv{Not "safe",1}`` gives ``"Not ""safe"""``
134 Added in Omega 1.3.4.
137 convert a time_t to strftime ``FMT`` (default: ``YYYY-MM-DD``). The
138 conversion is done in timezone UTC.
141 database name (multiple names are returned separated by "/").
144 number of documents in the database (if multiple databases are being
145 searched, this gives the total number).
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.
157 "and" or "or" (set from CGI variable DEFAULTOP).
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).
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.
171 lookup variable ``VAR`` in the environment.
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
180 lookup field ``NAME`` in document ``DOCID``. If ``DOCID`` is omitted
181 then the current hit is used (which only works inside ``$hitlist``).
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.::
186 $map{$field{keywords},<b>$html{$_}</b><br>}
189 pretty printed filesize (e.g. ``1 byte``, ``100 bytes``, ``2.1K``,
190 ``4.0M``, ``1.3G``). If ``SIZE`` is negative, expands to nothing.
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.
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.::
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}>
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.
220 name of current format (as set by CGI parameter``FMT``, or the default)
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.
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>``.
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}``).
248 display hitlist using format ``FMT``.
251 hits per page (as set by ``HITSPERPAGE``, or the default)
254 return the hostname from url ``URL``
257 html escape string (``<>&"`` are escaped to ``<``, etc).
260 html strip tags from string (``<...>``, etc).
262 $httpheader{NAME,VALUE}
263 specify an additional HTTP header to be generated by Omega.
266 $httpheader{Cache-Control,max-age=0$.private}
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.
274 document id of current document
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:\\\"``
280 Added in Omega 1.3.1.
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:\\"]``
286 Added in Omega 1.3.1, but buggy until 1.3.4.
289 MSet index one beyond the end of the current page (so ``$hit`` runs
290 from ``0`` to ``$sub{$last,1}``).
293 number of last page of hits (may be an underestimate unless
294 ``$thispage`` == ``$lastpage``).
297 number of entries in ``LIST``.
300 pretty print list. If ``LIST`` contains 1, 2, 3, 4 then::
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."
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).
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.
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
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::
329 "$or{$lookup{tld_en,$field{tld}},.$field{tld}}"
331 If a tld isn't in the CDB (e.g. "com"), this will expand to ".com".
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
341 return UTF-8 text ``TEXT`` converted to lower case.
344 map a list into the evaluated argument. If ``LIST`` is
347 "$map{LIST,x$_ = $_; }" = "x1 = 1; x2 = 2; "
349 Note that $map{} returns a list (this is a change from older
350 versions). If the tabs are a problem, use $list{$map{...},}
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.
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
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
367 estimated number of matches.
370 return ``true`` if ``$msize`` is exact (or "" if it is estimated).
371 Exactly equivalent to: ``$eq{$msizelower,$msizeupper}``
374 lower bound on number of matches.
377 upper bound on number of matches.
380 pretty print integer (with thousands separator).
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.
388 lookup an option value (as set by ``$set``).
391 lookup an option within a map (as set by ``$setmap``).
394 return codepoint for first character of UTF-8 string. If the argument
395 is an empty string, then an empty string is returned.
397 For example, ``$ord{One more time}`` gives ``79``.
399 To convert a Unicode code point into a UTF-8 string, see ``$chr``.
401 Added in Omega 1.3.4.
404 converts a number to a 4 byte big-endian binary string
407 percentage score of current hit (in range 1-100).
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.
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,...}``.
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.
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).
432 If PREFIX is omitted or empty, this is built from CGI ``P`` variable(s)
433 plus possible added terms from ``ADD`` and ``X``.
435 If PREFIX is non-empty, this is built from CGI ``P.PREFIX`` variables.
437 Note: In Omega < 1.3.3, $query simply joins together the query strings
438 with spaces rather than returning a list.
441 a human readable description of the ``Xapian::Query`` object which
442 omega builds. Mostly useful for debugging omega itself.
445 list of parsed query terms.
448 return list of values between ``START`` and ``END``.
451 raw record contents of document ``ID``.
454 document id ``ID`` if document is relevant, "" otherwise
455 (side-effect: removes id from list of relevant documents
456 returned by ``$relevants``).
459 return list of relevant documents
462 score (0-10) of current hit (equivalent to ``$div{$percentage,10}``).
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:
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
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}``
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.
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,}``):
520 * flag_auto_multiword_synonyms
523 * flag_boolean_any_case
524 * flag_cjk_ngram (new in 1.2.22 and 1.3.4)
530 * flag_spelling_correction (see ``$suggestion`` for suggested
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,}``).
543 You can use ``:flag_partial``, etc to set or unset a flag just for
546 Similarly, ``XFOO:stemmer`` specifies the stemmer to use for field
547 ``XFOO``, with ``stemmer`` providing a default.
549 $seterror{ERROR_MESSAGE}
550 set error message for the current execution, which can also be looked
553 Using ``$seterror`` error early in template prevents running the query.
555 For example, ``$seterror`` can be used when the user enters a wrong
556 parameter in the search.
559 add documents into the RSet
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).
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:
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::
573 $setmap{prefix,author,A,title,S}
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
583 $setmap{prefix,,$split{ S}}
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
589 $setmap{boolprefix,group,G}
591 Don't be tempted to add whitespace around the commas, unless you want
592 it to be included in the names and values!
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).
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.
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.
621 For example, if ``LIST`` contains a, b, c, d then::
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"
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).
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:
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
654 Options ``#`` and ``n`` aren't valid together.
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.
666 "$split{one two three}" = "one two three"
669 returns a list of any terms in the query which were ignored as
673 return the name of the sub-database containing ``DOCID`` (or the
674 current document in the histlist if ``DOCID`` is omitted).
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.
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``
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.
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.
698 If ``START`` is negative, it counts back from the end of ``STRING`` (so
699 ``$substr{hello,-1}`` is ``o``).
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.
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.
713 return the prefix (if any) from a term. Added in Omega 1.4.6.
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
724 page number of current page.
727 how long the match took (in seconds) e.g. ``0.078534``. If no timing
728 information was available, returns an empty value.
731 first document on current page of hit list (counting from 0)
734 list of up to ``N`` top relevance feedback terms (default 16)
736 $transform{REGEXP,SUBST,STRING[,OPTIONS]}
737 transform string using Perl-compatible regular expressions. This
738 command is sort of like the Perl code::
741 $string =~ s/REGEXP/SUBST/;
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.
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:
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
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).
765 $truncate{$field{text},500,..., ...}
768 remove adjacent duplicates, for example from an already sorted list
769 (similar to the Unix ``uniq`` command line tool).
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
777 $unpack{BINARYSTRING}
778 converts a 4 byte big-endian binary string to a number, for example::
780 $date{$unpack{$value{0}}}
783 remove the prefix (if any) from a term. Added in Omega 1.4.6.
786 maps a stemmed term to a list of the unstemmed forms of it used in
790 return UTF-8 text ``TEXT`` converted to upper case.
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
801 omega version string - e.g. "xapian-omega 1.2.6"
804 raw document weight of the current hit, as a floating point value
805 (mostly useful for debugging purposes).
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).
815 returns int(A / B) (or the text "divide by 0" if B is zero)
818 returns int(A % B) (or the text "divide by 0" if B is zero)
821 maximum of the arguments
824 minimum of the arguments
827 multiply arguments together
830 returns int((A * B) / C) (or the text "divide by 0" if C is zero)
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")
844 returns "true" if A and B are the same, "" otherwise.
847 returns "true" if A is numerically >= B.
850 returns "true" if A is numerically > B.
853 returns "true" if A is numerically <= B.
856 returns "true" if A is numerically < B.
859 returns "true" if A and B are not the same, "" if they are.
862 returns "true" for the empty string, "" otherwise.
865 logical short-cutting "or" of its arguments - returns first
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).
877 ``$cond`` provides a neater way of writing a cascading series of
878 ``$if`` checks. If there's only one condition, ``$cond`` is equivalent
881 Added in Omega 1.4.6.
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).
888 include another OmegaScript file
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).
897 Added in Omega 1.4.6.