Expression parser

Classes
struct	ap_expr_info_t
struct	ap_expr_eval_ctx_t
struct	ap_expr_lookup_parms
struct	ap_LINK_expr_lookup_t

Macros
#define	AP_EXPR_FLAG_SSL_EXPR_COMPAT   1
#define	AP_EXPR_FLAG_DONT_VARY   2
#define	AP_EXPR_FLAG_RESTRICTED   4
#define	AP_EXPR_FLAG_STRING_RESULT   8
#define	ap_expr_parse_cmd(cmd, expr, flags, err, lookup_fn)    ap_expr_parse_cmd_mi(cmd, expr, flags, err, lookup_fn, APLOG_MODULE_INDEX)

Typedefs
typedef struct ap_expr_node	ap_expr_t
typedef int	ap_expr_op_unary_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg)
typedef int	ap_expr_op_binary_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg1, const char *arg2)
typedef const char *()	ap_expr_string_func_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg)
typedef apr_array_header_t *()	ap_expr_list_func_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg)
typedef const char *()	ap_expr_var_func_t(ap_expr_eval_ctx_t *ctx, const void *data)
typedef int()	ap_expr_lookup_fn_t(ap_expr_lookup_parms *parms)
typedef int	ap_HOOK_expr_lookup_t(ap_expr_lookup_parms *parms)
typedef struct ap_LINK_expr_lookup_t	ap_LINK_expr_lookup_t

Functions
int	ap_expr_exec (request_rec *r, const ap_expr_info_t *expr, const char **err)
int	ap_expr_exec_re (request_rec *r, const ap_expr_info_t *expr, apr_size_t nmatch, ap_regmatch_t *pmatch, const char **source, const char **err)
int	ap_expr_exec_ctx (ap_expr_eval_ctx_t *ctx)
const char *	ap_expr_str_exec (request_rec *r, const ap_expr_info_t *expr, const char **err)
const char *	ap_expr_str_exec_re (request_rec *r, const ap_expr_info_t *expr, apr_size_t nmatch, ap_regmatch_t *pmatch, const char **source, const char **err)
int	ap_expr_lookup_default (ap_expr_lookup_parms *parms)
void	ap_hook_expr_lookup (ap_HOOK_expr_lookup_t *pf, const char *const *aszPre, const char *const *aszSucc, int nOrder)
int	ap_run_expr_lookup (ap_expr_lookup_parms *parms)
apr_array_header_t *	ap_hook_get_expr_lookup (void)
const char *	ap_expr_parse (apr_pool_t *pool, apr_pool_t *ptemp, ap_expr_info_t *info, const char *expr, ap_expr_lookup_fn_t *lookup_fn)
ap_expr_info_t *	ap_expr_parse_cmd_mi (const cmd_parms *cmd, const char *expr, unsigned int flags, const char **err, ap_expr_lookup_fn_t *lookup_fn, int module_index)
void	ap_expr_init (apr_pool_t *pool)

Detailed Description

Macro Definition Documentation

AP_EXPR_FLAG_DONT_VARY

#define AP_EXPR_FLAG_DONT_VARY   2

Don't add significant request headers to the Vary response header

Definition at line 61 of file ap_expr.h.

AP_EXPR_FLAG_RESTRICTED

#define AP_EXPR_FLAG_RESTRICTED   4

Don't allow functions/vars that bypass the current request's access restrictions or would otherwise leak confidential information. Used by e.g. mod_include.

Definition at line 66 of file ap_expr.h.

AP_EXPR_FLAG_SSL_EXPR_COMPAT

#define AP_EXPR_FLAG_SSL_EXPR_COMPAT   1

Use ssl_expr compatibility mode (changes the meaning of the comparison operators)

Definition at line 59 of file ap_expr.h.

AP_EXPR_FLAG_STRING_RESULT

#define AP_EXPR_FLAG_STRING_RESULT   8

Expression evaluates to a string, not to a bool

Definition at line 68 of file ap_expr.h.

ap_expr_parse_cmd

#define ap_expr_parse_cmd	(		cmd,
			expr,
			flags,
			err,
			lookup_fn
	)		ap_expr_parse_cmd_mi(cmd, expr, flags, err, lookup_fn, APLOG_MODULE_INDEX)

Convenience wrapper for ap_expr_parse_cmd_mi() that sets module_index = APLOG_MODULE_INDEX

Definition at line 340 of file ap_expr.h.

Typedef Documentation

ap_expr_list_func_t

typedef apr_array_header_t *() ap_expr_list_func_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg)

List valued function, takes a string argument and returns a list of strings Can currently only be called following the builtin '-in' operator.

Parameters

