Filter plugin for CaRP Evolution

CaRP: Caching RSS Parser - Documentation

Filter

Filter is a plugin bundled with CaRP Evolution. It enables more powerful filtering of RSS newsfeed items than is possible with CaRP's built-in filterin and filterout settings, including and, or, not, regular expression matching, and more.

Installation:
To install Filter, put filter.php into the "plugins" folder inside the folder containing carp.php. (If no plugins folder exists, create one.)

Use:
To use this plugin, do the following:

Enter the following command into your webpage after "require_once '/path/to/carp.php';":
CarpLoadPlugin('filter.php');
Use the functions listed below to set up whatever filtering you wish to use.

Example:
The following code will display any items whose title does not contain the word "microsoft", as long as its title or description contains either the word "apple" or the word "adobe":

FilterCarpAdd('title','microsoft','','!');
FilterCarpStartGroup('and');
FilterCarpAdd('title,desc','apple');
FilterCarpAdd('title,desc','adobe','or');

Note that the above example leaves out a few settings which are optional. The full code including the unnecessary settings is shown below for instructive purposes:

FilterCarpInOrOut('in');
FilterCarpAdd('title','microsoft','','!');
FilterCarpStartGroup('and');
FilterCarpAdd('title,desc','apple');
FilterCarpAdd('title,desc','adobe','or');
FilterCarpEndGroup();

"FilterFilterCarpInOrOut('in');" was unnecessary at the beginning because "in" is the default. "FilterCarpEndGroup();" was unnecessary at the end because no other settings followed which were not to be included in that group. See below for more information about each function.

Functions:

FilterCarpAdd($fields, $pattern, $and_or='and', $operator='contain');
This function adds a filtering setting. The last two parameters are optional if you wish to use the defaults indicated above.
$fields: A comma-separated list of which fields to check. Use the same CaRP internal field names as you would with CarpConf('iorder','[field names]'); (Note however that you cannot use the "link" field here--use "url" and/or "title" instead.)
$pattern: The text to look for. This is not case sensitive, except when doing a regular expression match without the "i" option (see below). HTML entities are converted to single characters before comparing.
$and_or: Specify whether to require this to match in addition to any previous filter ('and'), or whether to require only this or any previous filter ('or'). Defaults to 'and' if omitted or left blank (as in the example above).
$operator: 'contain', 'equal', 'begin', 'end' or 'regex'. The first four specify where in the field to look for $pattern ('contain' = anywhere, 'equal' = match the entire field). 'regex' indicates that $pattern is a regular expression. If omitted or left blank, the default is 'contain'.

To change "contain" to "doesn't contain", "begin" to "doesn't begin", etc., add an exclamation mark before the word, for example, '!contain', '!begin', etc. Because 'contain', is the default, "doesn't contain" may be specified with just an exclamation mark ('!').

When using 'regex', $pattern must contain a regular expression, including the beginning and ending delimiters and any options desired. For example, to do a case-insensitive check for "monster party", "monsters party", "Monsters party", etc., you could specify the pattern: '/monsters? party/i'.
FilterCarpStartGroup($and_or='or',$not=0);
This function begins the grouping of filter settings, like the beginning parenthesis in "title contains 'microsoft' and (title contains 'apple' or title contains 'adobe')". Without the parenthesis (without the grouping), this statement would be evaluated as if it were group like "(title contains 'microsoft' and title contains 'apple') or title contains 'adobe'" More generally, without grouping, "a and b or c and d and e or f" would be evaluated as if group as "((((a and b) or c) and d) and e) or f", with each test being combined with the cumulative results of all previous tests.
FilterCarpEndGroup();
This function ends the grouping of filter settings, like the ending parenthesis in the examples shown under FilterCarpStartGroup.
FilterCarpInOrOut($in_out);
This function controls whether settings added with the other functions are applied to settings for selecting (filtering in) or filtering out newsfeed items. When the Filter plugin is first loaded, the default is 'in'. Valid values for $in_out are, as you might expect, 'in' and 'out'. Call this function first, and then the other functions. If you specify both 'in' and 'out' settings, the 'in' settings are applied first, and then the 'out' settings are applied to any items filtered in by the 'in' settings.
FilterCarpReset();
Resets the plugin's settings.