Preset Browser Advanced Filtering

In the viewport options, there's a simple multi-line edit field labeled Filter String. This allows advanced users to limit what is displayed in the Preset Browser, by testing the markup and metadata. This filter affects the currently-visible files in the thumbnail browser or flat list, and can be set to filter only files, or both files and directories.

The basic input format for the filter is:

	(NOT class:attribute(options)={value}..{value}) COMBINER

You can have as many of these as you like, space-delimited.

• Parentheses - you can optionally wrap multiple tests in parentheses for grouping purposes. The COMBINER determines how this test is handled relative against the next test.

• NOT - the optional NOT prefix inverts the following test.

• class - the class is one of "intrinsic" metadata, user or shared, and determines where the attribute is pulled from.

• attribute - the internal name of the attribute to test. Attributes are case-sensitive, and are fairly arbitrary (beyond the fact that they obey internal string naming rules).

The intrinsic class supports the following special properties:

• path: (filepath) The full local path to the file.

• name: (string) The name portion of the path, including the extension.

• ext: (string) The extension of the file, if any.

• size: (memory) The file size on disk. Directories currently return a size of 0.

• isFile: (boolean) True if this is a file; false if this is a directory.

• numFiles: (integer) The total number of recognized files in a directory.

• numDirs: (integer) The total number of sub-directories in a directory.

• numChildren: (integer) The total number of recognized files and sub-directories in a directory.

• modTime: (string) When this file or directory was last modified or created (whichever is more recent).

Some examples of common user and shared markup include:

• isFavorite: (boolean) True if this entry is flagged as a favorite.

• starRating: (integer) 0-5 indicating the star rating assigned by the user.

• tags: (string) Arbitrary strings provided by the user for tagging purposes.

• author: (string) Author of the file.

• copyright: (string) Copyright information.

• desc: (string) Description of the file.

The markup is extensible by the user, and can contain arbitrary attributes.

(options)

These are optional but, if present, must be in parentheses and follow the attribute name. The available options depend on the datatype. The list of options are space-delimited. For strings:

• substring: Search the attribute for the test value as a substring. This is the default.

• pattern: Do pattern matching.

• case: Make the comparison case-sensitive. The default is case-insensitive.

• exact: The string must exactly match the test value. This can be used with case to enforce a case-sensitive compare.

Operator

The operator is a standard mathematical test, although the behavior is a bit different depending on the datatype.

• = (Equal); the value must match exactly. When used with strings, this does pattern matching, a substring search, or an exact match depending on which options are set.

• < (Less Than), > (Greater Than), <= (Less Than or Equal), >= (Greater Than or Equal); basic logic tests.

• On numeric types, this works as you would expect.

• On float numbers, this compares against a very small threshold (epsilon), since you can't directly compare floats for technical reasons.

• On strings, this does the C function strcmp (or the case in-sensitive version, depending on if the case option is set) and tests the result. This is most useful when comparing the modTime attribute against another time to find files newer or older than that time.

If no operator is provided, then the filter matches as long as class:attribute exists on the file or directory.

If the attribute does not exist on the file or directory, and an operator is present (meaning, you're not just doing an existence test), the test is considered a failure, irrespective of the value being tested against.

Value

The value to test against. It must be wrapped in one of the following ways:

• Curly braces {...}: The value string is parsed as a "raw" format value.

• Square braces [...]: The value string is parsed as a "nice" format value.

• Less than/greater than bracing <...>: The string is in the form class:attribute path and represents another attribute to be tested against. The path is optional. If present, it is the full local path to another file or directory in the dir cache; if omitted, then the attribute is pulled from the current entry.

These braces are allowed to nest, in case you need braces inside the search string. If there is an unbalanced curly brace inside of that string, it must be escaped with ` (backtick). If you have to search for a ` (backtick), it needs to be escaped with another ` (backtick). For example, ``(two backticks side-by-side).

Testing Against Non-Existent Attributes

It is also important to note that a value test only happens if the attribute actually exists on the item. This means that if you wanted to check for everything that has the isFavorite attribute set to false and you did this:

user:isFavorite={false}

It would only match entries that have been previously flagged as favorites and then turned off again (since turning it off just reset the attribute to false; it didn't remove it from the markup). Thus, you would need to do this for your filter:

user:isFavorite={false} OR NOT user:isFavorite

Which would match if the isFavorite attribute is false, or if the isFavorite attribute does not exist.

Range Testing

The .. (two periods) syntax can be used to do a range test between the value described above and a second value. The second value after the .. follows the same formatting rules as the first value. This is only valid with the = (equal) operator, since it doesn't make sense with any of the others.

When comparing numbers, values from class:attribute must by greater than or equal to the first value and less than or equal to the second value.

When comparing strings, they are both tested against class:attribute's value with strcmp( ). (For a case-insensitive version, if the case is set, other string options are ignored.)

For those who don't know, strcmp() returns if a string is "less than" (which can generally be thought of as meaning "comes before in sort order") or "greater than" another string. The class:attribute value string must test greater than or equal to the first value string, and less than or equal to the second test string. This is primarily useful when testing file times with the intrinsic:modTime attribute, allowing you to see if a file was created in between two time ranges.

Combiner

When performing multiple tests, the AND and OR combiners can be used to decide if they all must match or only some must match. AND is optional and is inferred, if not provided. This is most useful when combined with parentheses.

For example, this matches if a Favorite flag is set in the user markup, or if the user markup Star Rating does not exist, or it does exist and is less than 1.

user:isFavorite={true} AND (NOT user:starRating OR user:starRating<{1})