diff options
| -rw-r--r-- | include/serd/serd.h | 337 |
1 files changed, 115 insertions, 222 deletions
diff --git a/include/serd/serd.h b/include/serd/serd.h index 6e9b19dd..8510e615 100644 --- a/include/serd/serd.h +++ b/include/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 @@ -80,85 +78,46 @@ extern "C" { */ 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; -/** - 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_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) } 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 = 1u << 1u, /**< Empty blank node subject */ - SERD_EMPTY_O = 1u << 2u, /**< Empty blank node object */ - SERD_ANON_S_BEGIN = 1u << 3u, /**< Start of anonymous subject */ - SERD_ANON_O_BEGIN = 1u << 4u, /**< Start of anonymous object */ - SERD_ANON_CONT = 1u << 5u, /**< Continuation of anonymous node */ - SERD_LIST_S_BEGIN = 1u << 6u, /**< Start of list subject */ - SERD_LIST_O_BEGIN = 1u << 7u, /**< Start of list object */ - SERD_LIST_CONT = 1u << 8u /**< Continuation of list */ + SERD_EMPTY_S = 1u << 1u, ///< Empty blank node subject + SERD_EMPTY_O = 1u << 2u, ///< Empty blank node object + SERD_ANON_S_BEGIN = 1u << 3u, ///< Start of anonymous subject + SERD_ANON_O_BEGIN = 1u << 4u, ///< Start of anonymous object + SERD_ANON_CONT = 1u << 5u, ///< Continuation of anonymous node + SERD_LIST_S_BEGIN = 1u << 6u, ///< Start of list subject + SERD_LIST_O_BEGIN = 1u << 7u, ///< Start of list object + SERD_LIST_CONT = 1u << 8u ///< Continuation of list } SerdStatementFlag; -/** - Bitwise OR of SerdStatementFlag values. -*/ +/// Bitwise OR of SerdStatementFlag values typedef uint32_t SerdStatementFlags; /** @@ -191,7 +150,7 @@ typedef enum { 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, @@ -199,80 +158,68 @@ typedef enum { 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. - 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 } SerdType; -/** - Flags indicating certain string properties relevant to serialisation. -*/ +/// Flags indicating certain string properties relevant to serialisation typedef enum { - SERD_HAS_NEWLINE = 1u << 0u, /**< Contains line breaks ('\\n' or '\\r') */ - SERD_HAS_QUOTE = 1u << 1u /**< Contains quotes ('"') */ + SERD_HAS_NEWLINE = 1u << 0u, ///< Contains line breaks ('\\n' or '\\r') + SERD_HAS_QUOTE = 1u << 1u ///< Contains quotes ('"') } SerdNodeFlag; -/** - Bitwise OR of SerdNodeFlag values. -*/ +/// Bitwise OR of SerdNodeFlag values typedef uint32_t SerdNodeFlags; -/** - A syntactic RDF node. -*/ +/// A syntactic RDF node typedef struct { - const uint8_t* SERD_NULLABLE buf; /**< Value string */ - size_t n_bytes; /**< Size in bytes (excluding null) */ - size_t n_chars; /**< String length (excluding null) */ - SerdNodeFlags flags; /**< Node flags (string properties) */ - SerdType type; /**< Node type */ + const uint8_t* SERD_NULLABLE buf; ///< Value string + size_t n_bytes; ///< Size in bytes (excluding null) + size_t n_chars; ///< String length (excluding null) + SerdNodeFlags flags; ///< Node flags (string properties) + SerdType type; ///< Node type } SerdNode; -/** - An unterminated string fragment. -*/ +/// An unterminated string fragment typedef struct { - const uint8_t* SERD_NULLABLE buf; /**< Start of chunk */ - size_t len; /**< Length of chunk in bytes */ + const uint8_t* SERD_NULLABLE buf; ///< Start of chunk + size_t len; ///< Length of chunk in bytes } SerdChunk; -/** - An error description. -*/ +/// An error description typedef struct { - SerdStatus status; /**< Error code */ - const uint8_t* SERD_NULLABLE filename; /**< File with error */ - unsigned line; /**< Line in file with error or 0 */ - unsigned col; /**< Column in file with error */ - const char* SERD_NONNULL fmt; /**< Printf-style format string */ - va_list* SERD_NONNULL args; /**< Arguments for fmt */ + SerdStatus status; ///< Error code + const uint8_t* SERD_NULLABLE filename; ///< File with error + unsigned line; ///< Line in file with error or 0 + unsigned col; ///< Column in file with error + const char* SERD_NONNULL fmt; ///< Printf-style format string + va_list* SERD_NONNULL args; ///< Arguments for fmt } SerdError; /** - A parsed URI. + A parsed URI This struct directly refers to chunks 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 { - SerdChunk scheme; /**< Scheme */ - SerdChunk authority; /**< Authority */ - SerdChunk path_base; /**< Path prefix if relative */ - SerdChunk path; /**< Path suffix */ - SerdChunk query; /**< Query */ - SerdChunk fragment; /**< Fragment */ + SerdChunk scheme; ///< Scheme + SerdChunk authority; ///< Authority + SerdChunk path_base; ///< Path prefix if relative + SerdChunk path; ///< Path suffix + SerdChunk query; ///< Query + SerdChunk fragment; ///< Fragment } SerdURI; /** @@ -284,15 +231,15 @@ typedef struct { always ASCII). */ typedef enum { - SERD_STYLE_ABBREVIATED = 1u << 0u, /**< Abbreviate triples when possible. */ - SERD_STYLE_ASCII = 1u << 1u, /**< Escape all non-ASCII characters. */ - SERD_STYLE_RESOLVED = 1u << 2u, /**< Resolve URIs against base URI. */ - SERD_STYLE_CURIED = 1u << 3u, /**< Shorten URIs into CURIEs. */ - SERD_STYLE_BULK = 1u << 4u, /**< Write output in pages. */ + SERD_STYLE_ABBREVIATED = 1u << 0u, ///< Abbreviate triples when possible. + SERD_STYLE_ASCII = 1u << 1u, ///< Escape all non-ASCII characters. + SERD_STYLE_RESOLVED = 1u << 2u, ///< Resolve URIs against base URI. + SERD_STYLE_CURIED = 1u << 3u, ///< Shorten URIs into CURIEs. + SERD_STYLE_BULK = 1u << 4u, ///< Write output in pages. } SerdStyle; /** - 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 @@ -307,15 +254,14 @@ serd_free(void* SERD_NULLABLE ptr); @{ */ -/** - Return a string describing a status code. -*/ +/// Return a string describing a status code SERD_CONST_API const uint8_t* SERD_NONNULL serd_strerror(SerdStatus status); /** Measure a UTF-8 string. + @return Length of `str` in characters (except NULL). @param str A null-terminated UTF-8 string. @param n_bytes (Output) Set to the size of `str` in bytes (except NULL). @@ -341,6 +287,7 @@ serd_strtod(const char* SERD_NONNULL str, /** Decode a base64 string. + This function can be used to deserialise a blob node created with serd_node_new_blob(). @@ -387,9 +334,7 @@ typedef size_t (*SerdSource)(void* SERD_NONNULL buf, size_t nmemb, void* SERD_NONNULL stream); -/** - Sink function for raw string output. -*/ +/// Sink function for raw string output typedef size_t (*SerdSink)(const void* SERD_NONNULL buf, size_t len, void* SERD_NONNULL stream); @@ -417,27 +362,24 @@ serd_uri_to_path(const uint8_t* SERD_NONNULL 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 uint8_t* SERD_NULLABLE serd_file_uri_parse(const uint8_t* SERD_NONNULL uri, uint8_t* SERD_NONNULL* SERD_NULLABLE hostname); -/** - Return true iff `utf8` starts with a valid URI scheme. -*/ +/// Return true iff `utf8` starts with a valid URI scheme SERD_PURE_API bool serd_uri_string_has_scheme(const uint8_t* SERD_NULLABLE utf8); -/** - Parse `utf8`, writing result to `out`. -*/ +/// Parse `utf8`, writing result to `out` SERD_API SerdStatus serd_uri_parse(const uint8_t* SERD_NONNULL utf8, SerdURI* SERD_NONNULL out); @@ -445,7 +387,7 @@ serd_uri_parse(const uint8_t* SERD_NONNULL utf8, SerdURI* SERD_NONNULL out); /** 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 @@ -453,9 +395,7 @@ serd_uri_resolve(const SerdURI* SERD_NONNULL r, const SerdURI* SERD_NONNULL base, SerdURI* SERD_NONNULL 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* SERD_NONNULL uri, @@ -463,10 +403,10 @@ serd_uri_serialise(const SerdURI* SERD_NONNULL uri, void* SERD_NONNULL 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 + The `uri` is written as a relative URI 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. */ SERD_API @@ -506,18 +446,14 @@ serd_node_from_substring(SerdType type, const uint8_t* SERD_NULLABLE str, size_t len); -/** - Simple wrapper for serd_node_new_uri() to resolve a URI node. -*/ +/// Simple wrapper for serd_node_new_uri() to resolve a URI node SERD_API SerdNode serd_node_new_uri_from_node(const SerdNode* SERD_NONNULL uri_node, const SerdURI* SERD_NULLABLE base, SerdURI* SERD_NULLABLE out); -/** - Simple wrapper for serd_node_new_uri() to resolve a URI string. -*/ +/// Simple wrapper for serd_node_new_uri() to resolve a URI string SERD_API SerdNode serd_node_new_uri_from_string(const uint8_t* SERD_NULLABLE str, @@ -577,7 +513,7 @@ serd_node_new_relative_uri(const SerdURI* SERD_NONNULL uri, SerdURI* SERD_NULLABLE out); /** - 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). @@ -595,15 +531,14 @@ SERD_API SerdNode serd_node_new_decimal(double d, unsigned frac_digits); -/** - Create a new node by serialising `i` into an xsd:integer string. -*/ +/// Create a new node by serialising `i` into an xsd:integer string SERD_API SerdNode serd_node_new_integer(int64_t i); /** - 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(). @@ -624,9 +559,7 @@ SERD_API SerdNode serd_node_copy(const SerdNode* SERD_NULLABLE node); -/** - Return true iff `a` is equal to `b`. -*/ +/// Return true iff `a` is equal to `b` SERD_PURE_API bool serd_node_equals(const SerdNode* SERD_NONNULL a, @@ -658,7 +591,7 @@ typedef SerdStatus (*SerdErrorSink)(void* SERD_NULLABLE handle, const SerdError* SERD_NONNULL error); /** - Sink (callback) for base URI changes. + Sink (callback) for base URI changes Called whenever the base URI of the serialisation changes. */ @@ -666,7 +599,7 @@ typedef SerdStatus (*SerdBaseSink)(void* SERD_NULLABLE handle, const SerdNode* SERD_NONNULL uri); /** - Sink (callback) for namespace definitions. + Sink (callback) for namespace definitions Called whenever a prefix is defined in the serialisation. */ @@ -675,7 +608,7 @@ typedef SerdStatus (*SerdPrefixSink)(void* SERD_NULLABLE handle, const SerdNode* SERD_NONNULL uri); /** - Sink (callback) for statements. + Sink (callback) for statements Called for every RDF statement in the serialisation. */ @@ -690,7 +623,7 @@ typedef SerdStatus (*SerdStatementSink)( const SerdNode* SERD_NULLABLE object_lang); /** - 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 @@ -705,57 +638,43 @@ typedef SerdStatus (*SerdEndSink)(void* SERD_NULLABLE handle, @{ */ -/** - Create a new environment. -*/ +/// Create a new environment SERD_API SerdEnv* SERD_ALLOCATED serd_env_new(const SerdNode* SERD_NULLABLE base_uri); -/** - Free `ns`. -*/ +/// Free `env` SERD_API void serd_env_free(SerdEnv* SERD_NULLABLE env); -/** - Get the current base URI. -*/ +/// Get the current base URI SERD_API const SerdNode* SERD_NULLABLE serd_env_get_base_uri(const SerdEnv* SERD_NONNULL env, SerdURI* SERD_NULLABLE out); -/** - Set the current base URI. -*/ +/// Set the current base URI SERD_API SerdStatus serd_env_set_base_uri(SerdEnv* SERD_NONNULL env, const SerdNode* SERD_NULLABLE uri); -/** - Set a namespace prefix. -*/ +/// Set a namespace prefix SERD_API SerdStatus serd_env_set_prefix(SerdEnv* SERD_NONNULL env, const SerdNode* SERD_NONNULL name, const SerdNode* SERD_NONNULL uri); -/** - Set a namespace prefix. -*/ +/// Set a namespace prefix SERD_API SerdStatus serd_env_set_prefix_from_strings(SerdEnv* SERD_NONNULL env, const uint8_t* SERD_NONNULL name, const uint8_t* SERD_NONNULL uri); -/** - Qualify `uri` into a CURIE if possible. -*/ +/// Qualify `uri` into a CURIE if possible SERD_API bool serd_env_qualify(const SerdEnv* SERD_NONNULL env, @@ -801,9 +720,7 @@ serd_env_foreach(const SerdEnv* SERD_NONNULL env, @{ */ -/** - Create a new RDF reader. -*/ +/// Create a new RDF reader SERD_API SerdReader* SERD_ALLOCATED serd_reader_new(SerdSyntax syntax, @@ -815,7 +732,7 @@ serd_reader_new(SerdSyntax syntax, SerdEndSink SERD_NULLABLE end_sink); /** - 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 @@ -837,9 +754,7 @@ serd_reader_set_error_sink(SerdReader* SERD_NONNULL reader, SerdErrorSink SERD_NULLABLE error_sink, void* SERD_NULLABLE error_handle); -/** - Return the `handle` passed to serd_reader_new(). -*/ +/// Return the `handle` passed to serd_reader_new() SERD_PURE_API void* SERD_NULLABLE serd_reader_get_handle(const SerdReader* SERD_NONNULL reader); @@ -870,9 +785,7 @@ void serd_reader_set_default_graph(SerdReader* SERD_NONNULL reader, const SerdNode* SERD_NULLABLE graph); -/** - Read a file at a given `uri`. -*/ +/// Read a file at a given `uri` SERD_API SerdStatus serd_reader_read_file(SerdReader* SERD_NONNULL reader, @@ -909,7 +822,7 @@ serd_reader_start_source_stream(SerdReader* SERD_NONNULL reader, size_t page_size); /** - 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 @@ -920,25 +833,19 @@ SERD_API SerdStatus serd_reader_read_chunk(SerdReader* SERD_NONNULL reader); -/** - Finish an incremental read from a file handle. -*/ +/// Finish an incremental read from a file handle SERD_API SerdStatus serd_reader_end_stream(SerdReader* SERD_NONNULL reader); -/** - Read `file`. -*/ +/// Read `file` SERD_API SerdStatus serd_reader_read_file_handle(SerdReader* SERD_NONNULL reader, FILE* SERD_NONNULL file, const uint8_t* SERD_NULLABLE name); -/** - Read a user-specified byte source. -*/ +/// Read a user-specified byte source SERD_API SerdStatus serd_reader_read_source(SerdReader* SERD_NONNULL reader, @@ -948,17 +855,13 @@ serd_reader_read_source(SerdReader* SERD_NONNULL reader, const uint8_t* SERD_NULLABLE name, size_t page_size); -/** - Read `utf8`. -*/ +/// Read `utf8` SERD_API SerdStatus serd_reader_read_string(SerdReader* SERD_NONNULL reader, const uint8_t* SERD_NONNULL utf8); -/** - Free `reader`. -*/ +/// Free `reader` SERD_API void serd_reader_free(SerdReader* SERD_NULLABLE reader); @@ -969,9 +872,7 @@ serd_reader_free(SerdReader* SERD_NULLABLE reader); @{ */ -/** - Create a new RDF writer. -*/ +/// Create a new RDF writer SERD_API SerdWriter* SERD_ALLOCATED serd_writer_new(SerdSyntax syntax, @@ -981,16 +882,12 @@ serd_writer_new(SerdSyntax syntax, SerdSink SERD_NONNULL ssink, void* SERD_NULLABLE stream); -/** - Free `writer`. -*/ +/// Free `writer` SERD_API void serd_writer_free(SerdWriter* SERD_NULLABLE writer); -/** - Return the env used by `writer`. -*/ +/// Return the env used by `writer` SERD_PURE_API SerdEnv* SERD_NULLABLE serd_writer_get_env(SerdWriter* SERD_NONNULL writer); @@ -1008,7 +905,7 @@ serd_file_sink(const void* SERD_NONNULL buf, void* SERD_NONNULL stream); /** - 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 SerdChunk which is resized as necessary with realloc(). The `stream` parameter must point to @@ -1024,7 +921,7 @@ serd_chunk_sink(const void* SERD_NONNULL buf, /** Finish a serialisation to a chunk with serd_chunk_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 @@ -1043,9 +940,7 @@ serd_writer_set_error_sink(SerdWriter* SERD_NONNULL writer, SerdErrorSink SERD_NONNULL error_sink, void* SERD_NULLABLE error_handle); -/** - 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* SERD_NONNULL writer, @@ -1113,9 +1008,7 @@ SerdStatus serd_writer_end_anon(SerdWriter* SERD_NONNULL writer, const SerdNode* SERD_NULLABLE node); -/** - Finish a write. -*/ +/// Finish a write SERD_API SerdStatus serd_writer_finish(SerdWriter* SERD_NONNULL writer); |