swish++.conf(5)

💖 swish++.conf(5) — the SWISH++ config file format, bestie edition 💖

okay so this is a File Formats Manual page, and it's all about swish++.conf — the configuration file format that SWISH++ uses. if you've ever wondered how to tell SWISH++ what to do without losing your mind, this is the page. grab a snack 🍓, we're doing this together.

---

✨ NAME ✨

swish++.conf — the SWISH++ configuration file format. that's it, that's the name, iconic behavior honestly 👑

---

🌸 DESCRIPTION 🌸

the config file is built out of exactly three kinds of lines, no more no less:

• blank lines
• comments
• variable definitions

periodt. let's break each one down 💅

🫧 Blank lines

blank lines — or lines that are entirely whitespace — get straight-up ignored. they're giving nothing and SWISH++ is giving them nothing back. 🙈

💬 Comments

comments start with the # character and they keep going up to and including the end of the line. leading whitespace? allowed, go off. but here's the catch bestie — comments are only treated as comments if they're on lines by themselves. no sneaking a # at the end of a variable line, that's not the vibe. 😭

🎀 Variable definitions

variable definition lines look like this:

variable_name argument(s)

where variable_name is a member of one of the types described in the remaining sections (keep scrolling, we get there 🦋), and argument(s) are specific to every variable name. and for variable_name? case is irrelevant. write it however, she doesn't care.

🧚 Boolean variables

these ones take exactly one argument, and it has to be one of:

f, false, n, no, off, on, t, true, y, or yes

case is irrelevant. the variables of this type are: AssociateMeta, ExtractFilter, FollowLinks, Incremental, LaunchdCooperation, RecurseSubdirs, SearchBackground, StemWords, and StoreWordPositions.

🌈 Enumeration variables

these work just like string variables (see below, boo) except the argument has to be one of a set of pre-determined values. case is irrelevant. the variables of this type are: ResultsFormat and SearchDaemon.

• ResultsFormat must be either: classic or XML.
• SearchDaemon must be one of: none, tcp, unix, or both.

no freestyling, she has a type 💅

🦋 Filter variables

these are shaped like:

pattern command

where pattern is a shell pattern (regular expression) and command is the command-line to execute the filter.

inside a command, there are a few % substitutions that get done at run-time:

• b — basename of filename.
• B — basename minus last extension.
• e — extension of filename.
• E — second-to-last extension of filename.
• f — entire filename.
• F — filename minus last extension.

so basically: the % and the one character immediately after it get substituted as described up there. substituted filenames get skipped past and are not rescanned for more substitutions — but the remainder of the command is. to use a literal % or @, just double it. (for more on filter variables, see FILTERS below, we got a whole section for it 💖)

the variables of this type are: FilterAttachment and FilterFile.

🔢 Integer variables

these take one numeric argument. a special string of infinity means "the largest possible integer value." case is irrelevant. the variables of this type are: FilesReserve, ResultsMax, SocketQueueSize, SocketTimeout, ThreadsMax, ThreadsMin, ThreadTimeout, TitleLines, Verbosity, WordFilesMax, WordPercentMax, WordsNear, and WordThreshold.

⚠️ for WordThreshold, only the super-user can specify a value larger than the compiled-in default. yes really. know your place bestie 😌

💯 Percentage variables

these are like integer variables except if an optional trailing percent sign (%) is present, the value is taken to be a percentage rather than an absolute number. the variables of this type are: FilesGrow.

🎀 String variables

these take one argument that is the remainder of the line minus leading and trailing whitespace. wanna preserve whitespace? surround the argument in either single or double quotes. the quotes themselves get stripped from the argument — but only if they match. so match your quotes, okay? 🙏

the variables of this type are: ExtractExtension, Group, IndexFile, PidFile, ResultSeparator, SocketFile, StopWordFile, TempDirectory, and User.

⭐ Set variables

these take one or more arguments separated by whitespace. the variables of this type are: ExcludeClass, ExcludeFile, ExtractFile, and ExcludeMeta.

👑 Other variables

the variables of this type are: IncludeFile, IncludeMeta, and SocketAddress.

an IncludeFile configuration file line is shaped like:

module_name pattern ...

where module_name is the name of the module (case is irrelevant) that handles the indexing of the filename patterns that follow. the module names are: text (plain text), HTML (HTML and XHTML), ID3 (ID3 tags), LaTeX (LaTeX source), Mail (mail and news messages), Man (Unix manual pages), and RTF (Rich Text Format).

an IncludeMeta configuration file line is shaped like:

name[=new_name] ...

it's like a set variable except arguments may optionally be followed by reassignments. for example, a value of:

adr=address

says to include and index the words associated with the meta name adr, but to store the name as address in the generated index file so that queries would use address rather than adr. it's giving rebranding era ✨

a SocketAddress configuration file line is shaped like:

[ host : ] port

