MafwFilter

MafwFilter — filters for browsing

Synopsis

enum                MafwFilterType;
                    MafwFilter;
#define             MAFW_FILTER_IS_COMPLEX              (f)
#define             MAFW_FILTER_IS_SIMPLE               (f)
#define             MAFW_FILTER_IS_VALID                (f)
#define             MAFW_FILTER_AND                     (...)
#define             MAFW_FILTER_APPROX                  (k, v)
#define             MAFW_FILTER_EQ                      (k, v)
#define             MAFW_FILTER_EXISTS                  (k)
#define             MAFW_FILTER_GT                      (k, v)
#define             MAFW_FILTER_LT                      (k, v)
#define             MAFW_FILTER_NOT                     (...)
#define             MAFW_FILTER_OR                      (...)
#define             mafw_filter_add_children            (f, ...)
MafwFilter*         mafw_filter_add_children_n          (MafwFilter *filter,
                                                         ...);
void                mafw_filter_free                    (MafwFilter *filter);
MafwFilter*         mafw_filter_new                     (MafwFilterType type,
                                                         ...);
MafwFilter*         mafw_filter_parse                   (char const *filter);
gchar*              mafw_filter_to_string               (const MafwFilter *filter);
MafwFilter*         mafw_filter_copy                    (const MafwFilter *filter);
char*               mafw_filter_quote                   (char const *str);
char*               mafw_filter_unquote                 (char const *str);
charconst *         mafw_filter_unquote_char            (char const *str,
                                                         char *cp);

Description

MafwFilter is a tree of filter expressions, used by sources to parse the filter argument in mafw_source_browse(). It can be either built by parsing a string by mafw_filter_parse(), or constructed programmatically with mafw_filter_new() or the appropriate convenience macros.

Filter strings

The string representation of a filter is a slightly modified variant of the LDAP search string described in RFC 4515. Modifications are:

  1. `>=' and `<=' are replaced with `>' and `<' (only one character), and they mean GREATER THAN and LESS THAN.

  2. `~=' is replaced with `~' for approximate matching.

  3. the `exists' operator (`=*') is represented by `?'.

  4. extensible matching rules are not supported.

LDAPv3 escaping of `(', `)', `*' is used: they are substituted \XX, where XX is a 2-digit hexadecimal number. See the mafw_filter_quote() and mafw_filter_unquote() functions. Attributes may consist of characters from [_-a-zA-Z0-9].

Example

`(&(artist=belga)(year>2000))' -- matches artist named `belga' with `year' after 2000.

Programmatic construction of the same filter looks like this: 

MAFW_FILTER_AND(MAFW_FILTER_EQ("artist", "belga"),
	            MAFW_FILTER_GT("year", "2000"))

Details

enum MafwFilterType

typedef enum {
	MAFW_F_INVALID = 0,
	/* Aggregates. */
	mafw_f_and,
	mafw_f_or,
	mafw_f_not,
	/* Divider between aggregate and simple filters. */
	MAFW_F_COMPLEX,
	/* Simple ones. */
	mafw_f_exists,
	mafw_f_eq,
	mafw_f_lt,
	mafw_f_gt,
	mafw_f_approx,
	/* last element */
	MAFW_F_LAST,
} MafwFilterType;

Represents the different kinds of filters used in MAFW.

MAFW_F_INVALID zero value, not used.
mafw_f_and a conjunction.
mafw_f_or a disjunction.
mafw_f_not a negation.
MAFW_F_COMPLEX separator, not used.
mafw_f_exists existence.
mafw_f_eq equality.
mafw_f_lt less-than.
mafw_f_gt greater-than.
mafw_f_approx approximate matching.
MAFW_F_LAST separator, not used.

MafwFilter

typedef struct {
	MafwFilterType type;
	union {
		struct MafwFilter **parts;
		struct {
			char *key;
			char *value;
		};
	};
} MafwFilter;

Programmatic representation of a filter.

MafwFilterType type; the type of the filter (enum filter_type).
struct MafwFilter **parts; if the filter is aggregate; it's an array of pointers to child filter structures, terminated by NULL.
char *key; if the filter is simple; the attribute to match.
char *value; if the filter is simple; the value to match with. If the type is mafw_f_exists, it is an empty string.

MAFW_FILTER_IS_COMPLEX()

#define             MAFW_FILTER_IS_COMPLEX(f)

Checks if a filter is complex

f : a filter instance.

MAFW_FILTER_IS_SIMPLE()

#define             MAFW_FILTER_IS_SIMPLE(f)

Checks if a filter is simple

f : a filter instance.

MAFW_FILTER_IS_VALID()

#define             MAFW_FILTER_IS_VALID(f)

Checks if a filter is valid

f : a filter instance.

MAFW_FILTER_AND()

#define             MAFW_FILTER_AND(...)

Constructs a filter representing the conjunction of its arguments.

... : list of elements

