diff options
Diffstat (limited to 'serd')
| -rw-r--r-- | serd/serd.h | 673 |
1 files changed, 222 insertions, 451 deletions
diff --git a/serd/serd.h b/serd/serd.h index 6f9360cc..9b3e35f6 100644 --- a/serd/serd.h +++ b/serd/serd.h @@ -14,9 +14,7 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/** - @file serd.h API for Serd, a lightweight RDF syntax library. -*/ +/// @file serd.h API for Serd, a lightweight RDF syntax library #ifndef SERD_SERD_H #define SERD_SERD_H @@ -50,136 +48,73 @@ extern "C" { /** @defgroup serd Serd - A lightweight RDF syntax library. + A lightweight RDF syntax library @{ */ -/** - World. - - The World represents all library state shared between various objects. -*/ +/// Global library state typedef struct SerdWorldImpl SerdWorld; -/** - Nodes. - - A hashing container for nodes that can be used for interning and simplified - memory management. -*/ +/// Hashing node container for interning and simplified memory management typedef struct SerdNodesImpl SerdNodes; -/** - Statement. - - A subject, predicate, and object, with optional graph context. -*/ +/// A subject, predicate, and object, with optional graph context typedef struct SerdStatementImpl SerdStatement; -/** - Cursor, the origin of a statement in a document. -*/ +/// The origin of a statement in a document typedef struct SerdCursorImpl SerdCursor; -/** - Environment. - - Represents the state required to resolve a CURIE or relative URI, e.g. the - base URI and set of namespace prefixes at a particular point. -*/ +/// Lexical environment for relative URIs or CURIEs (base URI and namespaces) typedef struct SerdEnvImpl SerdEnv; -/** - RDF reader. - - Parses RDF by calling user-provided sink functions as input is consumed - (much like an XML SAX parser). -*/ +/// Streaming parser that reads a text stream and writes to a statement sink typedef struct SerdReaderImpl SerdReader; -/** - RDF writer. - - Provides a number of functions to allow writing RDF syntax out to some - stream. These functions are deliberately compatible with the sink functions - used by SerdReader, so a reader can be directly connected to a writer to - re-serialise a document with minimal overhead. -*/ +/// Streaming serialiser that writes a text stream as statements are pushed typedef struct SerdWriterImpl SerdWriter; -/** - An interface that receives a stream of RDF data. -*/ +/// An interface that receives a stream of RDF data typedef struct SerdSinkImpl SerdSink; -/** - A sink for bytes that receives string output. -*/ +/// A sink for bytes that receives string output typedef struct SerdByteSinkImpl SerdByteSink; -/** - Return status code. -*/ +/// Return status code typedef enum { - SERD_SUCCESS, /**< No error */ - SERD_FAILURE, /**< Non-fatal failure */ - SERD_ERR_UNKNOWN, /**< Unknown error */ - SERD_ERR_BAD_SYNTAX, /**< Invalid syntax */ - SERD_ERR_BAD_ARG, /**< Invalid argument */ - SERD_ERR_NOT_FOUND, /**< Not found */ - SERD_ERR_ID_CLASH, /**< Encountered clashing blank node IDs */ - SERD_ERR_BAD_CURIE, /**< Invalid CURIE (e.g. prefix does not exist) */ - SERD_ERR_INTERNAL, /**< Unexpected internal error (should not happen) */ - SERD_ERR_OVERFLOW /**< Stack overflow */ + SERD_SUCCESS, ///< No error + SERD_FAILURE, ///< Non-fatal failure + SERD_ERR_UNKNOWN, ///< Unknown error + SERD_ERR_BAD_SYNTAX, ///< Invalid syntax + SERD_ERR_BAD_ARG, ///< Invalid argument + SERD_ERR_NOT_FOUND, ///< Not found + SERD_ERR_ID_CLASH, ///< Encountered clashing blank node IDs + SERD_ERR_BAD_CURIE, ///< Invalid CURIE (e.g. prefix does not exist) + SERD_ERR_INTERNAL, ///< Unexpected internal error (should not happen) + SERD_ERR_OVERFLOW ///< Stack overflow } SerdStatus; -/** - RDF syntax type. -*/ +/// RDF syntax type typedef enum { - /** - Turtle - Terse RDF Triple Language (UTF-8). - @see <a href="http://www.w3.org/TeamSubmission/turtle/">Turtle</a> - */ - SERD_TURTLE = 1, - - /** - NTriples - Line-based RDF triples (ASCII). - @see <a href="http://www.w3.org/TR/rdf-testcases#ntriples">NTriples</a> - */ - SERD_NTRIPLES = 2, - - /** - NQuads - Line-based RDF quads (UTF-8). - @see <a href="https://www.w3.org/TR/n-quads/">NQuads</a> - */ - SERD_NQUADS = 3, - - /** - TriG - Terse RDF quads (UTF-8). - @see <a href="https://www.w3.org/TR/trig/">Trig</a> - */ - SERD_TRIG = 4 + SERD_TURTLE = 1, ///< Terse triples http://www.w3.org/TR/turtle + SERD_NTRIPLES = 2, ///< Line-based triples http://www.w3.org/TR/n-triples/ + SERD_NQUADS = 3, ///< Line-based quads http://www.w3.org/TR/n-quads/ + SERD_TRIG = 4 ///< Terse quads http://www.w3.org/TR/trig/ } SerdSyntax; -/** - Flags indicating inline abbreviation information for a statement. -*/ +/// Flags indicating inline abbreviation information for a statement typedef enum { - SERD_EMPTY_S = 1 << 0, /**< Empty blank node subject */ - SERD_ANON_S = 1 << 1, /**< Start of anonymous subject */ - SERD_ANON_O = 1 << 2, /**< Start of anonymous object */ - SERD_LIST_S = 1 << 3, /**< Start of list subject */ - SERD_LIST_O = 1 << 4 /**< Start of list object */ + SERD_EMPTY_S = 1 << 0, ///< Empty blank node subject + SERD_ANON_S = 1 << 1, ///< Start of anonymous subject + SERD_ANON_O = 1 << 2, ///< Start of anonymous object + SERD_LIST_S = 1 << 3, ///< Start of list subject + SERD_LIST_O = 1 << 4 ///< Start of list object } SerdStatementFlag; -/** - Bitwise OR of SerdStatementFlag values. -*/ +/// Bitwise OR of SerdStatementFlag values typedef uint32_t SerdStatementFlags; /** - Type of a syntactic RDF node. + Type of a syntactic RDF node This is more precise than the type of an abstract RDF node. An abstract node is either a resource, literal, or blank. In syntax there are two ways @@ -189,133 +124,115 @@ typedef uint32_t SerdStatementFlags; */ typedef enum { /** - The type of a nonexistent node. + The type of a nonexistent node This type is useful as a sentinel, but is never emitted by the reader. */ SERD_NOTHING = 0, /** - Literal value. + Literal value A literal optionally has either a language, or a datatype (not both). */ SERD_LITERAL = 1, /** - URI (absolute or relative). + URI (absolute or relative) Value is an unquoted URI string, which is either a relative reference with respect to the current base URI (e.g. "foo/bar"), or an absolute URI (e.g. "http://example.org/foo"). - @see <a href="http://tools.ietf.org/html/rfc3986">RFC3986</a>. + @see [RFC3986](http://tools.ietf.org/html/rfc3986) */ SERD_URI = 2, /** - CURIE, a shortened URI. + CURIE, a shortened URI Value is an unquoted CURIE string relative to the current environment, - e.g. "rdf:type". - @see <a href="http://www.w3.org/TR/curie">CURIE Syntax 1.0</a> + e.g. "rdf:type". @see [CURIE Syntax 1.0](http://www.w3.org/TR/curie) */ SERD_CURIE = 3, /** - A blank node. + A blank node - Value is a blank node ID, e.g. "id3", which is meaningful only within - this serialisation. - @see <a href="http://www.w3.org/TeamSubmission/turtle#nodeID">Turtle - <tt>nodeID</tt></a> + Value is a blank node ID without any syntactic prefix, like "id3", which + is meaningful only within this serialisation. @see [RDF 1.1 + Turtle](http://www.w3.org/TR/turtle/#grammar-production-BLANK_NODE_LABEL) */ SERD_BLANK = 4 } SerdNodeType; -/** - Flags indicating certain string properties relevant to serialisation. -*/ +/// Flags indicating certain string properties relevant to serialisation typedef enum { - SERD_HAS_NEWLINE = 1, /**< Contains line breaks ('\\n' or '\\r') */ - SERD_HAS_QUOTE = 1 << 1, /**< Contains quotes ('"') */ - SERD_HAS_DATATYPE = 1 << 2, /**< Literal node has datatype */ - SERD_HAS_LANGUAGE = 1 << 3 /**< Literal node has language */ + SERD_HAS_NEWLINE = 1, ///< Contains line breaks ('\\n' or '\\r') + SERD_HAS_QUOTE = 1 << 1, ///< Contains quotes ('"') + SERD_HAS_DATATYPE = 1 << 2, ///< Literal node has datatype + SERD_HAS_LANGUAGE = 1 << 3 ///< Literal node has language } SerdNodeFlag; -/** - Field in a statement. -*/ +/// Bitwise OR of SerdNodeFlag values +typedef uint32_t SerdNodeFlags; + +/// Field in a statement typedef enum { - SERD_SUBJECT = 0, /**< Subject */ - SERD_PREDICATE = 1, /**< Predicate ("key") */ - SERD_OBJECT = 2, /**< Object ("value") */ - SERD_GRAPH = 3 /**< Graph ("context") */ + SERD_SUBJECT = 0, ///< Subject + SERD_PREDICATE = 1, ///< Predicate ("key") + SERD_OBJECT = 2, ///< Object ("value") + SERD_GRAPH = 3 ///< Graph ("context") } SerdField; -/** - Bitwise OR of SerdNodeFlag values. -*/ -typedef uint32_t SerdNodeFlags; - -/** - A syntactic RDF node. -*/ +/// A syntactic RDF node typedef struct SerdNodeImpl SerdNode; -/** - An unterminated immutable slice of a string. -*/ +/// An unterminated immutable slice of a string typedef struct { - const char* buf; /**< Start of chunk */ - size_t len; /**< Length of chunk in bytes */ + const char* buf; ///< Start of chunk + size_t len; ///< Length of chunk in bytes } SerdStringView; -/** - A mutable buffer in memory. -*/ +/// A mutable buffer in memory typedef struct { - void* buf; /**< Buffer */ - size_t len; /**< Size of buffer in bytes */ + void* buf; ///< Buffer + size_t len; ///< Size of buffer in bytes } SerdBuffer; -/** - Log message level. -*/ +/// Log message level typedef enum { - SERD_LOG_LEVEL_INFO = 0, /**< Normal informative message */ - SERD_LOG_LEVEL_WARNING = 1, /**< Warning */ - SERD_LOG_LEVEL_ERROR = 2, /**< Error */ + SERD_LOG_LEVEL_INFO = 0, ///< Normal informative message + SERD_LOG_LEVEL_WARNING = 1, ///< Warning + SERD_LOG_LEVEL_ERROR = 2, ///< Error } SerdLogLevel; -/** - A message description. -*/ +/// A message description typedef struct { - SerdStatus status; /**< Status code */ - SerdLogLevel level; /**< Log level */ - const SerdCursor* cursor; /**< Origin of message, or NULL */ - const char* fmt; /**< Message format string (printf style) */ - va_list* args; /**< Arguments for fmt */ + SerdStatus status; ///< Status code + SerdLogLevel level; ///< Log level + const SerdCursor* cursor; ///< Origin of message, or NULL + const char* fmt; ///< Message format string (printf style) + va_list* args; ///< Arguments for fmt } SerdMessage; /** - A parsed URI. + A parsed URI This struct directly refers to slices in other strings, it does not own any memory itself. Thus, URIs can be parsed and/or resolved against a base URI in-place without allocating memory. */ typedef struct { - SerdStringView scheme; /**< Scheme */ - SerdStringView authority; /**< Authority */ - SerdStringView path_base; /**< Path prefix if relative */ - SerdStringView path; /**< Path suffix */ - SerdStringView query; /**< Query */ - SerdStringView fragment; /**< Fragment */ + SerdStringView scheme; ///< Scheme + SerdStringView authority; ///< Authority + SerdStringView path_base; ///< Path prefix if relative + SerdStringView path; ///< Path suffix + SerdStringView query; ///< Query + SerdStringView fragment; ///< Fragment } SerdURI; /** - Writer style options. + Writer style options The style of the writer output can be controlled by ORing together values from this enumeration. Note that some options are only supported @@ -323,16 +240,14 @@ typedef struct { always ASCII). */ typedef enum { - SERD_STYLE_ASCII = 1 << 0, /**< Escape all non-ASCII characters. */ + SERD_STYLE_ASCII = 1 << 0, ///< Escape all non-ASCII characters } SerdWriterFlag; -/** - Bitwise OR of SerdWriterFlag values. -*/ +/// Bitwise OR of SerdWriterFlag values typedef uint32_t SerdWriterFlags; /** - Free memory allocated by Serd. + Free memory allocated by Serd This function exists because some systems require memory allocated by a library to be freed by code in the same library. It is otherwise equivalent @@ -347,15 +262,14 @@ serd_free(void* ptr); @{ */ -/** - Return a string describing a status code. -*/ +/// Return a string describing a status code SERD_API const char* serd_strerror(SerdStatus status); /** - Measure a UTF-8 string. + Measure a UTF-8 string + @return Length of `str` in bytes. @param str A null-terminated UTF-8 string. @param flags (Output) Set to the applicable flags. @@ -365,7 +279,7 @@ size_t serd_strlen(const char* str, SerdNodeFlags* flags); /** - Parse a string to a double. + Parse a string to a double The API of this function is similar to the standard C strtod function, except this function is locale-independent and always matches the lexical @@ -384,7 +298,7 @@ serd_strtod(const char* str, size_t* end); */ /** - Return the number of bytes required to encode `size` bytes in base64. + Return the number of bytes required to encode `size` bytes in base64 @param size The number of input (binary) bytes to encode. @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045. @@ -395,7 +309,7 @@ size_t serd_base64_encoded_length(size_t size, bool wrap_lines); /** - Return the maximum number of bytes required to decode `size` bytes of base64. + Return the maximum number of bytes required to decode `size` bytes of base64 @param len The number of input (text) bytes to decode. @return The required buffer size to decode `size` bytes of base64. @@ -405,7 +319,7 @@ size_t serd_base64_decoded_size(size_t len); /** - Encode `size` bytes of `buf` into `str`, which must be large enough. + Encode `size` bytes of `buf` into `str`, which must be large enough @param str Output buffer of at least serd_base64_encoded_length(size) bytes. @param buf Input binary data. @@ -418,7 +332,7 @@ bool serd_base64_encode(char* str, const void* buf, size_t size, bool wrap_lines); /** - Decode a base64 string. + Decode a base64 string This function can be used to deserialise a blob node created with serd_new_blob(). @@ -439,7 +353,7 @@ serd_base64_decode(void* buf, size_t* size, const char* str, size_t len); */ /** - Function to detect I/O stream errors. + Function to detect I/O stream errors Identical semantics to `ferror`. @@ -448,7 +362,7 @@ serd_base64_decode(void* buf, size_t* size, const char* str, size_t len); typedef int (*SerdStreamErrorFunc)(void* stream); /** - Source function for raw string input. + Source function for raw string input Identical semantics to `fread`, but may set errno for more informative error reporting than supported by SerdStreamErrorFunc. @@ -465,7 +379,7 @@ typedef size_t (*SerdReadFunc)(void* buf, void* stream); /** - Sink function for raw string output. + Sink function for raw string output Identical semantics to `fwrite`, but may set errno for more informative error reporting than supported by SerdStreamErrorFunc. @@ -482,7 +396,7 @@ typedef size_t (*SerdWriteFunc)(const void* buf, void* stream); /** - Create a new byte sink. + Create a new byte sink @param write_func Function called with bytes to consume. @param stream Context parameter passed to `sink`. @@ -493,7 +407,7 @@ SerdByteSink* serd_byte_sink_new(SerdWriteFunc write_func, void* stream, size_t block_size); /** - Write to `sink`. + Write to `sink` Compatible with SerdWriteFunc. */ @@ -504,16 +418,12 @@ serd_byte_sink_write(const void* buf, size_t nmemb, SerdByteSink* sink); -/** - Flush any pending output in `sink` to the underlying write function. -*/ +/// Flush any pending output in `sink` to the underlying write function SERD_API void serd_byte_sink_flush(SerdByteSink* sink); -/** - Free `sink`. -*/ +/// Free `sink` SERD_API void serd_byte_sink_free(SerdByteSink* sink); @@ -525,7 +435,7 @@ serd_byte_sink_free(SerdByteSink* sink); */ /** - Get a syntax by name. + Get a syntax by name Case-insensitive, supports "Turtle", "NTriples", "NQuads", and "TriG". Zero is returned if the name is not recognized. @@ -535,7 +445,7 @@ SerdSyntax serd_syntax_by_name(const char* name); /** - Guess a syntax from a filename. + Guess a syntax from a filename This uses the file extension to guess the syntax of a file. Zero is returned if the extension is not recognized. @@ -545,7 +455,7 @@ SerdSyntax serd_guess_syntax(const char* filename); /** - Guess a syntax from a filename. + Guess a syntax from a filename This uses the file extension to guess the syntax of a file. Zero is returned if the extension is not recognized. @@ -565,49 +475,44 @@ static const SerdURI SERD_URI_NULL = { }; /** - Get the unescaped path and hostname from a file URI. + Get the unescaped path and hostname from a file URI + + The returned path and `*hostname` must be freed with serd_free(). + @param uri A file URI. @param hostname If non-NULL, set to the hostname, if present. @return The path component of the URI. - - The returned path and `*hostname` must be freed with serd_free(). */ SERD_API char* serd_file_uri_parse(const char* uri, char** hostname); -/** - Return true iff `utf8` starts with a valid URI scheme. -*/ +/// Return true iff `utf8` starts with a valid URI scheme SERD_API bool serd_uri_string_has_scheme(const char* utf8); -/** - Parse `utf8`, writing result to `out`. -*/ +/// Parse `utf8`, writing result to `out` SERD_API SerdStatus serd_uri_parse(const char* utf8, SerdURI* out); /** - Set target `t` to reference `r` resolved against `base`. + Set target `t` to reference `r` resolved against `base` - @see http://tools.ietf.org/html/rfc3986#section-5.2.2 + @see [RFC3986 5.2.2](http://tools.ietf.org/html/rfc3986#section-5.2.2) */ SERD_API void serd_uri_resolve(const SerdURI* r, const SerdURI* base, SerdURI* t); -/** - Serialise `uri` with a series of calls to `sink`. -*/ +/// Serialise `uri` with a series of calls to `sink` SERD_API size_t serd_uri_serialise(const SerdURI* uri, SerdWriteFunc sink, void* stream); /** - Serialise `uri` relative to `base` with a series of calls to `sink`. + Serialise `uri` relative to `base` with a series of calls to `sink` The `uri` is written as a relative URI iff if it a child of `base` and @c root. The optional `root` parameter must be a prefix of `base` and can be @@ -627,15 +532,13 @@ serd_uri_serialise_relative(const SerdURI* uri, @{ */ -/** - Create a new plain literal string node from `str`. -*/ +/// Create a new plain literal string node from `str` SERD_API SerdNode* serd_new_string(const char* str); /** - Create a new plain literal node from `str`. + Create a new plain literal node from `str` A plain literal has no datatype, but may have a language tag. The `lang` may be NULL, in which case this is equivalent to `serd_new_string()`. @@ -645,7 +548,7 @@ SerdNode* serd_new_plain_literal(const char* str, const char* lang); /** - Create a new typed literal node from `str`. + Create a new typed literal node from `str` A typed literal has no language tag, but may have a datatype. The `datatype` may be NULL, in which case this is equivalent to @@ -655,36 +558,28 @@ SERD_API SerdNode* serd_new_typed_literal(const char* str, const SerdNode* datatype); -/** - Create a new blank node. -*/ +/// Create a new blank node SERD_API SerdNode* serd_new_blank(const char* str); -/** - Create a new CURIE node. -*/ +/// Create a new CURIE node SERD_API SerdNode* serd_new_curie(const char* str); -/** - Return a deep copy of `node`. -*/ +/// Return a deep copy of `node` SERD_API SerdNode* serd_node_copy(const SerdNode* node); -/** - Return true iff `a` is equal to `b`. -*/ +/// Return true iff `a` is equal to `b` SERD_API bool serd_node_equals(const SerdNode* a, const SerdNode* b); /** - Compare two nodes. + Compare two nodes Returns less than, equal to, or greater than zero if `a` is less than, equal to, or greater than `b`, respectively. NULL is treated as less than any @@ -694,22 +589,18 @@ SERD_API int serd_node_compare(const SerdNode* a, const SerdNode* b); -/** - Create a new URI from a string. -*/ +/// Create a new URI from a string SERD_API SerdNode* serd_new_uri(const char* str); -/** - Create a new URI from a string, resolved against a base URI. -*/ +/// Create a new URI from a string, resolved against a base URI SERD_API SerdNode* serd_new_resolved_uri(const char* str, const SerdNode* base); /** - Resolve `node` against `base`. + Resolve `node` against `base` If `node` is not a relative URI, an equivalent new node is returned. */ @@ -718,7 +609,7 @@ SerdNode* serd_node_resolve(const SerdNode* node, const SerdNode* base); /** - Create a new file URI node from a file system path and optional hostname. + Create a new file URI node from a file system path and optional hostname Backslashes in Windows paths will be converted, and other characters will be percent encoded as necessary. @@ -731,17 +622,15 @@ SerdNode* serd_new_file_uri(const char* path, const char* hostname); /** - Create a new URI from a string, relative to a base URI. - - @param str URI string. - - @param base Base URI to make `str` relative to, if possible. - - @param root Optional root URI for resolution. + Create a new URI from a string, relative to a base URI The URI is made relative iff if it a child of `base` and `root`. The optional `root` parameter must be a prefix of `base` and can be used keep up-references ("../") within a certain namespace. + + @param str URI string. + @param base Base URI to make `str` relative to, if possible. + @param root Optional root URI for resolution. */ SERD_API SerdNode* @@ -750,7 +639,7 @@ serd_new_relative_uri(const char* str, const SerdNode* root); /** - Create a new node by serialising `d` into an xsd:decimal string. + Create a new node by serialising `d` into an xsd:decimal string The resulting node will always contain a `.', start with a digit, and end with a digit (i.e. will have a leading and/or trailing `0' if necessary). @@ -762,41 +651,33 @@ serd_new_relative_uri(const char* str, represent a double and float, respectively. @param d The value for the new node. - @param frac_digits The maximum number of digits after the decimal place. - - @param datatype Datatype of node, may be NULL in which case the node has - type xsd:decimal. + @param datatype Datatype of node, or NULL for xsd:decimal. */ SERD_API SerdNode* serd_new_decimal(double d, unsigned frac_digits, const SerdNode* datatype); /** - Create a new node by serialising `i` into an xsd:integer string. + Create a new node by serialising `i` into an xsd:integer string @param i Integer value to serialise. - - @param datatype Datatype of node, may be NULL in which case the node has - type xsd:integer. + @param datatype Datatype of node, or NULL for xsd:integer. */ SERD_API SerdNode* serd_new_integer(int64_t i, const SerdNode* datatype); /** - Create a node by serialising `buf` into an xsd:base64Binary string. + Create a node by serialising `buf` into an xsd:base64Binary string + This function can be used to make a serialisable node out of arbitrary binary data, which can be decoded using serd_base64_decode(). @param buf Raw binary input data. - @param size Size of `buf`. - @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045. - - @param datatype Datatype of node, may be NULL in which case the node has - type xsd:base64Binary. + @param datatype Datatype of node, or NULL for xsd:base64Binary. */ SERD_API SerdNode* @@ -805,54 +686,37 @@ serd_new_blob(const void* buf, bool wrap_lines, const SerdNode* datatype); -/** - Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL). -*/ +/// Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL) SERD_API SerdNodeType serd_node_get_type(const SerdNode* node); -/** - Return the string value of a node. -*/ +/// Return the string value of a node SERD_API const char* serd_node_get_string(const SerdNode* node); -/** - Return the length of the string value of a node in bytes. -*/ +/// Return the length of the string value of a node in bytes SERD_API size_t serd_node_get_length(const SerdNode* node); -/** - Return the datatype of a literal node, or NULL. -*/ +/// Return the datatype of a literal node, or NULL SERD_API const SerdNode* serd_node_get_datatype(const SerdNode* node); -/** - Return the language tag of a literal node, or NULL. -*/ +/// Return the language tag of a literal node, or NULL SERD_API const SerdNode* serd_node_get_language(const SerdNode* node); -/** - Return the flags (string properties) of a node. -*/ +/// Return the flags (string properties) of a node SERD_API SerdNodeFlags serd_node_get_flags(const SerdNode* node); -/** - Free any data owned by `node`. - - Note that if `node` is itself dynamically allocated (which is not the case - for nodes created internally by serd), it will not be freed. -*/ +/// Free `node` SERD_API void serd_node_free(SerdNode* node); @@ -864,24 +728,22 @@ serd_node_free(SerdNode* node); */ /** - Sink (callback) for log messages. + Sink (callback) for log messages @param handle Handle for user data. @param msg Message description. */ -typedef SerdStatus (*SerdMessageSink)(void* handle, - const SerdMessage* msg); +typedef SerdStatus (*SerdMessageSink)(void* handle, const SerdMessage* msg); /** - Sink (callback) for base URI changes. + Sink (callback) for base URI changes Called whenever the base URI of the serialisation changes. */ -typedef SerdStatus (*SerdBaseSink)(void* handle, - const SerdNode* uri); +typedef SerdStatus (*SerdBaseSink)(void* handle, const SerdNode* uri); /** - Sink (callback) for namespace definitions. + Sink (callback) for namespace definitions Called whenever a prefix is defined in the serialisation. */ @@ -890,7 +752,7 @@ typedef SerdStatus (*SerdPrefixSink)(void* handle, const SerdNode* uri); /** - Sink (callback) for statements. + Sink (callback) for statements Called for every RDF statement in the serialisation. */ @@ -899,14 +761,13 @@ typedef SerdStatus (*SerdStatementSink)(void* handle, const SerdStatement* statement); /** - Sink (callback) for anonymous node end markers. + Sink (callback) for anonymous node end markers This is called to indicate that the anonymous node with the given `value` will no longer be referred to by any future statements (i.e. the anonymous serialisation of the node is finished). */ -typedef SerdStatus (*SerdEndSink)(void* handle, - const SerdNode* node); +typedef SerdStatus (*SerdEndSink)(void* handle, const SerdNode* node); /** @} @@ -915,7 +776,7 @@ typedef SerdStatus (*SerdEndSink)(void* handle, */ /** - Create a new Serd World. + Create a new World It is safe to use multiple worlds in one process, though no objects can be shared between worlds. @@ -924,15 +785,13 @@ SERD_API SerdWorld* serd_world_new(void); -/** - Free `world`. -*/ +/// Free `world` SERD_API void serd_world_free(SerdWorld* world); /** - Return the nodes cache in `world`. + Return the nodes cache in `world` The returned cache is owned by the world and contains various nodes used frequently by the implementation. For convenience, it may be used to store @@ -943,7 +802,7 @@ SerdNodes* serd_world_get_nodes(SerdWorld* world); /** - Return a unique blank node. + Return a unique blank node The returned node is valid only until the next time serd_world_get_blank() is called or the world is destroyed. @@ -953,7 +812,7 @@ const SerdNode* serd_world_get_blank(SerdWorld* world); /** - Set a function to be called with log messages (typically errors). + Set a function to be called with log messages (typically errors) The `msg_sink` will be called with `handle` as its first argument. If no sink is set, messages are printed to stderr. @@ -970,58 +829,42 @@ serd_world_set_message_sink(SerdWorld* world, @{ */ -/** - Create a new environment. -*/ +/// Create a new environment SERD_API SerdEnv* serd_env_new(const SerdNode* base_uri); -/** - Copy an environment. -*/ +/// Copy an environment SERD_API SerdEnv* serd_env_copy(const SerdEnv* env); -/** - Return true iff `a` is equal to `b`. -*/ +/// Return true iff `a` is equal to `b` SERD_API bool serd_env_equals(const SerdEnv* a, const SerdEnv* b); -/** - Free `ns`. -*/ +/// Free `env` SERD_API void serd_env_free(SerdEnv* env); -/** - Get the current base URI. -*/ +/// Get the current base URI SERD_API const SerdNode* serd_env_get_base_uri(const SerdEnv* env); -/** - Set the current base URI. -*/ +/// Set the current base URI SERD_API SerdStatus serd_env_set_base_uri(SerdEnv* env, const SerdNode* uri); -/** - Set a namespace prefix. -*/ +/// Set a namespace prefix SERD_API SerdStatus serd_env_set_prefix(SerdEnv* env, const SerdNode* name, const SerdNode* uri); -/** - Set a namespace prefix. -*/ +/// Set a namespace prefix SERD_API SerdStatus serd_env_set_prefix_from_strings(SerdEnv* env, @@ -1029,7 +872,7 @@ serd_env_set_prefix_from_strings(SerdEnv* env, const char* uri); /** - Qualify `uri` into a CURIE if possible. + Qualify `uri` into a CURIE if possible Returns null if `node` can not be qualified. */ @@ -1038,7 +881,9 @@ SerdNode* serd_env_qualify(const SerdEnv* env, const SerdNode* uri); /** - Expand `node`, which must be a CURIE or URI, to a full URI. + Expand `node`, transforming CURIEs into URIs + + If `node` is a literal, its datatype is expanded if necessary. Returns null if `node` can not be expanded. */ @@ -1046,9 +891,7 @@ SERD_API SerdNode* serd_env_expand(const SerdEnv* env, const SerdNode* node); -/** - Write all prefixes in `env` to `sink`. -*/ +/// Write all prefixes in `env` to `sink` SERD_API void serd_env_write_prefixes(const SerdEnv* env, const SerdSink* sink); @@ -1060,7 +903,7 @@ serd_env_write_prefixes(const SerdEnv* env, const SerdSink* sink); */ /** - Create a new sink. + Create a new sink Initially, the sink has no set functions and will do nothing. Use the serd_sink_set_*_func functions to set handlers for various events. @@ -1072,84 +915,56 @@ SERD_API SerdSink* serd_sink_new(void* handle, SerdEnv* env); -/** - Free `sink`. -*/ +/// Free `sink` SERD_API void serd_sink_free(SerdSink* sink); -/** - Return the env used by `writer`. -*/ +/// Return the env used by `sink` SERD_API const SerdEnv* serd_sink_get_env(const SerdSink* sink); -/** - Set a function to be called when the base URI changes. -*/ +/// Set a function to be called when the base URI changes SERD_API SerdStatus serd_sink_set_base_func(SerdSink* sink, SerdBaseSink base_func); -/** - Set a function to be called when a namespace prefix is defined. -*/ +/// Set a function to be called when a namespace prefix is defined SERD_API SerdStatus serd_sink_set_prefix_func(SerdSink* sink, SerdPrefixSink prefix_func); -/** - Set a function to be called when a statement is emitted. -*/ +/// Set a function to be called when a statement is emitted SERD_API SerdStatus serd_sink_set_statement_func(SerdSink* sink, SerdStatementSink statement_func); -/** - Set a function to be called when an anonymous node ends. -*/ +/// Set a function to be called when an anonymous node ends SERD_API SerdStatus serd_sink_set_end_func(SerdSink* sink, SerdEndSink end_func); -/** - Set the base URI. - - Simple wrapper for the `SerdBaseSink` of `sink`. -*/ +/// Set the base URI SERD_API SerdStatus serd_sink_write_base(const SerdSink* sink, const SerdNode* uri); -/** - Set a namespace prefix. - - Simple wrapper for the `SerdPrefixSink` of `sink`. -*/ +/// Set a namespace prefix SERD_API SerdStatus serd_sink_write_prefix(const SerdSink* sink, const SerdNode* name, const SerdNode* uri); -/** - Write a statement. - - Simple wrapper for the `SerdStatementSink` of `sink`. -*/ +/// Write a statement SERD_API SerdStatus serd_sink_write_statement(const SerdSink* sink, SerdStatementFlags flags, const SerdStatement* statement); -/** - Write a statement from individual nodes. - - Simple wrapper for the `SerdStatementSink` of `sink`. -*/ +/// Write a statement from individual nodes SERD_API SerdStatus serd_sink_write(const SerdSink* sink, @@ -1159,11 +974,7 @@ serd_sink_write(const SerdSink* sink, const SerdNode* object, const SerdNode* graph); -/** - Mark the end of an anonymous node. - - Simple wrapper for the `SerdEndSink` of `sink`. -*/ +/// Mark the end of an anonymous node SERD_API SerdStatus serd_sink_write_end(const SerdSink* sink, const SerdNode* node); @@ -1174,9 +985,7 @@ serd_sink_write_end(const SerdSink* sink, const SerdNode* node); @{ */ -/** - Create a new RDF reader. -*/ +/// Create a new RDF reader SERD_API SerdReader* serd_reader_new(SerdWorld* world, @@ -1185,7 +994,7 @@ serd_reader_new(SerdWorld* world, size_t stack_size); /** - Enable or disable strict parsing. + Enable or disable strict parsing The reader is non-strict (lax) by default, which will tolerate URIs with invalid characters. Setting strict will fail when parsing such files. An @@ -1196,7 +1005,7 @@ void serd_reader_set_strict(SerdReader* reader, bool strict); /** - Set a prefix to be added to all blank node identifiers. + Set a prefix to be added to all blank node identifiers This is useful when multiple files are to be parsed into the same output (e.g. a store, or other files). Since Serd preserves blank node IDs, this @@ -1206,18 +1015,15 @@ serd_reader_set_strict(SerdReader* reader, bool strict); */ SERD_API void -serd_reader_add_blank_prefix(SerdReader* reader, - const char* prefix); +serd_reader_add_blank_prefix(SerdReader* reader, const char* prefix); -/** - Prepare to read from the file at a local file `uri`. -*/ +/// Prepare to read from the file at a local file `uri` SERD_API SerdStatus serd_reader_start_file(SerdReader* reader, const char* uri, bool bulk); /** - Prepare to read from a stream. + Prepare to read from a stream The `read_func` is guaranteed to only be called for `page_size` elements with size 1 (i.e. `page_size` bytes). @@ -1231,9 +1037,7 @@ serd_reader_start_stream(SerdReader* reader, const SerdNode* name, size_t page_size); -/** - Prepare to read from a string. -*/ +/// Prepare to read from a string SERD_API SerdStatus serd_reader_start_string(SerdReader* reader, @@ -1241,7 +1045,7 @@ serd_reader_start_string(SerdReader* reader, const SerdNode* name); /** - Read a single "chunk" of data during an incremental read. + Read a single "chunk" of data during an incremental read This function will read a single top level description, and return. This may be a directive, statement, or several statements; essentially it reads @@ -1253,7 +1057,7 @@ SerdStatus serd_reader_read_chunk(SerdReader* reader); /** - Read a complete document from the source. + Read a complete document from the source This function will continue pulling from the source until a complete document has been read. Note that this may block when used with streams, @@ -1264,7 +1068,7 @@ SerdStatus serd_reader_read_document(SerdReader* reader); /** - Finish reading from the source. + Finish reading from the source This will close the open file, if applicable, and ensure the reader has processed all input. @@ -1274,7 +1078,7 @@ SerdStatus serd_reader_finish(SerdReader* reader); /** - Free `reader`. + Free `reader` The reader will be finished via `serd_reader_finish()` if necessary. */ @@ -1288,9 +1092,7 @@ serd_reader_free(SerdReader* reader); @{ */ -/** - Create a new RDF writer. -*/ +/// Create a new RDF writer SERD_API SerdWriter* serd_writer_new(SerdWorld* world, @@ -1300,29 +1102,23 @@ serd_writer_new(SerdWorld* world, SerdWriteFunc write_func, void* stream); -/** - Free `writer`. -*/ +/// Free `writer` SERD_API void serd_writer_free(SerdWriter* writer); -/** - Return a sink interface that emits statements via `writer`. -*/ +/// Return a sink interface that emits statements via `writer` SERD_API const SerdSink* serd_writer_get_sink(SerdWriter* writer); -/** - Return the env used by `writer`. -*/ +/// Return the env used by `writer` SERD_API SerdEnv* serd_writer_get_env(SerdWriter* writer); /** - A convenience sink function for writing to a string. + A convenience sink function for writing to a string This function can be used as a SerdSink to write to a SerdBuffer which is resized as necessary with realloc(). The `stream` parameter must point to @@ -1334,35 +1130,31 @@ size_t serd_buffer_sink(const void* buf, size_t size, size_t nmemb, void* stream); /** - Finish a serialisation to a buffer with serd_buffer_sink(). + Finish a serialisation to a buffer with serd_buffer_sink() - The returned string is the result of the serialisation, which is NULL + The returned string is the result of the serialisation, which is null terminated (by this function) and owned by the caller. */ SERD_API char* serd_buffer_sink_finish(SerdBuffer* stream); -/** - Set a prefix to be removed from matching blank node identifiers. -*/ +/// Set a prefix to be removed from matching blank node identifiers SERD_API void -serd_writer_chop_blank_prefix(SerdWriter* writer, - const char* prefix); +serd_writer_chop_blank_prefix(SerdWriter* writer, const char* prefix); /** - Set the current output base URI (and emit directive if applicable). + Set the current output base URI (and emit directive if applicable) Note this function can be safely casted to SerdBaseSink. */ SERD_API SerdStatus -serd_writer_set_base_uri(SerdWriter* writer, - const SerdNode* uri); +serd_writer_set_base_uri(SerdWriter* writer, const SerdNode* uri); /** - Set the current root URI. + Set the current root URI The root URI should be a prefix of the base URI. The path of the root URI is the highest path any relative up-reference can refer to. For example, @@ -1373,12 +1165,9 @@ serd_writer_set_base_uri(SerdWriter* writer, */ SERD_API SerdStatus -serd_writer_set_root_uri(SerdWriter* writer, - const SerdNode* uri); +serd_writer_set_root_uri(SerdWriter* writer, const SerdNode* uri); -/** - Finish a write. -*/ +/// Finish a write SERD_API SerdStatus serd_writer_finish(SerdWriter* writer); @@ -1389,15 +1178,13 @@ serd_writer_finish(SerdWriter* writer); @{ */ -/** - Create a new node set. -*/ +/// Create a new node set SERD_API SerdNodes* serd_nodes_new(void); /** - Free `nodes` and all nodes that are stored in it. + Free `nodes` and all nodes that are stored in it Note that this invalidates any pointers previously returned from `serd_nodes_intern()` or `serd_nodes_manage()` calls on `nodes`. @@ -1407,7 +1194,7 @@ void serd_nodes_free(SerdNodes* nodes); /** - Intern `node`. + Intern `node` Multiple calls with equivalent nodes will return the same pointer. @@ -1418,7 +1205,7 @@ const SerdNode* serd_nodes_intern(SerdNodes* nodes, const SerdNode* node); /** - Manage `node`. + Manage `node` Like `serd_nodes_intern`, but takes ownership of `node`, freeing it and returning a previously interned/managed equivalent node if necessary. @@ -1430,7 +1217,7 @@ const SerdNode* serd_nodes_manage(SerdNodes* nodes, SerdNode* node); /** - Dereference `node`. + Dereference `node` Decrements the reference count of `node`, and frees the internally stored equivalent node if this was the last reference. Does nothing if no node @@ -1446,44 +1233,32 @@ serd_nodes_deref(SerdNodes* nodes, const SerdNode* node); @{ */ -/** - Return the given node in `statement`. -*/ +/// Return the given node in `statement` SERD_API const SerdNode* serd_statement_get_node(const SerdStatement* statement, SerdField field); -/** - Return the subject in `statement`. -*/ +/// Return the subject in `statement` SERD_API const SerdNode* serd_statement_get_subject(const SerdStatement* statement); -/** - Return the predicate in `statement`. -*/ +/// Return the predicate in `statement` SERD_API const SerdNode* serd_statement_get_predicate(const SerdStatement* statement); -/** - Return the object in `statement`. -*/ +/// Return the object in `statement` SERD_API const SerdNode* serd_statement_get_object(const SerdStatement* statement); -/** - Return the graph in `statement`. -*/ +/// Return the graph in `statement` SERD_API const SerdNode* serd_statement_get_graph(const SerdStatement* statement); -/** - Return the source location where `statement` originated, or NULL. -*/ +/// Return the source location where `statement` originated, or NULL SERD_API const SerdCursor* serd_statement_get_cursor(const SerdStatement* statement); @@ -1529,7 +1304,7 @@ bool serd_cursor_equals(const SerdCursor* lhs, const SerdCursor* rhs); /** - Return the document name. + Return the document name This is typically a file URI, but may be a descriptive string node for statements that originate from streams. @@ -1538,16 +1313,12 @@ SERD_API const SerdNode* serd_cursor_get_name(const SerdCursor* cursor); -/** - Return the one-relative line number in the document. -*/ +/// Return the one-relative line number in the document SERD_API unsigned serd_cursor_get_line(const SerdCursor* cursor); -/** - Return the zero-relative column number in the line. -*/ +/// Return the zero-relative column number in the line SERD_API unsigned serd_cursor_get_column(const SerdCursor* cursor); |