Filter

The following options affect only the render and export commands.

`--filter <[OP]{FIELD}:{QUERY}>`

Filter books/annotations before outputting.

Filtering allows you to specify, to a certain degree, which books and/or annotations to output. Currently, this is available for the export and render commands.

For example, this filter would only render annotations where its respective book's title is exactly the art spirit AND their tags contain the #star tag.

readstor render \
    --extract-tags \
    --filter "=title:the art spirit" \
    --filter "tag:#star"

This filter would export annotations where its respective book's author contains the string krishnamurti AND their tags contain either #star or #love.

readstor export \
    --extract-tags \
    --filter "author:krishnmurti" \
    --filter "?tag:#star #love"

Note that filters are case-insensitive.

Filter Results

After all the filters are run, a confirmation prompt is shown with a brief summary of the filtered down books/annotations.

$ readstor render \
    --extract-tags \
    --filter "=title:the art spirit" \
    --filter "tag:#star"
...
   ----------------------------------------------------------------
   Found 9 annotations from 2 books:
    • Think on These Things by Krishnamurti
    • The Art Spirit by Robert Henri
   ----------------------------------------------------------------
   Continue? [y/N]: █

This prompt can be auto-confirmed by passing the --auto-confirm-filter flag.

Filter Syntax

A filter consists of three parts: an optional operator, a field and a query. The syntax structure is as follows:

[operator]{field}:{query}

For example, looking at part of the command from above, we can see the three district parts of a filter:

readstor render \
    --extract-tags \
    --filter "=title:the art spirit" \
              │└──┬┘ └───────────┬┘
              │   │              │
              │   │              └────────── query: the art spirit
              │   └───────────────────────── field: title
              └────────────────────────── operator: = (exact)
    --filter "tag:#star"
              └┬┘ └──┬┘
               │     │
               │     └────────────────────── query: #star
               └──────────────────────────── field: tag
                                operator (default): ? (any)

Operator

The operator token determines how matching will be handled against the query.


Name	`operator`
Description	The match operation to use when filtering.
Valid Values	`?`(any) `*` (all) `=` (exact)
Required	No
Default	`?` (any)

When a filter is processed, the query is split on its spaces to create its component queries. For example, the input string the art sprit turns into three parts: the, art and spirit, and depending on the operator these three parts are handled differently in order to determine if an annotation is filtered out or not.

Operator	Name	Description
`?`	Any	Matches if any part of the split query is a match.
`*`	All	Matches if all parts of the split query are a match.
`=`	Exact	Matches if the original unsplit query is an exact match.

Note that when searching for an exact match in the tags field i.e. =tags:[query], the query remains split and the set of tags in the query is compared to those in each annotation.

Field

The field token determines which field to run the filter on.


Name	`field`
Description	The field to use for filtering.
Valid Values	`title` `author` `tags`
Required	Yes
Default	-

Currently, only three fields are supported:

Name	Searches	Description
`title`	books	The title of the book.
`author`	books	The author of the book.
`tags`	annotations	The annotation's `#tags`.

Query

The query string determines what will be searched in the specified field. A query is a space delineated set of words where each word can potentially be a separate search term depending on the specified operator.


Name	`query`
Description	A space delineated query string.
Valid Values	Any
Required	Yes
Default	-

`--auto-confirm-filter`

Auto-confirm Filter Results.

ReadStor