Graph patterns

## Graph patterns Graph patterns — Collections of triple patterns, sub-graph patterns with operators. |

## Synopsis

    typedef             rasqal_graph_pattern;
    int                 rasqal_graph_pattern_add_constraint (rasqal_graph_pattern *gp,
                                                             rasqal_expression *expr);
    int                 rasqal_graph_pattern_add_sub_graph_pattern
                                                            (rasqal_graph_pattern *graph_pattern,
                                                             rasqal_graph_pattern *sub_graph_pattern);
    rasqal_expression*  rasqal_graph_pattern_get_constraint (rasqal_graph_pattern *gp,
                                                             int idx);
    raptor_sequence*    rasqal_graph_pattern_get_constraint_sequence
                                                            (rasqal_graph_pattern *gp);
    int                 rasqal_graph_pattern_get_index      (rasqal_graph_pattern *gp);
    rasqal_graph_pattern_operator rasqal_graph_pattern_get_operator
                                                            (rasqal_graph_pattern *graph_pattern);
    rasqal_graph_pattern* rasqal_graph_pattern_get_sub_graph_pattern
                                                            (rasqal_graph_pattern *graph_pattern,
                                                             int idx);
    raptor_sequence*    rasqal_graph_pattern_get_sub_graph_pattern_sequence
                                                            (rasqal_graph_pattern *graph_pattern);
    rasqal_triple*      rasqal_graph_pattern_get_triple     (rasqal_graph_pattern *graph_pattern,
                                                             int idx);
    enum                rasqal_graph_pattern_operator;
    const char*         rasqal_graph_pattern_operator_as_string
                                                            (rasqal_graph_pattern_operator op);
    void                rasqal_graph_pattern_print          (rasqal_graph_pattern *gp,
                                                             FILE *fh);
    int                 (*rasqal_graph_pattern_visit_fn)    (rasqal_query *query,
                                                             rasqal_graph_pattern *gp,
                                                             void *user_data);
    int                 rasqal_graph_pattern_visit          (rasqal_query *query,
                                                             rasqal_graph_pattern *gp,
                                                             rasqal_graph_pattern_visit_fn fn,
                                                             void *user_data);

## Description

Graph patterns form a a tree structure that build a rasqal_query top-level graph pattern (see `rasqal_query_get_query_graph_pattern()`) which may have sub-graph patterns. Graph patterns at the leaf of the tree operate over triple patterns (rasqal_triple) matching the RDF triples in the data sources for `RASQAL_GRAPH_PATTERN_OPERATOR_BASIC` or `RASQAL_GRAPH_PATTERN_OPERATOR_OPTIONAL`. Other graph patterns operators operate over sub graph patterns and group them, union them or apply a GRAPH matching keyword (`RASQAL_GRAPH_PATTERN_OPERATOR_GRAPH`).

## Details

### rasqal_graph_pattern

    rasqal_graph_pattern* graph_pattern;

Rasqal graph pattern class.

### rasqal_graph_pattern_add_constraint ()

    int                 rasqal_graph_pattern_add_constraint (rasqal_graph_pattern *gp,
                                                             rasqal_expression *expr);

Add a constraint expression to the graph_pattern.

`gp` : | rasqal_graph_pattern query object
`expr` : | rasqal_expression expr - ownership taken
Returns : | non-0 on failure

### rasqal_graph_pattern_add_sub_graph_pattern ()

    int                 rasqal_graph_pattern_add_sub_graph_pattern
                                                            (rasqal_graph_pattern *graph_pattern,
                                                             rasqal_graph_pattern *sub_graph_pattern);

Add a sub graph pattern to a graph pattern.

`graph_pattern` : | graph pattern to add to
`sub_graph_pattern` : | graph pattern to add inside
Returns : | non-0 on failure

### rasqal_graph_pattern_get_constraint ()

    rasqal_expression*  rasqal_graph_pattern_get_constraint (rasqal_graph_pattern *gp,
                                                             int idx);

Get a constraint in the sequence of constraint expressions in the query.

`gp` : | rasqal_graph_pattern query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_expression pointer or NULL if out of the sequence range

### rasqal_graph_pattern_get_constraint_sequence ()

    raptor_sequence*    rasqal_graph_pattern_get_constraint_sequence
                                                            (rasqal_graph_pattern *gp);

Get the sequence of constraints expressions in the query.

`gp` : | rasqal_graph_pattern object
Returns : | a raptor_sequence of rasqal_expression pointers.

### rasqal_graph_pattern_get_index ()

    int                 rasqal_graph_pattern_get_index      (rasqal_graph_pattern *gp);

Get the graph pattern absolute index in the array of graph patterns.

The graph pattern index is assigned when `rasqal_query_prepare()` is run on a query containing a graph pattern.

`gp` : | rasqal_graph_pattern graph pattern
Returns : | index or <0 if no index has been assigned yet

### rasqal_graph_pattern_get_operator ()

    rasqal_graph_pattern_operator rasqal_graph_pattern_get_operator
                                                            (rasqal_graph_pattern *graph_pattern);