MAFW_FILTER_APPROX()

#define MAFW_FILTER_APPROX(k, v) mafw_filter_new(mafw_f_approx, k, v)

Constructs a filter representing `value of k approximately matches v'.

k : metadata key.
v : the value.

MAFW_FILTER_EQ()

#define MAFW_FILTER_EQ(k, v)     mafw_filter_new(mafw_f_eq, k, v)

Constructs a filter representing `value of k equals to v'.

k : metadata key.
v : the value.

MAFW_FILTER_EXISTS()

#define MAFW_FILTER_EXISTS(k)    mafw_filter_new(mafw_f_exists, k, NULL)

Constructs a filter representing `k is not empty'.

k : metadata key.

MAFW_FILTER_GT()

#define MAFW_FILTER_GT(k, v)     mafw_filter_new(mafw_f_gt, k, v)

Constructs a filter representing `value of k is greater than v'.

k : metadata key.
v : the value.

MAFW_FILTER_LT()

#define MAFW_FILTER_LT(k, v)     mafw_filter_new(mafw_f_lt, k, v)

Constructs a filter representing `value of k is less than v'.

k : metadata key.
v : the value.

MAFW_FILTER_NOT()

#define MAFW_FILTER_NOT(...) mafw_filter_new(mafw_f_not, ##__VA_ARGS__, NULL)

Constructs a filter representing negation of its argument.

... : list of elements

MAFW_FILTER_OR()

#define MAFW_FILTER_OR(...)  mafw_filter_new(mafw_f_or, ##__VA_ARGS__, NULL)

Constructs a filter representing disjunction of its arguments.

... : list of elements

mafw_filter_add_children()

#define             mafw_filter_add_children(f, ...)

Adds children nodes to the given filter. Does nothing if the filter is not an aggregate filter (AND, OR). Use the mafw_filter_add_children() convenience macro that adds the terminating NULL automatically.

f : the filter to add to.
... : list of children

mafw_filter_add_children_n ()

MafwFilter*         mafw_filter_add_children_n          (MafwFilter *filter,
                                                         ...);

Adds children nodes to the given filter. Does nothing if the filter is not an aggregate filter (AND, OR). Use the mafw_filter_add_children() convenience macro that adds the terminating NULL automatically.

filter : the filter to add to.
... : a NULL terminated list of "s" to add.
Returns : the modified filter.

mafw_filter_free ()

void                mafw_filter_free                    (MafwFilter *filter);

Frees a filter tree recursively. Does nothing if NULL is passed.

filter : the filter tree to free.

mafw_filter_new ()

MafwFilter*         mafw_filter_new                     (MafwFilterType type,
                                                         ...);

Creates a new filter tree node.

type : the type of the filter (MafwFilterType).
... : depending on the type, either a NULL terminated list of "s", or if it's a simple type, a key and a value. In the second case, the key and value pointers are duplicated.
Returns : the newly allocated filter node.

mafw_filter_parse ()

MafwFilter*         mafw_filter_parse                   (char const *filter);

Builds a filter tree from the given filter expression.

filter : the string representation of a MAFW filter.
Returns : a newly allocated filter tree, or NULL if the string contains syntax errors.

mafw_filter_to_string ()

gchar*              mafw_filter_to_string               (const MafwFilter *filter);

Transforms the MafwFilter into a string representation. If you created that MafwFilter from a string representation, the result of calling this function doesn't have to return the same string, just the an equivalent one.

filter : a MafwFilter
Returns : a newly allocated string, or NULL if the filter was NULL or incorrect

mafw_filter_copy ()

MafwFilter*         mafw_filter_copy                    (const MafwFilter *filter);

Copies a MafwFilter

filter : a MafwFilter
Returns : a newly allocated MafwFilter, or NULL if any error occurs

mafw_filter_quote ()

char*               mafw_filter_quote                   (char const *str);

Quotes str according to LDAPv3 rules. The following characters are quoted: '*', '(', ')', '\'.

str : the string to quote.
Returns : a newly allocated quoted string.

mafw_filter_unquote ()

char*               mafw_filter_unquote                 (char const *str);

Unquotes the LDAPv3 quoted string str.

str : a LDAPv3 quoted string.
Returns : a newly allocated string containing the unquoted value of str or NULL if str is quoted improperly

mafw_filter_unquote_char ()

charconst *         mafw_filter_unquote_char            (char const *str,
                                                         char *cp);

Unquotes one token (a character or an escape sequence) of str. The token must not be an unquoted NIL, so you need to check the end-of-string condition prior to calling this function. This is because the return value would point out of bounds or be ambiguous otherwise. This function is intended for sources that need to unescape then reescape in a domain-specific format property values.

str : points to the token to unquote
cp : points to the char to store the unquoted value
Returns : the starting position of the next token or NULL if the current token was found to be ununquotable.

See Also

MafwSource
Generated by GTK-Doc V1.10