Overarching handler for TiddlyWeb filters.
Filters provide an extensible syntax for limiting any Collection by attributes in the entities in the collection. Though primarily for Tiddlers, Bags and Recipes can be filtered as well.
The basic filters provide selecting and sorting on attributes of the entities and limiting (the number of) entities. These basic types can be extended with plugins, and the ways attributes are handled can also be extended.
Filters are parsed from a string that is formatted as a CGI query string with parameters and arguments. The parameter is a filter type. Each filter is processed in sequence: the first processing all the entities handed to it, the next taking only those that result from the first.
Filters can be extended by adding more parsers to FILTER_PARSERS. Parsers for existing filter types may be extended as well (see the documentation for each type).
The call signature for a filter is:
filter(entities, indexable=indexable, environ=environ)
The attribute and value for which a filter filters is established in the parsing stage and set as upvalues of the filter closure that gets created.
indexable and environ are optional parameters that in special cases allow a select style filter to be optimized with the use of an index. In the current implementation this is only done when:
- the select filter is the first filter in a stack of filters passed to recursive_filter
- the entities to be filtered are tiddlers and a bag is provided (which helps manage the index)
When both of the above are true the system looks for a module named by tiddlyweb.config[‘indexer’], imports it, looks for a function called indexy_query, and passes environ and information about the bag and the attribute being selected.
What index_query does to satisfy the query is up to the module. It should return a list of tiddlers that have been loaded from tiddlyweb.store.
If for some reason index_query does not wish to perform the query (e.g. the index cannot satisfy the query) it may raise FilterIndexRefused and the normal filtering process will be performed.
Bases: exceptions.Exception
An exception to throw when an attempt is made to filter on an unavailable attribute.
Bases: tiddlyweb.filters.FilterError
A filter index has refused to satisfy a filter with its index.
Take a string that looks like a CGI query string and parse if for filters. Return a tuple of a list of filter functions and a string of whatever was in the query string that did not result in a filter.
Recursively process the list of filters found by parse_for_filters against the given list of entities.
Each next filter processes only those entities that were results of the previous filter.
Misnamed, early versions were more truly recursive.
Limit a group of entities using a syntax similar to SQL Limit:
limit=<index>,<count> limit=<count>
Make a slice of a list of entities based on a count and index.
Parse the argument of a limit filter for a count and index argument, return a function which does the limiting.
Exceptions while parsing are passed up the stack.
Filter routines for selecting some entities, usually tiddlers, from a collection of entities, usually by an attribute of the tiddlers.
The syntax is:
select=attribute:value # attribute is value select=attribute:!value # attribute is not value select=attribute:>value # attribute is greater than value select=attribute:<value # attribute is less than value
ATTRIBUTE_SELECTOR is checked for a function which returns true or false for whether the provide value matches for the entity being tested. The default case is lower case string equality. Other functions may be provided by plugins and other extensions. Attributes may be virtual, i.e. not real attributes on entity. For example we can check for the presence of a tag in a tiddlers tags attribute with
select=tag:tagvalue
An attribute function takes an entity, an attribute name and a value, may do anything it wants with it, and must return True or False.
‘!’ negates a selection, getting all those entities that don’t match.
‘>’ gets those entities that sort greater than the value.
‘<’ gets those entities that sort less than the value.
When doing sorting ATTRIBUTE_SORT_KEY is consulted to canonicalize the value. See tiddlyweb.filters.sort.
Return true if the named bag is in the recipe.
Look in the entity for an attribute with the provided value. First proper attributes are checked, then extended fields. If neither of these are present, return False.
Return true if the entity has the named field.
Select entities where value of attribute matches the provide value.
If negate is true, get those that don’t match.
Parse a select parse command into attributes and arguments and return a function (for later use) which will do the selecting.
Select entities that sort greater or less than the provided value for the provided attribute.
Return true if the provided entity has a tag of value in its tag list.
Return true if the provided entity has the string provided in value in its text attribute.
Sort a collection of entities by some attribute. The syntax is:
sort=attribute # sort ascending sort=-attribute # sort descending
Atribute is either a real entity attribute or a key in ATTRIBUTE_SORT_KEY that has as its value a function used to generate a key to pass to the sort. ATTRIBUTE_SORT_KEY can be extended by plugins.
Treat attribute as int if it looks like one.
Take a string of 14 or less digits and turn it into 14 digits for the sake of comparing entity dates.
Sort a group of entities by some attribute. Inspect ATTRIBUTE_SORT_KEY to see if there is a special function by which we should generate the value for this attribute.
Create a function which will sort a collection of entities.