mp.c File Reference

Mood parser helper functions. More...

#include "para.h"
#include <regex.h>
#include <fnmatch.h>
#include <osl.h>
#include <lopsub.h>
#include "string.h"
#include "error.h"
#include "afh.h"
#include "afs.h"
#include "mp.h"
#include "mp.bison.h"

Macros
#define	MP_AFSI(_name)
	Define a function which returns a field of the afs_info structure. More...
#define	MP_AFHI(_name)
	Define a function which returns a field of the afh_info structure. More...
#define	MP_TAG(_name)
	Define a function which extracts and returns the value of a meta tag. More...

Functions
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...
__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...
char *	mp_path (struct mp_context *ctx)
	Return the full path to the audio file. 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...
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...
int64_t	mp_year (struct mp_context *ctx)
	Parse and return the value of the year tag. More...
int	mp_init (const char *definition, int nbytes, struct mp_context **result, char **errmsg)
	Initialize the mood parser. More...
bool	mp_eval_row (const struct osl_row *aft_row, struct mp_context *ctx)
	Determine whether the given audio file is admissible. More...
void	mp_shutdown (struct mp_context *ctx)
	Deallocate the resources of a mood parser. More...

Detailed Description

Mood parser helper functions.

This file contains the public and the private API of the flex/bison based mood parser.

The public API (at the bottom of the file) allows parsing the same mood definition many times in an efficient manner.

The first function to call is mp_init(), which analyzes the given mood definition syntactically. It returns the abstract syntax tree of the mood definition and pre-compiles all regular expression patterns to make later pattern matching efficient.

Semantic analysis is performed in mp_eval_row(). This function is called from mood.c once for each file in the audio file table. It utilizes the abstract syntax tree and the pre-compiled regular expressions to determine the set of admissible audio files.

If the mood is no longer needed, mp_shutdown() should be called to free the resources.

The internal API is described in mp.h.

Macro Definition Documentation

MP_AFSI

#define MP_AFSI

(

_name

)

Value:

        int64_t mp_ ## _name(struct mp_context *ctx) \
        { \
                int ret = get_afsi(ctx); \
                if (ret < 0) \
                        return 0; \
                return ctx->afsi._name; \
        }

Define a function which returns a field of the afs_info structure.

Parameters

_name

The name of the field.

The defined function casts the value to int64_t. On errors, zero is returned.

MP_AFHI

#define MP_AFHI

(

_name

)

Value:

        int64_t mp_ ## _name(struct mp_context *ctx) \
        { \
                int ret = get_afhi(ctx); \
                if (ret < 0) \
                        return 0; \
                return ctx->afhi._name; \
        }

Define a function which returns a field of the afh_info structure.

Parameters

_name

The name of the field.

The defined function casts the value to int64_t. On errors, zero is returned.

MP_TAG

#define MP_TAG

(

_name

)

Value:

        char *mp_ ## _name (struct mp_context *ctx) \
        { \
                int ret = get_afhi(ctx); \
                if (ret < 0) \
                        return ""; \
                return ctx->afhi.tags._name; \
        }

Define a function which extracts and returns the value of a meta tag.

Parameters

_name

The name of the tag (artist, title, ...).

The function will return a pointer to memory owned by the audio file selector. On errors, or if the current audio file has no tag of the given name, the function returns the empty string. The caller must not attempt to free the returned string.

Function Documentation

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_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().

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_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_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.

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_init()

int mp_init	(	const char *	definition,
		int	nbytes,
		struct mp_context **	result,
		char **	errmsg
	)

Initialize the mood parser.

This allocates and sets up the internal structures of the mood parser and creates an abstract syntax tree from the given mood definition. It must be called before mp_eval_row() can be called.

The context pointer returned by this function may be passed to mp_eval_row() to determine whether an audio file is admissible.

Parameters

definition	A reference to the mood definition.
nbytes	The size of the mood definition.
result	Opaque context pointer is returned here.
errmsg	Optional error message is returned here.

It's OK to pass a NULL pointer or a zero sized buffer as the mood definition. This corresponds to the "dummy" mood for which all audio files are admissible.

The error message pointer may also be NULL in which case no error message is returned. Otherwise, the caller must free the returned string.

Returns

Standard. On success *errmsg is set to NULL.

References mp_free_ast(), PARA_NOTICE_LOG, and zalloc().

mp_eval_row()

bool mp_eval_row	(	const struct osl_row *	aft_row,
		struct mp_context *	ctx
	)

Determine whether the given audio file is admissible.

Parameters

aft_row	The audio file to check for admissibility.
ctx	As returned from mp_init().

Returns

Whether the audio file is admissible.

If the mood parser was set up without an input buffer (dummy mood), this function returns true (without looking at the audio file metadata) to indicate that the given audio file should be considered admissible.

See also

mood_load(), mp_eval_ast().

References mp_eval_ast().

mp_shutdown()

void mp_shutdown

(

struct mp_context *

ctx

)

Deallocate the resources of a mood parser.

This function frees the abstract syntax tree which was created by mp_init().

Parameters

ctx	As returned from mp_init().

It's OK to pass a NULL pointer, in which case the function does nothing.

References mp_free_ast().