Expressions 3 RASQAL Library
Expressions Query language expressions.

## Synopsis

    typedef     rasqal_expression;
    enum        rasqal_op;
    enum        rasqal_compare_flags;
    enum        rasqal_pattern_flags;
    rasqal_expression* rasqal_new_1op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg);
    rasqal_expression* rasqal_new_2op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg1,
                                                 rasqal_expression *arg2);
    rasqal_expression* rasqal_new_3op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg1,
                                                 rasqal_expression *arg2,
                                                 rasqal_expression *arg3);
    rasqal_expression* rasqal_new_cast_expression
                                                (raptor_uri *name,
                                                 rasqal_expression *value);
    rasqal_expression* rasqal_new_function_expression
                                                (raptor_uri *name,
                                                 raptor_sequence *args);
    rasqal_expression* rasqal_new_literal_expression
                                                (rasqal_literal *literal);
    rasqal_expression* rasqal_new_string_op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg1,
                                                 rasqal_literal *literal);
    rasqal_expression* rasqal_new_expression_from_expression
                                                (rasqal_expression *e);
    void        rasqal_free_expression          (rasqal_expression *e);
    rasqal_literal* rasqal_expression_evaluate  (rasqal_query *query,
                                                 rasqal_expression *e,
                                                 int flags);
    int         (*rasqal_expression_foreach_fn) (void *user_data,
                                                 rasqal_expression *e);
    int         rasqal_expression_foreach       (rasqal_expression *e,
                                                 rasqal_expression_foreach_fn fn,
                                                 void *user_data);
    void        rasqal_expression_print         (rasqal_expression *e,
                                                 FILE *fh);
    void        rasqal_expression_print_op      (rasqal_expression *e,
                                                 FILE *fh);
    int         (*rasqal_expression_visit_fn)   (void *user_data,
                                                 rasqal_expression *e);
    int         rasqal_expression_visit         (rasqal_expression *e,
                                                 rasqal_expression_visit_fn fn,
                                                 void *user_data);

## Description

Expressions form an expression tree that can be evaluated using `rasqal_expression_evaluate()` over rasqal_op operators, rasqal_literal constants and rasqal_variable values bound in some rasqal_query_result. The result is a rasqal_literal value.

## Details

### rasqal_expression

    typedef struct rasqal_expression_s rasqal_expression;

expression (arg1), unary op (arg1), binary op (arg1,arg2), literal or variable

rasqal_expression

### enum rasqal_op

    typedef enum {
      /* internal */
      RASQAL_EXPR_UNKNOWN,
      RASQAL_EXPR_AND,
      RASQAL_EXPR_OR,
      RASQAL_EXPR_EQ,
      RASQAL_EXPR_NEQ,
      RASQAL_EXPR_LT,
      RASQAL_EXPR_GT,
      RASQAL_EXPR_LE,
      RASQAL_EXPR_GE,
      RASQAL_EXPR_UMINUS,
      RASQAL_EXPR_PLUS,
      RASQAL_EXPR_MINUS,
      RASQAL_EXPR_STAR,
      RASQAL_EXPR_SLASH,
      RASQAL_EXPR_REM,
      RASQAL_EXPR_STR_EQ,
      RASQAL_EXPR_STR_NEQ,
      RASQAL_EXPR_STR_MATCH,
      RASQAL_EXPR_STR_NMATCH,
      RASQAL_EXPR_TILDE,
      RASQAL_EXPR_BANG,
      RASQAL_EXPR_LITERAL,
      RASQAL_EXPR_FUNCTION,
      RASQAL_EXPR_BOUND,
      RASQAL_EXPR_STR,
      RASQAL_EXPR_LANG,
      RASQAL_EXPR_DATATYPE,
      RASQAL_EXPR_ISURI,
      RASQAL_EXPR_ISBLANK,
      RASQAL_EXPR_ISLITERAL,
      RASQAL_EXPR_CAST,
      RASQAL_EXPR_ORDER_COND_ASC,
      RASQAL_EXPR_ORDER_COND_DESC,
      RASQAL_EXPR_LANGMATCHES,
      RASQAL_EXPR_REGEX,
      /* internal */
      RASQAL_EXPR_LAST= RASQAL_EXPR_REGEX
    } rasqal_op;