Get the graph pattern operator .

The operator for the given graph pattern. See also `rasqal_graph_pattern_operator_as_string()`.

`graph_pattern` : | rasqal_graph_pattern graph pattern object
Returns : | graph pattern operator

### rasqal_graph_pattern_get_sub_graph_pattern ()

    rasqal_graph_pattern* rasqal_graph_pattern_get_sub_graph_pattern
                                                            (rasqal_graph_pattern *graph_pattern,
                                                             int idx);

Get a sub-graph pattern inside a graph pattern.

`graph_pattern` : | rasqal_graph_pattern graph pattern object
`idx` : | index into the sequence of sub graph_patterns in the graph pattern
Returns : | rasqal_graph_pattern or NULL if out of range

### rasqal_graph_pattern_get_sub_graph_pattern_sequence ()

    raptor_sequence*    rasqal_graph_pattern_get_sub_graph_pattern_sequence
                                                            (rasqal_graph_pattern *graph_pattern);

Get the sequence of graph patterns inside a graph pattern .

`graph_pattern` : | rasqal_graph_pattern graph pattern object
Returns : | a raptor_sequence of rasqal_graph_pattern pointers.

### rasqal_graph_pattern_get_triple ()

    rasqal_triple*      rasqal_graph_pattern_get_triple     (rasqal_graph_pattern *graph_pattern,
                                                             int idx);

Get a triple inside a graph pattern.

`graph_pattern` : | rasqal_graph_pattern graph pattern object
`idx` : | index into the sequence of triples in the graph pattern
Returns : | rasqal_triple or NULL if out of range

### enum rasqal_graph_pattern_operator

    typedef enum {
      RASQAL_GRAPH_PATTERN_OPERATOR_UNKNOWN   = 0,
      RASQAL_GRAPH_PATTERN_OPERATOR_BASIC     = 1,
      RASQAL_GRAPH_PATTERN_OPERATOR_OPTIONAL  = 2,
      RASQAL_GRAPH_PATTERN_OPERATOR_UNION     = 3,
      RASQAL_GRAPH_PATTERN_OPERATOR_GROUP     = 4,
      RASQAL_GRAPH_PATTERN_OPERATOR_GRAPH     = 5,

      RASQAL_GRAPH_PATTERN_OPERATOR_LAST=RASQAL_GRAPH_PATTERN_OPERATOR_GRAPH
    } rasqal_graph_pattern_operator;

Graph pattern operators

`RASQAL_GRAPH_PATTERN_OPERATOR_UNKNOWN` | Internal.
`RASQAL_GRAPH_PATTERN_OPERATOR_BASIC` | Just triple patterns and constraints.
`RASQAL_GRAPH_PATTERN_OPERATOR_OPTIONAL` | Set of graph patterns (ANDed) and constraints.
`RASQAL_GRAPH_PATTERN_OPERATOR_UNION` | Set of graph patterns (UNIONed) and constraints.
`RASQAL_GRAPH_PATTERN_OPERATOR_GROUP` | Set of graph patterns (ANDed) and constraints.
`RASQAL_GRAPH_PATTERN_OPERATOR_GRAPH` | A graph term + a graph pattern and constraints.
`RASQAL_GRAPH_PATTERN_OPERATOR_LAST` | Internal.

### rasqal_graph_pattern_operator_as_string ()

    const char*         rasqal_graph_pattern_operator_as_string
                                                            (rasqal_graph_pattern_operator op);

Get a string for the query verb.

`op` : | the rasqal_graph_pattern_operator verb of the query
Returns : | pointer to a shared string label for the query verb

### rasqal_graph_pattern_print ()

    void                rasqal_graph_pattern_print          (rasqal_graph_pattern *gp,
                                                             FILE *fh);

Print a rasqal_graph_pattern in a debug format.

The print debug format may change in any release.

`gp` : | the rasqal_graph_pattern object
`fh` : | the FILE* handle to print to

### rasqal_graph_pattern_visit_fn ()

    int                 (*rasqal_graph_pattern_visit_fn)    (rasqal_query *query,
                                                             rasqal_graph_pattern *gp,
                                                             void *user_data);

User function to visit an graph_pattern and operate on it with `rasqal_graph_pattern_visit()` or `rasqal_query_graph_pattern_visit()`

`query` : | rasqal_query containing the graph pattern
`gp` : | current graph_pattern
`user_data` : | user data passed in
Returns : | 0 to truncate the visit

### rasqal_graph_pattern_visit ()

    int                 rasqal_graph_pattern_visit          (rasqal_query *query,
                                                             rasqal_graph_pattern *gp,
                                                             rasqal_graph_pattern_visit_fn fn,
                                                             void *user_data);

Visit a user function over a rasqal_graph_pattern

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

`query` : | rasqal_query to operate on
`gp` : | rasqal_graph_pattern graph pattern
`fn` : | pointer to function to apply that takes user data and graph pattern parameters
`user_data` : | user data for applied function
Returns : | 0 if the visit was truncated.