volksdata/include/graph.h

#ifndef _LSUP_GRAPH_H
#define _LSUP_GRAPH_H

#include "store.h"
#include "environment.h"
#include "term.h"


/** @brief Graph object.
 */
typedef struct graph_t LSUP_Graph;

/** @brief Graph iterator.
 *
 * This opaque handle is generated by #LSUP_graph_lookup and is used to iterate
 * over lookup results with #LSUP_graph_iter_next. It must be freed with
 * #LSUP_graph_iter_free when done.
 */
typedef struct graph_iter_t LSUP_GraphIterator;


/** @brief Create an empty graph.
 *
 * @param[in] uri URI of the new graph. If NULL, a UUID4 URN is generated. The
 *  graph owns the handle.
 *
 * @param store_type[in] Type of store backing the graph. One of the values of
 *  #LSUP_StoreType.
 *
 * @param[in] store_id Identifier for the back end store. This may be
 *  interpreted differently by each store implementation. For the MDB store,
 *  this is the file path where the store is located. It is ignored by volatile
 *  stores (with LSUP_STORE_PERM feature flag set to false). If a store
 *  does not exist for the given identifier, a new one is initialized. If this
 *  parameter is NULL, the default store for the selected type is used.
 *
 * @param[in] nsm Namespace map to use for an in-memory graph. This is ignored
 *  by graphs backed by permanent stores, which handle their own namespace map.
 *  If this is NULL, the graph is assigned a global namespace map that lives
 *  until #LSUP_done() is called.
 *
 * @return New graph, or NULL on error. Must be freed with #LSUP_graph_free().
 */
LSUP_Graph *
LSUP_graph_new (
        LSUP_Term *uri, const LSUP_StoreType store_type, const char *store_id,
        LSUP_NSMap *nsm, size_t size);


/** @brief Copy triples from a source graph into a destination one.
 *
 * The destination graph is not initialized here, so the copy is cumulative.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param src[in] Source graph.
 *
 * @param dest[in] Destination graph.
 */
LSUP_rc
LSUP_graph_copy_contents_txn (
        void *txn, const LSUP_Graph *src, LSUP_Graph *dest);


/// Non-transactional version of #LSUP_graph_copy_contents_txn.
inline LSUP_rc
LSUP_graph_copy_contents (const LSUP_Graph *src, LSUP_Graph *dest)
{ return LSUP_graph_copy_contents_txn (NULL, src, dest); }


/** Perform a boolean operation between two graphs.
 *
 * This method populates an initialized graph with the result of the operation
 * between two other graphs. The resulting graph may be of any store type and
 * may be the result of graphs of different store types.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param op[in] Operation to perform. One of #LSUP_bool_op.
 *
 * @param gr1[in] First operand.
 *
 * @param gr2[in] Second operand.
 *
 * @param res[out] Result graph. The handle should be initialized via
 *  #LSUP_graph_new() or equivalent. Any preexisting contents are not removed.
 *  If an unrecoverable error occurs, this graph is freed.
 *
 * @return LSUP_OK on success; <0 on error.
 */
LSUP_rc
LSUP_graph_bool_op_txn (
        void *txn, const LSUP_bool_op op,
        const LSUP_Graph *gr1, const LSUP_Graph *gr2, LSUP_Graph *res);


/// Non-transactional version of #LSUP_graph_bool_op_txn.
inline LSUP_rc
LSUP_graph_bool_op (
        const LSUP_bool_op op,
        const LSUP_Graph *gr1, const LSUP_Graph *gr2, LSUP_Graph *res)
{ return LSUP_graph_bool_op_txn (NULL, op, gr1, gr2, res); }


/** @brief Free a graph.
 */
void
LSUP_graph_free (LSUP_Graph *gr);


/** @brief Compare two graphs.
 *
 * Note that if any of the two graphs has an open transaction, the function
 * is performed in the first graph's transaction.
 *
 * @param[in] gr1 First operand.
 *
 * @param[in] gr2 Second operand.
 *
 * @return True if the graphs are topologically equal, false otherwise.
 */