Rasqal expression operators. A mixture of unary, binary and tertiary operators (string matches). Also includes casting and two ordering operators from ORDER BY in SPARQL.

`RASQAL_EXPR_UNKNOWN`

  Internal

`RASQAL_EXPR_AND`

  Expression for AND(A, B)

`RASQAL_EXPR_OR`

  Expression for OR(A, B)

`RASQAL_EXPR_EQ`

  Expression for A equals B

`RASQAL_EXPR_NEQ`

  Expression for A not equals B.

`RASQAL_EXPR_LT`

  Expression for A less than B.

`RASQAL_EXPR_GT`

  Expression for A greather than B.

`RASQAL_EXPR_LE`

  Expression for A less than or equal to B.

`RASQAL_EXPR_GE`

  Expression for A greater than or equal to B.

`RASQAL_EXPR_UMINUS`

  Expression for -A.

`RASQAL_EXPR_PLUS`

  Expression for +A.

`RASQAL_EXPR_MINUS`

  Expression for A-B.

`RASQAL_EXPR_STAR`

  Expression for A*B.

`RASQAL_EXPR_SLASH`

  Expression for A/B.

`RASQAL_EXPR_REM`

  Expression for A/B remainder.

`RASQAL_EXPR_STR_EQ`

  Expression for A string equals B.

`RASQAL_EXPR_STR_NEQ`

  Expression for A string not-equals B.

`RASQAL_EXPR_STR_MATCH`

  Expression for string A matches literal regex B with flags.

`RASQAL_EXPR_STR_NMATCH`

  Expression for string A not-matches literal regex B with flags.

`RASQAL_EXPR_TILDE`

  Expression for binary not A.

`RASQAL_EXPR_BANG`

  Expression for logical not A.

`RASQAL_EXPR_LITERAL`

  Expression for a rasqal_literal.

`RASQAL_EXPR_FUNCTION`

  Expression for a function A with arguments (B...).

`RASQAL_EXPR_BOUND`

  Expression for SPARQL ISBOUND(A).

`RASQAL_EXPR_STR`

  Expression for SPARQL STR(A).

`RASQAL_EXPR_LANG`

  Expression for SPARQL LANG(A).

`RASQAL_EXPR_DATATYPE`

  Expression for SPARQL DATATYPE(A).

`RASQAL_EXPR_ISURI`

  Expression for SPARQL ISURI(A).

`RASQAL_EXPR_ISBLANK`

  Expression for SPARQL ISBLANK(A).

`RASQAL_EXPR_ISLITERAL`

  Expression for SPARQL ISLITERAL(A).

`RASQAL_EXPR_CAST`

  Expression for cast literal A to type B.

`RASQAL_EXPR_ORDER_COND_ASC`

  Expression for SPARQL order condition ascending.

`RASQAL_EXPR_ORDER_COND_DESC`

  Expression for SPARQL order condition descending.

`RASQAL_EXPR_LANGMATCHES`

  Expression for SPARQL LANGMATCHES(A, B).

`RASQAL_EXPR_REGEX`

  Expression for string A matches expression regex B with flags.

`RASQAL_EXPR_LAST`

  Internal

rasqal_op

### enum rasqal_compare_flags

    typedef enum {
      RASQAL_COMPARE_NOCASE = 1,
      RASQAL_COMPARE_XQUERY = 2
    } rasqal_compare_flags;

Flags for `rasqal_expression_evaluate()` or `rasqal_literal_compare()`.

`RASQAL_COMPARE_NOCASE`

  String comparisons are case independent.

`RASQAL_COMPARE_XQUERY`

  XQuery comparsion rules apply.

rasqal_compare_flags

