# Query Search Expressions

Query search expressions are used to specify a matching criteria for an HTML file. For any given HTML file, they evaluate to either true (matched) or false (unmatched).

The following syntax can be used for query search expressions:

expression
| element [operator element [operator element [...]]]
element
| name | True if keyword name exists or boolean value of meta name.
| name `=` value | True if meta name has a value which is equal to value.
| name `==` value | True if meta name has a value which is equal to value (C++ style syntax).
| name `<>` value | True if meta name has a value which is not equal to value.
| name `!=` value | True if meta name has a value which is not equal to value (C++ style syntax).
| name `<` value | True if meta name has a value which is less than value.
| name `<=` value | True if meta name has a value which is less than or equal to value.
| name `>` value | True if meta name has a value which is greater than value.
| name `>=` value | True if meta name has a value which is greater than or equal to value.
| name `<<` string | True if meta name has a value which begins with the text substring string.
| name `>>` string | True if meta name has a value which contains the text substring string.
| name `<<<` string`` | True if meta name has a value which begins with the word string. ¹
| name `>>>` string`` | True if meta name has a value which contains the word string. ¹
| `*` | True if keyword list is not empty.
| `#` | True if keyword list contains at least one non-hidden keyword. ²
| `(`expression`)` | True if expression is true.
| `!` element | True if element is false.
operator
| `&` | AND: True if both elements are true
| `|` | OR: True if either element is true (or both elements are true)

name`` | The name of the attribute to test. This can be a keyword or a pre-defined meta name. Keywords are true if they exist in the keyword list, or false if they don't exist. Meta names may have both a boolean value (true or false) and a numeric/string value. If the name is used alone as an element, then the boolean value is returned. If the name is compared to a value, then the numeric/string value is used. The name must be enclosed in quotes (single or double) if it contains any special characters (`~=<>!&|(),;`). Embedded spaces are allowed even in unquoted names. See the Names section below for a complete list of valid names.
value | The value to be compared to. This must be enclosed in quotes (single or double) if it contains any special characters (`~=<>!&|(),;`) or if it contains any leading or trailing spaces. Embedded spaces are allowed even in unquoted values. If this is a text string (or a number in quotes) then a string comparison will be performed. All string comparisons are case-insensitive. If this is a number (not enclosed in quotes) then a numeric comparison will be performed. The numeric comparison will always be false if name has a non-numeric value or does not have a value at all. It will also be false if name does not exist.
string | A text string value. This is always treated as a text string, even if it's a number, because the comparison is a string-only comparison.

Operators are executed strictly from left to right. Expressions inside parentheses are always executed first. Spaces are ignored unless they appear in quotes or are embedded in a multi-word name or value.

¹ | A word is any substring that matches string and is surrounded by non-word characters. Word characters are letters, numbers, and underscore ( _ ).
² | A hidden keyword is a keyword that begins with the underscore ( _ ) character.

### Names

The following names are supported in all queries. You should avoid using keywords with that are the same as pre-defined meta names, since you will be unable to test for their existance (meta names have precidence over keywords):

Name | Boolean value is true if... | Numeric/String Value
--- | --- | ---
keyword | The keyword exists in the keyword list of the HTML file | (none)
title | The HTML file contains a title | The title of the HTML file
desc or description | The HTML file contains a description | The description of the HTML file
tdesc | The HTML file contains a title and/or a description | The "title`;` description" of the HTML file
href | (undefined) | The relative URL of the HTML file
count | There is at least one slide in the set (count > 0) | The total number of slides in the set (including subsets)
sets | There is at least one subset in the set (sets > 0) | The number of subsets in the set
size | There is at least one byte used by image files (size > 0) | The total number of bytes used by the image files in the set

The following additional meta names are supported only by the #if directive in index template files:

Name | Boolean value is true if... | Numeric/String Value
--- | --- | ---
thumb or thumbnail | The index has a thumbnail associated with it | The relative URL of the thumbnail image file
thumbWidth | The width of the thumbnail is known | The width of the thumbnail image file (0 if unknown)
thumbHeight | The height of the thumbnail is known | The height of the thumbnail image file (0 if unknown)
fileLinks | The index contains at least one file link | The total number of file links in the index
thumbFileLinks | The index contains at least one file link with a thumbnail | The number of file links with thumbnails in the index
dirLinks | The index contains at least one directory link | The total number of directory links in the index
thumbDirLinks | The index contains at least one directory link with a thumbnail | The number of directory links with thumbnails in the index
page | (undefined) | The current page number of a multi-page index
pages | The index contains multiple pages (pages >= 2) | The total number of pages in a multi-page index
section string | The section identified by start string exists (see ${section}) | (none)
file filename | The filename exists | (none)

Examples

1. | `color` | Matches any HTML file that contains the keyword "color".
2. | `"b&w"` | Matches any HTML file that contains the keyword "b&w". "b&w" must be in quotes since "&" is an operator.
3. | `one|two|three` | Matches any HTML file that contains any or all of the keywords "one", "two", or "three".
4. | `one|two&!three` | Matches any HTML file that contains the keyword "one" and/or "two", but does not contain the keyword "three".
5. | `*&!two` | Matches any HTML file that contains at least one keyword, but does not contain the keyword "two".
6. | `(1|one)&(3|three)` | Matches any HTML file that contains the digit or word "one" and the digit or word "three".
7. | `title=John` | Matches any HTML file that has the title "John".
8. | `title<<John & color` | Matches any HTML file that has a title beginning with "John" and the keyword "color".
9. | `tdesc=>Star Trek` | Matches any HTML file with the phrase "Star Trek" in its title or description.
10. | `section "<!-- BEGIN HEADING -->"` | True if the section starting with "`<!-- BEGIN HEADING -->`" exists in the index.
11. | `file "bigthumb.jpg"` | True if the file "bigthumb.jpg" exists in the index directory (quotes are optional).

Table of Contents