Chris@0: /*
Chris@0:   Copyright 2011-2013 David Robillard <http://drobilla.net>
Chris@0: 
Chris@0:   Permission to use, copy, modify, and/or distribute this software for any
Chris@0:   purpose with or without fee is hereby granted, provided that the above
Chris@0:   copyright notice and this permission notice appear in all copies.
Chris@0: 
Chris@0:   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
Chris@0:   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
Chris@0:   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
Chris@0:   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
Chris@0:   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
Chris@0:   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
Chris@0:   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    @file sord.h API for Sord, a lightweight RDF model library.
Chris@0: */
Chris@0: 
Chris@0: #ifndef SORD_SORD_H
Chris@0: #define SORD_SORD_H
Chris@0: 
Chris@0: #include <stddef.h>
Chris@0: #include <stdint.h>
Chris@0: #include <stdio.h>
Chris@0: 
Chris@0: #include "serd/serd.h"
Chris@0: 
Chris@0: #ifdef SORD_SHARED
Chris@0: #    ifdef _WIN32
Chris@0: #        define SORD_LIB_IMPORT __declspec(dllimport)
Chris@0: #        define SORD_LIB_EXPORT __declspec(dllexport)
Chris@0: #    else
Chris@0: #        define SORD_LIB_IMPORT __attribute__((visibility("default")))
Chris@0: #        define SORD_LIB_EXPORT __attribute__((visibility("default")))
Chris@0: #    endif
Chris@0: #    ifdef SORD_INTERNAL
Chris@0: #        define SORD_API SORD_LIB_EXPORT
Chris@0: #    else
Chris@0: #        define SORD_API SORD_LIB_IMPORT
Chris@0: #    endif
Chris@0: #else
Chris@0: #    define SORD_API
Chris@0: #endif
Chris@0: 
Chris@0: #ifdef __cplusplus
Chris@0: extern "C" {
Chris@0: #else
Chris@0: #    include <stdbool.h>
Chris@0: #endif
Chris@0: 
Chris@0: /**
Chris@0:    @defgroup sord Sord
Chris@0:    A lightweight RDF model library.
Chris@0: 
Chris@0:    Sord stores RDF (subject object predicate context) quads, where the context
Chris@0:    may be omitted (to represent triples in the default graph).
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Sord World.
Chris@0:    The World represents all library state, including interned strings.
Chris@0: */
Chris@0: typedef struct SordWorldImpl SordWorld;
Chris@0: 
Chris@0: /**
Chris@0:    Sord Model.
Chris@0: 
Chris@0:    A model is an indexed set of Quads (i.e. it can contain several RDF
Chris@0:    graphs).  It may be searched using various patterns depending on which
Chris@0:    indices are enabled.
Chris@0: */
Chris@0: typedef struct SordModelImpl SordModel;
Chris@0: 
Chris@0: /**
Chris@0:    Model Inserter.
Chris@0: 
Chris@0:    An inserter is used for writing statements to a model using the Serd sink
Chris@0:    interface.  This makes it simple to write to a model directly using a
Chris@0:    SerdReader, or any other code that writes statements to a SerdStatementSink.
Chris@0: */
Chris@0: typedef struct SordInserterImpl SordInserter;
Chris@0: 
Chris@0: /**
Chris@0:    Model Iterator.
Chris@0: */
Chris@0: typedef struct SordIterImpl SordIter;
Chris@0: 
Chris@0: /**
Chris@0:    RDF Node.
Chris@0:    A Node is a component of a Quad.  Nodes may be URIs, blank nodes, or
Chris@0:    (in the case of quad objects only) string literals. Literal nodes may
Chris@0:    have an associate language or datatype (but not both).
Chris@0: */
Chris@0: typedef struct SordNodeImpl SordNode;
Chris@0: 
Chris@0: /**
Chris@0:    Quad of nodes (a statement), or a quad pattern.
Chris@0: 
Chris@0:    Nodes are ordered (S P O G).  The ID of the default graph is 0.
Chris@0: */
Chris@0: typedef const SordNode* SordQuad[4];
Chris@0: 
Chris@0: /**
Chris@0:    Index into a SordQuad.
Chris@0: */
Chris@0: typedef enum {
Chris@0: 	SORD_SUBJECT   = 0,  /**< Subject */
Chris@0: 	SORD_PREDICATE = 1,  /**< Predicate (a.k.a. "key") */
Chris@0: 	SORD_OBJECT    = 2,  /**< Object    (a.k.a. "value") */
Chris@0: 	SORD_GRAPH     = 3   /**< Graph     (a.k.a. "context") */
Chris@0: } SordQuadIndex;
Chris@0: 
Chris@0: /**
Chris@0:    Type of a node.
Chris@0: */
Chris@0: typedef enum {
Chris@0: 	SORD_URI     = 1,  /**< URI */
Chris@0: 	SORD_BLANK   = 2,  /**< Blank node identifier */
Chris@0: 	SORD_LITERAL = 3   /**< Literal (string with optional lang or datatype) */
Chris@0: } SordNodeType;
Chris@0: 
Chris@0: /**
Chris@0:    Indexing option.
Chris@0: */
Chris@0: typedef enum {
Chris@0: 	SORD_SPO = 1,       /**< Subject,   Predicate, Object */
Chris@0: 	SORD_SOP = 1 << 1,  /**< Subject,   Object,    Predicate */
Chris@0: 	SORD_OPS = 1 << 2,  /**< Object,    Predicate, Subject */
Chris@0: 	SORD_OSP = 1 << 3,  /**< Object,    Subject,   Predicate */
Chris@0: 	SORD_PSO = 1 << 4,  /**< Predicate, Subject,   Object */
Chris@0: 	SORD_POS = 1 << 5   /**< Predicate, Object,    Subject */
Chris@0: } SordIndexOption;
Chris@0: 
Chris@0: /**
Chris@0:    @name World
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Create a new Sord World.
Chris@0:    It is safe to use multiple worlds in one process, though no data
Chris@0:    (e.g. nodes) can be shared between worlds, and this should be avoided if
Chris@0:    possible for performance reasons.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordWorld*
Chris@0: sord_world_new(void);
Chris@0: 
Chris@0: /**
Chris@0:    Free @c world.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_world_free(SordWorld* world);
Chris@0: 
Chris@0: /**
Chris@0:    Set a function to be called when errors occur.
Chris@0: 
Chris@0:    The @p error_sink will be called with @p handle as its first argument.  If
Chris@0:    no error function is set, errors are printed to stderr.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_world_set_error_sink(SordWorld*    world,
Chris@0:                           SerdErrorSink error_sink,
Chris@0:                           void*         handle);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @name Node
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Get a URI node from a string.
Chris@0: 
Chris@0:    Note this function measures @c str, which is a common bottleneck.
Chris@0:    Use sord_node_from_serd_node instead if @c str is already measured.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_new_uri(SordWorld* world, const uint8_t* uri);
Chris@0: 
Chris@0: /**
Chris@0:    Get a URI node from a relative URI string.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_new_relative_uri(SordWorld*     world,
Chris@0:                       const uint8_t* str,
Chris@0:                       const uint8_t* base_uri);
Chris@0: 
Chris@0: /**
Chris@0:    Get a blank node from a string.
Chris@0: 
Chris@0:    Note this function measures @c str, which is a common bottleneck.
Chris@0:    Use sord_node_from_serd_node instead if @c str is already measured.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_new_blank(SordWorld* world, const uint8_t* str);
Chris@0: 
Chris@0: /**
Chris@0:    Get a literal node from a string.
Chris@0: 
Chris@0:    Note this function measures @c str, which is a common bottleneck.
Chris@0:    Use sord_node_from_serd_node instead if @c str is already measured.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_new_literal(SordWorld*     world,
Chris@0:                  SordNode*      datatype,
Chris@0:                  const uint8_t* str,
Chris@0:                  const char*    lang);
Chris@0: 
Chris@0: /**
Chris@0:    Copy a node (obtain a reference).
Chris@0: 
Chris@0:    Node that since nodes are interned and reference counted, this does not
Chris@0:    actually create a deep copy of @c node.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_node_copy(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Free a node (drop a reference).
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_node_free(SordWorld* world, SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL).
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNodeType
Chris@0: sord_node_get_type(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return the string value of a node.
Chris@0: */
Chris@0: SORD_API
Chris@0: const uint8_t*
Chris@0: sord_node_get_string(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return the string value of a node, and set @c len to its length.
Chris@0: */
Chris@0: SORD_API
Chris@0: const uint8_t*
Chris@0: sord_node_get_string_counted(const SordNode* node, size_t* len);
Chris@0: 
Chris@0: /**
Chris@0:    Return the language of a literal node (or NULL).
Chris@0: */
Chris@0: SORD_API
Chris@0: const char*
Chris@0: sord_node_get_language(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return the datatype URI of a literal node (or NULL).
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_node_get_datatype(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return the flags (string attributes) of a node.
Chris@0: */
Chris@0: SORD_API
Chris@0: SerdNodeFlags
Chris@0: sord_node_get_flags(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return true iff node can be serialised as an inline object.
Chris@0: 
Chris@0:    More specifically, this returns true iff the node is the object field
Chris@0:    of exactly one statement, and therefore can be inlined since it needn't
Chris@0:    be referred to by name.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_node_is_inline_object(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Return true iff @c a is equal to @c b.
Chris@0: 
Chris@0:    Note this is much faster than comparing the node's strings.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_node_equals(const SordNode* a,
Chris@0:                  const SordNode* b);
Chris@0: 
Chris@0: /**
Chris@0:    Return a SordNode as a SerdNode.
Chris@0: 
Chris@0:    The returned node is shared and must not be freed or modified.
Chris@0: */
Chris@0: SORD_API
Chris@0: const SerdNode*
Chris@0: sord_node_to_serd_node(const SordNode* node);
Chris@0: 
Chris@0: /**
Chris@0:    Create a new SordNode from a SerdNode.
Chris@0: 
Chris@0:    The returned node must be freed using sord_node_free.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_node_from_serd_node(SordWorld*      world,
Chris@0:                          SerdEnv*        env,
Chris@0:                          const SerdNode* node,
Chris@0:                          const SerdNode* datatype,
Chris@0:                          const SerdNode* lang);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @name Model
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Create a new model.
Chris@0: 
Chris@0:    @param world The world in which to make this model.
Chris@0: 
Chris@0:    @param indices SordIndexOption flags (e.g. SORD_SPO|SORD_OPS).  Be sure to
Chris@0:    enable an index where the most significant node(s) are not variables in your
Chris@0:    queries (e.g. to make (? P O) queries, enable either SORD_OPS or SORD_POS).
Chris@0: 
Chris@0:    @param graphs If true, store (and index) graph contexts.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordModel*
Chris@0: sord_new(SordWorld* world,
Chris@0:          unsigned  indices,
Chris@0:          bool      graphs);
Chris@0: 
Chris@0: /**
Chris@0:    Close and free @c model.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_free(SordModel* model);
Chris@0: 
Chris@0: /**
Chris@0:    Get the world associated with @c model.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordWorld*
Chris@0: sord_get_world(SordModel* model);
Chris@0: 
Chris@0: /**
Chris@0:    Return the number of nodes stored in @c world.
Chris@0: 
Chris@0:    Nodes are included in this count iff they are a part of a quad in @c world.
Chris@0: */
Chris@0: SORD_API
Chris@0: size_t
Chris@0: sord_num_nodes(const SordWorld* world);
Chris@0: 
Chris@0: /**
Chris@0:    Return the number of quads stored in @c model.
Chris@0: */
Chris@0: SORD_API
Chris@0: size_t
Chris@0: sord_num_quads(const SordModel* model);
Chris@0: 
Chris@0: /**
Chris@0:    Return an iterator to the start of @c model.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordIter*
Chris@0: sord_begin(const SordModel* model);
Chris@0: 
Chris@0: /**
Chris@0:    Search for statements by a quad pattern.
Chris@0:    @return an iterator to the first match, or NULL if no matches found.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordIter*
Chris@0: sord_find(SordModel* model, const SordQuad pat);
Chris@0: 
Chris@0: /**
Chris@0:    Search for statements by nodes.
Chris@0:    @return an iterator to the first match, or NULL if no matches found.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordIter*
Chris@0: sord_search(SordModel*      model,
Chris@0:             const SordNode* s,
Chris@0:             const SordNode* p,
Chris@0:             const SordNode* o,
Chris@0:             const SordNode* g);
Chris@0: /**
Chris@0:    Search for a single node that matches a pattern.
Chris@0:    Exactly one of @p s, @p p, @p o must be NULL.
Chris@0:    This function is mainly useful for predicates that only have one value.
Chris@0:    The returned node must be freed using sord_node_free.
Chris@0:    @return the first matching node, or NULL if no matches are found.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordNode*
Chris@0: sord_get(SordModel*      model,
Chris@0:          const SordNode* s,
Chris@0:          const SordNode* p,
Chris@0:          const SordNode* o,
Chris@0:          const SordNode* g);
Chris@0: 
Chris@0: /**
Chris@0:    Return true iff a statement exists.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_ask(SordModel*      model,
Chris@0:          const SordNode* s,
Chris@0:          const SordNode* p,
Chris@0:          const SordNode* o,
Chris@0:          const SordNode* g);
Chris@0: 
Chris@0: /**
Chris@0:    Return the number of matching statements.
Chris@0: */
Chris@0: SORD_API
Chris@0: uint64_t
Chris@0: sord_count(SordModel*      model,
Chris@0:            const SordNode* s,
Chris@0:            const SordNode* p,
Chris@0:            const SordNode* o,
Chris@0:            const SordNode* g);
Chris@0: 
Chris@0: /**
Chris@0:    Check if @a model contains a triple pattern.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_contains(SordModel* model, const SordQuad pat);
Chris@0: 
Chris@0: /**
Chris@0:    Add a quad to a model.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_add(SordModel* model, const SordQuad quad);
Chris@0: 
Chris@0: /**
Chris@0:    Remove a quad from a model.
Chris@0: 
Chris@0:    Note that is it illegal to remove while iterating over @c model.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_remove(SordModel* model, const SordQuad quad);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @name Inserter
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Create an inserter for writing statements to a model.
Chris@0: */
Chris@0: SORD_API
Chris@0: SordInserter*
Chris@0: sord_inserter_new(SordModel* model,
Chris@0:                   SerdEnv*   env);
Chris@0: 
Chris@0: /**
Chris@0:    Free an inserter.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_inserter_free(SordInserter* inserter);
Chris@0: 
Chris@0: /**
Chris@0:    Set the current base URI for writing to the model.
Chris@0: 
Chris@0:    Note this function can be safely casted to SerdBaseSink.
Chris@0: */
Chris@0: SORD_API
Chris@0: SerdStatus
Chris@0: sord_inserter_set_base_uri(SordInserter*   inserter,
Chris@0:                            const SerdNode* uri);
Chris@0: 
Chris@0: /**
Chris@0:    Set a namespace prefix for writing to the model.
Chris@0: 
Chris@0:    Note this function can be safely casted to SerdPrefixSink.
Chris@0: */
Chris@0: SORD_API
Chris@0: SerdStatus
Chris@0: sord_inserter_set_prefix(SordInserter*   inserter,
Chris@0:                          const SerdNode* name,
Chris@0:                          const SerdNode* uri);
Chris@0: 
Chris@0: /**
Chris@0:    Write a statement to the model.
Chris@0: 
Chris@0:    Note this function can be safely casted to SerdStatementSink.
Chris@0: */
Chris@0: SORD_API
Chris@0: SerdStatus
Chris@0: sord_inserter_write_statement(SordInserter*      inserter,
Chris@0:                               SerdStatementFlags flags,
Chris@0:                               const SerdNode*    graph,
Chris@0:                               const SerdNode*    subject,
Chris@0:                               const SerdNode*    predicate,
Chris@0:                               const SerdNode*    object,
Chris@0:                               const SerdNode*    object_datatype,
Chris@0:                               const SerdNode*    object_lang);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @name Iteration
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Set @c quad to the quad pointed to by @c iter.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_iter_get(const SordIter* iter, SordQuad quad);
Chris@0: 
Chris@0: /**
Chris@0:    Return a field of the quad pointed to by @c iter.
Chris@0: */
Chris@0: SORD_API
Chris@0: const SordNode*
Chris@0: sord_iter_get_node(const SordIter* iter, SordQuadIndex index);
Chris@0: 
Chris@0: /**
Chris@0:    Return the store pointed to by @c iter.
Chris@0: */
Chris@0: SORD_API
Chris@0: const SordModel*
Chris@0: sord_iter_get_model(SordIter* iter);
Chris@0: 
Chris@0: /**
Chris@0:    Increment @c iter to point to the next statement.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_iter_next(SordIter* iter);
Chris@0: 
Chris@0: /**
Chris@0:    Return true iff @c iter is at the end of its range.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_iter_end(const SordIter* iter);
Chris@0: 
Chris@0: /**
Chris@0:    Free @c iter.
Chris@0: */
Chris@0: SORD_API
Chris@0: void
Chris@0: sord_iter_free(SordIter* iter);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @name Utilities
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Match two quads (using ID comparison only).
Chris@0: 
Chris@0:    This function is a straightforward and fast equivalence match with wildcard
Chris@0:    support (ID 0 is a wildcard). It does not actually read node data.
Chris@0:    @return true iff @c x and @c y match.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_quad_match(const SordQuad x, const SordQuad y);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @name Serialisation
Chris@0:    @{
Chris@0: */
Chris@0: 
Chris@0: /**
Chris@0:    Return a reader that will read into @c model.
Chris@0: */
Chris@0: SORD_API
Chris@0: SerdReader*
Chris@0: sord_new_reader(SordModel* model,
Chris@0:                 SerdEnv*   env,
Chris@0:                 SerdSyntax syntax,
Chris@0:                 SordNode*  graph);
Chris@0: 
Chris@0: /**
Chris@0:    Write a model to a writer.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_write(SordModel*  model,
Chris@0:            SerdWriter* writer,
Chris@0:            SordNode*   graph);
Chris@0: 
Chris@0: /**
Chris@0:    Write a range to a writer.
Chris@0: 
Chris@0:    This increments @c iter to its end, then frees it.
Chris@0: */
Chris@0: SORD_API
Chris@0: bool
Chris@0: sord_write_iter(SordIter*   iter,
Chris@0:                 SerdWriter* writer);
Chris@0: 
Chris@0: /**
Chris@0:    @}
Chris@0:    @}
Chris@0: */
Chris@0: 
Chris@0: #ifdef __cplusplus
Chris@0: }  /* extern "C" */
Chris@0: #endif
Chris@0: 
Chris@0: #endif  /* SORD_SORD_H */