### enum rasqal_pattern_flags

    typedef enum {
      RASQAL_PATTERN_FLAGS_OPTIONAL=1,

      RASQAL_PATTERN_FLAGS_LAST=RASQAL_PATTERN_FLAGS_OPTIONAL
    } rasqal_pattern_flags;

Flags for rasqal_graph_pattern.

`RASQAL_PATTERN_FLAGS_OPTIONAL`

  True when the graph pattern is an optional match.

`RASQAL_PATTERN_FLAGS_LAST`

  Internal

rasqal_pattern_flags

### rasqal_new_1op_expression ()

    rasqal_expression* rasqal_new_1op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg);

Constructor - create a new 1-operand expression.

The operators are: RASQAL_EXPR_TILDE RASQAL_EXPR_BANG RASQAL_EXPR_UMINUS RASQAL_EXPR_BOUND RASQAL_EXPR_STR RASQAL_EXPR_LANG RASQAL_EXPR_LANGMATCHES RASQAL_EXPR_DATATYPE RASQAL_EXPR_ISURI RASQAL_EXPR_ISBLANK RASQAL_EXPR_ISLITERAL RASQAL_EXPR_ORDER_COND_ASC RASQAL_EXPR_ORDER_COND_DESC

RASQAL_EXPR_BANG and RASQAL_EXPR_UMINUS are used by RDQL and SPARQL. RASQAL_EXPR_TILDE by RDQL only. The rest by SPARQL only.

op :

  Expression operator

arg :

  Operand 1

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_1op_expression

### rasqal_new_2op_expression ()

    rasqal_expression* rasqal_new_2op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg1,
                                                 rasqal_expression *arg2);

Constructor - create a new 2-operand expression.

The operators are: RASQAL_EXPR_AND RASQAL_EXPR_OR RASQAL_EXPR_EQ RASQAL_EXPR_NEQ RASQAL_EXPR_LT RASQAL_EXPR_GT RASQAL_EXPR_LE RASQAL_EXPR_GE RASQAL_EXPR_PLUS RASQAL_EXPR_MINUS RASQAL_EXPR_STAR RASQAL_EXPR_SLASH RASQAL_EXPR_REM RASQAL_EXPR_STR_EQ RASQAL_EXPR_STR_NEQ

RASQAL_EXPR_REM RASQAL_EXPR_STR_EQ and RASQAL_EXPR_STR_NEQ are not used by SPARQL. RASQAL_EXPR_REM is used by RDQL.

op :

  Expression operator

arg1 :

  Operand 1

arg2 :

  Operand 2

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_2op_expression

### rasqal_new_3op_expression ()

    rasqal_expression* rasqal_new_3op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg1,
                                                 rasqal_expression *arg2,
                                                 rasqal_expression *arg3);

Constructor - create a new 3-operand expression.

The only operator is: RASQAL_EXPR_REGEX

op :

  Expression operator

arg1 :

  Operand 1

arg2 :

  Operand 2

arg3 :

  Operand 3 (may be NULL)

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_3op_expression

### rasqal_new_cast_expression ()

    rasqal_expression* rasqal_new_cast_expression
                                                (raptor_uri *name,
                                                 rasqal_expression *value);

Constructor - create a new expression for casting and expression to a datatype

name :

  cast datatype URI

value :

  expression value to cast to datatype type

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_cast_expression

### rasqal_new_function_expression ()

    rasqal_expression* rasqal_new_function_expression
                                                (raptor_uri *name,
                                                 raptor_sequence *args);

Constructor - create a new expression for a function with expression arguments

name :

  function name

args :

  sequence of rasqal_expression function arguments

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_function_expression

### rasqal_new_literal_expression ()

    rasqal_expression* rasqal_new_literal_expression
                                                (rasqal_literal *literal);

Constructor - create a new expression for a rasqal_literal

literal :

  Literal operand 1

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_literal_expression