bool
LSUP_graph_equals (const LSUP_Graph *gr1, const LSUP_Graph *gr2);


/** @brief Read-only graph URI.
 *
 * To change the graph URI, use #LSUP_graph_set_uri.
 */
LSUP_Term *
LSUP_graph_uri (const LSUP_Graph *gr);


/** @brief Underlying graph store handle.
 */
LSUP_Store *
LSUP_graph_store (const LSUP_Graph *gr);


/** Set the URI of a graph.
 *
 * Note that by changing the URI of a graph backed by a context-sensitive store
 * (i.e. LSUP_STORE_MDB*) effectively changes the underlying data set that the
 * graph points to. Triples are looked up in, and added to, the context that
 * the graph URI represents. A non-context graph retains the same triple set
 * when graph URI changes.
 *
 * @param gr[in] Graph handle.
 *
 * @param uri[in] IRI handle. The graph takes ownership of the handle.
 *
 * @return LSUP_OK on success; <0 on error.
 */
LSUP_rc
LSUP_graph_set_uri (LSUP_Graph *gr, LSUP_Term *uri);


/** @brief Get the namespace map for an in-memory graph.
 *
 * @return Namespace handler for in-memory graphs, NULL for MDB graphs.
 */
LSUP_NSMap *
LSUP_graph_namespace (const LSUP_Graph *gr);


/** @brief Set the namespace map for an in-memory graph.
 *
 * This has no effect on graph stores with LSUP_STORE_PERM.
 *
 * @param[in] gr Graph to set the namespace map for.
 *
 * @param[in] nsm Namespace handle.
 */
void
LSUP_graph_set_namespace (LSUP_Graph *gr, LSUP_NSMap *nsm);


/** @brief Number of triples in a graph.
 */
size_t
LSUP_graph_size (const LSUP_Graph *gr);


/** @brief Whether a graph contains a triple.
 *
 * @param[in] gr Graph to look up into.
 *
 * @param[in] spo Triple to look up.
 *
 * @return 1 if the triple is found, 0 if not found.
 */
bool
LSUP_graph_contains (const LSUP_Graph *gr, const LSUP_Triple *spo);


/** @brief Begin a transaction.
 *
 * If the underlying store supports it, begin a transaction.
 *
 * Note that the transaction affects all graphs sharing the same store, and it
 * may be closed using a different graph as long as this is backed by the same
 * store. Only one transaction may be opened at a time for the store.
 *
 * The transaction must be either committed with #LSUP_graph_commit() or
 * rolled back with #LSUP_graph_abort().
 *
 * TODO Deprecate in favor of direct access to the store handle.
 *
 * @param[in] gr Graph handle.
 *
 * @param[in] flags Unused for now, use 0. TODO
 *
 * @param[out] txn Address to be populated with the new transaction handle.
 *
 * @return LSUP_OK on success; LSUP_VALUE_ERR if the graph store does not
 *  support transactions; LSUP_TXN_ERR if the store has already an uncommitted
 *  transaction; <0 on other errors from the underlying store.
 */
LSUP_rc
LSUP_graph_begin (LSUP_Graph *gr, int flags, void **txn);


/** @brief Commit a transaction.
 *
 * If the underlying store supports it, commit an open transaction. In case of
 * error, the transaction is left open and it is advisable to roll it back with
 * #LSUP_graph_abort().
 *
 * TODO Deprecate in favor of direct access to the store handle.
 *
 * @param[in] gr Graph handle.
 *
 * @return LSUP_OK if the transaction was committed successfully; LSUP_NOACTION
 *  if NULL was passed; LSUP_TXN_ERR on error.
 */
LSUP_rc LSUP_graph_commit (LSUP_Graph *gr, void *txn);


/** @brief Abort (roll back) a transaction.
 *
 * If the underlying store supports it, abort an open transaction and abandon
 * all changes.
 *
 * TODO Deprecate in favor of direct access to the store handle.
 *
 * @param[in] gr Graph handle.
 */
