We saw a few examples of filter steps in the previous section. Let's take a closer look at the syntax.

Operators, suffixes, and parameters

Filter steps are composed of three parts, which take this basic form:

operator:suffix[parameter]

• An operator describes the task the filter performs. TiddlyWiki supports a large number of operators, and some plugins add additional operators.
• A suffix further refines the meaning of the operator, often by listing a specific field that it applies to. Only some operators accept a suffix at all, and it is usually optional even when it is accepted.
• A parameter describes what the operator should try to find or do. For instance, with the tag operator, the parameter indicates which tag you want to match.

The exact meaning of the suffix and parameter depends on which operator is being used.

As briefly mentioned in the previous section, you can place a ! (pronounced not or bang) before the operator. Typically, this negates its meaning, so that whatever tiddlers it would have allowed to pass it now filters out, and vice versa. With a few operators, it does something different and operator-specific.

Putting this together, a simple filter step we saw in the previous section was tag[Contact]. In this step, tag is the operator and Contact is the parameter. Most commonly, the parameter goes in square brackets, but we'll learn in chapter 4 that these can be replaced with <angle brackets> or {curly braces} for different effects.

The tag operator has an optional suffix strict (don't worry about what it does for now). If we used it, our filter step would look like tag:strict[Contact].

Inputs and outputs

We can also talk about the inputs or input tiddlers and outputs or output tiddlers of a filter step. Unlike operators, suffixes, or parameters, these do not correspond to text in the filter expression; rather, they are the data that moves through the pipeline from left to right when TiddlyWiki evaluates the filter.

Input tiddlers are the tiddlers that come down the pipeline from the left side of the operator.

• If the filter run is [tag[Person]], all tiddlers in the wiki are input tiddlers to tag[Person]. Unless you use one of a special set of filter operators called constructors as the first step in a run, all tiddlers in the wiki are the inputs to the leftmost step. Constructors ignore any input they receive and generate an entirely new set of output tiddlers based only on their suffix and parameters (i.e., they construct a list), so if TiddlyWiki sees one as the first step of a run, it saves itself some effort by not passing the constructor any input at all.
• If the filter run is [title[JaneDoe]tag[Person]], the sole input tiddler to tag[Person] is JaneDoe. (title is a constructor.)
• If the filter run is [tag[Application]tag[Person]], the input tiddlers to tag[Person] are all the tiddlers in the wiki tagged with Application.

Output tiddlers, similarly, are the tiddlers that get passed off to the next step in the run (or become the result of the entire filter run, if this is the last step). In the [tag[Application]tag[Person]] example above, the outputs of tag[Application] are all the tiddlers in the wiki tagged with Application. Or to put it another way, the outputs of tag[Application] are the inputs to tag[Person].

Multiple suffixes and parameters

Most filter steps that you'll use early in your TiddlyWiki career will have one parameter, and sometimes one suffix. However, certain filter operators accept more than one suffix and/or more than one parameter:

• Multiple suffixes are separated by additional colons, like search:myfield:literal[parameter].
• Multiple parameters are separated by commas between additional pairs of brackets, like pad[5],[-].

Exercises

Takeaways

Takeaways are not available in the static version of Grok TiddlyWiki. Visit the wiki version of this page to study takeaways.