### rasqal_new_string_op_expression ()

    rasqal_expression* rasqal_new_string_op_expression
                                                (rasqal_op op,
                                                 rasqal_expression *arg1,
                                                 rasqal_literal *literal);

Constructor - create a new expression with one expression and one string operand.

The operators are: RASQAL_EXPR_STR_MATCH (RDQL, SPARQL) and RASQAL_EXPR_STR_NMATCH (RDQL)

op :

  Expression operator

arg1 :

  Operand 1

literal :

  Literal operand 2

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_string_op_expression

### rasqal_new_expression_from_expression ()

    rasqal_expression* rasqal_new_expression_from_expression
                                                (rasqal_expression *e);

Copy Constructor - create a new rasqal_expression object from an existing rasqal_expression object.

e :

  rasqal_expression object to copy

Returns :

  a new rasqal_expression object or NULL on failure

rasqal_new_expression_from_expression

### rasqal_free_expression ()

    void        rasqal_free_expression          (rasqal_expression *e);

Destructor - destroy a rasqal_expression object.

e :

  rasqal_expression object

rasqal_free_expression

### rasqal_expression_evaluate ()

    rasqal_literal* rasqal_expression_evaluate  (rasqal_query *query,
                                                 rasqal_expression *e,
                                                 int flags);

Evaluate a rasqal_expression tree to give a rasqal_literal result or error.

query :

  rasqal_query this expression belongs to

e :

  The expression to evaluate.

flags :

  Flags for `rasqal_literal_compare()` and RASQAL_COMPARE_NOCASE for string matches.

Returns :

  a rasqal_literal value or NULL on failure.

rasqal_expression_evaluate

### rasqal_expression_foreach_fn ()

    int         (*rasqal_expression_foreach_fn) (void *user_data,
                                                 rasqal_expression *e);

User function to visit an expression and operate on it.

deprecated: Use rasqal_expression_visit_fn and `rasqal_expression_visit()`

user_data :

  user data passed in with `rasqal_expression_foreach()`

e :

  current expression

Returns :

  0 to truncate the visit

rasqal_expression_foreach_fn

### rasqal_expression_foreach ()

    int         rasqal_expression_foreach       (rasqal_expression *e,
                                                 rasqal_expression_foreach_fn fn,
                                                 void *user_data);

Visit a user function over a rasqal_expression

deprecated: Use `rasqal_expression_visit()` instead.

e :

  rasqal_expression to visit

fn :

  visit function

user_data :

  user data to pass to visit function

Returns :

  0 if the visit was truncated.

rasqal_expression_foreach

### rasqal_expression_print ()

    void        rasqal_expression_print         (rasqal_expression *e,
                                                 FILE *fh);

Print a Rasqal expression in a debug format.

The print debug format may change in any release.

e :

  rasqal_expression object.

fh :

  The FILE* handle to print to.

rasqal_expression_print

### rasqal_expression_print_op ()

    void        rasqal_expression_print_op      (rasqal_expression *e,
                                                 FILE *fh);

Print a rasqal expression operator in a debug format.

The print debug format may change in any release.

e :

  the rasqal_expression object

fh :

  the FILE* handle to print to

rasqal_expression_print_op

### rasqal_expression_visit_fn ()

    int         (*rasqal_expression_visit_fn)   (void *user_data,
                                                 rasqal_expression *e);

User function to visit an expression and operate on it with `rasqal_expression_visit()`

user_data :

  user data passed in with `rasqal_expression_visit()`

e :

  current expression

Returns :

  0 to truncate the visit

rasqal_expression_visit_fn

### rasqal_expression_visit ()

    int         rasqal_expression_visit         (rasqal_expression *e,
                                                 rasqal_expression_visit_fn fn,
                                                 void *user_data);

Visit a user function over a rasqal_expression

If the user function fn returns 0, the visit is truncated.

e :

  rasqal_expression to visit

fn :

  visit function

user_data :

  user data to pass to visit function

Returns :

  0 if the visit was truncated.

rasqal_expression_visit