void LSUP_graph_abort (LSUP_Graph *gr, void *txn);


/** @brief Initialize an iterator to add triples.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param[in] gr Graph to add to. It is added to the iterator state.
 *
 * @return Iterator handle. This should be passed to #LSUP_graph_add_iter() and
 * must be freed with #LSUP_graph_add_done().
 */
LSUP_GraphIterator *
LSUP_graph_add_init_txn (void *txn, LSUP_Graph *gr);


/// Non-transactional version of #LSUP_graph_init_txn.
inline LSUP_GraphIterator *
LSUP_graph_add_init (LSUP_Graph *gr)
{ return LSUP_graph_add_init_txn (NULL, gr); }


/** @brief Add a single triple to the store.
 *
 * @param[in] it Iterator obtained with #LSUP_graph_add_init().
 *
 * @param[in] spo Triple to add. Caller retains ownership.
 */
LSUP_rc
LSUP_graph_add_iter_txn (
        void *txn, LSUP_GraphIterator *it, const LSUP_Triple *spo);


/// Non-transactional version of #LSUP_graph_add_iter_txn.
inline LSUP_rc
LSUP_graph_add_iter (LSUP_GraphIterator *it, const LSUP_Triple *spo)
{ return LSUP_graph_add_iter_txn (NULL, it, spo); }


/** @brief Finalize an add iteration loop and free the iterator.
 *
 * DO NOT USE with iterators obtained with other than #LSUP_graph_add_init().
 *
 * @param[in] it Iterator to finalize.
 */
void
LSUP_graph_add_done (LSUP_GraphIterator *it);


/** @brief Add triples to a graph.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param[in] gr Graph to add triples to.
 *
 * @param[in] trp Array of triples to add. The last triple must be NULL.
 *
 * @param[in] strp Array of buffer triples to add. The last one must be NULL.
 *
 * @param[out] ct This will be filled with the total number of triples
 *  inserted.
 */
LSUP_rc
LSUP_graph_add_txn (
        void *txn, LSUP_Graph *gr, const LSUP_Triple trp[], size_t *ct);


/// Non-transactional version of #LSUP_graph_add_txn.
inline LSUP_rc
LSUP_graph_add (
        LSUP_Graph *gr, const LSUP_Triple trp[], size_t *ct)
{ return LSUP_graph_add_txn (NULL, gr, trp, ct); }


/** @brief Delete triples by a matching pattern.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param gr[in] Graph to delete triples from.
 *
 * @param ptn[in] Matching pattern. Any and all of s, p, o can be NULL.
 *
 * @param ct[out] If not NULL it is populated with the number of triples
 *  deleted.
 */
LSUP_rc
LSUP_graph_remove_txn (
        void *txn, LSUP_Graph *gr, const LSUP_Term *s, const LSUP_Term *p,
        const LSUP_Term *o, size_t *ct);


/// Non-transactional version of #LSUP_graph_remove_txn.
inline LSUP_rc
LSUP_graph_remove (
        LSUP_Graph *gr, const LSUP_Term *s, const LSUP_Term *p,
        const LSUP_Term *o, size_t *ct)
{ return LSUP_graph_remove_txn (NULL, gr, s, p, o, ct); }


/** Look up triples by a matching pattern and yield an iterator.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param gr[in] Graph to look up.
 *
 * @param spo[in] Triple to look for. Any and all terms can be NULL, which
 *  indicate unbound terms.
 *
 * @param it[out] Pointer to a #LSUP_GraphIterator to be generated. It must be
 *  freed with #LSUP_graph_iter_free after use.
 */
LSUP_GraphIterator *
LSUP_graph_lookup_txn (void *txn, const LSUP_Graph *gr, const LSUP_Term *s,
        const LSUP_Term *p, const LSUP_Term *o, size_t *ct);


/// Non-transactional version of #LSUP_graph_lookup_txn.
inline LSUP_GraphIterator *
LSUP_graph_lookup (const LSUP_Graph *gr, const LSUP_Term *s,
        const LSUP_Term *p, const LSUP_Term *o, size_t *ct)
{ return LSUP_graph_lookup_txn (NULL, gr, s, p, o, ct); }


