FeedFilterWithRegularExpressions

From GregariusWiki

Feed Filter with Regular Expressions is a plugin written by Rory McKinley.

Contents 1 Introduction 2 Config Screen Layout 3 Matching Title / Description 4 Substituting for the backslash 5 Adding Criteria 6 Boolean Logic and how FFRE matches items 7 Acknowledgements

[edit] Introduction

FFRE allows the user to input a number of criteria that may be used to filter out incoming items. These criteria may be simple strings or more complicated, Perl-Compatible Regular Expressions (PCRE). The user can also select whether each criterion applies to the item description, title or both the description and the title.

[edit] Config Screen Layout

When you first see the edit screen for FFRE, it will show the following items (from top to bottom):

1. Plugin Title
2. "Add a Criterion" button
3. "Backslash Substitute" input field
4. "Criterion 1" input field together witha checkbox for NOT and a checkbox for case-sensitivity
5. "Apply To" radio buttons that are used to which part fo the item the criterion applies to (title, description or both)
6. A "Submit Changes" and a "Cancel" button

[edit] Matching Title / Description

Before matching title or description, FFRE will check to see if the $item array has an element called "title" or "description" or both, depending on the user selection. If the relevant attribute(s) are missing - e.g. the pattern matches the title of the item, but the title does not exist - FFRE will just pass the item through and not filter it.

[edit] Substituting for the backslash

In PCRE, the backslash plays a fairly significant role. However, in the version of Gregarius currently used for testing (0.5.4), as part of the process of retrieving the plugin configuration variables, any backslashes are stripped out of the values - thereby crippling the PCRE. As a work-around, you can substitute another character for the backslash. Then when FFRE builds the pattern it will use for matching, it will replace all occurences of the substitute character with the backslash.

Obviously, if you are using simple strings, you will not need to worry about this, except to make sure that your simple string does not include the character that is currently set as the backslash substitute.

[edit] Adding Criteria

You can put any pattern that you wish to match into the Criterion field. This can range from a simple string to a PCRE. If you are going to use a PCRE, you must not enter the pattern delimiters that are requried for PCRE at the start and end of the pattern. FFRE will add those for you. Note - currently the default delimiter is the backtick (`), so if you are planning on using the backtick within the pattern, you should change the delimiter in the code by setting the value of the FFRE_PATTERNDELIMITER constant in the code to a character that will not be found in the pattern.

You can set matching to be case-sensitive on a per-criterion basis. If the "Case Sensitive" checkbox is unchecked, the matching of that particular criterion will be case-insensitive. You can also use the "NOT" checkbox to negate the matching. I.e. an item is only pased through the filter if it doesn't contain the negated criterion.

To enter more than one criterion, just click on the "Add a Criterion" button. A new criterion field will appear, together with boolean radio buttons for AND and OR (see Boolean Logic below).

If you leave a criterion field empty, when next you edit the settings, you will see that the empty criterion field has "disappeared". This is because FFRE will collapse the criterion set to remove the empty fields.

[edit] Boolean Logic and how FFRE matches items

FFRE has a rather simple way of addressing the matching process, especially when it comes to the boolean logic. FIrst, FFRE assesses each of the criteria against the current feed item. If the pattern in a criterion matches, FFRE stores a True value for that criterion, if not, FFRE stores False. This takes any use of the negation, case-sensitivity and Title/Description switches into account.

Once all criteria have been assesed, FFRE then looks at the boolean operators. To handle the different precedence between the "AND" and "OR" operators, FFRE converts all Boolean results joined by "AND" operators into the relevant Boolean value. After that, it processes any criteria that are "connected" by "OR" operators.

[edit] Acknowledgements

This plugin is based on the original Feed Filter code by Martey Dodoo [1] and a concept "spec" by Ian Gilfillan [2]. The javascript is heavily based on code done by Dustin Diaz [3].

Ian Gilfillan also assisted with the testing of the plugin and putting up with stupid questions.