that is: an optional host and colon followed by a port number. the host may be one of a host name, an IPv4 address (in dot-decimal notation), an IPv6 address (in colon notation) if supported by the operating system, or the * character meaning "any IP address." omitting the host and colon also means "any IP address." casual 💅

---

🔥 FILTERS 🔥

🍓 Filtering files

via the FilterFile configuration file variable, files matching patterns can be filtered prior to indexing or extraction. for example, to uncompress bzip2'd, gzip'd, and compress'd files prior to indexing or extraction, the FilterFile variable lines in a configuration file would be:

FilterFile *.bz2  bunzip2 -c %f > @%F
FilterFile *.gz   gunzip -c %f > @%F
FilterFile *.Z    uncompress -c %f > @%F

given that, a filename such as foo.txt.gz would become foo.txt. and if files having txt extensions should be indexed, then it will be. slay 💖

note that the command on the FilterFile line must not simply be:

gunzip @%f                    # WRONG!

because gunzip will replace the compressed file with the uncompressed one. and we do not want that. 🚫

here's an example to convert PDF to plain text for indexing using the xpdf(1) package's pdftotext command:

FilterFile *.pdf  pdftotext %f @%F.txt

a file can be filtered more than once prior to indexing or extraction, i.e., filters can be "chained" together. for example, if the uncompression and PDF examples shown above are used together, compressed PDF files will also be indexed or extracted — i.e., filenames ending with one of .pdf.bz2, .pdf.gz, or .pdf.Z double extensions. chaining ate, no crumbs 🌈

note, however, that just because a filename has an extension for which a filter has been specified does not mean that a file will be filtered and subsequently indexed or extracted. when index++ or extract++ encounters a file having an extension for which a filter has been specified, it performs the filename substitution(s) on it first to determine what the target filename would be. if the extension of that filename should be indexed or extracted — because it is among the set of extensions specified with either the -e or --pattern options or the IncludeFile variable, or is not among the set specified with either the -E or --no-pattern options or the ExcludeFile variable — then the filter(s) are executed to create it. it's a whole vibe check before anything actually happens, iykyk 💅

💌 Filtering attachments

via the FilterAttachment configuration file variable, e-mail attachments whose MIME types match particular patterns can be filtered and thus indexed. an attachment is written to a temporary file by itself (after having been base-64 decoded, if necessary) and a filter command is called on that file.

for example, to convert a PDF attachment to plain text so it can be indexed, the FilterAttachment variable line in a configuration file would be:

FilterAttachment application/pdf    pdftotext %f @%F.txt

MIME types must be specified entirely in lower case. no shouting allowed, lowercase only bestie 😌

patterns can be useful for MIME types. for example:

FilterAttachment application/*word  extract++ -f %f > @%F.txt

can be used regardless of whether the MIME type is application/msword (the official MIME type for Microsoft Word documents) or application/vnd.ms-word (an older version). one line, two moods, we love efficiency 🫶

the MIME types that are built into index++(1) are: text/plain, text/enriched (but only if the RTF module is compiled in), text/html (but only if the HTML module is compiled in), text/*vcard, message/rfc822, multipart/something (where something is one of: alternative, mixed, or parallel). FilterAttachment variable lines can override the handling of the built-in MIME types. bold. we respect it. 👑

unlike file filters, attachment filters must convert directly to plain text and can not be "chained" together. (this restriction exists because there is no way to know what any intermediate MIME types would be to apply more filters.) no chains for attachments, that's the rule and she's sticking to it 💀

---

🌟 SEE ALSO 🌟

bzip(1), compress(1), extract++(1), gunzip(1), gzip(1), index++(1), pdftotext(1), search++(1), uncompress(1), glob(7)

and the reading list, because she's well-read and you should be too 📚:

• Nathaniel S. Borenstein. "The text/enriched MIME Content-type," Request for Comments 1563, Network Working Group of the Internet Engineering Task Force, January 1994.
• David H. Crocker. "Standard for the Format of ARPA Internet Text Messages," Request for Comments 822, Department of Electrical Engineering, University of Delaware, August 1982.
• Frank Dawson and Tim Howes. "vCard MIME Directory Profile," Request for Comments 2426, Network Working Group of the Internet Engineering Task Force, September 1998.
• Ned Freed and Nathaniel S. Borenstein. "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies," Request for Comments 2045, RFC 822 Extensions Working Group of the Internet Engineering Task Force, November 1996.
• International Standards Organization. "ISO/IEC 9945-2: Information Technology -- Portable Operating System Interface (POSIX) -- Part 2: Shell and Utilities," 1993.
• Steven Pemberton, et al. XHTML 1.0: The Extensible HyperText Markup Language, World Wide Web Consortium, January 2000.

---

💜 AUTHOR 💜

Paul J. Lucas <pauljlucas@mac.com>

---

aaaand that's the whole page bestie, you ate that 💅✨ this absolute banger of a manual page is from SWISH++, dated June 16, 2005 — yeah she's vintage, she's classic, she's still iconic. go forth and configure responsibly 🎀🦋💖