lsup_rdf/include/graph.h

#ifndef _LSUP_GRAPH_H
#define _LSUP_GRAPH_H

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


/** @defgroup graph RDF graph module
 * @ingroup public
 * @{
 */

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

/** @brief Graph iterator.
 *
 * This opaque handle is generated by #LSUP_graph_lookup_txn 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] store Back end store handle. It may be the result of
 * #LSUP_store_new(), or NULL; in the latter case, it defaults to a temporary
 * HTable store that is freed together with the graph.
 *
 * @param[in] uri URI of the new graph. If NULL, a UUID4 URN is generated. The
 *  term is copied into the graph and may be freed after this function is
 *  called.
 *
 * @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_Store *store, const LSUP_Term *uri, LSUP_NSMap *nsm);


/** @brief Create a temp graph from stored triples.
 *
 * The new graph is stored in a hash map and is made up of all the triples
 * found in the store with the given context URI. The new graph URI is the
 * same as the given context.
 *
 * @param[in] txn Transaction handle. If not `NULL`, new child transaction will
 *  be opened under the one provided.
 *
 * @param[in] store Back end store handle. The store must exist.
 *
 * @param[in] uri URI of the graph to retrieve.
 *
 * @param[out] ct If not NULL, it will be populated with the number of triples
 * found.
 *
 * @return New graph handle. It must be freed by the caller. If no matching
 * context URI was found, NULL is returned.
 */
LSUP_Graph *
LSUP_graph_get_txn (
        void *txn, LSUP_Store *store, const LSUP_Term *uri, size_t *ct);


/// Non-transactional version of #LSUP_graph_get_txn().
#define LSUP_graph_get(...) LSUP_graph_get_txn (NULL, __VA_ARGS__)


/** @brief Copy triples from a source graph into a destination one.
 *
 * The destination graph is not initialized here, so the copy is cumulative.
 *
 * A 3-term pattern may be provided to filter triples to be extracted from the
 * source graph. If all terms are NULL, all triples are copied.
 *
 * @param[in] txn Transaction handle. It may be NULL, or an open transaction
 *  handle, in which case the copy is done within the specified transaction.
 *
 * @param[in] src Source graph.
 *
 * @param[in] dest Destination graph.
 *
 * @param[in] s, p, o Terms to look up for filtering. Any and all terms can be
 * NULL, which indicate unbound terms.
 *
 * @return LSUP_OK on success; LSUP_NOACTION if no triples were copied; <0
 *  if an error occurred.
 */
LSUP_rc
LSUP_graph_copy_contents_txn (
        void *txn, const LSUP_Graph *src, LSUP_Graph *dest,
        const LSUP_Term *s, const LSUP_Term *p, const LSUP_Term *o);


/// Non-transactional version of #LSUP_graph_copy_contents_txn().
#define LSUP_graph_copy_contents(...) \
    LSUP_graph_copy_contents_txn (NULL, __VA_ARGS__)


/* @brief Copy all triples from a graph.
 *
 * This is a shortcut for #LSUP_graph_copy_contents_txn(). If you need to
 * specify a transaction handle and/or a filter for the copy, use that.
 *
 * @param[in] src Source graph.
 *
 * @param[in] dest Destination graph.
 *
 * @return LSUP_OK on success; LSUP_NOACTION if no triples were copied; <0
 *  if an error occurred.
 */
#define LSUP_graph_copy(src, dest) \
    LSUP_graph_copy_contents_txn (NULL, src, dest, NULL, NULL, NULL)


/** 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 R/W transaction handle for the destination store.  It may be
 * NULL, or an open transaction within which the operation is performed.
 *
 * @param[in] op Operation to perform. One of #LSUP_bool_op.
 *
 * @param[in] gr1 First operand.
 *
 * @param[in] gr2 Second operand.
 *
 * @param[out] res 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, and any preexisting
 *  triples are lost. Therefore, reusing a result graph handle should only be
 *  done in tightly controlled loops or sequences.
 *
 * @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.
#define LSUP_graph_bool_op(...) LSUP_graph_bool_op_txn (NULL, __VA_ARGS__)


/** @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.
 */
const 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 context that the
 * triples are bound 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 a graph URI changes, and relative URI lookups are resolved in
 * real-time against the current graph URI.
 *
 * @param[in] gr Graph handle.
 *
 * @param[in] uri 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 Initialize an iterator to add triples.
 *
 * @param[in] txn Transaction handle. It may be NULL. If not NULL, its handle
 * will be bound to the iterator handle for its whole life cycle.
 *
 * @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_add_init_txn().
#define LSUP_graph_add_init(...) LSUP_graph_add_init_txn (NULL, __VA_ARGS__)


/** @brief Add a single triple to the store.
 *
 * @param[in] it Iterator obtained with #LSUP_graph_add_init_txn().
 *
 * @param[in] spo Triple to add. Caller retains ownership. NOTE: the triple
 *  subject and object, if IRIRefs, are stored as relative to the graph URI.
 */
LSUP_rc
LSUP_graph_add_iter (LSUP_GraphIterator *it, const LSUP_Triple *spo);


/** @brief Finalize an add iteration loop and free the iterator.
 *
 * DO NOT USE with iterators obtained with other than
 * #LSUP_graph_add_init_txn().
 *
 * @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 NULL-terminated array of triple handles to add.
 *
 * @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, LSUP_Triple *const *trp, size_t *ct);


/// Non-transactional version of #LSUP_graph_add_txn.
#define LSUP_graph_add(...) LSUP_graph_add_txn (NULL, __VA_ARGS__)


/** @brief Delete triples by a matching pattern.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param[in] gr Graph to delete triples from.
 *
 * @param[in] s, p, o Matching pattern. Any and all of s, p, o can be NULL.
 *
 * @param[out] ct 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.
#define LSUP_graph_remove(...) LSUP_graph_remove_txn (NULL, __VA_ARGS__)


/** @brief Look up triples by a matching pattern and yield an iterator.
 *
 * @param[in] txn Transaction handle. It may be NULL.
 *
 * @param[in] gr Graph to look up.
 *
 * @param[in] s Subject to look for. It can be NULL, which indicates an
 * unbound term.
 *
 * @param[in] p Predicate to look for. It can be NULL, which indicates an
 * unbound term.
 *
 * @param[in] o Object to look for. It can be NULL, which indicates an
 * unbound term.
 *
 * @param[out] ct If not NULL, this handle is populated with the number of
 *  entries found.
 *
 * @return 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.
#define LSUP_graph_lookup(...) LSUP_graph_lookup_txn (NULL, __VA_ARGS__)


/** @brief Advance a cursor obtained by a lookup and return a matching triple.
 *
 * @param[in] it Iterator handle obtained through #LSUP_graph_lookup_txn.
 *
 * @param[out] spo 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_txn(). 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_link_map_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_txn().
 *
 * @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] ts Source term set.
 *
 * @return Blank node representing the first list item.
 */
LSUP_Term *
LSUP_bnode_add_collection (LSUP_GraphIterator *it, LSUP_TermSet *ts);

/// @}  END defgroup graph
#endif