Version 2 moods.
[paraslash.git] / mp.h
1 /*
2 * Copyright (C) 2017 Andre Noll <maan@tuebingen.mpg.de>
3 *
4 * Licensed under the GPL v2. For licencing details see COPYING.
5 */
6
7 /**
8 * \file mp.h Internal mood parser API (backend).
9 *
10 * This header is included from the lexer, the parser, and from \ref mp.c, but
11 * not from \ref mood.c, the only user of the mood parser front end. It
12 * contains structures and function prototypes which are considered
13 * implementation details.
14 *
15 * There is one function for each keyword in the context-free grammar of the
16 * parser. These functions return the semantic value of the keyword.
17 *
18 * The functions declared here are defined either in mp.c or in mp.y.
19 */
20
21 /** Opaque, only known to mp.c. Passed to the generated mp_yyparse(). */
22 struct mp_context;
23
24 /**
25 * Since we use a reentrant lexer, all functions generated by flex(1)
26 * receive an additional argument of this type.
27 */
28 typedef void *mp_yyscan_t;
29
30 /** Parsed regex pattern. */
31 struct mp_re_pattern {
32 regex_t preg; /**< Pre-compiled regex. **/
33 unsigned flags; /**< Subset of the cflags described in regex(3). */
34 };
35
36 /** Parsed wildcard pattern. */
37 struct mp_wc_pattern {
38 char *pat; /**< Unescaped C string (without quotes and flags). */
39 unsigned flags; /**< For modifying matching behaviour. */
40 };
41
42 /**
43 * The possible values of a node in the abstract syntax tree (AST).
44 *
45 * Constant semantic values (string literals, numeric constants, wildcard and
46 * regex patterns which are part of the mood definition) are determined during
47 * \ref mp_init() while values which depend on the audio file (path, bitrate,
48 * etc.) are determined during mp_eval_row().
49 *
50 * This union, and the \ref mp_ast_node structure below are used extensively in
51 * mp.y. However, both need to be public because the lexer must be able to
52 * create AST nodes for the constant semantic values.
53 */
54 union mp_semantic_value {
55 bool boolval; /**< Comparators, =~ and =|. */
56 char *strval; /**< String literals, tags, path. */
57 int64_t intval; /**< Constants, bitrate, frequency, etc. */
58 struct mp_wc_pattern wc_pattern; /**< Right-hand side operand of =|. */
59 struct mp_re_pattern re_pattern; /**< Right-hand side operand of =~. */
60 };
61
62 /**
63 * Describes one node of the abstract syntax tree.
64 *
65 * A node is either interior or a leaf node. Interior nodes have at least one
66 * child while leaf nodes have a semantic value and no children.
67 *
68 * Examples: (a) STRING_LITERAL has a semantic value (the unescaped string
69 * literal) and no children, (b) NEG (unary minus) has no semantic value but
70 * one child (the numeric expression that is to be negated), (c) LESS_OR_EQUAL
71 * has no semantic value and two children (the two numeric expressions being
72 * compared).
73 */
74 struct mp_ast_node {
75 /** Corresponds to a token type, for example LESS_OR_EQUAL. */
76 int id;
77 union {
78 /** Pointers to the child nodes (interior nodes only). */
79 struct mp_ast_node **children;
80 /** Leaf nodes only. */
81 union mp_semantic_value sv;
82 };
83 /**
84 * The number of children is implicitly given by the id, but we include
85 * it here to avoid having to maintain a lookup table. The AST is
86 * usually small, so we can afford to waste a byte per node.
87 */
88 uint8_t num_children;
89 };
90
91 /* Called from both the lexer and the parser. */
92 __printf_3_4 void mp_parse_error(int line, struct mp_context *ctx,
93 const char *fmt, ...);
94
95 /* Helper functions for the lexer. */
96 unsigned parse_quoted_string(const char *src, const char quote_chars[2],
97 char **result);
98 int mp_parse_regex_pattern(const char *src, struct mp_re_pattern *result);
99 void mp_parse_wildcard_pattern(const char *src, struct mp_wc_pattern *result);
100
101 /*
102 * The functions below are implemented in mp.y. They are documented here
103 * because mp.y is not doxyfied.
104 */
105
106 /**
107 * Allocate a new leaf node for the abstract syntax tree.
108 *
109 * \param id Initial value for the ->id field of the new node
110 *
111 * \return Pointer to a node whose ->num_children field is initialized to zero.
112 * The caller is expected to initialize the ->sv field.
113 */
114 struct mp_ast_node *mp_new_ast_leaf_node(int id);
115
116 /**
117 * Evaluate an abstract syntax tree, starting at the root node.
118 *
119 * \param root As returned from \ref mp_init() via the context pointer.
120 * \param ctx Contains the aft row to evaluate.
121 *
122 * \return True if the AST evaluates to true, a non-empty string, or a
123 * non-zero number. False otherwise.
124 *
125 * \sa mp_eval_row().
126 */
127 bool mp_eval_ast(struct mp_ast_node *root, struct mp_context *ctx);
128
129 /**
130 * Deallocate an abstract syntax tree.
131 *
132 * This frees the memory occupied by the nodes of the AST, the child pointers
133 * of the internal nodes and the (constant) semantic values of the leaf nodes
134 * (string literals, unescaped wildcard patterns and pre-compiled regular
135 * expressions).
136 *
137 * \param root It's OK to pass NULL here.
138 */
139 void mp_free_ast(struct mp_ast_node *root);
140
141 /* Helper functions for the parser. */
142 bool mp_is_set(const char *attr, struct mp_context *ctx);
143 char *mp_path(struct mp_context *ctx);
144 int64_t mp_year(struct mp_context *ctx);
145 int64_t mp_num_attributes_set(struct mp_context *ctx);
146
147 /* Generated with MP_AFSI() */
148 /** \cond MP_AFSI */
149 int64_t mp_num_played(struct mp_context *ctx);
150 int64_t mp_image_id(struct mp_context *ctx);
151 int64_t mp_lyrics_id(struct mp_context *ctx);
152 /** \endcond */
153
154 /* Generated with MP_AFHI() */
155 /** \cond MP_AFHI */
156 int64_t mp_bitrate(struct mp_context *ctx);
157 int64_t mp_frequency(struct mp_context *ctx);
158 int64_t mp_channels(struct mp_context *ctx);
159 /** \endcond */
160
161 /* Generated with MP_TAG() */
162 /** \cond MP_TAG */
163 char *mp_artist(struct mp_context *ctx);
164 char *mp_title(struct mp_context *ctx);
165 char *mp_album(struct mp_context *ctx);
166 char *mp_comment(struct mp_context *ctx);
167 /** \endcond */