So that's what filters are…now what do they look like, and how do we use them?

Filters, or, more formally, filter expressions, consist of one or more filter runs, which each contain one or more filter steps. For now, we'll only worry about filter expressions containing a single run – you'll be able to accomplish most basic tasks without needing multiple runs. However, know that individual runs can be combined in various ways to form a more complex filter expression, and we'll discuss this further in chapter 5.

If you've ever used any shell language (Bash, MS-DOS, PowerShell, etc.) – or even if you haven't – you can think of a filter run as a pipeline. You put a list of tiddlers into the left end of the pipeline; unless you say otherwise, all tiddlers in the wiki go in the left end. The tiddlers then pass from left to right through a series of steps in the pipeline. Each step can remove tiddlers from the list that don't match some criteria, generate and output a new list of tiddlers based on the existing list, or ignore the existing list and spit out an entirely new list. The next step then gets to make its own changes to the list output by this step, and so on until we come to the right side of the pipeline and the output of the last step is the result of the filter run.

Here are some very simple filter expressions. Each of them has just one run containing one step:

• [title[JaneDoe]] – this returns the tiddler JaneDoe
  • This is such a common usage that you can leave out the word title, resulting in just [[JaneDoe]].
• [tag[Contact]] – this returns all tiddlers tagged Contact
• [links[]] – this returns all the tiddlers that have been linked to by any tiddler in your wiki

Trying some filters

Let's try using some of these filters. To do so, open Advanced Search . You can find this option in the Tools tab in the sidebar or next to the search box, or you can press Ctrl+Shift+A. Then pick the Filter tab and type in one of the expressions above. You'll see a list of the tiddlers that match.

If you try the last filter listed above, [links[]], you might notice a whole bunch of funny-looking tiddlers show up, with names starting with $:/. What's up with those? Those are system tiddlers; they contain configuration settings or bits and pieces of TiddlyWiki itself. If you don't want to see the system tiddlers, add !is[system] to the beginning of the filter run to eliminate them (read ! as not). So that will look like [!is[system]links[]].

Let's look at that one again: [!is[system]links[]]. This run has two steps: first we eliminate all tiddlers that are system tiddlers (alternatively, you could choose to think of it as “keep all tiddlers that are not system tiddlers”), then we look at each of the tiddlers in that reduced list and spit out all of the tiddlers it links to.

Common mistakes

Filter expressions are quite sensitive to minor mistakes in punctuation. Once you've become familiar with the most common mistakes, spotting and fixing them will be trivial, but at first they may be extremely frustrating. These three errors are particularly common:

• Forgetting the outer set of square brackets, which define a filter run. Just tag[Contact], for instance, is not a valid filter expression, as it consists of a single filter step, not a complete filter run. If you see the text Filter error: Missing [ in filter expression instead of the list of tiddlers you expected, this is likely your problem.
• Including the opening square bracket but not the closing one. For some runs, the filter expression may look symmetric even if all the brackets haven't been closed yet (for example, [tag[Contact]). A useful habit to develop is inserting both the left and the right square bracket whenever you come to a left square bracket, then pressing the left arrow key to put the cursor back between them – this way, you won't have to remember how many brackets need to be closed.
• Putting a space between filter steps, like [!is[system] links[]]. What this actually does is filter on the values of the field called links (a space followed by the word links). Unless that is actually what you want, leave out the space.

Exercises

Takeaways

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