/* Copyright 2011-2021 David Robillard Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ /// @file serd.h API for Serd, a lightweight RDF syntax library #ifndef SERD_SERD_H #define SERD_SERD_H #include #include #include #include // IWYU pragma: keep #if defined(_WIN32) && !defined(SERD_STATIC) && defined(SERD_INTERNAL) # define SERD_API __declspec(dllexport) #elif defined(_WIN32) && !defined(SERD_STATIC) # define SERD_API __declspec(dllimport) #elif defined(__GNUC__) # define SERD_API __attribute__((visibility("default"))) #else # define SERD_API #endif #ifdef __GNUC__ # define SERD_PURE_FUNC __attribute__((pure)) # define SERD_CONST_FUNC __attribute__((const)) # define SERD_MALLOC_FUNC __attribute__((malloc)) #else # define SERD_PURE_FUNC # define SERD_CONST_FUNC # define SERD_MALLOC_FUNC #endif #if defined(__clang__) && __clang_major__ >= 7 # define SERD_NONNULL _Nonnull # define SERD_NULLABLE _Nullable # define SERD_ALLOCATED _Null_unspecified #else # define SERD_NONNULL # define SERD_NULLABLE # define SERD_ALLOCATED #endif #define SERD_PURE_API \ SERD_API \ SERD_PURE_FUNC #define SERD_CONST_API \ SERD_API \ SERD_CONST_FUNC #define SERD_MALLOC_API \ SERD_API \ SERD_MALLOC_FUNC #ifdef __cplusplus extern "C" { # if defined(__GNUC__) # pragma GCC diagnostic push # pragma GCC diagnostic ignored "-Wzero-as-null-pointer-constant" # endif #endif /** @defgroup serd Serd C API @{ */ /// 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_DATATYPE = 1u << 2u, ///< Literal node has datatype SERD_HAS_LANGUAGE = 1u << 3u ///< Literal node has language } SerdNodeFlag; /// Bitwise OR of SerdNodeFlag values typedef uint32_t SerdNodeFlags; /** @defgroup serd_string_view String View @{ */ /** An immutable slice of a string. This type is used for many string parameters, to allow referring to slices of strings in-place and to avoid redundant string measurement. */ typedef struct { const char* SERD_NULLABLE buf; ///< Start of string size_t len; ///< Length of string in bytes } SerdStringView; #ifdef __cplusplus # define SERD_EMPTY_STRING() \ SerdStringView { "", 0u } # define SERD_STRING(str) \ SerdStringView { str, strlen(str) } # define SERD_OPTIONAL_STRING(str) \ SerdStringView { (str) ? (str) : "", (str) ? strlen(str) : 0u } # define SERD_SUBSTRING(str, len) \ SerdStringView { (str), (len) } #else /// Return a view of an empty string # define SERD_EMPTY_STRING() \ (SerdStringView) { "", 0u } /** Return a view of an entire string by measuring it. This makes a view of the given string by measuring it with `strlen`. @param str Non-null pointer to the start of a null-terminated C string. */ # define SERD_STRING(str) \ (SerdStringView) { (str), strlen(str) } /** Return a view of an entire string by measuring it, or the empty string. This is the same as SERD_STRING(), but tolerates null, in which case an empty string view is returned. @param str Pointer to the start of a null-terminated C string, or null. */ # define SERD_OPTIONAL_STRING(str) \ (SerdStringView) { (str) ? (str) : "", (str) ? strlen(str) : 0u } /** Return a view of a substring, or a premeasured string. This makes either a view of a slice of a string (which may not be null terminated), or a view of a string that has already been measured. This is faster than SERD_STRING() for dynamic strings since it does not call `strlen`, so should be used when the length of the string is already known. @param str Pointer to the start of the substring. @param len Length of the substring in bytes, not including the trailing null terminator if present. */ # define SERD_SUBSTRING(str, len) \ (SerdStringView) { (str), (len) } #endif /** @} */ /// A mutable buffer in memory typedef struct { void* SERD_NULLABLE buf; ///< Buffer size_t len; ///< Size of buffer in bytes } SerdBuffer; /** 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 to the standard C free() function. */ SERD_API void serd_free(void* SERD_NULLABLE ptr); /** @defgroup serd_status Status Codes @{ */ /// 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 or unknown namespace prefix SERD_ERR_INTERNAL, ///< Unexpected internal error SERD_ERR_OVERFLOW, ///< Stack overflow } SerdStatus; /** A status code with an associated byte count. This is returned by functions which write to a buffer to inform the caller about the size written, or in case of overflow, size required. */ typedef struct { /** Status code. This reports the status of the operation as usual, and also dictates the meaning of `count`. */ SerdStatus status; /** Number of bytes written or required. On success, this is the total number of bytes written. On #SERD_ERR_OVERFLOW, this is the number of bytes of output space that are required for success. */ size_t count; } SerdWriteResult; /// Return a string describing a status code SERD_CONST_API const char* SERD_NONNULL serd_strerror(SerdStatus status); /** @} @defgroup serd_string String Utilities @{ */ /** 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. */ SERD_API size_t serd_strlen(const char* SERD_NONNULL str, SerdNodeFlags* SERD_NULLABLE flags); /** @} @defgroup serd_streams Byte Streams @{ */ /** Function to detect I/O stream errors. Identical semantics to `ferror`. @return Non-zero if `stream` has encountered an error. */ typedef int (*SerdStreamErrorFunc)(void* SERD_NONNULL stream); /** Source function for raw string input. Identical semantics to `fread`, but may set errno for more informative error reporting than supported by SerdStreamErrorFunc. @param buf Output buffer. @param size Size of a single element of data in bytes (always 1). @param nmemb Number of elements to read. @param stream Stream to read from (FILE* for fread). @return Number of elements (bytes) read, which is short on error. */ typedef size_t (*SerdReadFunc)(void* SERD_NONNULL buf, size_t size, size_t nmemb, void* SERD_NONNULL stream); /** Sink function for raw string output. Identical semantics to `fwrite`, but may set errno for more informative error reporting than supported by SerdStreamErrorFunc. @param buf Input buffer. @param size Size of a single element of data in bytes (always 1). @param nmemb Number of elements to read. @param stream Stream to write to (FILE* for fread). @return Number of elements (bytes) written, which is short on error. */ typedef size_t (*SerdWriteFunc)(const void* SERD_NONNULL buf, size_t size, size_t nmemb, void* SERD_NONNULL stream); /** @} @defgroup serd_syntax Syntax Utilities @{ */ /// Syntax supported by serd typedef enum { 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; /** Get a syntax by name. Case-insensitive, supports "Turtle", "NTriples", "NQuads", and "TriG". Zero is returned if the name is not recognized. */ SERD_PURE_API SerdSyntax serd_syntax_by_name(const char* SERD_NONNULL name); /** 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. */ SERD_PURE_API SerdSyntax serd_guess_syntax(const char* SERD_NONNULL filename); /** Return whether a syntax can represent multiple graphs. @return True for #SERD_NQUADS and #SERD_TRIG, false otherwise. */ SERD_CONST_API bool serd_syntax_has_graphs(SerdSyntax syntax); /** @} @defgroup serd_uri URI @{ */ /** A parsed URI. This URI representation is designed for fast streaming, it allows creating relative URI references or resolving them into absolute URIs in-place without any string allocation. Each component refers to slices in other strings, so a URI view must outlive any strings it was parsed from. The components are not necessarily null-terminated. The scheme, authority, path, query, and fragment simply point to the string value of those components, not including any delimiters. The path_prefix is a special component for storing relative or resolved paths. If it points to a string (usually a base URI the URI was resolved against), then this string is prepended to the path. Otherwise, the length is interpret as the number of up-references ("../") that must be prepended to the path. */ typedef struct { SerdStringView scheme; ///< Scheme SerdStringView authority; ///< Authority SerdStringView path_prefix; ///< Path prefix for relative/resolved paths SerdStringView path; ///< Path suffix SerdStringView query; ///< Query SerdStringView fragment; ///< Fragment } SerdURIView; static const SerdURIView SERD_URI_NULL = {{NULL, 0}, {NULL, 0}, {NULL, 0}, {NULL, 0}, {NULL, 0}, {NULL, 0}}; /// Return true iff `string` starts with a valid URI scheme SERD_PURE_API bool serd_uri_string_has_scheme(const char* SERD_NONNULL string); /// Parse `string` and return a URI view that points into it SERD_PURE_API SerdURIView serd_parse_uri(const char* SERD_NONNULL string); /** 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 A filesystem path. */ SERD_API char* SERD_NULLABLE serd_parse_file_uri(const char* SERD_NONNULL uri, char* SERD_NONNULL* SERD_NULLABLE hostname); /** Return reference `r` resolved against `base`. This will make `r` an absolute URI if possible. @see [RFC3986 5.2.2](http://tools.ietf.org/html/rfc3986#section-5.2.2) @param r URI reference to make absolute, for example "child/path". @param base Base URI, for example "http://example.org/base/". @return An absolute URI, for example "http://example.org/base/child/path", or `r` if it is not a URI reference that can be resolved against `base`. */ SERD_PURE_API SerdURIView serd_resolve_uri(SerdURIView r, SerdURIView base); /** Return `r` as a reference relative to `base` if possible. @see [RFC3986 5.2.2](http://tools.ietf.org/html/rfc3986#section-5.2.2) @param r URI to make relative, for example "http://example.org/base/child/path". @param base Base URI, for example "http://example.org/base". @return A relative URI reference, for example "child/path", `r` if it can not be made relative to `base`, or a null URI if `r` could be made relative to base, but the path prefix is already being used (most likely because `r` was previously a relative URI reference that was resolved against some base). */ SERD_PURE_API SerdURIView serd_relative_uri(SerdURIView r, SerdURIView base); /** Return whether `r` can be written as a reference relative to `base`. For example, with `base` "http://example.org/base/", this returns true if `r` is also "http://example.org/base/", or something like "http://example.org/base/child" ("child") "http://example.org/base/child/grandchild#fragment" ("child/grandchild#fragment"), "http://example.org/base/child/grandchild?query" ("child/grandchild?query"), and so on. @return True if `r` and `base` are equal or if `r` is a child of `base`. */ SERD_PURE_API bool serd_uri_is_within(SerdURIView r, SerdURIView base); /** Write `uri` as a string to `sink`. This will call `sink` several times to emit the URI. @param uri URI to write as a string. @param sink Sink to write string output to. @param stream Opaque user argument to pass to `sink`. @return The number of bytes written. */ SERD_API size_t serd_write_uri(SerdURIView uri, SerdWriteFunc SERD_NONNULL sink, void* SERD_NONNULL stream); /** @} @defgroup serd_node Node @{ */ /// A syntactic RDF node typedef struct SerdNodeImpl SerdNode; /** Type of a node. An RDF node, in the abstract sense, can be either a resource, literal, or a blank. This type is more precise, because syntactically there are two ways to refer to a resource (by URI or CURIE). There are also two ways to refer to a blank node in syntax (by ID or anonymously), but this is handled by statement flags rather than distinct node types. */ typedef enum { /** Literal value. A literal optionally has either a language, or a datatype (not both). */ SERD_LITERAL = 1, /** 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 [RFC3986](http://tools.ietf.org/html/rfc3986) */ SERD_URI = 2, /** CURIE, a shortened URI. Value is an unquoted CURIE string relative to the current environment, 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 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; /** Create a new "simple" node that is just a string. This can be used to create blank, CURIE, or URI nodes from an already measured string or slice of a buffer, which avoids a strlen compared to the friendly constructors. This may not be used for literals since those must be measured to set the SERD_HAS_NEWLINE and SERD_HAS_QUOTE flags. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_simple_node(SerdNodeType type, SerdStringView string); /// Create a new plain literal string node from `str` SERD_API SerdNode* SERD_ALLOCATED serd_new_string(SerdStringView string); /** Create a new plain literal node from `str` with `lang`. A plain literal has no datatype, but may have a language tag. The `lang` may be empty, in which case this is equivalent to `serd_new_string()`. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_plain_literal(SerdStringView str, SerdStringView lang); /** 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 `serd_new_string()`. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_typed_literal(SerdStringView str, SerdStringView datatype_uri); /// Create a new blank node SERD_API SerdNode* SERD_ALLOCATED serd_new_blank(SerdStringView string); /// Create a new CURIE node SERD_API SerdNode* SERD_ALLOCATED serd_new_curie(SerdStringView string); /// Create a new URI node SERD_API SerdNode* SERD_ALLOCATED serd_new_uri(SerdStringView string); /// Create a new URI from a URI view SERD_API SerdNode* SERD_ALLOCATED serd_new_parsed_uri(SerdURIView uri); /** 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. If `path` is relative, `hostname` is ignored. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_file_uri(SerdStringView path, SerdStringView hostname); /// Create a new node by serialising `b` into an xsd:boolean string SERD_API SerdNode* SERD_ALLOCATED serd_new_boolean(bool b); /** Create a new canonical xsd:decimal literal. The resulting node will always contain a '.', start with a digit, and end with a digit (a leading and/or trailing '0' will be added if necessary), for example, "1.0". It will never be in scientific notation. @param d The value for the new node. @param datatype Datatype of node, or NULL for xsd:decimal. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_decimal(double d, const SerdNode* SERD_NULLABLE datatype); /** Create a new canonical xsd:double literal. The returned node will always be in scientific notation, like "1.23E4", except for NaN and negative/positive infinity, which are "NaN", "-INF", and "INF", respectively. Uses the shortest possible representation that precisely describes `d`, which has at most 17 significant digits (under 24 characters total). @param d Double value to write. @return A literal node with datatype xsd:double. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_double(double d); /** Create a new canonical xsd:float literal. Uses identical formatting to serd_new_double(), except with at most 9 significant digits (under 14 characters total). @param f Float value of literal. @return A literal node with datatype xsd:float. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_float(float f); /** Create a new canonical xsd:integer literal. @param i Integer value of literal. @param datatype Datatype of node, or NULL for xsd:integer. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_integer(int64_t i, const SerdNode* SERD_NULLABLE datatype); /** Create a new canonical xsd:base64Binary literal. This function can be used to make a node out of arbitrary binary data, which can be decoded using serd_base64_decode(). @param buf Raw binary data to encode in node. @param size Size of `buf` in bytes. @param datatype Datatype of node, or null for xsd:base64Binary. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_base64(const void* SERD_NONNULL buf, size_t size, const SerdNode* SERD_NULLABLE datatype); /** Return the value of `node` as a boolean. This will work for booleans, and numbers of any datatype if they are 0 or 1. @return The value of `node` as a `bool`, or `false` on error. */ SERD_API bool serd_get_boolean(const SerdNode* SERD_NONNULL node); /** Return the value of `node` as a double. This will coerce numbers of any datatype to double, if the value fits. @return The value of `node` as a `double`, or NaN on error. */ SERD_API double serd_get_double(const SerdNode* SERD_NONNULL node); /** Return the value of `node` as a float. This will coerce numbers of any datatype to float, if the value fits. @return The value of `node` as a `float`, or NaN on error. */ SERD_API float serd_get_float(const SerdNode* SERD_NONNULL node); /** Return the value of `node` as a long (signed 64-bit integer). This will coerce numbers of any datatype to long, if the value fits. @return The value of `node` as a `int64_t`, or 0 on error. */ SERD_API int64_t serd_get_integer(const SerdNode* SERD_NONNULL node); /** Return the maximum size of a decoded base64 node in bytes. This returns an upper bound on the number of bytes that would be decoded by serd_get_base64(). This is calculated as a simple constant-time arithmetic expression based on the length of the encoded string, so may be larger than the actual size of the data due to things like additional whitespace. */ SERD_PURE_API size_t serd_get_base64_size(const SerdNode* SERD_NONNULL node); /** Decode a base64 node. This function can be used to decode a node created with serd_new_base64(). @param node A literal node which is an encoded base64 string. @param buf_size The size of `buf` in bytes. @param buf Buffer where decoded data will be written. @return On success, #SERD_SUCCESS is returned along with the number of bytes written. If the output buffer is too small, then #SERD_ERR_OVERFLOW is returned along with the number of bytes required for successful decoding. */ SERD_API SerdWriteResult serd_get_base64(const SerdNode* SERD_NONNULL node, size_t buf_size, void* SERD_NONNULL buf); /// Return a deep copy of `node` SERD_API SerdNode* SERD_ALLOCATED serd_node_copy(const SerdNode* SERD_NULLABLE node); /// Free any data owned by `node` SERD_API void serd_node_free(SerdNode* SERD_NULLABLE node); /// Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL) SERD_PURE_API SerdNodeType serd_node_type(const SerdNode* SERD_NONNULL node); /// Return the node's string SERD_CONST_API const char* SERD_NONNULL serd_node_string(const SerdNode* SERD_NONNULL node); /// Return the length of the node's string in bytes (excluding terminator) SERD_PURE_API size_t serd_node_length(const SerdNode* SERD_NULLABLE node); /** Return a view of the string in a node. This is a convenience wrapper for serd_node_string() and serd_node_length() that can be used to get both in a single call. */ SERD_PURE_API SerdStringView serd_node_string_view(const SerdNode* SERD_NONNULL node); /** Return a parsed view of the URI in a node. It is best to check the node type before calling this function, though it is safe to call on non-URI nodes. In that case, it will return a null view with all fields zero. Note that this parses the URI string contained in the node, so it is a good idea to keep the value if you will be using it several times in the same scope. */ SERD_PURE_API SerdURIView serd_node_uri_view(const SerdNode* SERD_NONNULL node); /// Return the flags (string properties) of a node SERD_PURE_API SerdNodeFlags serd_node_flags(const SerdNode* SERD_NONNULL node); /// Return the datatype of the literal node, if present SERD_PURE_API const SerdNode* SERD_NULLABLE serd_node_datatype(const SerdNode* SERD_NONNULL node); /// Return the language tag of the literal node, if present SERD_PURE_API const SerdNode* SERD_NULLABLE serd_node_language(const SerdNode* SERD_NONNULL node); /// Return true iff `a` is equal to `b` SERD_PURE_API bool serd_node_equals(const SerdNode* SERD_NULLABLE a, const SerdNode* SERD_NULLABLE b); /** @} @defgroup serd_world World @{ */ /// Global library state typedef struct SerdWorldImpl SerdWorld; /// An error description typedef struct { SerdStatus status; ///< Error code const char* 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; /** Callback function for errors. @param handle Handle for user data. @param error Error description. */ typedef SerdStatus (*SerdErrorFunc)(void* SERD_NULLABLE handle, const SerdError* SERD_NONNULL error); /** Create a new Serd World. It is safe to use multiple worlds in one process, though no objects can be shared between worlds. */ SERD_MALLOC_API SerdWorld* SERD_ALLOCATED serd_world_new(void); /// Free `world` SERD_API void serd_world_free(SerdWorld* SERD_NULLABLE world); /** Set a function to be called when errors occur. The `error_func` will be called with `handle` as its first argument. If no error function is set, errors are printed to stderr. */ SERD_API void serd_world_set_error_func(SerdWorld* SERD_NONNULL world, SerdErrorFunc SERD_NULLABLE error_func, void* SERD_NULLABLE handle); /** @} @defgroup serd_event Event Handlers @{ */ /// 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 } SerdStatementFlag; /// Bitwise OR of SerdStatementFlag values typedef uint32_t SerdStatementFlags; /** Sink function for base URI changes Called whenever the base URI of the serialisation changes. */ typedef SerdStatus (*SerdBaseFunc)(void* SERD_NULLABLE handle, const SerdNode* SERD_NONNULL uri); /** Sink function for namespace definitions. Called whenever a prefix is defined in the serialisation. */ typedef SerdStatus (*SerdPrefixFunc)(void* SERD_NULLABLE handle, const SerdNode* SERD_NONNULL name, const SerdNode* SERD_NONNULL uri); /** Sink function for statements. Called for every RDF statement in the serialisation. */ typedef SerdStatus (*SerdStatementFunc)(void* SERD_NULLABLE handle, SerdStatementFlags flags, const SerdNode* SERD_NULLABLE graph, const SerdNode* SERD_NONNULL subject, const SerdNode* SERD_NONNULL predicate, const SerdNode* SERD_NONNULL object); /** Sink function 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 (so the anonymous node is finished). */ typedef SerdStatus (*SerdEndFunc)(void* SERD_NULLABLE handle, const SerdNode* SERD_NONNULL node); /** @} @defgroup serd_sink Sink @{ */ /// An interface that receives a stream of RDF data typedef struct SerdSinkImpl SerdSink; /// Function to free an opaque handle typedef void (*SerdFreeFunc)(void* SERD_NULLABLE ptr); /** 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. @param handle Opaque handle that will be passed to sink functions. @param free_handle Free function to call on handle in serd_sink_free(). */ SERD_API SerdSink* SERD_ALLOCATED serd_sink_new(void* SERD_NULLABLE handle, SerdFreeFunc SERD_NULLABLE free_handle); /// Free `sink` SERD_API void serd_sink_free(SerdSink* SERD_NULLABLE sink); /// Set a function to be called when the base URI changes SERD_API SerdStatus serd_sink_set_base_func(SerdSink* SERD_NONNULL sink, SerdBaseFunc SERD_NULLABLE base_func); /// Set a function to be called when a namespace prefix is defined SERD_API SerdStatus serd_sink_set_prefix_func(SerdSink* SERD_NONNULL sink, SerdPrefixFunc SERD_NULLABLE prefix_func); /// Set a function to be called when a statement is emitted SERD_API SerdStatus serd_sink_set_statement_func(SerdSink* SERD_NONNULL sink, SerdStatementFunc SERD_NULLABLE statement_func); /// Set a function to be called when an anonymous node ends SERD_API SerdStatus serd_sink_set_end_func(SerdSink* SERD_NONNULL sink, SerdEndFunc SERD_NULLABLE end_func); /// Set the base URI SERD_API SerdStatus serd_sink_write_base(const SerdSink* SERD_NONNULL sink, const SerdNode* SERD_NONNULL uri); /// Set a namespace prefix SERD_API SerdStatus serd_sink_write_prefix(const SerdSink* SERD_NONNULL sink, const SerdNode* SERD_NONNULL name, const SerdNode* SERD_NONNULL uri); /// Write a statement from individual nodes SERD_API SerdStatus serd_sink_write(const SerdSink* SERD_NONNULL sink, SerdStatementFlags flags, const SerdNode* SERD_NONNULL subject, const SerdNode* SERD_NONNULL predicate, const SerdNode* SERD_NONNULL object, const SerdNode* SERD_NULLABLE graph); /// Mark the end of an anonymous node SERD_API SerdStatus serd_sink_write_end(const SerdSink* SERD_NONNULL sink, const SerdNode* SERD_NONNULL node); /** @} @defgroup serd_env Environment @{ */ /// Lexical environment for relative URIs or CURIEs (base URI and namespaces) typedef struct SerdEnvImpl SerdEnv; /// Create a new environment SERD_API SerdEnv* SERD_ALLOCATED serd_env_new(SerdStringView base_uri); /// Free `env` SERD_API void serd_env_free(SerdEnv* SERD_NULLABLE env); /// Get the current base URI SERD_PURE_API const SerdNode* SERD_NULLABLE serd_env_base_uri(const SerdEnv* SERD_NULLABLE env); /// Set the current base URI SERD_API SerdStatus serd_env_set_base_uri(SerdEnv* SERD_NONNULL env, SerdStringView uri); /** Set a namespace prefix. A namespace prefix is used to expand CURIE nodes, for example, with the prefix "xsd" set to "http://www.w3.org/2001/XMLSchema#", "xsd:decimal" will expand to "http://www.w3.org/2001/XMLSchema#decimal". */ SERD_API SerdStatus serd_env_set_prefix(SerdEnv* SERD_NONNULL env, SerdStringView name, SerdStringView uri); /// Qualify `uri` into a CURIE if possible SERD_API bool serd_env_qualify(const SerdEnv* SERD_NULLABLE env, const SerdNode* SERD_NONNULL uri, const SerdNode* SERD_NULLABLE* SERD_NONNULL prefix, SerdStringView* SERD_NONNULL suffix); /** Expand `curie`. Errors: SERD_ERR_BAD_ARG if `curie` is not valid, or SERD_ERR_BAD_CURIE if prefix is not defined in `env`. */ SERD_API SerdStatus serd_env_expand(const SerdEnv* SERD_NULLABLE env, const SerdNode* SERD_NULLABLE curie, SerdStringView* SERD_NONNULL uri_prefix, SerdStringView* SERD_NONNULL uri_suffix); /** Expand `node`, which must be a CURIE or URI, to a full URI. Returns null if `node` can not be expanded. */ SERD_API SerdNode* SERD_ALLOCATED serd_env_expand_node(const SerdEnv* SERD_NULLABLE env, const SerdNode* SERD_NONNULL node); /// Call `func` for each prefix defined in `env` SERD_API void serd_env_foreach(const SerdEnv* SERD_NONNULL env, SerdPrefixFunc SERD_NONNULL func, void* SERD_NULLABLE handle); /** @} @defgroup serd_reader Reader @{ */ /// Streaming parser that reads a text stream and writes to a statement sink typedef struct SerdReaderImpl SerdReader; /// Create a new RDF reader SERD_API SerdReader* SERD_ALLOCATED serd_reader_new(SerdWorld* SERD_NONNULL world, SerdSyntax syntax, const SerdSink* SERD_NONNULL sink, size_t stack_size); /** 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 error is printed for invalid input in either case. */ SERD_API void serd_reader_set_strict(SerdReader* SERD_NONNULL reader, bool strict); /** 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 (a model or a file). Since Serd preserves blank node IDs, this could cause conflicts where two non-equivalent blank nodes are merged, resulting in corrupt data. By setting a unique blank node prefix for each parsed file, this can be avoided, while preserving blank node names. */ SERD_API void serd_reader_add_blank_prefix(SerdReader* SERD_NONNULL reader, const char* SERD_NULLABLE prefix); /// Prepare to read from the file at a local file `uri` SERD_API SerdStatus serd_reader_start_file(SerdReader* SERD_NONNULL reader, const char* SERD_NONNULL uri, bool bulk); /** 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). */ SERD_API SerdStatus serd_reader_start_stream(SerdReader* SERD_NONNULL reader, SerdReadFunc SERD_NONNULL read_func, SerdStreamErrorFunc SERD_NONNULL error_func, void* SERD_NONNULL stream, const char* SERD_NULLABLE name, size_t page_size); /// Prepare to read from a string SERD_API SerdStatus serd_reader_start_string(SerdReader* SERD_NONNULL reader, const char* SERD_NONNULL utf8); /** 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 until a '.' is encountered. This is particularly useful for reading directly from a pipe or socket. */ SERD_API SerdStatus serd_reader_read_chunk(SerdReader* SERD_NONNULL reader); /** 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, for incremental reading use serd_reader_read_chunk(). */ SERD_API SerdStatus serd_reader_read_document(SerdReader* SERD_NONNULL reader); /** Finish reading from the source. This should be called before starting to read from another source. */ SERD_API SerdStatus serd_reader_finish(SerdReader* SERD_NONNULL reader); /** Free `reader`. The reader will be finished via `serd_reader_finish()` if necessary. */ SERD_API void serd_reader_free(SerdReader* SERD_NULLABLE reader); /** @} @defgroup serd_writer Writer @{ */ /// Streaming serialiser that writes a text stream as statements are pushed typedef struct SerdWriterImpl SerdWriter; /** Writer style options. These flags allow more precise control of writer output style. Note that some options are only supported for some syntaxes, for example, NTriples does not support abbreviation and is always ASCII. */ typedef enum { SERD_WRITE_ABBREVIATED = 1u << 0u, ///< Abbreviate triples when possible SERD_WRITE_ASCII = 1u << 1u, ///< Escape all non-ASCII characters SERD_WRITE_RESOLVED = 1u << 2u, ///< Resolve URIs against base URI SERD_WRITE_CURIED = 1u << 3u, ///< Shorten URIs into CURIEs SERD_WRITE_BULK = 1u << 4u, ///< Write output in pages } SerdWriterFlag; /// Bitwise OR of SerdWriterFlag values typedef uint32_t SerdWriterFlags; /// Create a new RDF writer SERD_API SerdWriter* SERD_ALLOCATED serd_writer_new(SerdWorld* SERD_NONNULL world, SerdSyntax syntax, SerdWriterFlags flags, SerdEnv* SERD_NONNULL env, SerdWriteFunc SERD_NONNULL ssink, void* SERD_NULLABLE stream); /// Free `writer` SERD_API void serd_writer_free(SerdWriter* SERD_NULLABLE writer); /// Return a sink interface that emits statements via `writer` SERD_CONST_API const SerdSink* SERD_NONNULL serd_writer_sink(SerdWriter* SERD_NONNULL writer); /** 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 an initialized SerdBuffer. When the write is finished, the string should be retrieved with serd_buffer_sink_finish(). */ SERD_API size_t serd_buffer_sink(const void* SERD_NONNULL buf, size_t size, size_t nmemb, void* SERD_NONNULL stream); /** Finish writing to a buffer with serd_buffer_sink(). 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_NONNULL serd_buffer_sink_finish(SerdBuffer* SERD_NONNULL stream); /** Set a prefix to be removed from matching blank node identifiers. This is the counterpart to serd_reader_add_blank_prefix() which can be used to "undo" added prefixes. */ SERD_API void serd_writer_chop_blank_prefix(SerdWriter* SERD_NONNULL writer, const char* SERD_NULLABLE prefix); /** Set the current output base URI, and emit a directive if applicable. Note this function can be safely casted to SerdBaseSink. */ SERD_API SerdStatus serd_writer_set_base_uri(SerdWriter* SERD_NONNULL writer, const SerdNode* SERD_NULLABLE 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, with root and base , will be written as <../>, but will be written non-relatively as . If the root is not explicitly set, it defaults to the base URI, so no up-references will be created at all. */ SERD_API SerdStatus serd_writer_set_root_uri(SerdWriter* SERD_NONNULL writer, const SerdNode* SERD_NULLABLE uri); /** Finish a write. This flushes any pending output, for example terminating punctuation, so that the output is a complete document. */ SERD_API SerdStatus serd_writer_finish(SerdWriter* SERD_NONNULL writer); /** @} @} */ #ifdef __cplusplus # if defined(__GNUC__) # pragma GCC diagnostic pop # endif } /* extern "C" */ #endif #endif /* SERD_SERD_H */