lsup_rdf/include/graph.h

#ifndef _LSUP_GRAPH_H
#define _LSUP_GRAPH_H

#include "environment.h"

/*
 * Define backend types and checks.
 */

#define BACKEND_TBL                                              \
    ENTRY(  MEM,       0)/* Memory backend, hash map. */         \
    ENTRY(  MDB,       1)/* LMDB back end on persistent disk. */ \
    ENTRY(  MDB_TMP,   2)/* LMDB back end on RAM disk. */        \

typedef enum LSUP_store_type {
#define ENTRY(a, b) LSUP_STORE_##a = b,
    BACKEND_TBL
#undef ENTRY
} LSUP_store_type;


/** @brief Graph object.
 */
typedef struct Graph 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 GraphIterator LSUP_GraphIterator;


/** @brief Create an empty graph.
 *
 * The new graph has zero capacity and a random URN. To change either one, use
 * #LSUP_graph_resize and #LSUP_graph_set_uri, respectively.
 *
 * The graph is assigned a default (volatile) namespace map if it's in memory,
 * hence all graphs share the same namespace map by default. To change this,
 * use #LSUP_graph_set_namespace(). MDB graphs use a persistent namespace map
 * that is common to all the graphs in the same store. This cannot be changed.
 *
 * @param store_type[in] Type of store for the graph. One of the values of
 *  #LSUP_store_type.
 *
 * @param gr[out] Pointer to a pointer to the new graph. It must be freed with
 *  #LSUP_graph_free when done.
 *
 * @return LSUP_OK if the graph was created, or < 0 if an error occurred.
 */
LSUP_Graph *
LSUP_graph_new_env (const LSUP_Env *env, const LSUP_store_type store_type);


/** @brief Create an empty graph with the default environment.
 *
 * This is likely to be used more often than #LSUP_graph_new_env().
 */
#define LSUP_graph_new(type) LSUP_graph_new_env (LSUP_default_env, type)


/** @brief Create an array of graph from triples matching a pattern in a store.
 *
 * The s, p, o lookup terms behave as in #LSUP_store_lookup().
 *
 * @param[in] s Lookup subject.
 *
 * @param[in] p Lookup predicate.
 *
 * @param[in] o Lookup object.
 *
 * @param[in] env Environment to look into. If NULL, it is set to the deafult
 *  environment.
 *
 * @return A NULL-terminated array of graphs.
 */
LSUP_Graph **
LSUP_graph_new_lookup_env (
        const LSUP_Env *env, const LSUP_Term *s,
        const LSUP_Term *p, const LSUP_Term *o);

/** @brief Shortcut for #LSUP_graph_new_lookup_env() on default MDB store.
 */
#define LSUP_graph_new_lookup(s, p, o) \
    LSUP_graph_new_lookup_env (LSUP_default_env, (s), (p), (o))


/** @brief copy a graph into a new one.
 *
 * The new graph is compacted to the minimum required size.
 *
 * src[in] Graph to be copied.
 *
 * @param uri URI of the destination graph. If NULL, a UUID4 URN is generated.
 *
 * @param gr[out] Pointer to a pointer to the destination graph. It must be
 *  freed with #LSUP_graph_free when done.
 *
 * @return LSUP_OK if the graph was copied, or < 0 if an error occurred.
 */
LSUP_Graph *
LSUP_graph_copy (const LSUP_Graph *src);


/** @brief Copy the contents of a graph into a permanent store.
 *
 * It is possible to store a memory graph, a RAMdisk MDB graph, or a
 * permanently stored graph into another environment.
 *
 * The namespace map associated with the graph is stored into the destination
 * as well, except for existing namespaces and prefixes.
 *
 * @param[in] src Graph to store.
 *
 * @param[out] dest Pointer to graph handle for the new stored graph. The new
 *  graph will have the same URI as the source.
 *
 * @param[in] env Environment to copy to. If NULL, it is set to the deafult
 *  LSUP store. This makes it possible to copy MDB graphs across different
 *  environments. If the source is a MDB graph and the environment is the same
 *  as the source, no change occurs.
 *
 * @return LSUP_OK on success; LSUP_NOACTION if the graph is already stored in
 *  the same enviroment; <0 on error.
 */
LSUP_rc
LSUP_graph_store (
        const LSUP_Graph *src, LSUP_Graph **dest_p, const LSUP_Env *env);


/** Perform a boolean operation between two graphs.
 *
 * This method yields a new graph as the result of the operation.
 *
 * @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. It must be freed with #LSUP_graph_free when
 *  done.
 */
LSUP_Graph *
LSUP_graph_bool_op(
        const LSUP_bool_op op, const LSUP_Graph *gr1, const LSUP_Graph *gr2);


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


/** @brief Compare two graphs.
 *
 * @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);


/** 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 whose URI is to be changed.
 *
 * @param uri[in] New URI as a string. If NULL, a UUID4 URN is generated.
 *
 * @return LSUP_OK on success; <0 on error.
 */
LSUP_rc
LSUP_graph_set_uri (LSUP_Graph *gr, const char *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 MDB graphs.
 *
 * @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] 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 (LSUP_Graph *gr);



/** @brief Add a single triple to the store.
 *
 * @param[in] it Iterator obtained with #LSUP_graph_add_init().
 *
 * @param[in] sspo Serialized triple to add.
 */
LSUP_rc
LSUP_graph_add_iter (
        LSUP_GraphIterator *it, const LSUP_BufferTriple *sspo);


/** @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 and/or serialized triples to a graph.
 *
 * For API users it may be more convenient to use the more specialized
 * #LSUP_graph_add_trp.
 *
 * @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] inserted This will be filled with the total number of triples
 *  inserted.
 */
LSUP_rc
LSUP_graph_add (
        LSUP_Graph *gr, const LSUP_Triple trp[],
        const LSUP_BufferTriple strp[], size_t *inserted);


/** @brief Insert RDF triples into a graph.
 *
 * This is a convenience method for external callers which most likely have
 * non-serialized triples at hand.
 */
#define LSUP_graph_add_trp(gr, trp, ins) LSUP_graph_add (gr, trp, NULL, ins)


/** @brief Delete triples by a matching pattern.
 *
 * @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 (
        LSUP_Graph *gr, const LSUP_Term *s, const LSUP_Term *p,
        const LSUP_Term *o, size_t *ct);


/** Look up triples by a matching pattern and yield an iterator.
 *
 * @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 (const LSUP_Graph *gr, const LSUP_Term *s,
        const LSUP_Term *p, const LSUP_Term *o, size_t *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 to be populated with the next result. May be NULL
 *  (e.g. for counters).
 *
 * @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 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 the iterator counter.
 */
size_t
LSUP_graph_iter_cur (LSUP_GraphIterator *it);

#endif