ctx	The evaluation context
data	An opaque context provided by the lookup hook function
arg	The argument

Returns

The functions result list of strings, may be NULL for 'empty array'

Definition at line 242 of file ap_expr.h.

ap_expr_lookup_fn_t

typedef int() ap_expr_lookup_fn_t(ap_expr_lookup_parms *parms)

Function for looking up the provider function for a variable, operator or function in an expression.

Parameters

parms

The parameter struct, also determines where the result is stored.

Returns

OK on success, !OK on failure, DECLINED if the requested name is not handled by this function

Definition at line 291 of file ap_expr.h.

ap_expr_op_binary_t

typedef int ap_expr_op_binary_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg1, const char *arg2)

Binary operator, takes two string arguments and returns a bool value. The name must have the form '-cmp' (at least two letters).

Parameters

ctx	The evaluation context
data	An opaque context provided by the lookup hook function
arg1	The left operand
arg2	The right operand

Returns

0 or 1

Definition at line 222 of file ap_expr.h.

ap_expr_op_unary_t

typedef int ap_expr_op_unary_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg)

The parser can be extended with variable lookup, functions, and and operators.

During parsing, the parser calls the lookup function to resolve a name into a function pointer and an opaque context for the function. If the argument to a function or operator is constant, the lookup function may also parse that argument and store the parsed data in the context.

The default lookup function is the hook ap_expr_lookup_default which just calls ap_run_expr_lookup. Modules can use it to make functions and variables generally available.

An ap_expr consumer can also provide its own custom lookup function to modify the set of variables and functions that are available. The custom lookup function can in turn call 'ap_run_expr_lookup'. Unary operator, takes one string argument and returns a bool value. The name must have the form '-z' (one letter only).

Parameters

ctx	The evaluation context
data	An opaque context provided by the lookup hook function
arg	The (right) operand

Returns

0 or 1

Definition at line 211 of file ap_expr.h.

ap_expr_string_func_t

typedef const char *() ap_expr_string_func_t(ap_expr_eval_ctx_t *ctx, const void *data, const char *arg)

String valued function, takes a string argument and returns a string

Parameters

ctx	The evaluation context
data	An opaque context provided by the lookup hook function
arg	The argument

Returns

The functions result string, may be NULL for 'empty string'

Definition at line 231 of file ap_expr.h.

ap_expr_t

typedef struct ap_expr_node ap_expr_t

A node in the expression parse tree

Definition at line 38 of file ap_expr.h.

ap_expr_var_func_t

typedef const char *() ap_expr_var_func_t(ap_expr_eval_ctx_t *ctx, const void *data)

Variable lookup function, takes no argument and returns a string

Parameters

ctx	The evaluation context
data	An opaque context provided by the lookup hook function

Returns

The expanded variable

Definition at line 251 of file ap_expr.h.

ap_HOOK_expr_lookup_t

typedef int ap_HOOK_expr_lookup_t(ap_expr_lookup_parms *parms)

Definition at line 299 of file ap_expr.h.

ap_LINK_expr_lookup_t

typedef struct ap_LINK_expr_lookup_t ap_LINK_expr_lookup_t

Function Documentation

ap_expr_exec()

int ap_expr_exec	(	request_rec *	r,
		const ap_expr_info_t *	expr,
		const char **	err
	)

Evaluate a parse tree, simple interface

Parameters

r	The current request
expr	The expression to be evaluated
err	Where an error message should be stored

Returns

> 0 if expression evaluates to true, == 0 if false, < 0 on error

Note

err will be set to NULL on success, or to an error message on error

request headers used during evaluation will be added to the Vary: response header, unless AP_EXPR_FLAG_DONT_VARY is set.

Definition at line 815 of file util_expr_eval.c.

ap_expr_exec_ctx()

int ap_expr_exec_ctx

(

ap_expr_eval_ctx_t *

ctx

)

Evaluate a parse tree, full featured version

Parameters

ctx	The evaluation context with all data filled in

Returns

> 0 if expression evaluates to true, == 0 if false, < 0 on error

Note

*ctx->err will be set to NULL on success, or to an error message on error

request headers used during evaluation will be added to the Vary: response header if ctx->vary_this is set.

Definition at line 821 of file util_expr_eval.c.

ap_expr_exec_re()

int ap_expr_exec_re	(	request_rec *	r,
		const ap_expr_info_t *	expr,
		apr_size_t	nmatch,
		ap_regmatch_t *	pmatch,
		const char **	source,
		const char **	err
	)

Evaluate a parse tree, with access to regexp backreference

Parameters

r	The current request
expr	The expression to be evaluated
nmatch	size of the regex match vector pmatch
pmatch	information about regex matches
source	the string that pmatch applies to
err	Where an error message should be stored

