Search Features
The Search Edit and
Volume Search controls
offer a rich set of search features.
A simple search string consists of one or more words,
separated by one or more whitespace characters.
For example:
fluent sql
The above search string will find articles that contain
both words fluent and sql, ignoring case.
Articles are sorted by the number of occurrences of the
search word(s).
Sage excludes articles missing one or more of the search words.
Sage supports more sophisticated search strings,
based on the following concepts…
- The pipe operator, |, implements the familiar "or" operator.
- The exclamation mark, !, implements the familiar "not" operator.
- Quoted strings (using double-quotes: "...") escape characters that would otherwise have special meaning (such as pipes, parenthesis, etc).
- Quoted strings have another purpose: finding words in a specific sequence.
- Regular expressions are also supported.
- Parenthesis characters, ( and ), group sub-expressions.
- The colon operator, :, manipulates various flags, controlling options such as case sensitivity whole vs. partial word match, and more.
- The semi-colon symbol, ;, is reserved for future expansion.
As indicated above,
having two adjacent expressions (separated by whitespace)
is an implicit "and" operator.
For example…
abc !xyz 123
The above search string asks for articles containing
both the strings abc and 123, but without the string xyz.
Another example…
abc (x | y | z) def
The above search string ask for articles containing:
the string abc, the string def,
and at least one of the following: x, y, or z.
The pipe symbol is the "or" operator.
For example…
abc | xyz
The above search string asks for articles containing
the words abc and/or xyz.
Another example…
abc | xyz | (d e f)
The above search string asks for articles matching at least
one of the following criteria:
- Contain abc,
- Contain xyz,
- Contain d and e and f (in any order).
The exclamation mark is the "not" operator.
For example…
abc !xyz
The above search expression asks for articles containing abc,
excluding those that contain xyz.
Another example…
fluent sql !(alder | ginkgo)
The above example asks for articles containing both
fluent and sql,
excluding those that contain alder and/or ginkgo.
Use parentheses to group sub-expressions,
for example…
(a b) | (x y)
The above expression asks for articles containing
both a and b, and/or containing both x and y.
The "and" operator performs the familiar short-circuit evaluation:
if the left operand is false, the right operand is not evaluated.
The ! operator also performs a kind of short-circuit evaluation.
For example, consider the search string fluent !(sql | vdb).
If an article has one or more occurrences of fluent,
it may count as a match, but not if it contains sql or vdb.
Normally, the sub-expression (sql | vdb) would find any/all
occurrences of sql and vdb, and count them all up.
However, since this sub-expression is the operand of the !
operator, it is evaluated in such a way as to stop on the
first occurrence of sql or vdb.
In other words, the ! operator avoids counting up all the
reasons why the article doesn't match, stopping at the first one.
This leads to an interesting, and potentially useful, side-effect.
Consider these two search strings…
fluent (sql | vdb)
fluent !!(sql | vdb)
They both return the same set of articles.
However, the one with the double negative avoids counting
the words sql and vdb.
So, the order of the search results will differ.
For the first one, results are ordered
by the combined count of all three words.
For the second one, results are ordered
by the count of fluent only.
Typically, the | operator evaluates both operands,
even when the first one is true (to count all words involved).
However, if the | operator is (directly or indirectly)
a sub-expression of the ! operator, short-circuit kicks in:
if the left operand is true, the right operand is not evaluated,
because Sage knows that it isn't supposed to count everything
(instead, it just needs to determine whether the count is zero
or non-zero, in effect).
In a search string, you may use double-quote characters to
build a quoted string.
Such a string will escape special characters
(pipe, parentheses, etc).
To include a quote character in a string,
simply double it up, as is the practice in SQL and Delphi.
For example…
a | "x|y"
The above search string asks for articles
containing the string a and/or
containing the three-character string x|y.
In a quoted string,
any sequence of one or more whitespace characters
matches with one or more whitespace characters
in the text being searched.
For example…
"fluent sql"
The above search string matches articles
containing the word fluent,
followed by one or more whitespace characters,
followed immediately by the word sql.
The characters (if any) before and after a quoted string
must be whitespace or operators.
For example, these are both illegal…
"abc"xyz
xyz"abc"
A space is required in the above examples, as in…
"abc" xyz
xyz "abc"
A space is not required if the character before/after the
string is an operator…
("abc"|xyz)"123"!456
The above is allowed, and is equivalent to…
("abc" | xyz) "123" !456
Sage supports regular expressions,
denoted by a quoted string with the r prefix…
registry | r"@Set.*Value"
The above matches articles containing the string registry,
and/or containing the regular expression @Set.*Value
(which looks for strings such as
@SetPropBagValue and @SetRegValue).
This notation is an exception to the rule
that the character before a quoted string
must be an operator or whitespace.
The R flag offers a slightly cleaner syntax,
if the entire search string is a single regular expression.
Sage offers several flags to control
various search-related options.
Each flag is identified by a single letter…
To use one or more flags,
specify the flag name(s), followed by a colon,
followed by an expression.
For example…
cw:MiniCalc
The above search string looks for articles containing
the whole word MiniCalc, case sensitively.
This would not match the following strings:
minicalc, MiniCalcExtras, or VDBMiniCalc.
| Flag | Description | Top-Level |
|---|---|---|
| A | All volumes | Yes |
| T | volume Titles | Yes |
| V | Volume links | Yes |
| H | Headings | Yes |
| D | Density | Yes |
| R | Regular expr | Yes |
| W | Whole words | No |
| C | Case-sensitive | No |
Except for flags appearing at the beginning of the search string,
flags applying to a sub-expression must appear immediately
after an open parenthesis –
and they apply for the remainder of the parenthesized expression.
For example…
a | (w:b c)
The above search string looks for articles containing
the string a (partial word matching), and/or
articles containing both b and c (whole words only).
Thus, the above would match x b c but not xb c.
As indicated in the table above,
some flags are allowed at the top-level only.
For example, the following is illegal…
a | (vw:b c)
The v flag, along with certain others,
must be specified at the beginning of the search string.
For example, the above should be written as follows…
v:a | (w:b c)
This flag, which may only appear at the
top level,
instructs Sage to search all volumes,
including private and hidden volumes.
This flag, which may only appear at the
top level,
instructs Sage to search only volume titles,
and return links to volumes.
This flag cannot be used with the V and/or H flags.
This flag, which may only appear at the
top level,
instructs Sage to return links to volumes.
Without this flag, Sage returns links to articles.
With this flag, Sage searches all relevant articles,
aggregates search results by volume,
sorts the volumes,
and returns a list of volume links.
This flag, which may only appear at the
top level,
instructs Sage to ignore the article contents,
and search headings only
(that is, titles of volumes, topics, articles, and sections).
This flag, which may only appear at the
top level,
controls how Sage sorts search results.
By default, search results are sorted by comparing the number
of hits in the headings (titles), and as a tie-breaker,
comparing the number of hits in the article content.
With the D flag, Sage sorts search results by combining
the headings and contents of each article,
and comparing the density
(the ratio of hits divided by text length).
So, if two articles have the same number of occurrences of
the search word, the shorter article will appear first
(as it is more densely populated with the search word).
This flag, which may only appear at the
top level,
provides a more convenient way to search for
a single regular expression.
When this flag is present,
all text after the colon is taken, verbatim,
as the regular expression.
For example, the following are equivalent…
r"ab*c""d"
r:ab*c"d
As the above example illustrates,
the R flag can be slightly less verbose.
However, as this flag can only appear at the top level,
you will still need to use the other syntax
when a regular expression is
only part of the overall search string.
For example…
alpha beta r"ab*c""d
This flag instructs Sage to look for whole words only.
To qualify as a whole word,
the characters on either side of the word (if any)
must not be: letters, digits, or underscores.
This flag instructs Sage to honor case
(without this flag, Sage ignores case).
Sage provides a syntax for disabling a flag
that has been enabled previously.
When specifying the flag character(s),
a dash indicates that the remaining character(s)
will be disabled.
For example…
w:xyz | (a b (c-w:c d) e f)
The above string asks for articles containing the string xyz
(whole words, ignore case) and/or containing
each of the following strings:
a, b, c, d, e, and f
(whole words only, ignore case, except for c and d,
which honor case and allow partial word matching).
Note that the above could also be written as…
(w:xyz) | ((w:a b e f) (c:c d))
But as this example shows,
it is sometimes much cleaner to use the dash.
⏱ Last Modified: 10/24 9:45:52 am