Boolean Text Search

Synchronet's text-search prompts (message scan, mail scan, file search, and the less-style file pager) accept a small boolean query language: combine search terms with AND / OR / NOT operators, group them with parentheses, and quote terms to require a whole-word match. The language is compatible with the syntax that PCBoard and Wildcat! used for the same purpose, with a few deliberate extensions.

The boolean parser is used at every Text to search for prompt. In the stock command shell (exec/default.js):

Note: the file menu's S (“Search for Filename(s)”) is a separate wildcard-pattern filename match (*.zip, WILD*.EXE, etc.) and does not use the boolean parser. Sysops with custom shells may bind these commands differently — the parser engages whenever the underlying scan function receives the SCAN_FIND (messages) or FL_FIND (files) mode flag.

Programmatic callers (e.g. bbs.scan_posts(sub, mode, find) in JavaScript) inherit the same syntax — the find string they pass is parsed identically.

At any boolean search prompt — including the file pager's / search — entering a lone ? displays a one-screen quick-reference help file (''text/menu/textsrch.msg'') and re-prompts. The prompt itself includes the hint (?=help) so the feature is discoverable without reading the docs first. In the pager case, the help text scrolls onto the screen the same way the pager's main ? help already does; press Home or PgUp to return to the original content if needed.

A query is a boolean expression of search terms, operators, and groups.

A bare term is any run of characters that doesn't include an operator character (&, |, !, (, ), “). Embedded whitespace is part of the term — it does not mean implicit AND. So VGA monitor is one phrase that matches whenever VGA appears immediately followed by monitor.

TEST            -> contains 'TEST' anywhere (substring, case-insensitive)
VGA monitor     -> contains the phrase 'VGA monitor'
no-such-string  -> contains the literal 'no-such-string' (hyphens are not special)

Keyword forms are case-insensitive and only recognized as operators when surrounded by whitespace, parens, or operator characters — so BANDIT is one phrase, while BAND AND IT is BAND AND IT.

Precedence: NOT > AND > OR. So A | B & C means A OR (B AND C). Use parentheses if you want a different grouping.

You can omit the & when it would precede a ! or NOT — the AND is implied. So dog !cat is the same as dog & !cat or dog AND NOT cat.

Parentheses control evaluation order:

(windows | dos) & modem      -- (windows or dos) and modem
windows | dos & modem        -- windows or (dos and modem)

Wrapping a term in double quotes turns on word-boundary matching: the match must be preceded and followed by a non-word character (or the start / end of the haystack). This is useful when a short search term would otherwise match inside a longer word.

TEST       -> matches  TEST, TESTING, BACKTEST, ...   (substring)
"TEST"     -> matches  TEST, (TEST), 'TEST'.          but NOT TESTING, BACKTEST

A “word character” is any letter, digit, or underscore. Everything else (spaces, punctuation, brackets, etc.) is a boundary.

Quoted phrases preserve any internal whitespace and operator characters as literal content, with word-boundary checks applied to the outer ends of the phrase. This is what makes “SMITH & JONES” searchable as a literal phrase including the &.

"hard disk"     -> matches 'the hard disk here', not 'hard disks' or 'hard diskette'
"new york"      -> matches 'New York City'
"smith & jones" -> matches 'Smith & Jones report'  (the & is literal, not AND)

A leading space inside the quotes disables the word-boundary check on the left edge; a trailing space disables it on the right edge. Padding both sides turns a quoted term into a pure substring search.

This is what lets you, for instance, search for “co” to match the abbreviation co. but not cocoa or coffee, while ” co “ still matches co anywhere including inside cocoa.

hello & world                 -- both present
hello | hi | greetings        -- any of these
"PCBoard" !pirate             -- whole word PCBoard, exclude messages with 'pirate'
( spam | scam ) & ! "yahoo"   -- spam or scam, but not the word 'yahoo'
"SMITH & JONES"               -- literal phrase with an ampersand
foo bar                       -- the phrase 'foo bar' (NOT implicit AND)
foo & bar                     -- the words 'foo' and 'bar' (in any order)

If the parser can't understand your query, the BBS prints

Invalid search expression: <reason>

and returns you to the prompt (showing the inline help). Common reasons:

• unterminated quoted string

  — a ” opened a quoted phrase but no closing “ was found

• expected ')'

  — a ( opened a group but the matching ) is missing

• expected search term

  — an operator was followed by another operator or end of input

• unexpected '<char>' at offset N

  — a stray ) or some other syntactically out-of-place character

The dialect is intentionally compatible with PCBoard and Wildcat! conventions where they agree, and a strict superset elsewhere:

• All published PCBoard and Wildcat! example queries parse and evaluate the same way they did in those systems.
• Operator keywords (AND / OR / NOT) are accepted in addition to the symbolic forms — PCBoard only used the symbols; Wildcat! supported both.
• Standard precedence (NOT > AND > OR) is used instead of PCBoard's documented strict left-to-right, but the two only differ on hand-crafted examples that no published manual used. Add parentheses if you depend on a specific grouping.
• An implicit AND is inserted before ! / NOT (as in Wildcat!'s (windows | DOS) & (modem | comm) !OS/2 example). PCBoard required the & to be explicit; the implicit form is more permissive but never changes the meaning of an already-valid PCBoard query.
• PCBoard treated (text) (parens around a single word with no operator inside) as a search for the literal string (text) — including the parens. Synchronet always treats (...) as grouping, so (text) is equivalent to text. If you want to search for parens literally, quote them: ”(text)“.

• Message Bases — where Find on a sub-board uses this syntax
• Electronic Mail — where / at the mail prompt uses this syntax
• File Areas — where Find in descriptions uses this syntax
• Text Files — where the file pager's / uses this syntax
• Menu Files — textsrch.msg is the inline-help display file