CtplLexerExpr

CtplLexerExpr — Syntax analyser for mathematical/test expressions

Synopsis

#include <ctpl/lexer-expr.h>

#define             CTPL_EXPR_CHARS
#define             CTPL_OPERAND_CHARS
#define             CTPL_OPERATOR_CHARS
#define             CTPL_LEXER_EXPR_ERROR
enum                CtplLexerExprError;
CtplTokenExpr *     ctpl_lexer_expr_lex                 (CtplInputStream *stream,
                                                         GError **error);
CtplTokenExpr *     ctpl_lexer_expr_lex_full            (CtplInputStream *stream,
                                                         gboolean lex_all,
                                                         GError **error);
CtplTokenExpr *     ctpl_lexer_expr_lex_string          (const gchar *expr,
                                                         gssize len,
                                                         GError **error);
const gchar *       ctpl_operator_to_string             (CtplOperator op);
CtplOperator        ctpl_operator_from_string           (const gchar *str,
                                                         gssize len,
                                                         gsize *operator_len);

Description

Syntax analyser for mathematical or test expressions creating a token tree from an expression.

To analyse an expression, use ctpl_lexer_expr_lex(). The resulting expression should be freed with ctpl_token_expr_free() when no longer needed.

An expression is something like a mathematical expression that can include references to variables. The allowed things are:

Binary operators

addition (+), subtraction (-), multiplication (*), division (/), modulo (%), and the boolean equality (==), non-equality (!=), inferiority (<), inferiority-or-equality (<=), superiority (>), superiority-or-equality (>=), AND (&&), and OR (||).

The boolean operators results to the integer 0 if their expression evaluates to false, or to the positive integer 1 if their expression evaluates to true. This result might be used as a plain integer.

The operators' priority is very common: boolean operators have the higher priority, followed by division, modulo and multiplication, and finally addition and subtraction which have the lower priority. When two operators have the same priority, the left one is prior over the right one.

Unary operators

The unary operators plus (+) and minus (-), that may precede any numeric operand.

Operands

Any numeric constant that ctpl_input_stream_read_number() supports, or any reference to any environment variable.

Parentheses

Parentheses may be placed to delimit sub-expressions, allowing a fine control over operator priority.

Example 9. A simple expression

1
42 * 2


Example 10. A more complicated expression

1
(foo + 1) * 3 - 2 * bar


Of course, the latter example supposes that the environment contains the two variables foo and bar.

Details

CTPL_EXPR_CHARS

#define             CTPL_EXPR_CHARS

Characters valid inside an expression


CTPL_OPERAND_CHARS

#define             CTPL_OPERAND_CHARS

Characters valid for an operand


CTPL_OPERATOR_CHARS

#define CTPL_OPERATOR_CHARS "+-/*=><%!&|"

Characters valid for an operator.


CTPL_LEXER_EXPR_ERROR

#define CTPL_LEXER_EXPR_ERROR (ctpl_lexer_expr_error_quark ())

Error domain of CtplLexerExprError.


enum CtplLexerExprError

typedef enum _CtplLexerExprError
{
  CTPL_LEXER_EXPR_ERROR_MISSING_OPERAND,
  CTPL_LEXER_EXPR_ERROR_MISSING_OPERATOR,
  CTPL_LEXER_EXPR_ERROR_SYNTAX_ERROR,
  CTPL_LEXER_EXPR_ERROR_FAILED
} CtplLexerExprError;

Error codes that lexing functions can throw, from the CTPL_LEXER_EXPR_ERROR domain.

CTPL_LEXER_EXPR_ERROR_MISSING_OPERAND

An operand is missing

CTPL_LEXER_EXPR_ERROR_MISSING_OPERATOR

An operator is missing

CTPL_LEXER_EXPR_ERROR_SYNTAX_ERROR

The expression has invalid syntax

CTPL_LEXER_EXPR_ERROR_FAILED

An error occurred without any precision on what failed.

ctpl_lexer_expr_lex ()

CtplTokenExpr *     ctpl_lexer_expr_lex                 (CtplInputStream *stream,
                                                         GError **error);

Tries to lex the expression in stream. If you want to lex a CtplInputStream that (may) hold other data after the expression, see ctpl_lexer_expr_lex_full().

stream :

A CtplInputStream from where read the expression

error :

Return location for errors, or NULL to ignore them.

Returns :

A new CtplTokenExpr or NULL on error.

ctpl_lexer_expr_lex_full ()

CtplTokenExpr *     ctpl_lexer_expr_lex_full            (CtplInputStream *stream,
                                                         gboolean lex_all,
                                                         GError **error);

Tries to lex the expression in stream.

stream :

A CtplInputStream

lex_all :

Whether to lex stream until EOF or until the end of a valid expression. This is useful for expressions inside other data.

error :

Return location for errors, or NULL to ignore them.

Returns :

A new CtplTokenExpr or NULL on error.

ctpl_lexer_expr_lex_string ()

CtplTokenExpr *     ctpl_lexer_expr_lex_string          (const gchar *expr,
                                                         gssize len,
                                                         GError **error);

Tries to lex the expression in expr. See ctpl_lexer_expr_lex().

expr :

An expression

len :

Length of expr or -1 to read the whole string

error :

Return location for errors, or NULL to ignore them

Returns :

A new CtplTokenExpr or NULL on error.

ctpl_operator_to_string ()

const gchar *       ctpl_operator_to_string             (CtplOperator op);

Gets the string representation of an operator. This representation is understood by the lexer if op is valid.

op :

A CtplOperator

Returns :

A string representing the operator. This string should not be modified or freed.

ctpl_operator_from_string ()

CtplOperator        ctpl_operator_from_string           (const gchar *str,
                                                         gssize len,
                                                         gsize *operator_len);

Tries to convert a string to an operator, as the lexer may do.

str :

A string starting with an operator

len :

length to read from str, or -1 to read the whole string.

operator_len :

Return location for the length of the read operator, or NULL.

Returns :

The read operator or CTPL_OPERATOR_NONE if none successfully read.