mp.h File Reference

Internal mood parser API (backend). More...

Data Structures
struct	mp_re_pattern
	Parsed regex pattern. More...
struct	mp_wc_pattern
	Parsed wildcard pattern. More...
union	mp_semantic_value
	The possible values of a node in the abstract syntax tree (AST). More...
struct	mp_ast_node
	Describes one node of the abstract syntax tree. More...

Typedefs
typedef void *	mp_yyscan_t
	Since we use a reentrant lexer, all functions generated by flex(1) receive an additional argument of this type. More...

Functions
__printf_3_4 void	mp_parse_error (int line, struct mp_context *ctx, const char *fmt,...)
	Set the error bit in the parser context and log a message. More...
unsigned	parse_quoted_string (const char *src, const char quote_chars[2], char **result)
	Parse a (generalized) string literal. More...
int	mp_parse_regex_pattern (const char *src, struct mp_re_pattern *result)
	Parse and compile an extended regular expression pattern, including flags. More...
void	mp_parse_wildcard_pattern (const char *src, struct mp_wc_pattern *result)
	Parse a wildcard pattern, including flags. More...
struct mp_ast_node *	mp_new_ast_leaf_node (int id)
	Allocate a new leaf node for the abstract syntax tree. More...
bool	mp_eval_ast (struct mp_ast_node *root, struct mp_context *ctx)
	Evaluate an abstract syntax tree, starting at the root node. More...
void	mp_free_ast (struct mp_ast_node *root)
	Deallocate an abstract syntax tree. More...
bool	mp_is_set (const char *attr, struct mp_context *ctx)
	Check whether the given attribute is set for the current audio file. More...
char *	mp_path (struct mp_context *ctx)
	Return the full path to the audio file. More...
int64_t	mp_year (struct mp_context *ctx)
	Parse and return the value of the year tag. More...
int64_t	mp_num_attributes_set (struct mp_context *ctx)
	Count the number of attributes set. More...
int64_t	mp_duration (struct mp_context *ctx)
	Return the duration of the audio file from the afh info structure. More...

Detailed Description

Internal mood parser API (backend).

This header is included from the lexer, the parser, and from mp.c, but not from mood.c, the only user of the mood parser front end. It contains structures and function prototypes which are considered implementation details.

There is one function for each keyword in the context-free grammar of the parser. These functions return the semantic value of the keyword.

The functions declared here are defined either in mp.c or in mp.y.

Typedef Documentation

mp_yyscan_t

typedef void* mp_yyscan_t

Since we use a reentrant lexer, all functions generated by flex(1) receive an additional argument of this type.

Function Documentation

mp_parse_error()

__printf_3_4 void mp_parse_error	(	int	line,
		struct mp_context *	ctx,
		const char *	fmt,
			...
	)

Set the error bit in the parser context and log a message.

Parameters

line	The number of the input line which caused the error.
ctx	Contains the error bit.
fmt	Usual format string.

This is called if the lexer or the parser detect an error in the mood definition. Only the first error is logged (with a severity of "warn").

References PARA_WARNING_LOG, xasprintf(), and xvasprintf().

parse_quoted_string()

unsigned parse_quoted_string	(	const char *	src,
		const char	quote_chars[2],
		char **	result
	)

Parse a (generalized) string literal.

Parameters

src	The string to parse.
quote_chars	Opening and closing quote characters.
result	The corresponding C string is returned here.

This function turns a generalized C99 string literal like "xyz\n" into a C string (containing the three characters 'x', 'y' and 'z', followed by a newline character and the terminating zero byte). The function receives quote characters as an argument so that, for example, regular expression patterns enclosed in '/' can be parsed as well. To parse a proper string literal, one has to pass two double quotes as the second argument.

The function strips off the opening and leading quote characters, replaces double backslashes by single backslashes and handles the usual escapes like
and ".

The caller must make sure that the input is well-formed. The function simply aborts if the input is not a valid C99 string literal (modulo the quote characters).

Returns

Offset of the first character after the closing quote. For proper string literals this will be the terminating zero byte of the input string, for regular expression patterns it is the beginning of the flags which modify the matching behaviour.

See also

mp_parse_regex_pattern(), mp_parse_wildcard_pattern().

References alloc().

Referenced by mp_parse_regex_pattern(), and mp_parse_wildcard_pattern().

mp_parse_regex_pattern()

int mp_parse_regex_pattern	(	const char *	src,
		struct mp_re_pattern *	result
	)

Parse and compile an extended regular expression pattern, including flags.

Parameters

src	The pattern to parse.
result	C-string and flags are returned here.

A regex pattern is identical to a C99 string literal except (a) it is enclosed in '/' characters rather than double quotes, (b) double quote characters which are part of the pattern do not need to be quoted with backslashes, but slashes must be quoted in this way, and (c) the closing slash may be followed by one or more flag characters which modify the matching behaviour.

