Expression parser

Collaboration diagram for Expression parser:

Data Structures
struct	ap_expr_info_t
struct	ap_expr_eval_ctx_t
struct	ap_expr_lookup_parms

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 const char *()	ap_expr_string_list_func_t(ap_expr_eval_ctx_t *ctx, const void *data, const apr_array_header_t *args)
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)

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)
int	expr_lookup (ap_expr_lookup_parms *parms)
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

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.

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)

AP_EXPR_FLAG_STRING_RESULT

#define AP_EXPR_FLAG_STRING_RESULT   8

Expression evaluates to a string, not to a bool

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

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'

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

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

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

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'

ap_expr_string_list_func_t

typedef const char*() ap_expr_string_list_func_t(ap_expr_eval_ctx_t *ctx, const void *data, const apr_array_header_t *args)

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

Parameters

ctx	The evaluation context
data	An opaque context provided by the lookup hook function
args	The list of string arguments

Returns

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

ap_expr_t

typedef struct ap_expr_node ap_expr_t

A node in the expression parse tree

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

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.

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.

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.

ap_expr_init()

void ap_expr_init

(

apr_pool_t *

pool

)

Internal initialisation of ap_expr (for httpd internal use)

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.

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.

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

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.

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.

expr_lookup()

int expr_lookup

(

ap_expr_lookup_parms *

parms

)