Returns

> 0 if expression evaluates to true, == 0 if false, < 0 on error

Note

err will be set to NULL on success, or to an error message on error

nmatch/pmatch/source can be used both to make previous matches available to ap_expr_exec_re and to use ap_expr_exec_re's matches later on.

request headers used during evaluation will be added to the Vary: response header, unless AP_EXPR_FLAG_DONT_VARY is set.

Definition at line 875 of file util_expr_eval.c.

ap_expr_init()

void ap_expr_init

(

apr_pool_t *

pool

)

Internal initialisation of ap_expr (for httpd internal use)

Definition at line 1825 of file util_expr_eval.c.

ap_expr_lookup_default()

int ap_expr_lookup_default

(

ap_expr_lookup_parms *

parms

)

Default lookup function which just calls ap_run_expr_lookup(). ap_run_expr_lookup cannot be used directly because it has the wrong calling convention under Windows.

Definition at line 374 of file util_expr_eval.c.

ap_expr_parse()

const char * ap_expr_parse	(	apr_pool_t *	pool,
		apr_pool_t *	ptemp,
		ap_expr_info_t *	info,
		const char *	expr,
		ap_expr_lookup_fn_t *	lookup_fn
	)

Parse an expression into a parse tree

Parameters

pool	Pool
ptemp	temp pool
info	The ap_expr_info_t struct (with values filled in)
expr	The expression string to parse
lookup_fn	The lookup function to use, NULL for default

Returns

NULL on success, error message on error. A pointer to the resulting parse tree will be stored in info->root_node.

Definition at line 379 of file util_expr_eval.c.

ap_expr_parse_cmd_mi()

ap_expr_info_t * ap_expr_parse_cmd_mi	(	const cmd_parms *	cmd,
		const char *	expr,
		unsigned int	flags,
		const char **	err,
		ap_expr_lookup_fn_t *	lookup_fn,
		int	module_index
	)

High level interface to ap_expr_parse that also creates ap_expr_info_t and uses info from cmd_parms to fill in most of it.

Parameters

cmd	The cmd_parms struct
expr	The expression string to parse
flags	The flags to use, see AP_EXPR_FLAG_*
err	Set to NULL on success, error message on error
lookup_fn	The lookup function used to lookup vars, functions, and operators
module_index	The module_index to set for the expression

Returns

The parsed expression

Note

Usually ap_expr_parse_cmd() should be used

Definition at line 428 of file util_expr_eval.c.

ap_expr_str_exec()

const char * ap_expr_str_exec	(	request_rec *	r,
		const ap_expr_info_t *	expr,
		const char **	err
	)

Evaluate a parse tree of a string valued expression

Parameters

r	The current request
expr	The expression to be evaluated
err	Where an error message should be stored

Returns

The result string, NULL on error

Note

err will be set to NULL on success, or to an error message on error

request headers used during evaluation will be added to the Vary: response header, unless AP_EXPR_FLAG_DONT_VARY is set.

Definition at line 963 of file util_expr_eval.c.

ap_expr_str_exec_re()

const char * ap_expr_str_exec_re	(	request_rec *	r,
		const ap_expr_info_t *	expr,
		apr_size_t	nmatch,
		ap_regmatch_t *	pmatch,
		const char **	source,
		const char **	err
	)

Evaluate a parse tree of a string valued expression

Parameters

r	The current request
expr	The expression to be evaluated
nmatch	size of the regex match vector pmatch
pmatch	information about regex matches
source	the string that pmatch applies to
err	Where an error message should be stored

Returns

The result string, NULL on error

Note

err will be set to NULL on success, or to an error message on error

nmatch/pmatch/source can be used both to make previous matches available to ap_expr_exec_re and to use ap_expr_exec_re's matches later on.

request headers used during evaluation will be added to the Vary: response header, unless AP_EXPR_FLAG_DONT_VARY is set.

Definition at line 907 of file util_expr_eval.c.

ap_hook_expr_lookup()

void ap_hook_expr_lookup	(	ap_HOOK_expr_lookup_t *	pf,
		const char *const *	aszPre,
		const char *const *	aszSucc,
		int	nOrder
	)

Definition at line 51 of file util_expr_eval.c.

ap_hook_get_expr_lookup()

apr_array_header_t * ap_hook_get_expr_lookup

(

void

)

Definition at line 51 of file util_expr_eval.c.

ap_run_expr_lookup()

int ap_run_expr_lookup

(

ap_expr_lookup_parms *

parms

)

< Module declines to handle

< Module declines to handle

Definition at line 51 of file util_expr_eval.c.