1 /*
2   Copyright 2021 Northern.tech AS
3 
4   This file is part of CFEngine 3 - written and maintained by Northern.tech AS.
5 
6   This program is free software; you can redistribute it and/or modify it
7   under the terms of the GNU General Public License as published by the
8   Free Software Foundation; version 3.
9 
10   This program is distributed in the hope that it will be useful,
11   but WITHOUT ANY WARRANTY; without even the implied warranty of
12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   GNU General Public License for more details.
14 
15   You should have received a copy of the GNU General Public License
16   along with this program; if not, write to the Free Software
17   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
18 
19   To the extent this program is licensed as part of the Enterprise
20   versions of CFEngine, the applicable Commercial Open Source License
21   (COSL) may apply to this file if you as a licensee so wish it. See
22   included file COSL.txt.
23 */
24 
25 #ifndef CFENGINE_STRING_EXPRESSIONS_H
26 #define CFENGINE_STRING_EXPRESSIONS_H
27 
28 /*
29    String expressions grammar:
30 
31    <name> ::= <term>
32               <term> <name>
33 
34    <term> ::= <token>
35               <var-ref>
36 
37    <token> ::= [a-zA-Z0-9_:]+
38 
39    <var-ref> ::= $( <qname> )
40                  ${ <qname> }
41 
42    <qname> ::= <name>
43                <name> . <name>
44 
45    Subsequent <term>s are concatenated during evaluation.
46 */
47 
48 typedef enum
49 {
50     CONCAT,
51     LITERAL,
52     VARREF
53 } StringOp;
54 
55 typedef enum
56 {
57     VAR_REF_TYPE_SCALAR,
58     VAR_REF_TYPE_LIST
59 } VarRefType;
60 
61 typedef struct StringExpression_ StringExpression;
62 
63 struct StringExpression_
64 {
65     StringOp op;
66     union StringExpressionValue
67     {
68         struct
69         {
70             StringExpression *lhs;
71             StringExpression *rhs;
72         } concat;
73 
74         struct
75         {
76             char *literal;
77         } literal;
78 
79         struct
80         {
81             StringExpression *name;
82             VarRefType type;
83         } varref;
84     } val;
85 };
86 
87 /* Parsing and evaluation */
88 
89 /*
90  * Result of parsing.
91  *
92  * if succeeded, then result is the result of parsing and position is last
93  * character consumed.
94  *
95  * if not succeeded, then result is NULL and position is last character consumed
96  * before the error.
97  */
98 typedef struct
99 {
100     StringExpression *result;
101     int position;
102 } StringParseResult;
103 
104 StringParseResult ParseStringExpression(const char *expr, int start, int end);
105 
106 /*
107  * Evaluator should return either heap-allocated string or NULL.  In later case
108  * evaluation will be aborted and NULL will be returned from
109  * EvalStringExpression.
110  */
111 typedef char *(*VarRefEvaluator) (const char *varname, VarRefType type, void *param);
112 
113 /*
114  * Result is heap-allocated. In case evalfn() returns NULL whole
115  * EvalStringExpression returns NULL as well.
116  */
117 char *EvalStringExpression(const StringExpression *expr, VarRefEvaluator evalfn, void *param);
118 
119 /*
120  * Frees StringExpression produced by ParseStringExpression. NULL-safe.
121  */
122 void FreeStringExpression(StringExpression *expr);
123 
124 #endif
125