Expressions

Expressions — Query language expressions.

Synopsis




typedef             rasqal_expression;
enum                rasqal_op;
enum                rasqal_compare_flags;
enum                rasqal_pattern_flags;
rasqal_expression*  rasqal_new_0op_expression           (rasqal_op op);
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


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,
  RASQAL_EXPR_GROUP_COND_ASC,
  RASQAL_EXPR_GROUP_COND_DESC,
  RASQAL_EXPR_COUNT,
  RASQAL_EXPR_VARSTAR,
  /* internal */
  RASQAL_EXPR_LAST= RASQAL_EXPR_VARSTAR
} 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_GROUP_COND_ASC Expression for LAQRS group condition ascending.
RASQAL_EXPR_GROUP_COND_DESC Expression for LAQRS group condition descending.
RASQAL_EXPR_COUNT Expression for LAQRS select COUNT()
RASQAL_EXPR_VARSTAR Expression for LAQRS select Variable *
RASQAL_EXPR_LAST Internal

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.

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

rasqal_expression*  rasqal_new_0op_expression           (rasqal_op op);

Constructor - create a new 0-operand (constant) expression.

The operators are: RASQAL_EXPR_VARSTAR

The only operator here is the '*' in COUNT(*) as used by LAQRS.

op : Expression operator
Returns : a new rasqal_expression object or NULL on failure

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_GROUP_COND_ASC RASQAL_EXPR_GROUP_COND_DESC RASQAL_EXPR_COUNT

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

void                rasqal_free_expression              (rasqal_expression *e);

Destructor - destroy a rasqal_expression object.

e : rasqal_expression object

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

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

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.