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