A compact, field-agnostic query language for filtering records. More...

Typedefs
typedef const char (	N_QUERY_GET) (const char field, void user_data)
	Field-value getter: return the value of `field` for the record being evaluated (NUL-terminated, borrowed), or NULL when the field is unknown/empty.

Functions
N_QUERY *	n_query_compile (const char expr, char errbuf, size_t errlen)
	Compile an expression into a query.
N_QUERY *	n_query_compile_ex (const char expr, const char const fields, size_t nfields, char errbuf, size_t errlen)
	Compile `expr`, rejecting any field not in `fields`.
int	n_query_eval (const N_QUERY query, N_QUERY_GET get, void user_data)
	Evaluate a compiled query against one record via `get`.
void	n_query_free (N_QUERY **query)
	Free a compiled query and set the pointer to NULL.

Detailed Description

A compact, field-agnostic query language for filtering records.

The grammar is:

query := or or := and ( "OR" and )* and := not ( "AND" not )* not := "NOT" not | primary primary := "(" or ")" | comparison comparison := FIELD OP VALUE

FIELD is an identifier (letters, digits, '_' and '.', e.g. "host" or "req.path"). VALUE is a bareword (run of non-space, non-operator, non-paren characters) or a double-quoted string. The operators are:

= case-insensitive string equality != case-insensitive string inequality ~ case-insensitive substring contains !~ does not contain =~ regex match (PCRE via n_pcre) !~~ regex does not match

< >= <= numeric comparison (both sides parsed as numbers)

AND/OR/NOT are case-insensitive keywords. Evaluation pulls each field's value through a caller-supplied getter, so the language is independent of any record type: the caller maps field names to its own data.

Typedef Documentation

◆ N_QUERY_GET

typedef const char *(* N_QUERY_GET) (const char *field, void *user_data)

Field-value getter: return the value of field for the record being evaluated (NUL-terminated, borrowed), or NULL when the field is unknown/empty.

Definition at line 71 of file n_query.h.

Function Documentation

◆ n_query_compile()

N_QUERY * n_query_compile	(	const char *	expr,
		char *	errbuf,
		size_t	errlen )

Compile an expression into a query.

On error returns NULL and, when errbuf is non-NULL, writes a short message into it. Free with n_query_free. An empty/whitespace expression compiles to a match-all query.

Definition at line 399 of file n_query.c.

References n_query_compile_ex().

Referenced by expect_parse_error(), and run().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_query_compile_ex()

N_QUERY * n_query_compile_ex	(	const char *	expr,
		const char const	fields,
		size_t	nfields,
		char *	errbuf,
		size_t	errlen )

Compile expr, rejecting any field not in fields.

n_query_compile cannot tell a misspelled field from an empty one: the getter returns NULL for both, which evaluates as the empty string, so field != value and field !~ value on a TYPO match every record and the operator is told nothing. Passing the vocabulary catches it at compile time, with the offending name in errbuf, which is the only point at which it can still be reported.

Parameters

expr	The query text.
fields	The known field names, or NULL to skip validation (which is what n_query_compile does, so existing callers are unchanged).
nfields	Length of `fields`.
errbuf	Receives the reason on failure.
errlen	Size of `errbuf`.