The only flags which are currently supported are 'i' to ignore case in match (REG_ICASE) and 'n' to change the handling of newline characters (REG_NEWLINE).

Returns

Standard. This function calls parse_quoted_string(), hence it aborts if the input string is malformed. However, errors from para_regcomp are returned without aborting the process. The rationale behind this difference is that passing a malformed string must be considered an implementation bug because malformed strings should be rejected earlier by the lexer.

See also

mp_parse_wildcard_pattern(), parse_quoted_string(), para_regcomp(), regex(3).

References mp_re_pattern::flags, para_regcomp(), parse_quoted_string(), and mp_re_pattern::preg.

mp_parse_wildcard_pattern()

void mp_parse_wildcard_pattern	(	const char *	src,
		struct mp_wc_pattern *	result
	)

Parse a wildcard pattern, including flags.

Parameters

src	The pattern to parse.
result	C-string and flags are returned here.

This function parses a shell wildcard pattern. It is similar to mp_parse_regex_pattern(), so the remarks mentioned there apply to this function as well.

Wildcard patterns differ from regular expression patterns in that (a) they must be enclosed in '|' characters, (b) they support different flags for modifying matching behaviour, and (c) there is no cache for them.

The following flags, whose meaning is explained in fnmatch(3), are currently supported: 'n' (FNM_NOESCAPE), 'p' (FNM_PATHNAME), 'P' (FNM_PERIOD), 'l' (FNM_LEADING_DIR), 'i' (FNM_CASEFOLD), 'e' (FNM_EXTMATCH). The last flag is a GNU extension. It is silently ignored on non GNU systems.

See also

parse_quoted_string(), mp_parse_regex_pattern(), fnmatch(3).

References mp_wc_pattern::flags, parse_quoted_string(), and mp_wc_pattern::pat.

mp_new_ast_leaf_node()

struct mp_ast_node* mp_new_ast_leaf_node

(

int

id

)

Allocate a new leaf node for the abstract syntax tree.

Parameters

id	Initial value for the ->id field of the new node

Returns

Pointer to a node whose ->num_children field is initialized to zero. The caller is expected to initialize the ->sv field.

mp_eval_ast()

bool mp_eval_ast	(	struct mp_ast_node *	root,
		struct mp_context *	ctx
	)

Evaluate an abstract syntax tree, starting at the root node.

Parameters

root	As returned from mp_init() via the context pointer.
ctx	Contains the aft row to evaluate.

Returns

True if the AST evaluates to true, a non-empty string, or a non-zero number. False otherwise.

See also

mp_eval_row().

Referenced by mp_eval_row().

mp_free_ast()

void mp_free_ast

(

struct mp_ast_node *

root

)

Deallocate an abstract syntax tree.

This frees the memory occupied by the nodes of the AST, the child pointers of the internal nodes and the (constant) semantic values of the leaf nodes (string literals, unescaped wildcard patterns and pre-compiled regular expressions).

Parameters

root	It's OK to pass NULL here.

Referenced by mp_init(), and mp_shutdown().

mp_is_set()

bool mp_is_set	(	const char *	attr,
		struct mp_context *	ctx
	)

Check whether the given attribute is set for the current audio file.

Parameters

attr	The string to look up in the attribute table.
ctx	See mp_path().

First, determine the bit number which corresponds to the attribute, then check if this bit is set in the ->attributes field of the afs_info structure of the audio file.

Returns

True if the attribute is set, false if it is not. On errors, for example if the given string is no attribute, the function returns false.

See also

get_attribute_bitnum_by_name().

References get_attribute_bitnum_by_name().

mp_path()

char* mp_path

(

struct mp_context *

ctx

)

Return the full path to the audio file.

Parameters

ctx	Contains a reference to the row of the audio file table which corresponds to the current audio file. The path of the audio file, the afs_info and the afh_info structures (which contain the tag information) can be retrieved through this reference.

Returns

A reference to the path. Must not be freed by the caller.

See also

get_audio_file_path_of_row().

References get_audio_file_path_of_row().

mp_year()

int64_t mp_year

(

struct mp_context *

ctx

)

Parse and return the value of the year tag.

Parameters

ctx	See mp_path().

Returns

If the year tag is not present, can not be parsed, or its value is less than zero, the function returns 0. If the value is less than 100, we add 1900.

mp_num_attributes_set()

int64_t mp_num_attributes_set

(

struct mp_context *

ctx

)

Count the number of attributes set.

Parameters

ctx	See mp_path().

Returns

The number of bits which are set in the ->attributes field of the afs_info structure of the current audio file.

mp_duration()

int64_t mp_duration

(

struct mp_context *

ctx

)

Return the duration of the audio file from the afh info structure.

Parameters

ctx	See mp_path().

The duration is computed by multiplying the number of chunks and the duration of one chunk.

Returns

The approximate number of milliseconds.