Filter Expressions
==================

Filter expressions can be used to display only files in the file-view that match a certain criteria. They can be entered into the Filter Panel (**Windows->Filter** or **F3**).

The filter expression will be evaluated for each file loaded. If it evaluates to *True* for a file, then that file will be shown. Otherwise, puddletag will hide it. All comparisons are case-insensitive.

Strings
^^^^^^^

+ Strings are either a single word containing no white-space eg. *Thisisvalid* is a valid string but *No spaces are allowed* is not a valid string.
+ Anything enclosed in double-quotes will be regarded as a string. Eg *"You can do this"* or even *"artist"*.
+ Strings not enclosed in double quotes will be assumed to be a field. The field's value as stored in the file will be used provided:
    + The field is listed in :doc:`tags`. If the field isn't present in the file it'll evaluate to an empty string. Eg **artist** or **title**, but not **madeupfield**.
    + The field is present in the file. If not the string will be interpreted as normal text.
+ Any text in the form **%string%** (if it's not enclosed in quotes) will be assumed to be a field.

Expressions
^^^^^^^^^^^

.. describe:: string

    Evaluates to *True* if a contains **string** in any of it's fields.

.. describe:: MISSING field

    Evaluates to *True* if field is not present in a file. Eg. **MISSING artist** or **MISSING style**

.. describe:: PRESENT field

    Evaluates to *True* if field is present in a file. Eg. **PRESENT artist** or **PRESENT style**

.. describe:: expr1 GREATER expr2

    Evaluates to *True* if **expr1 is greater than expr2**. Conversion to floats will be attempted first. For strings comparision using ASCII positions are done. Eg. **track GREATER replay_gain**, **artist GREATER "some words"**.

.. describe:: expr1 LESS expr2

    Evaluates to *True* if **expr1 is less than expr2**. Conversion to floats will be attempted first. For strings comparision using ASCII positions are done. Eg. **track LESS replay_gain**, **artist LESS "some words"**.

.. describe:: expr1 EQUAL expr2

    Evaluates to *True* if **expr1 equals expr2**. Conversion to floats will be attempted first. For strings comparision using ASCII positions are done. Eg. **track EQUAL replay_gain**, **artist EQUAL "some words"**.

.. describe:: field HAS expr

    Evaluates to *True* if **expr is contained in field** for each file. Eg. **artist HAS Jon**, **%title% HAS "Remixed By"**.

.. describe:: field IS expr

    Evaluates to *True* if **field=expr** for each file. Eg. **artist IS "Bongo Maffin"**, **title IS Monster**.

.. describe:: expr1 AND expr2

    Evaluates to *True* if **both expr1 and expr2 evaluate to True** for each file. Eg. **artist IS "Bongo Maffin" AND title IS Monster**.


.. describe:: expr1 OR expr2

    Evaluates to *True* if **either expr1 and expr2 evaluate to True** for the file. Eg. **artist IS "Bongo Maffin" OR title IS Monster**.

.. describe:: NOT expr

    Evaluates to *True* if **expr is False**. Eg. **NOT artist IS "Bongo Maffin" OR title IS Monster**.