/** @brief Advance a cursor obtained by a lookup and return a matching triple.
 *
 * @param it[in] Iterator handle obtained through #LSUP_graph_lookup.
 *
 * @param spo[out] Triple handle pointer to be populated with the next result.
 * If not NULL, it will allocate a new triple and new terms, and should be
 * freed with LSUP_triple_free().
 *
 * @return LSUP_OK if a result was found; LSUP_END if the end of the match list
 *  was reached.
 */
LSUP_rc
LSUP_graph_iter_next (LSUP_GraphIterator *it, LSUP_Triple **spo);


/** @brief Return the graph related to an iterator.
 */
const LSUP_Graph *
LSUP_graph_iter_graph (LSUP_GraphIterator *it);


/** @brief Free a graph iterator.
 *
 * DO NOT USE with iterators obtained with #LSUP_graph_add_init(). Use
 * #LSUP_graph_add_done() with those.
 *
 * @param[in] it Iterator to finalize.
 */
void
LSUP_graph_iter_free (LSUP_GraphIterator *it);


/** @brief Get term pairs connected to a term in a graph.
 *
 * This returns a #LSUP_LinkMap extracted from a graph for a given term. The
 * map can generate triples using #LSUP_link_map_triples().
 *
 * Depending on the type requested (`LSUP_CONN_*), the term can be leveraged
 * as a subject, predicate, or object.
 *
 * @param[in] gr Graph to extract the connection list from.
 *
 * @param[in] t Term to query for connections.
 *
 * @param[in] type Type of connections to look up.
 *
 * @return Link map for the requested term. It should be freed with
 *  #LSUP_conn_list_free().
 */
LSUP_LinkMap *
LSUP_graph_connections (
        const LSUP_Graph *gr, LSUP_Term *t, LSUP_LinkType type);


/** @brief Get a list of terms related to a term pair in a graph.
 *
 * @param[in] gr Graph to extract terms from.
 *
 * @param[in] t1 First term.
 *
 * @param[in] t1_pos Position of the first term in the triples to look up.
 *
 * @param[in] t2 Second term.
 *
 * @param[in] t2_pos Position of the second term in the triples to look up.
 *
 * @return Term set of results.
 */
LSUP_TermSet *
LSUP_graph_term_set (
        const LSUP_Graph *gr, LSUP_Term *t1, LSUP_TriplePos t1_pos,
        LSUP_Term *t2, LSUP_TriplePos t2_pos);


/** @brief Get all unique subjcts, predicates, or objects in a graph.
 *
 * @param[in] gr Graph handle.
 *
 * @param[in] pos Position in the triples of the terms to look for.
 */
LSUP_TermSet *
LSUP_graph_unique_terms (const LSUP_Graph *gr, LSUP_TriplePos pos);


/** @brief Add triples for a term and related connection list to a graph.
 *
 * The connection list can be of inbound, outbound, or edge type; depending on
 * that, triples are added with the given term as the subject, the predicate,
 * or the object.
 *
 * @param[in] it Graph iterator obtained with #LSUP_graph_add_init().
 *
 * @param[in] t Term to be associated with the collection list.
 *
 * @param[in] cl Link map.
 *
 * @return Number of triples parsed on success, or <0 (LSUP_*_ERR) on error.
 */
size_t
LSUP_graph_add_link_map (
        LSUP_GraphIterator *it, LSUP_Term *t, LSUP_LinkMap *cl);


/** @brief Add triples for an anonymous collection to a graph.
 *
 * The `rdf:first`, `rdf:rest`, etc. terms are automatically added and the term
 * for the first item in the list is returned.
 *
 * @param[in] it Graph iterator to use for insertion.
 *
 * @param[in] ol NUL-terminated term array.
 *
 * @return Blank node representing the first list item.
 */
LSUP_Term *
LSUP_bnode_add_collection (LSUP_GraphIterator *it, LSUP_TermSet *ts);

#endif