[Proposal] Module header metadata: let filter operators describe their syntax

While creating an TiddlyWiki Language Server for VSCode, that dynamically shows extended information about all kinds of wikitext. Currently it's hard to gather detailed filter info, without some hacks.

Proposal

Let filter operator modules describe their syntax in a meta-data field.

Why

Nothing in a running wiki says what an operator's parameter or suffix is: operator modules export plain functions. The docs' op-parameter and op-suffix fields exist only in tw5.com and are prose. Header descriptions can't tell a field operand from a value (title.js: "comparing title fields for equality", yet its operand is a value). So a tool that completes field names after [sort[ has to guess from the operator's code.

Header fields

At boot, header lines up to the first blank line already become fields of the module tiddler:

/*\
title: $:/core/modules/filters/search.js
type: application/javascript
module-type: filteroperator
op-syntax: [search[$text$]] [search:$field-list$:$flag-list$[$text$]]
op-flags: literal whitespace regexp words some casesensitive anchored

Filter operator for searching for the text in the operand tiddler

\*/

• op-syntax: every form of the operator in filter syntax, space separated. $kind$ marks what the writer supplies; $field=title$ gives a default.
• op-flags: the words a $flag-list$ accepts.

Kinds: title, title-list, tag, field, field-list, flag-list, index, number, date, regexp, text.

$kind$ rather than <kind>, because the filter parser reads < as a variable operand, even in a suffix. With $kind$, $tw.wiki.parseFilter reads each form like any filter.

Metadata only

For security reasons, the engine never reads these fields, so an edited field cannot change how a filter runs; tools treat them as hints. A core test can keep them updated: every form must name an operator its module exports.

Uses

Operator modules are shadow tiddlers, so wikitext reads the fields directly, e.g. [all[shadows]module-type[filteroperator]get[op-syntax]]:

• docs pages transclude op-syntax instead of keeping a copy
• the Control Panel lists every operator's forms, plugins included
• filter inputs and editors suggest fields, tags and flags

Open questions

1. Kinds vocabulary and field names?
2. The same pattern for run prefixes and widgets?