/* 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 #if defined(__MINGW32__) # define SERD_LOG_FUNC(fmt, a) __attribute__((format(gnu_printf, fmt, a))) #elif defined(__GNUC__) # define SERD_LOG_FUNC(fmt, a) __attribute__((format(printf, fmt, a))) #else # define SERD_LOG_FUNC(fmt, a) #endif #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 @{ */ /** @defgroup serd_version Version Serd uses a single [semantic version number](https://semver.org) which reflects changes to the C library ABI. @{ */ /** The major version number of the serd library. Semver: Increments when incompatible API changes are made. */ #define SERD_MAJOR_VERSION 1 /** The minor version number of the serd library. Semver: Increments when functionality is added in a backwards compatible manner. */ #define SERD_MINOR_VERSION 0 /** The micro version number of the serd library. Semver: Increments when changes are made that do not affect the API, such as performance improvements or bug fixes. */ #define SERD_MICRO_VERSION 1 /** @} @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_NONNULL 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 /** @} @defgroup serd_memory Memory Management @{ */ struct SerdAllocatorImpl; /** A memory allocator. This object-like structure provides an interface like the standard C functions malloc(), calloc(), realloc(), free(), and aligned_alloc(). It contains function pointers that differ from their standard counterparts by taking a context parameter (a pointer to this struct), which allows the user to implement custom stateful allocators. */ typedef struct SerdAllocatorImpl SerdAllocator; /** General malloc-like memory allocation function. This works like the standard C malloc(), except has an additional handle parameter for implementing stateful allocators without static data. */ typedef void* SERD_ALLOCATED (*SerdAllocatorMallocFunc)( // SerdAllocator* SERD_NULLABLE allocator, size_t size); /** General calloc-like memory allocation function. This works like the standard C calloc(), except has an additional handle parameter for implementing stateful allocators without static data. */ typedef void* SERD_ALLOCATED (*SerdAllocatorCallocFunc)( // SerdAllocator* SERD_NULLABLE allocator, size_t nmemb, size_t size); /** General realloc-like memory reallocation function. This works like the standard C remalloc(), except has an additional handle parameter for implementing stateful allocators without static data. */ typedef void* SERD_ALLOCATED (*SerdAllocatorReallocFunc)( // SerdAllocator* SERD_NULLABLE allocator, void* SERD_NULLABLE ptr, size_t size); /** General free-like memory deallocation function. This works like the standard C remalloc(), except has an additional handle parameter for implementing stateful allocators without static data. */ typedef void (*SerdAllocatorFreeFunc)( // SerdAllocator* SERD_NULLABLE allocator, void* SERD_NULLABLE ptr); /** General aligned_alloc-like memory deallocation function. This works like the standard C aligned_alloc(), except has an additional handle parameter for implementing stateful allocators without static data. */ typedef void* SERD_ALLOCATED (*SerdAllocatorAlignedAllocFunc)( // SerdAllocator* SERD_NULLABLE allocator, size_t alignment, size_t size); /** General aligned memory deallocation function. This works like the standard C free(), but must be used to free memory allocated with the aligned_alloc() method of the allocator. This allows portability to systems (like Windows) that can not use the same free function in these cases. */ typedef void (*SerdAllocatorAlignedFreeFunc)( // SerdAllocator* SERD_NULLABLE allocator, void* SERD_NULLABLE ptr); /// Definition of SerdAllocator struct SerdAllocatorImpl { SerdAllocatorMallocFunc SERD_ALLOCATED malloc; SerdAllocatorCallocFunc SERD_ALLOCATED calloc; SerdAllocatorReallocFunc SERD_ALLOCATED realloc; SerdAllocatorFreeFunc SERD_ALLOCATED free; SerdAllocatorAlignedAllocFunc SERD_ALLOCATED aligned_alloc; SerdAllocatorAlignedFreeFunc SERD_ALLOCATED aligned_free; }; /// Return the default allocator which simply uses the system allocator SERD_CONST_API SerdAllocator* SERD_NONNULL serd_default_allocator(void); /** 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. This may be used to free memory allocated using serd_default_allocator(). */ SERD_API void serd_free(SerdAllocator* SERD_NULLABLE allocator, void* SERD_NULLABLE ptr); /** @} @defgroup serd_status Status Codes @{ */ /// Return status code typedef enum { SERD_SUCCESS, ///< Success SERD_FAILURE, ///< Non-fatal failure SERD_UNKNOWN_ERROR, ///< Unknown error SERD_NO_DATA, ///< Missing input SERD_OVERFLOW, ///< Insufficient space SERD_BAD_ALLOC, ///< Memory allocation failed SERD_BAD_ARG, ///< Invalid argument SERD_BAD_CALL, ///< Invalid call SERD_BAD_CURIE, ///< Invalid CURIE or unknown namespace prefix SERD_BAD_CURSOR, ///< Use of invalidated cursor SERD_BAD_EVENT, ///< Invalid event in stream SERD_BAD_INDEX, ///< No optimal model index available SERD_BAD_LABEL, ///< Encountered clashing blank node label SERD_BAD_LITERAL, ///< Invalid literal SERD_BAD_PATTERN, ///< Invalid statement pattern SERD_BAD_READ, ///< Error reading from file SERD_BAD_STACK, ///< Stack overflow SERD_BAD_SYNTAX, ///< Invalid syntax SERD_BAD_TEXT, ///< Invalid text encoding SERD_BAD_URI, ///< Invalid or unresolved URI SERD_BAD_WRITE, ///< Error writing to file SERD_BAD_DATA, ///< Invalid data } 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_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 @{ */ /** Return `path` as a canonical absolute path. This expands all symbolic links, relative references, and removes extra directory separators. Null is returned on error, including if the path does not exist. @return A newly allocated string that must be freed with serd_free() using the world allocator, or null. */ SERD_API char* SERD_ALLOCATED serd_canonical_path(SerdAllocator* SERD_NULLABLE allocator, const char* SERD_NONNULL path); /** Compare two strings ignoring case. @return Less than, equal to, or greater than zero if `s1` is less than, equal to, or greater than `s2`, respectively. */ SERD_PURE_API int serd_strncasecmp(const char* SERD_NONNULL s1, const char* SERD_NONNULL s2, size_t n); /** @} @defgroup serd_io_functions I/O Function Types These function types define the low-level interface that serd uses to read and write input. They are deliberately compatible with the standard C functions for reading and writing from files. @{ */ /** Function for reading input bytes from a stream. This has identical semantics to `fread`, but may set `errno` for more informative error reporting than supported by #SerdErrorFunc. @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); /** Function for writing output bytes to a stream. This has identical semantics to `fwrite`, but may set `errno` for more informative error reporting than supported by #SerdErrorFunc. @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); /** Function for detecting I/O stream errors. This has identical semantics to `ferror`. @return Non-zero if `stream` has encountered an error. */ typedef int (*SerdErrorFunc)(void* SERD_NONNULL stream); /** Function for closing an I/O stream. This has identical semantics to `fclose`. Note that when writing, this may flush the stream which can cause errors, including errors caused by previous writes that appeared successful at the time. Therefore it is necessary to check the return value of this function to properly detect write errors. @return Non-zero if `stream` has encountered an error. */ typedef int (*SerdCloseFunc)(void* SERD_NONNULL stream); /** @} @defgroup serd_syntax Syntax Utilities @{ */ /// Syntax supported by serd typedef enum { SERD_SYNTAX_EMPTY = 0, ///< Empty syntax SERD_TURTLE = 1, ///< Terse triples http://www.w3.org/TR/turtle SERD_NTRIPLES = 2, ///< Flat triples http://www.w3.org/TR/n-triples/ SERD_NQUADS = 3, ///< Flat 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". @return The syntax with the given name, or the empty syntax if the name is unknown. */ 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, for example a filename that ends with ".ttl" will be considered Turtle. @return The likely syntax of the given file, or the empty syntax if the extension is unknown. */ SERD_PURE_API SerdSyntax serd_guess_syntax(const char* SERD_NONNULL filename); /** Return whether a syntax can represent multiple graphs in one document. @return True for #SERD_NQUADS and #SERD_TRIG, false otherwise. */ SERD_CONST_API bool serd_syntax_has_graphs(SerdSyntax syntax); /** @} @defgroup serd_data Data @{ @defgroup serd_uri URI @{ */ /** A parsed view of a URI. This representation is designed for fast streaming. It makes it possible to create relative URI references or resolve 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. Note that 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 interpreted 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 allocator Allocator for the returned string. @param uri A file URI. @param hostname If non-NULL, set to the hostname, if present. @return A newly allocated path string that must be freed with serd_free(). */ SERD_API char* SERD_NULLABLE serd_parse_file_uri(SerdAllocator* SERD_NULLABLE allocator, 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); /** Return the length of `uri` as a string. This can be used to get the expected number of bytes that will be written by serd_write_uri(). @return A string length in bytes, not including the null terminator. */ SERD_PURE_API size_t serd_uri_string_length(SerdURIView uri); /** 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 length of the written URI string (not including a null terminator), which may be less than `serd_uri_string_length(uri)` on error. */ SERD_API size_t serd_write_uri(SerdURIView uri, SerdWriteFunc SERD_NONNULL sink, void* SERD_NONNULL stream); /** Write a file URI to `sink` from a 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. @param path File system path. @param hostname Optional hostname. @param sink Sink to write string output to. @param stream Opaque user argument to pass to `sink`. @return The length of the written URI string (not including a null terminator). */ SERD_API size_t serd_write_file_uri(SerdStringView path, SerdStringView hostname, SerdWriteFunc SERD_NONNULL sink, void* SERD_NONNULL stream); /** @} @defgroup serd_node Node @{ */ /// An 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). Serd also has support for variable nodes to support some features, which are not RDF nodes. 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, /** 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 = 3, /** A variable node. Value is a variable name without any syntactic prefix, like "name", which is meaningful only within this serialisation. @see [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/#rVar) */ SERD_VARIABLE = 4 } SerdNodeType; /** @defgroup serd_node_value Values Serd supports reading and writing machine-native numbers, called "values", in a standards-conformant and portable way. The value structure is used in the API to allow passing and returning a primitive value of any supported type. Note that this is just an API convenience, literal nodes themselves always store their values as strings. @{ */ /// The type of a #SerdValue typedef enum { SERD_NOTHING, ///< Sentinel for unknown datatypes or errors SERD_BOOL, ///< xsd:boolean (bool) SERD_DOUBLE, ///< xsd:double (double) SERD_FLOAT, ///< xsd:float (float) SERD_LONG, ///< xsd:long (int64_t) SERD_INT, ///< xsd:integer (int32_t) SERD_SHORT, ///< xsd:short (int16_t) SERD_BYTE, ///< xsd:byte (int8_t) SERD_ULONG, ///< xsd:unsignedLong (uint64_t) SERD_UINT, ///< xsd:unsignedInt (uint32_t) SERD_USHORT, ///< xsd:unsignedShort (uint16_t) SERD_UBYTE, ///< xsd:unsignedByte (uint8_t) } SerdValueType; /// The data of a #SerdValue (the actual machine-native primitive) typedef union { bool as_bool; double as_double; float as_float; int64_t as_long; int32_t as_int; int16_t as_short; int8_t as_byte; uint64_t as_ulong; uint32_t as_uint; uint16_t as_ushort; uint8_t as_ubyte; } SerdValueData; /// A primitive value with a type tag typedef struct { SerdValueType type; SerdValueData data; } SerdValue; /// Convenience constructor to make a #SERD_NOTHING (non-)value SERD_CONST_API SerdValue serd_nothing(void); /// Convenience constructor to make a #SERD_BOOL value SERD_CONST_API SerdValue serd_bool(bool v); /// Convenience constructor to make a #SERD_DOUBLE value SERD_CONST_API SerdValue serd_double(double v); /// Convenience constructor to make a #SERD_FLOAT value SERD_CONST_API SerdValue serd_float(float v); /// Convenience constructor to make a #SERD_LONG value SERD_CONST_API SerdValue serd_long(int64_t v); /// Convenience constructor to make a #SERD_INT value SERD_CONST_API SerdValue serd_int(int32_t v); /// Convenience constructor to make a #SERD_SHORT value SERD_CONST_API SerdValue serd_short(int16_t v); /// Convenience constructor to make a #SERD_BYTE value SERD_CONST_API SerdValue serd_byte(int8_t v); /// Convenience constructor to make a #SERD_ULONG value SERD_CONST_API SerdValue serd_ulong(uint64_t v); /// Convenience constructor to make a #SERD_UINT value SERD_CONST_API SerdValue serd_uint(uint32_t v); /// Convenience constructor to make a #SERD_USHORT value SERD_CONST_API SerdValue serd_ushort(uint16_t v); /// Convenience constructor to make a #SERD_UBYTE value SERD_CONST_API SerdValue serd_ubyte(uint8_t v); /// Flags that describe the details of a node typedef enum { SERD_IS_LONG = 1u << 0u, ///< Literal node should be triple-quoted SERD_HAS_DATATYPE = 1u << 1u, ///< Literal node has datatype SERD_HAS_LANGUAGE = 1u << 2u ///< Literal node has language } SerdNodeFlag; /// Bitwise OR of SerdNodeFlag values typedef uint32_t SerdNodeFlags; /** @} @defgroup serd_node_construction Construction This is the low-level node construction API, which can be used to construct nodes into existing buffers. Advanced applications can use this to specially manage node memory, for example by allocating nodes on the stack, or with a special allocator. Note that nodes are "plain old data", so there is no need to destroy a constructed node, and nodes may be trivially copied, for example with memcpy(). @{ */ /** Construct a node into an existing buffer. This is the universal node constructor which can construct any node. An error will be returned if the parameters do not make sense. In particular, #SERD_HAS_DATATYPE or #SERD_HAS_LANGUAGE (but not both) may only be given if `type` is #SERD_LITERAL, and `meta` must be syntactically valid based on that flag. This function may also be used to determine the size of buffer required by passing a null buffer with zero size. @param buf_size The size of `buf` in bytes, or zero to only measure. @param buf Buffer where the node will be written, or null to only measure. @param type The type of the node to construct. @param string The string body of the node. @param flags Flags that describe the details of the node. @param meta The string value of the literal's metadata. If #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If #SERD_HAS_LANGUAGE is set, then this must be a language tag like "en-ca". Otherwise, it is ignored. @return A result with a `status` and a `count` of bytes written. If the buffer is too small for the node, then `status` will be #SERD_OVERFLOW, and `count` will be set to the number of bytes required to successfully construct the node. */ SERD_API SerdWriteResult serd_node_construct(size_t buf_size, void* SERD_NULLABLE buf, SerdNodeType type, SerdStringView string, SerdNodeFlags flags, SerdStringView meta); /** Construct a simple "token" node. "Token" is just a shorthand used in this API to refer to a node that is not a typed or tagged literal, that is, a node that is just one string. This can be used to create URIs, blank nodes, variables, and simple string literals. Note that string literals constructed with this function will have no flags set, and so will be written as "short" literals (not triple-quoted). To construct long literals, use the more advanced serd_construct_literal() with the #SERD_IS_LONG flag. See the serd_node_construct() documentation for details on buffer usage and the return value. */ SERD_API SerdWriteResult serd_node_construct_token(size_t buf_size, void* SERD_NULLABLE buf, SerdNodeType type, SerdStringView string); /** Construct a URI node from a parsed URI. This is similar to serd_node_construct_token(), but will serialise a parsed URI into the new node. This can be used to resolve a relative URI reference or expand a CURIE directly into a node without needing to allocate the URI string separately. */ SerdWriteResult serd_node_construct_uri(size_t buf_size, void* SERD_NULLABLE buf, SerdURIView uri); /** Construct a file URI node from a path and optional hostname. This is similar to serd_node_construct_token(), but will create a new file URI from a file path and optional hostname, performing any necessary escaping. */ SerdWriteResult serd_node_construct_file_uri(size_t buf_size, void* SERD_NULLABLE buf, SerdStringView path, SerdStringView hostname); /** Construct a literal node with an optional datatype or language. Either a datatype (which must be an absolute URI) or a language (which must be an RFC5646 language tag) may be given, but not both. This is the most general literal constructor, which can be used to construct any literal node. This works like serd_node_construct(), see its documentation for details. */ SERD_API SerdWriteResult serd_node_construct_literal(size_t buf_size, void* SERD_NULLABLE buf, SerdStringView string, SerdNodeFlags flags, SerdStringView meta); /** Construct a canonical literal for a primitive value. The constructed node will be a typed literal in canonical form for the xsd datatype corresponding to the value. */ SerdWriteResult serd_node_construct_value(size_t buf_size, void* SERD_NULLABLE buf, SerdValue value); /** Construct a canonical xsd:decimal literal. The constructed node will be an xsd:decimal literal, like "12.34", with datatype xsd:decimal. The 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. This is a convenience wrapper for serd_node_construct_literal() that constructs a node directly from a `double`. */ SerdWriteResult serd_node_construct_decimal(size_t buf_size, void* SERD_NULLABLE buf, double value); /** Construct a canonical xsd:integer literal. The constructed node will be an xsd:integer literal like "1234", with the given datatype, or datatype xsd:integer if none is given. It is the caller's responsibility to ensure that the value is within the range of the given datatype. */ SerdWriteResult serd_node_construct_integer(size_t buf_size, void* SERD_NULLABLE buf, int64_t value); /** Construct a canonical xsd:hexBinary literal. The constructed node will be an xsd:hexBinary literal like "534D", with datatype xsd:hexBinary. */ SerdWriteResult serd_node_construct_hex(size_t buf_size, void* SERD_NULLABLE buf, size_t value_size, const void* SERD_NONNULL value); /** Construct a canonical xsd:base64Binary literal. The constructed node will be an xsd:base64Binary literal like "Zm9vYmFy", with datatype xsd:base64Binary. */ SerdWriteResult serd_node_construct_base64(size_t buf_size, void* SERD_NULLABLE buf, size_t value_size, const void* SERD_NONNULL value); /** @} @defgroup serd_node_allocation Dynamic Allocation This is a convenient higher-level node construction API which allocates nodes with an allocator. The returned nodes must be freed with serd_node_free() using the same allocator. Note that in most cases it is better to use a #SerdNodes instead of managing individual node allocations. @{ */ /** Create a new node of any type. This is a wrapper for serd_node_construct() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_node_new(SerdAllocator* SERD_NULLABLE allocator, SerdNodeType type, SerdStringView string, SerdNodeFlags flags, SerdStringView meta); /** Create a new simple "token" node. This is a wrapper for serd_node_construct_token() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_token(SerdAllocator* SERD_NULLABLE allocator, SerdNodeType type, SerdStringView string); /** Create a new string literal node. This is a trivial wrapper for serd_new_token() that passes `SERD_LITERAL` for the type. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_string(SerdAllocator* SERD_NULLABLE allocator, SerdStringView string); /** Create a new URI node from a string. This is a wrapper for serd_node_construct_uri() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_uri(SerdAllocator* SERD_NULLABLE allocator, SerdStringView string); /** Create a new URI node from a parsed URI. This is a wrapper for serd_node_construct_uri() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_parsed_uri(SerdAllocator* SERD_NULLABLE allocator, SerdURIView uri); /** Create a new file URI node from a path and optional hostname. This is a wrapper for serd_node_construct_file_uri() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_file_uri(SerdAllocator* SERD_NULLABLE allocator, SerdStringView path, SerdStringView hostname); /** Create a new literal node. This is a wrapper for serd_node_construct_literal() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_literal(SerdAllocator* SERD_NULLABLE allocator, SerdStringView string, SerdNodeFlags flags, SerdStringView meta); /** Create a new canonical value node. This is a wrapper for serd_node_construct_value() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_value(SerdAllocator* SERD_NULLABLE allocator, SerdValue value); /** Create a new canonical xsd:decimal literal. This is a wrapper for serd_node_construct_decimal() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_decimal(SerdAllocator* SERD_NULLABLE allocator, double d); /** Create a new canonical xsd:integer literal. This is a wrapper for serd_node_construct_integer() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_integer(SerdAllocator* SERD_NULLABLE allocator, int64_t i); /** Create a new canonical xsd:hexBinary literal. This is a wrapper for serd_node_construct_hex() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_hex(SerdAllocator* SERD_NULLABLE allocator, const void* SERD_NONNULL buf, size_t size); /** Create a new canonical xsd:base64Binary literal. This is a wrapper for serd_node_construct_base64() that allocates a new node on the heap. @return A newly allocated node that must be freed with serd_node_free(), or null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_base64(SerdAllocator* SERD_NULLABLE allocator, const void* SERD_NONNULL buf, size_t size); /** @} */ /** Return the primitive value of `node`. This will return a typed value if the node can be read as one, or a value with type #SERD_NOTHING otherwise. @return The value of `node` as a #SerdValue, if possible. */ SERD_API SerdValue serd_get_value(const SerdNode* SERD_NONNULL node); /** Return the value of `node` as a specific type of number. This is like serd_get_number(), but will coerce the value of the node to the requrested type if possible. @param node The node to interpret as a number. @param type The desired numeric datatype of the result. @param lossy Whether lossy conversions can be used. If this is false, then this function only succeeds if the value could be converted back to the original datatype of the node without loss. Otherwise, precision may be reduced or values may be truncated to fit the result. @return The value of `node` as a #SerdValue, or nothing. */ SERD_API SerdValue serd_get_value_as(const SerdNode* SERD_NONNULL node, SerdValueType type, bool lossy); /** Return the maximum size of a decoded hex or base64 binary node in bytes. This returns an upper bound on the number of bytes that would be decoded by serd_get_blob(). 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. @return The size of the decoded hex or base64 blob `node`, or zero if it does not have datatype or . */ SERD_PURE_API size_t serd_get_blob_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_OVERFLOW is returned along with the number of bytes required for successful decoding. */ SERD_API SerdWriteResult serd_get_blob(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(SerdAllocator* SERD_NULLABLE allocator, const SerdNode* SERD_NULLABLE node); /// Free any data owned by `node` SERD_API void serd_node_free(SerdAllocator* SERD_NULLABLE allocator, 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); /** 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 other node. Nodes are ordered first by type, then by string value, then by language or datatype, if present. */ SERD_PURE_API int serd_node_compare(const SerdNode* SERD_NONNULL a, const SerdNode* SERD_NONNULL b); /** @} @defgroup serd_nodes Nodes @{ */ /// Hashing node container for interning and simplified memory management typedef struct SerdNodesImpl SerdNodes; /// Create a new node set SERD_API SerdNodes* SERD_ALLOCATED serd_nodes_new(SerdAllocator* SERD_NULLABLE allocator); /** Free `nodes` and all nodes that are stored in it. Note that this invalidates any node pointers previously returned from `nodes`. */ SERD_API void serd_nodes_free(SerdNodes* SERD_NULLABLE nodes); /// Return the number of interned nodes SERD_PURE_API size_t serd_nodes_size(const SerdNodes* SERD_NONNULL nodes); /** Return the existing interned copy of a node if it exists. This either returns an equivalent to the given node, or null if this node has not been interned. */ SERD_API const SerdNode* SERD_NULLABLE serd_nodes_get(const SerdNodes* SERD_NONNULL nodes, const SerdNode* SERD_NULLABLE node); /** Intern `node`. Multiple calls with equivalent nodes will return the same pointer. @return A node that is different than, but equivalent to, `node`. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_intern(SerdNodes* SERD_NONNULL nodes, const SerdNode* SERD_NULLABLE node); /** Make a simple "token" node. "Token" is just a shorthand used in this API to refer to a node that is not a typed or tagged literal, that is, a node that is just one string. This can be used to make URIs, blank nodes, variables, and simple string literals. Note that string literals constructed with this function will have no flags set, and so will be written as "short" literals (not triple-quoted). To construct long literals, use the more advanced serd_nodes_literal() with the #SERD_IS_LONG flag. A new node will be added if an equivalent node is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_token(SerdNodes* SERD_NONNULL nodes, SerdNodeType type, SerdStringView string); /** Make a string node. A new node will be added if an equivalent node is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_string(SerdNodes* SERD_NONNULL nodes, SerdStringView string); /** Make a URI node from a string. A new node will be constructed with serd_node_construct_token() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_uri(SerdNodes* SERD_NONNULL nodes, SerdStringView string); /** Make a URI node from a parsed URI. A new node will be constructed with serd_node_construct_uri() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_parsed_uri(SerdNodes* SERD_NONNULL nodes, SerdURIView uri); /** Make a file URI node from a path and optional hostname. A new node will be constructed with serd_node_construct_file_uri() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_file_uri(SerdNodes* SERD_NONNULL nodes, SerdStringView path, SerdStringView hostname); /** Make a literal node with optional datatype or language. This can create complex literals with an associated datatype URI or language tag, and control whether a literal should be written as a short or long (triple-quoted) string. @param nodes The node set to get this literal from. @param string The string value of the literal. @param flags Flags to describe the literal and its metadata. Note that at most one of #SERD_HAS_DATATYPE and #SERD_HAS_LANGUAGE may be set. @param meta The string value of the literal's metadata. If #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If #SERD_HAS_LANGUAGE is set, then this must be an RFC 5646 language tag like "en-ca". Otherwise, it is ignored. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_literal(SerdNodes* SERD_NONNULL nodes, SerdStringView string, SerdNodeFlags flags, SerdStringView meta); /** Make a canonical value node. A new node will be constructed with serd_node_construct_value() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_value(SerdNodes* SERD_NONNULL nodes, SerdValue value); /** Make a canonical xsd:decimal node. A new node will be constructed with serd_node_construct_decimal() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_decimal(SerdNodes* SERD_NONNULL nodes, double value); /** Make a canonical xsd:integer node. A new node will be constructed with serd_node_construct_integer() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_integer(SerdNodes* SERD_NONNULL nodes, int64_t value); /** Make a canonical xsd:hexBinary node. A new node will be constructed with serd_node_construct_hex() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_hex(SerdNodes* SERD_NONNULL nodes, const void* SERD_NONNULL value, size_t value_size); /** Make a canonical xsd:base64Binary node. A new node will be constructed with serd_node_construct_base64() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_base64(SerdNodes* SERD_NONNULL nodes, const void* SERD_NONNULL value, size_t value_size); /** Make a blank node. A new node will be constructed with serd_node_construct_token() if an equivalent one is not already in the set. */ SERD_API const SerdNode* SERD_ALLOCATED serd_nodes_blank(SerdNodes* SERD_NONNULL nodes, SerdStringView string); /** 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 equivalent to `node` is stored in `nodes`. */ SERD_API void serd_nodes_deref(SerdNodes* SERD_NONNULL nodes, const SerdNode* SERD_NULLABLE node); /** @} @defgroup serd_caret Caret @{ */ /// The origin of a statement in a text document typedef struct SerdCaretImpl SerdCaret; /** Create a new caret. Note that, to minimise model overhead, the caret does not own the name node, so `name` must have a longer lifetime than the caret for it to be valid. That is, serd_caret_name() will return exactly the pointer `name`, not a copy. @param allocator Allocator to use for caret memory. @param name The name of the document or stream (usually a file URI) @param line The line number in the document (1-based) @param col The column number in the document (1-based) @return A new caret that must be freed with serd_caret_free() */ SERD_API SerdCaret* SERD_ALLOCATED serd_caret_new(SerdAllocator* SERD_NULLABLE allocator, const SerdNode* SERD_NONNULL name, unsigned line, unsigned col); /// Return a copy of `caret` SERD_API SerdCaret* SERD_ALLOCATED serd_caret_copy(SerdAllocator* SERD_NULLABLE allocator, const SerdCaret* SERD_NULLABLE caret); /// Free `caret` SERD_API void serd_caret_free(SerdAllocator* SERD_NULLABLE allocator, SerdCaret* SERD_NULLABLE caret); /// Return true iff `lhs` is equal to `rhs` SERD_PURE_API bool serd_caret_equals(const SerdCaret* SERD_NULLABLE lhs, const SerdCaret* SERD_NULLABLE rhs); /** Return the document name. This is typically a file URI, but may be a descriptive string node for statements that originate from streams. */ SERD_PURE_API const SerdNode* SERD_NONNULL serd_caret_name(const SerdCaret* SERD_NONNULL caret); /// Return the one-relative line number in the document SERD_PURE_API unsigned serd_caret_line(const SerdCaret* SERD_NONNULL caret); /// Return the zero-relative column number in the line SERD_PURE_API unsigned serd_caret_column(const SerdCaret* SERD_NONNULL caret); /** @} @defgroup serd_statement Statement @{ */ /// A subject, predicate, and object, with optional graph context typedef struct SerdStatementImpl SerdStatement; /// Index of a node in a statement typedef enum { SERD_SUBJECT = 0, ///< Subject SERD_PREDICATE = 1, ///< Predicate ("key") SERD_OBJECT = 2, ///< Object ("value") SERD_GRAPH = 3, ///< Graph ("context") } SerdField; /** Create a new statement. Note that, to minimise model overhead, statements do not own their nodes, so they must have a longer lifetime than the statement for it to be valid. For statements in models, this is the lifetime of the model. For user-created statements, the simplest way to handle this is to use `SerdNodes`. @param allocator Allocator to use for statement memory. @param s The subject @param p The predicate ("key") @param o The object ("value") @param g The graph ("context") @param caret Optional caret at the origin of this statement @return A new statement that must be freed with serd_statement_free() */ SERD_API SerdStatement* SERD_ALLOCATED serd_statement_new(SerdAllocator* SERD_NULLABLE allocator, const SerdNode* SERD_NONNULL s, const SerdNode* SERD_NONNULL p, const SerdNode* SERD_NONNULL o, const SerdNode* SERD_NULLABLE g, const SerdCaret* SERD_NULLABLE caret); /// Return a copy of `statement` SERD_API SerdStatement* SERD_ALLOCATED serd_statement_copy(SerdAllocator* SERD_NULLABLE allocator, const SerdStatement* SERD_NULLABLE statement); /// Free `statement` SERD_API void serd_statement_free(SerdAllocator* SERD_NULLABLE allocator, SerdStatement* SERD_NULLABLE statement); /// Return the given node of the statement SERD_PURE_API const SerdNode* SERD_NULLABLE serd_statement_node(const SerdStatement* SERD_NONNULL statement, SerdField field); /// Return the subject of the statement SERD_PURE_API const SerdNode* SERD_NONNULL serd_statement_subject(const SerdStatement* SERD_NONNULL statement); /// Return the predicate of the statement SERD_PURE_API const SerdNode* SERD_NONNULL serd_statement_predicate(const SerdStatement* SERD_NONNULL statement); /// Return the object of the statement SERD_PURE_API const SerdNode* SERD_NONNULL serd_statement_object(const SerdStatement* SERD_NONNULL statement); /// Return the graph of the statement SERD_PURE_API const SerdNode* SERD_NULLABLE serd_statement_graph(const SerdStatement* SERD_NONNULL statement); /// Return the source location where the statement originated, or NULL SERD_PURE_API const SerdCaret* SERD_NULLABLE serd_statement_caret(const SerdStatement* SERD_NONNULL statement); /** Return true iff `a` is equal to `b`, ignoring statement caret metadata. Only returns true if nodes are equivalent, does not perform wildcard matching. */ SERD_PURE_API bool serd_statement_equals(const SerdStatement* SERD_NULLABLE a, const SerdStatement* SERD_NULLABLE b); /** Return true iff the statement matches the given pattern. Nodes match if they are equivalent, or if one of them is NULL. The statement matches if every node matches. */ SERD_PURE_API bool serd_statement_matches(const SerdStatement* SERD_NONNULL statement, const SerdNode* SERD_NULLABLE subject, const SerdNode* SERD_NULLABLE predicate, const SerdNode* SERD_NULLABLE object, const SerdNode* SERD_NULLABLE graph); /** @} @} @defgroup serd_world World @{ */ /// Global library state typedef struct SerdWorldImpl SerdWorld; /** 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(SerdAllocator* SERD_NULLABLE allocator); /// Free `world` SERD_API void serd_world_free(SerdWorld* SERD_NULLABLE world); /// Return the allocator used by `world` SERD_PURE_API SerdAllocator* SERD_NONNULL serd_world_allocator(const SerdWorld* SERD_NONNULL 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 additional nodes which will be freed when the world is freed. */ SERD_PURE_API SerdNodes* SERD_NONNULL serd_world_nodes(SerdWorld* SERD_NONNULL world); /** 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. */ SERD_API const SerdNode* SERD_NONNULL serd_world_get_blank(SerdWorld* SERD_NONNULL world); /** @} @defgroup serd_logging Logging @{ */ /// Log entry level, compatible with syslog typedef enum { SERD_LOG_LEVEL_EMERGENCY, ///< Emergency, system is unusable SERD_LOG_LEVEL_ALERT, ///< Action must be taken immediately SERD_LOG_LEVEL_CRITICAL, ///< Critical condition SERD_LOG_LEVEL_ERROR, ///< Error SERD_LOG_LEVEL_WARNING, ///< Warning SERD_LOG_LEVEL_NOTICE, ///< Normal but significant condition SERD_LOG_LEVEL_INFO, ///< Informational message SERD_LOG_LEVEL_DEBUG ///< Debug message } SerdLogLevel; /** A structured log field. Fields are used to add metadata to log messages. Syslog-compatible keys should be used where possible, otherwise, keys should be namespaced to prevent clashes. Serd itself uses the following keys: - ERRNO - The `errno` of the original system error if any (decimal string) - SERD_COL - The 1-based column number in the file (decimal string) - SERD_FILE - The file which caused this message (string) - SERD_LINE - The 1-based line number in the file (decimal string) */ typedef struct { const char* SERD_NONNULL key; ///< Field name const char* SERD_NONNULL value; ///< Field value } SerdLogField; /** Function for handling log messages. By default, the log is printed to `stderr`. This can be overridden by passing a function of this type to serd_set_log_func(). @param handle Pointer to opaque user data. @param level Log level. @param n_fields Number of entries in `fields`. @param fields An array of `n_fields` extra log fields. @param message Log message. */ typedef SerdStatus (*SerdLogFunc)(void* SERD_NULLABLE handle, SerdLogLevel level, size_t n_fields, const SerdLogField* SERD_NULLABLE fields, SerdStringView message); /// A #SerdLogFunc that does nothing (for suppressing log output) SERD_CONST_API SerdStatus serd_quiet_log_func(void* SERD_NULLABLE handle, SerdLogLevel level, size_t n_fields, const SerdLogField* SERD_NULLABLE fields, SerdStringView message); /** Set a function to be called with log messages (typically errors). If no custom logging function is set, then messages are printed to stderr. @param world World that will send log entries to the given function. @param log_func Log function to call for every log message. Each call to this function represents a complete log message with an implicit trailing newline. @param handle Opaque handle that will be passed to every invocation of `log_func`. */ SERD_API void serd_set_log_func(SerdWorld* SERD_NONNULL world, SerdLogFunc SERD_NULLABLE log_func, void* SERD_NULLABLE handle); /** Write a message to the log with a `va_list`. This is the fundamental and most powerful function for writing entries to the log, the others are convenience wrappers that ultimately call this. This writes a single complete entry to the log, and so may not be used to print parts of a line like a more general printf-like function. There should be no trailing newline in `fmt`. Arguments following `fmt` should correspond to conversion specifiers in the format string as in printf from the standard C library. @param world World to log to. @param level Log level. @param n_fields Number of entries in `fields`. @param fields An array of `n_fields` extra log fields. @param fmt Format string. @param args Arguments for `fmt`. @return A status code, which is always #SERD_SUCCESS with the default log function. If a custom log function is set with serd_set_log_func() and it returns an error, then that error is returned here. */ SERD_API SERD_LOG_FUNC(5, 0) SerdStatus serd_vxlogf(const SerdWorld* SERD_NONNULL world, SerdLogLevel level, size_t n_fields, const SerdLogField* SERD_NULLABLE fields, const char* SERD_NONNULL fmt, va_list args); /** Write a message to the log with extra fields. This is a convenience wrapper for serd_vxlogf() that takes the format arguments directly. */ SERD_API SERD_LOG_FUNC(5, 6) SerdStatus serd_xlogf(const SerdWorld* SERD_NONNULL world, SerdLogLevel level, size_t n_fields, const SerdLogField* SERD_NULLABLE fields, const char* SERD_NONNULL fmt, ...); /** Write a simple message to the log. This is a convenience wrapper for serd_vxlogf() which sets no extra fields. */ SERD_API SERD_LOG_FUNC(3, 0) SerdStatus serd_vlogf(const SerdWorld* SERD_NONNULL world, SerdLogLevel level, const char* SERD_NONNULL fmt, va_list args); /** Write a simple message to the log. This is a convenience wrapper for serd_vlogf() that takes the format arguments directly. */ SERD_API SERD_LOG_FUNC(3, 4) SerdStatus serd_logf(const SerdWorld* SERD_NONNULL world, SerdLogLevel level, const char* SERD_NONNULL fmt, ...); /** Write a message to the log with a caret position. This is a convenience wrapper for serd_vxlogf() which sets `SERD_FILE`, `SERD_LINE`, and `SERD_COL` to the position of the given caret. Entries are typically printed with a GCC-style prefix like "file.ttl:16:4". */ SERD_API SERD_LOG_FUNC(4, 0) SerdStatus serd_vlogf_at(const SerdWorld* SERD_NONNULL world, SerdLogLevel level, const SerdCaret* SERD_NULLABLE caret, const char* SERD_NONNULL fmt, va_list args); /** Write a message to the log with a caret position. This is a convenience wrapper for serd_vlogf_at() that takes the format arguments directly. */ SERD_API SERD_LOG_FUNC(4, 5) SerdStatus serd_logf_at(const SerdWorld* SERD_NONNULL world, SerdLogLevel level, const SerdCaret* SERD_NULLABLE caret, const char* SERD_NONNULL fmt, ...); /** @} @} @defgroup serd_streaming Data Streaming @{ */ /** @defgroup serd_event Events @{ */ /// Type of a SerdEvent typedef enum { SERD_BASE = 1, ///< Base URI changed SERD_PREFIX = 2, ///< New URI prefix SERD_STATEMENT = 3, ///< Statement SERD_END = 4 ///< End of anonymous node } SerdEventType; /// Flags indicating inline abbreviation information for a statement typedef enum { SERD_EMPTY_S = 1u << 0u, ///< Empty blank node subject SERD_EMPTY_G = 1u << 1u, ///< Empty blank node graph SERD_ANON_S = 1u << 2u, ///< Start of anonymous subject SERD_ANON_O = 1u << 3u, ///< Start of anonymous object SERD_LIST_S = 1u << 4u, ///< Start of list subject SERD_LIST_O = 1u << 5u, ///< Start of list object SERD_TERSE_S = 1u << 6u, ///< Start of terse subject SERD_TERSE_O = 1u << 7u ///< Start of terse object } SerdStatementFlag; /// Bitwise OR of SerdStatementFlag values typedef uint32_t SerdStatementFlags; /** Event for base URI changes. Emitted whenever the base URI changes. */ typedef struct { SerdEventType type; ///< #SERD_BASE const SerdNode* SERD_NONNULL uri; ///< Base URI } SerdBaseEvent; /** Event for namespace definitions. Emitted whenever a prefix is defined. */ typedef struct { SerdEventType type; ///< #SERD_PREFIX const SerdNode* SERD_NONNULL name; ///< Prefix name const SerdNode* SERD_NONNULL uri; ///< Namespace URI } SerdPrefixEvent; /** Event for statements. Emitted for every statement. */ typedef struct { SerdEventType type; ///< #SERD_STATEMENT SerdStatementFlags flags; ///< Flags for pretty-printing const SerdStatement* SERD_NONNULL statement; ///< Statement } SerdStatementEvent; /** Event for the end of anonymous node descriptions. This is emitted to indicate that the given anonymous node will no longer be described. This is used by the writer which may, for example, need to write a delimiter. */ typedef struct { SerdEventType type; ///< #SERD_END const SerdNode* SERD_NONNULL node; ///< Anonymous node that is finished } SerdEndEvent; /** An event in a data stream. Streams of data are represented as a series of events. Events represent everything that can occur in an RDF document, and are used to plumb together different components. For example, when parsing a document, a reader emits a stream of events which can be sent to a writer to rewrite a document, or to an inserter to build a model in memory. */ typedef union { SerdEventType type; ///< Event type (always set) SerdBaseEvent base; ///< Base URI changed SerdPrefixEvent prefix; ///< New namespace prefix SerdStatementEvent statement; ///< Statement SerdEndEvent end; ///< End of anonymous node } SerdEvent; /// Function for handling events typedef SerdStatus (*SerdEventFunc)(void* SERD_NULLABLE handle, const SerdEvent* SERD_NONNULL event); /** @} @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. @param world The world the new sink will be a part of. @param handle Opaque handle that will be passed to sink functions. @param event_func Function that will be called for every event. @param free_handle Free function to call on handle in serd_sink_free(). */ SERD_API SerdSink* SERD_ALLOCATED serd_sink_new(const SerdWorld* SERD_NONNULL world, void* SERD_NULLABLE handle, SerdEventFunc SERD_NULLABLE event_func, SerdFreeFunc SERD_NULLABLE free_handle); /// Free `sink` SERD_API void serd_sink_free(SerdSink* SERD_NULLABLE sink); /// Send an event to the sink SERD_API SerdStatus serd_sink_write_event(const SerdSink* SERD_NONNULL sink, const SerdEvent* SERD_NONNULL event); /// 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 SERD_API SerdStatus serd_sink_write_statement(const SerdSink* SERD_NONNULL sink, SerdStatementFlags flags, const SerdStatement* SERD_NONNULL statement); /// 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_canon Canon @{ */ /// Flags that control canonical node transformation typedef enum { SERD_CANON_LAX = 1u << 0u, ///< Tolerate and pass through invalid input } SerdCanonFlag; /// Bitwise OR of SerdCanonFlag values typedef uint32_t SerdCanonFlags; /** Return a new sink that transforms literals to canonical form where possible. The returned sink acts like `target` in all respects, except literal nodes in statements may be modified from the original. */ SERD_API SerdSink* SERD_ALLOCATED serd_canon_new(const SerdWorld* SERD_NONNULL world, const SerdSink* SERD_NONNULL target, SerdCanonFlags flags); /** @} @defgroup serd_filter Filter @{ */ /** Return a new sink that filters out statements that do not match a pattern. The returned sink acts like `target` in all respects, except that some statements may be dropped. @param world The world the new sink will be a part of. @param target The target sink to pass the filtered data to. @param subject The optional subject of the filter pattern. @param predicate The optional predicate of the filter pattern. @param object The optional object of the filter pattern. @param graph The optional graph of the filter pattern. @param inclusive If true, then only statements that match the pattern are passed through. Otherwise, only statements that do *not* match the pattern are passed through. */ SERD_API SerdSink* SERD_ALLOCATED serd_filter_new(const SerdWorld* SERD_NONNULL world, const SerdSink* SERD_NONNULL target, const SerdNode* SERD_NULLABLE subject, const SerdNode* SERD_NULLABLE predicate, const SerdNode* SERD_NULLABLE object, const SerdNode* SERD_NULLABLE graph, bool inclusive); /** @} @} @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(SerdWorld* SERD_NONNULL world, SerdStringView base_uri); /// Copy an environment SERD_API SerdEnv* SERD_ALLOCATED serd_env_copy(SerdAllocator* SERD_NULLABLE allocator, const SerdEnv* SERD_NULLABLE env); /// Return true iff `a` is equal to `b` SERD_PURE_API bool serd_env_equals(const SerdEnv* SERD_NULLABLE a, const SerdEnv* SERD_NULLABLE b); /// 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 prefix and suffix (like a CURIE) if possible. @param env Environment with prefixes to use. @param uri URI to qualify. @param prefix On success, pointed to a prefix string slice, which is only valid until the next time `env` is mutated. @param suffix On success, pointed to a suffix string slice, which is only valid until the next time `env` is mutated. @return #SERD_SUCCESS, or #SERD_FAILURE if `uri` can not be qualified with `env`. */ SERD_API SerdStatus serd_env_qualify(const SerdEnv* SERD_NULLABLE env, SerdStringView uri, SerdStringView* SERD_NONNULL prefix, SerdStringView* SERD_NONNULL suffix); /** Expand `curie` to an absolute URI if possible. For example, if `env` has the prefix "rdf" set to , then calling this with curie "rdf:type" will produce . Returns null if `node` can not be expanded. */ SERD_API SerdNode* SERD_ALLOCATED serd_env_expand_curie(const SerdEnv* SERD_NULLABLE env, SerdStringView curie); /** Expand `node` to an absolute URI if possible. 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_NULLABLE node); /// Write all prefixes in `env` to `sink` SERD_API void serd_env_write_prefixes(const SerdEnv* SERD_NONNULL env, const SerdSink* SERD_NONNULL sink); /** Create a node from a string representation in `syntax`. The string should be a node as if written as an object in the given syntax, without any extra quoting or punctuation, which is the format returned by serd_node_to_syntax(). These two functions, when used with #SERD_TURTLE, can be used to round-trip any node to a string and back. @param allocator Allocator used for the returned node, and any temporary objects if `env` is null. @param str String representation of a node. @param syntax Syntax to use. Should be either SERD_TURTLE or SERD_NTRIPLES (the others are redundant). Note that namespaced (CURIE) nodes and relative URIs can not be expressed in NTriples. @param env Environment of `str`. This must define any abbreviations needed to parse the string. @return A newly allocated node that must be freed with serd_node_free() using the world allocator. */ SERD_API SerdNode* SERD_ALLOCATED serd_node_from_syntax(SerdAllocator* SERD_NULLABLE allocator, const char* SERD_NONNULL str, SerdSyntax syntax, SerdEnv* SERD_NULLABLE env); /** Return a string representation of `node` in `syntax`. The returned string represents that node as if written as an object in the given syntax, without any extra quoting or punctuation. @param allocator Allocator used for the returned node, and any temporary objects if `env` is null. @param node Node to write as a string. @param syntax Syntax to use. Should be either SERD_TURTLE or SERD_NTRIPLES (the others are redundant). Note that namespaced (CURIE) nodes and relative URIs can not be expressed in NTriples. @param env Environment for the output string. This can be used to abbreviate things nicely by setting namespace prefixes. @return A newly allocated string that must be freed with serd_free() using the world allocator. */ SERD_API char* SERD_ALLOCATED serd_node_to_syntax(SerdAllocator* SERD_NULLABLE allocator, const SerdNode* SERD_NONNULL node, SerdSyntax syntax, const SerdEnv* SERD_NULLABLE env); /** @} @defgroup serd_syntax_io Reading and Writing @{ @defgroup serd_input_stream Input Streams An input stream is used for reading input as a raw stream of bytes. It is compatible with standard C `FILE` streams, but allows different functions to be provided for things like reading from a buffer or a socket. @{ */ /// An input stream that produces bytes typedef struct { void* SERD_NULLABLE stream; ///< Opaque parameter for functions SerdReadFunc SERD_NONNULL read; ///< Read bytes from input SerdErrorFunc SERD_NULLABLE error; ///< Stream error accessor SerdCloseFunc SERD_NULLABLE close; ///< Close input } SerdInputStream; /** Open a stream that reads from a provided function. @param read_func Function to read input. @param error_func Function used to detect errors. @param close_func Function to close the stream after reading is done. @param stream Opaque stream parameter for functions. @return An opened input stream, or all zeros on error. */ SERD_CONST_API SerdInputStream serd_open_input_stream(SerdReadFunc SERD_NONNULL read_func, SerdErrorFunc SERD_NONNULL error_func, SerdCloseFunc SERD_NULLABLE close_func, void* SERD_NULLABLE stream); /** Open a stream that reads from a string. The string pointer that position points to must remain valid until the stream is closed. This pointer serves as the internal stream state and will be mutated as the stream is used. @param position Pointer to a valid string pointer for use as stream state. @return An opened input stream, or all zeros on error. */ SERD_CONST_API SerdInputStream serd_open_input_string(const char* SERD_NONNULL* SERD_NONNULL position); /** Open a stream that reads from a file. An arbitrary `FILE*` can be used with serd_open_input_stream() as well, this convenience function opens the file properly for reading with serd, and sets flags for optimized I/O if possible. @param path Path of file to open and read from. */ SERD_API SerdInputStream serd_open_input_file(const char* SERD_NONNULL path); /** Close an input stream. This will call the close function, and reset the stream internally so that no further reads can be made. For convenience, this is safe to call on NULL, and safe to call several times on the same input. */ SERD_API SerdStatus serd_close_input(SerdInputStream* SERD_NULLABLE input); /** @} @defgroup serd_reader Reader @{ */ /// Streaming parser that reads a text stream and writes to a statement sink typedef struct SerdReaderImpl SerdReader; /// Reader options typedef enum { /** Tolerate invalid input where possible. This will attempt to ignore invalid input and continue reading. Invalid Unicode characters will be replaced with the replacement character, and various other syntactic problems will be ignored. If there are more severe problems, the reader will try to skip the statement and continue parsing. This should work reasonably well for line-based syntaxes like NTriples and NQuads, but abbreviated Turtle or TriG may not recover. Note that this flag should be used carefully, since it can result in data loss. */ SERD_READ_LAX = 1u << 0u, /** Support reading variable nodes. As an extension, serd supports reading variables nodes with SPARQL-like syntax, for example "?foo" or "$bar". This can be used for storing graph patterns and templates. */ SERD_READ_VARIABLES = 1u << 1u, /** Read relative URI references exactly without resolving them. Normally, the reader expands all relative URIs against the base URI. This flag disables that, so that URI references are passed to the sink exactly as they are in the input. */ SERD_READ_RELATIVE = 1u << 2u, /** Read blank node labels without adding a prefix unique to the document. Normally, the reader adds a prefix like "f1", "f2", and so on, to blank node labels, to separate the namespaces from separate input documents. This flag disables that, so that blank node labels will be read without any prefix added. Note that this flag should be used carefully, since it can result in data corruption. Specifically, if data from separate documents parsed with this flag is combined, the IDs from each document may clash. */ SERD_READ_GLOBAL = 1u << 3u, /** Read generated blank node labels exactly without adjusting them. Normally, the reader will adapt blank node labels in the input that clash with its scheme for generating new ones, for example mapping "_:b123" to "_:B123". This flag disables that, so that blank node labels are passed to the sink exactly as they are in the input. Note that this flag should be used carefully, since it can result in data corruption. Specifically, if the input is a syntax like Turtle with anonymous nodes, the generated IDs for those nodes may clash with IDs from the input document. */ SERD_READ_GENERATED = 1u << 4u, } SerdReaderFlag; /// Bitwise OR of SerdReaderFlag values typedef uint32_t SerdReaderFlags; /// Create a new RDF reader SERD_API SerdReader* SERD_ALLOCATED serd_reader_new(SerdWorld* SERD_NONNULL world, SerdSyntax syntax, SerdReaderFlags flags, SerdEnv* SERD_NONNULL env, const SerdSink* SERD_NONNULL sink, size_t stack_size); /** Prepare to read some input. This sets up the reader to read from the given input, but will not read any bytes from it. This should be followed by serd_reader_read_chunk() or serd_reader_read_document() to actually read the input. @param reader The reader. @param input An opened input stream to read from. @param input_name The name of the input stream for error messages. @param block_size The number of bytes to read from the stream at once. */ SERD_API SerdStatus serd_reader_start(SerdReader* SERD_NONNULL reader, SerdInputStream* SERD_NONNULL input, const SerdNode* SERD_NULLABLE input_name, size_t block_size); /** 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_buffer Buffer The #SerdBuffer type represents a writable area of memory with a known size. An implementation of #SerdWriteFunc, #SerdErrorFunc, and #SerdCloseFunc are provided which allow output to be written to a buffer in memory instead of to a file as with `fwrite`, `ferror`, and `fclose`. @{ */ /// A dynamically resizable mutable buffer in memory typedef struct { SerdAllocator* SERD_NULLABLE allocator; ///< Allocator for buf void* SERD_NULLABLE buf; ///< Buffer size_t len; ///< Size of buffer in bytes } SerdBuffer; /** A function for writing to a buffer, resizing it if necessary. This function can be used as a #SerdWriteFunc to write to a #SerdBuffer which is reallocated as necessary. The `stream` parameter must point to an initialized #SerdBuffer. Note that when writing a string, the string in the buffer will not be null-terminated until serd_buffer_close() is called. */ SERD_API size_t serd_buffer_write(const void* SERD_NONNULL buf, size_t size, size_t nmemb, void* SERD_NONNULL stream); /** Close the buffer for writing. This writes a terminating null byte, so the contents of the buffer are safe to read as a string after this call. */ SERD_API int serd_buffer_close(void* SERD_NONNULL stream); /** @} @defgroup serd_output_stream Output Streams An output stream is used for writing output as a raw stream of bytes. It is compatible with standard C `FILE` streams, but allows different functions to be provided for things like writing to a buffer or a socket. @{ */ /// An output stream that receives bytes typedef struct { void* SERD_NULLABLE stream; ///< Opaque parameter for functions SerdWriteFunc SERD_NONNULL write; ///< Write bytes to output SerdErrorFunc SERD_NULLABLE error; ///< Stream error accessor SerdCloseFunc SERD_NULLABLE close; ///< Close output } SerdOutputStream; /** Open a stream that writes to a provided function. @param write_func Function to write output. @param error_func Function used to detect errors. @param close_func Function to close the stream after writing is done. @param stream Opaque stream parameter for write_func and close_func. @return An opened output stream, or all zeros on error. */ SERD_CONST_API SerdOutputStream serd_open_output_stream(SerdWriteFunc SERD_NONNULL write_func, SerdErrorFunc SERD_NULLABLE error_func, SerdCloseFunc SERD_NULLABLE close_func, void* SERD_NULLABLE stream); /** Open a stream that writes to a buffer. The `buffer` is owned by the caller, but will be reallocated using the buffer's allocator as necessary. Note that the string in the buffer will not be null terminated until the stream is closed. @param buffer Buffer to write output to. @return An opened output stream, or all zeros on error. */ SERD_CONST_API SerdOutputStream serd_open_output_buffer(SerdBuffer* SERD_NONNULL buffer); /** Open a stream that writes to a file. An arbitrary `FILE*` can be used with serd_open_output_stream() as well, this convenience function opens the file properly for writing with serd, and sets flags for optimized I/O if possible. @param path Path of file to open and write to. */ SERD_API SerdOutputStream serd_open_output_file(const char* SERD_NONNULL path); /** Close an output stream. This will call the close function, and reset the stream internally so that no further writes can be made. For convenience, this is safe to call on NULL, and safe to call several times on the same output. Failure is returned in both of those cases. */ SERD_API SerdStatus serd_close_output(SerdOutputStream* SERD_NULLABLE output); /** @} @defgroup serd_writer Writer @{ */ /// Streaming writer that writes a text stream as it receives events 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 { /** Escape all non-ASCII characters. Although all the supported syntaxes are UTF-8 by definition, this can be used to escape all non-ASCII characters so that data will survive transmission through ASCII-only channels. */ SERD_WRITE_ASCII = 1u << 0u, /** Write expanded URIs instead of prefixed names. This will avoid shortening URIs into CURIEs entirely, even if the output syntax supports prefixed names. This can be useful for making chunks of syntax context-free. */ SERD_WRITE_EXPANDED = 1u << 1u, /** Write URI references exactly as they are received. Normally, the writer resolves URIs against the base URI, so it can potentially writem them as relative URI references. This flag disables that, so URI nodes are written exactly as they are received. When fed by a reader with #SERD_READ_RELATIVE enabled, this will write URI references exactly as they are in the input. */ SERD_WRITE_VERBATIM = 1u << 2u, /** Write terser output without newlines. For Turtle and TriG, this enables a terser form of output which only has newlines at the top level. This can result in very long lines, but is more compact and useful for making these abbreviated syntaxes line-based. */ SERD_WRITE_TERSE = 1u << 3u, /** Tolerate lossy output. This will tolerate input that can not be written without loss, in particular invalid UTF-8 text. Note that this flag should be used carefully, since it can result in data loss. */ SERD_WRITE_LAX = 1u << 4u, /** Write rdf:type as a normal predicate. This disables the special "a" syntax in Turtle and TriG. */ SERD_WRITE_RDF_TYPE = 1u << 5u, /** Suppress writing directives that describe the context. This writes data as usual, but suppresses writing `prefix` directives in Turtle and TriG. The resulting output is a fragment of a document with implicit context, so it will only be readable in a suitable enviromnent. */ SERD_WRITE_CONTEXTUAL = 1u << 6u } 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, const SerdEnv* SERD_NONNULL env, SerdOutputStream* SERD_NONNULL output, size_t block_size); /// 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); /** 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, SerdStringView 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); /** @} @} @defgroup serd_storage Storage @{ */ /** @defgroup serd_cursor Cursor @{ */ /** A cursor that iterates over statements in a model. A cursor is a smart iterator that visits all statements that match a pattern. */ typedef struct SerdCursorImpl SerdCursor; /// Return a new copy of `cursor` SERD_API SerdCursor* SERD_ALLOCATED serd_cursor_copy(SerdAllocator* SERD_NULLABLE allocator, const SerdCursor* SERD_NULLABLE cursor); /// Return the statement pointed to by `cursor` SERD_API const SerdStatement* SERD_NULLABLE serd_cursor_get(const SerdCursor* SERD_NULLABLE cursor); /** Increment cursor to point to the next statement. @return Failure if `cursor` was already at the end. */ SERD_API SerdStatus serd_cursor_advance(SerdCursor* SERD_NONNULL cursor); /// Return true if the cursor has reached its end SERD_PURE_API bool serd_cursor_is_end(const SerdCursor* SERD_NULLABLE cursor); /** Return true iff `lhs` equals `rhs`. Two cursors are equivalent if they point to the same statement in the same index in the same model, or are both the end of the same model. Note that two cursors can point to the same statement but not be equivalent, since they may have reached the statement via different indices. */ SERD_PURE_API bool serd_cursor_equals(const SerdCursor* SERD_NULLABLE lhs, const SerdCursor* SERD_NULLABLE rhs); /// Free `cursor` SERD_API void serd_cursor_free(SerdCursor* SERD_NULLABLE cursor); /** @} @defgroup serd_range Range @{ */ /// Flags that control the style of a model serialisation typedef enum { SERD_NO_TYPE_FIRST = 1u << 0u ///< Disable writing rdf:type ("a") first } SerdDescribeFlag; /// Bitwise OR of SerdDescribeFlag values typedef uint32_t SerdDescribeFlags; /** Describe a range of statements by writing to a sink. This will consume the given cursor, and emit at least every statement it visits. More statements from the model may be written in order to describe anonymous blank nodes that are associated with a subject in the range. The default is to write statements in an order suited for pretty-printing with Turtle or TriG with as many anonymous nodes as possible. If `SERD_NO_INLINE_OBJECTS` is given, a simple sorted stream is written instead, which is faster since no searching is required, but can result in ugly output for Turtle or Trig. */ SERD_API SerdStatus serd_describe_range(const SerdCursor* SERD_NULLABLE range, const SerdSink* SERD_NONNULL sink, SerdDescribeFlags flags); /** @} @defgroup serd_model Model @{ */ /// An indexed set of statements typedef struct SerdModelImpl SerdModel; /** Statement ordering. Statements themselves always have the same fields in the same order (subject, predicate, object, graph), but a model can keep indices for different orderings to provide good performance for different kinds of queries. */ typedef enum { SERD_ORDER_SPO, ///< Subject, Predicate, Object SERD_ORDER_SOP, ///< Subject, Object, Predicate SERD_ORDER_OPS, ///< Object, Predicate, Subject SERD_ORDER_OSP, ///< Object, Subject, Predicate SERD_ORDER_PSO, ///< Predicate, Subject, Object SERD_ORDER_POS, ///< Predicate, Object, Subject SERD_ORDER_GSPO, ///< Graph, Subject, Predicate, Object SERD_ORDER_GSOP, ///< Graph, Subject, Object, Predicate SERD_ORDER_GOPS, ///< Graph, Object, Predicate, Subject SERD_ORDER_GOSP, ///< Graph, Object, Subject, Predicate SERD_ORDER_GPSO, ///< Graph, Predicate, Subject, Object SERD_ORDER_GPOS ///< Graph, Predicate, Object, Subject } SerdStatementOrder; /// Flags that control model storage and indexing typedef enum { SERD_STORE_GRAPHS = 1u << 0u, ///< Store and index the graph of statements SERD_STORE_CARETS = 1u << 1u, ///< Store original caret of statements } SerdModelFlag; /// Bitwise OR of SerdModelFlag values typedef uint32_t SerdModelFlags; /** Create a new model. @param world The world in which to make this model. @param default_order The order for the default index, which is always present and responsible for owning all the statements in the model. This should almost always be #SERD_ORDER_SPO or #SERD_ORDER_GSPO (which support writing pretty documents), but advanced applications that do not want either of these indices can use a different order. Additional indices can be added with serd_model_add_index(). @param flags Options that control what data is stored in the model. */ SERD_API SerdModel* SERD_ALLOCATED serd_model_new(SerdWorld* SERD_NONNULL world, SerdStatementOrder default_order, SerdModelFlags flags); /// Return a deep copy of `model` SERD_API SerdModel* SERD_ALLOCATED serd_model_copy(SerdAllocator* SERD_NULLABLE allocator, const SerdModel* SERD_NONNULL model); /// Return true iff `a` is equal to `b`, ignoring statement cursor metadata SERD_API bool serd_model_equals(const SerdModel* SERD_NULLABLE a, const SerdModel* SERD_NULLABLE b); /// Close and free `model` SERD_API void serd_model_free(SerdModel* SERD_NULLABLE model); /** Add an index for a particular statement order to the model. @return Failure if this index already exists. */ SERD_API SerdStatus serd_model_add_index(SerdModel* SERD_NONNULL model, SerdStatementOrder order); /** Add an index for a particular statement order to the model. @return Failure if this index does not exist. */ SERD_API SerdStatus serd_model_drop_index(SerdModel* SERD_NONNULL model, SerdStatementOrder order); /// Get the world associated with `model` SERD_PURE_API SerdWorld* SERD_NONNULL serd_model_world(SerdModel* SERD_NONNULL model); /// Get all nodes interned in `model` SERD_PURE_API const SerdNodes* SERD_NONNULL serd_model_nodes(const SerdModel* SERD_NONNULL model); /// Get the default statement order of `model` SERD_PURE_API SerdStatementOrder serd_model_default_order(const SerdModel* SERD_NONNULL model); /// Get the flags enabled on `model` SERD_PURE_API SerdModelFlags serd_model_flags(const SerdModel* SERD_NONNULL model); /// Return the number of statements stored in `model` SERD_PURE_API size_t serd_model_size(const SerdModel* SERD_NONNULL model); /// Return true iff there are no statements stored in `model` SERD_PURE_API bool serd_model_empty(const SerdModel* SERD_NONNULL model); /** Return a cursor at the start of every statement in the model. The returned cursor will advance over every statement in the model's default order. */ SERD_API SerdCursor* SERD_ALLOCATED serd_model_begin(const SerdModel* SERD_NONNULL model); /** Return a cursor past the end of the model. This returns the "universal" end cursor, which is equivalent to any cursor for this model that has reached its end. */ SERD_CONST_API const SerdCursor* SERD_NONNULL serd_model_end(const SerdModel* SERD_NONNULL model); /// Return a cursor over all statements in the model in a specific order SERD_API SerdCursor* SERD_ALLOCATED serd_model_begin_ordered(const SerdModel* SERD_NONNULL model, SerdStatementOrder order); /** Search for statements that match a pattern. @return An iterator to the first match, or NULL if no matches found. */ SERD_API SerdCursor* SERD_ALLOCATED serd_model_find(const SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE s, const SerdNode* SERD_NULLABLE p, const SerdNode* SERD_NULLABLE o, const SerdNode* SERD_NULLABLE g); /** Search for a single node that matches a pattern. Exactly one of `s`, `p`, `o` must be NULL. This function is mainly useful for predicates that only have one value. @return The first matching node, or NULL if no matches are found. */ SERD_API const SerdNode* SERD_NULLABLE serd_model_get(const SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE s, const SerdNode* SERD_NULLABLE p, const SerdNode* SERD_NULLABLE o, const SerdNode* SERD_NULLABLE g); /** Search for a single statement that matches a pattern. This function is mainly useful for predicates that only have one value. @return The first matching statement, or NULL if none are found. */ SERD_API const SerdStatement* SERD_NULLABLE serd_model_get_statement(const SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE s, const SerdNode* SERD_NULLABLE p, const SerdNode* SERD_NULLABLE o, const SerdNode* SERD_NULLABLE g); /// Return true iff a statement exists SERD_API bool serd_model_ask(const SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE s, const SerdNode* SERD_NULLABLE p, const SerdNode* SERD_NULLABLE o, const SerdNode* SERD_NULLABLE g); /// Return the number of matching statements SERD_API size_t serd_model_count(const SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE s, const SerdNode* SERD_NULLABLE p, const SerdNode* SERD_NULLABLE o, const SerdNode* SERD_NULLABLE g); /** Add a statement to a model from nodes. This function fails if there are any active iterators on `model`. */ SERD_API SerdStatus serd_model_add(SerdModel* SERD_NONNULL model, const SerdNode* SERD_NONNULL s, const SerdNode* SERD_NONNULL p, const SerdNode* SERD_NONNULL o, const SerdNode* SERD_NULLABLE g); /** Add a statement to a model from nodes with a caret This function fails if there are any active iterators on `model`. */ SERD_API SerdStatus serd_model_add_with_caret(SerdModel* SERD_NONNULL model, const SerdNode* SERD_NONNULL s, const SerdNode* SERD_NONNULL p, const SerdNode* SERD_NONNULL o, const SerdNode* SERD_NULLABLE g, const SerdCaret* SERD_NULLABLE caret); /** Add a statement to a model. This function fails if there are any active iterators on `model`. If statement is null, then SERD_FAILURE is returned. */ SERD_API SerdStatus serd_model_insert(SerdModel* SERD_NONNULL model, const SerdStatement* SERD_NONNULL statement); /** Add a range of statements to a model. This function fails if there are any active iterators on `model`. */ SERD_API SerdStatus serd_model_insert_statements(SerdModel* SERD_NONNULL model, SerdCursor* SERD_NONNULL range); /** Remove a statement from a model via an iterator. Calling this function invalidates all other iterators on this model. @param model The model which `iter` points to. @param cursor Cursor pointing to the element to erase. This cursor is advanced to the next statement on return. */ SERD_API SerdStatus serd_model_erase(SerdModel* SERD_NONNULL model, SerdCursor* SERD_NONNULL cursor); /** Remove a range of statements from a model. This can be used with serd_model_find() to erase all statements in a model that match a pattern. Calling this function invalidates all iterators on `model`. @param model The model which `range` points to. @param range Range to erase, which will be empty on return. */ SERD_API SerdStatus serd_model_erase_statements(SerdModel* SERD_NONNULL model, SerdCursor* SERD_NONNULL range); /** Remove everything from a model. Calling this function invalidates all iterators on `model`. @param model The model to clear. */ SERD_API SerdStatus serd_model_clear(SerdModel* SERD_NONNULL model); /** @} @defgroup serd_inserter Inserter @{ */ /** Create an inserter for writing statements to a model. Once created, an inserter is just a sink with no additional interface. @param model The model to insert received statements into. @param default_graph Optional default graph, which will be set on received statements that have no graph. This allows, for example, loading a Turtle document into an isolated graph in the model. @return A newly allocated sink which must be freed with serd_sink_free(). */ SERD_API SerdSink* SERD_ALLOCATED serd_inserter_new(SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE default_graph); /** @} @defgroup serd_validator Validator @{ */ /// Model validator typedef struct SerdValidatorImpl SerdValidator; /// A check that a validator can perform against a model typedef enum { /// Checks nothing and always succeeds (for use as a sentinel) SERD_CHECK_NOTHING, /** Checks that all properties with owl:allValuesFrom restrictions have valid value types. */ SERD_CHECK_ALL_VALUES_FROM, /// Checks that the value of any property with range xsd:anyURI is a URI SERD_CHECK_ANY_URI, /** Checks that any instance of a class with a owl:cardinality property restriction has exactly that many values of that property. */ SERD_CHECK_CARDINALITY_EQUAL, /** Checks that any instance of a class with a owl:maxCardinality property restriction has no more than that many values of that property. */ SERD_CHECK_CARDINALITY_MAX, /** Checks that any instance of a class with a owl:minCardinality property restriction has at least that many values of that property. */ SERD_CHECK_CARDINALITY_MIN, /** Checks that no class is a sub-class of itself, recursively. This ensures that the graph is acyclic with respect to rdfs:subClassOf. If this check fails, all further checks are aborted. */ SERD_CHECK_CLASS_CYCLE, /// Checks that every rdfs:Class has an rdfs:label SERD_CHECK_CLASS_LABEL, /** Checks that no datatype is a sub-datatype of itself, recursively. This ensures that the graph is acyclic with respect to owl:onDatatype. If this check fails, all further checks are aborted. */ SERD_CHECK_DATATYPE_CYCLE, /// Checks that datatype properties have literal (not instance) values SERD_CHECK_DATATYPE_PROPERTY, /// Checks that every datatype is defined as a rdfs:Datatype SERD_CHECK_DATATYPE_TYPE, /// Checks that there are no instances of deprecated classes SERD_CHECK_DEPRECATED_CLASS, /// Checks that there are no uses of deprecated properties SERD_CHECK_DEPRECATED_PROPERTY, /** Checks that every instance explicitly has every type required of it. This is a (often overly) strict check that assumes a closed world and requires every instance to explicitly have the type(s) required of it. */ SERD_CHECK_EXPLICIT_INSTANCE_TYPE, /// Checks that no instance has several values of a functional property SERD_CHECK_FUNCTIONAL_PROPERTY, /// Checks that there are no instances where a literal is expected SERD_CHECK_INSTANCE_LITERAL, /** Checks that every instance with an explicit type matches that type. This is a broad check that triggers other type-related checks, but mainly it will check that every instance of a class conforms to any restrictions on that class. */ SERD_CHECK_INSTANCE_TYPE, /** Checks that at most one instance has a given value of an inverse functional property. */ SERD_CHECK_INVERSE_FUNCTIONAL_PROPERTY, /// Checks that there are no literals where an instance is expected SERD_CHECK_LITERAL_INSTANCE, /** Checks that literal values are not greater than or equal to any applicable xsd:maxExclusive datatype restrictions. */ SERD_CHECK_LITERAL_MAX_EXCLUSIVE, /** Checks that literal values are not greater than any applicable xsd:maxInclusive datatype restrictions. */ SERD_CHECK_LITERAL_MAX_INCLUSIVE, /** Checks that literal values are not less than or equal to any applicable xsd:minExclusive datatype restrictions. */ SERD_CHECK_LITERAL_MIN_EXCLUSIVE, /** Checks that literal values are not less than any applicable xsd:minInclusive datatype restrictions. */ SERD_CHECK_LITERAL_MIN_INCLUSIVE, /** Checks that literals with xsd:pattern restrictions match the regular expression pattern for their datatype. */ SERD_CHECK_LITERAL_PATTERN, /** Checks that literals with supported restrictions conform to those restrictions. This is a high-level check that triggers the more specific individual literal restriction checks. */ SERD_CHECK_LITERAL_RESTRICTION, /** Checks that literals with supported XSD datatypes are valid. The set of supported types is the same as when writing canonical forms. */ SERD_CHECK_LITERAL_VALUE, /// Checks that object properties have instance (not literal) values SERD_CHECK_OBJECT_PROPERTY, /** Checks that there are no typed literals where a plain literal is expected. A plain literal may have an optional language tag, but not a datatype. */ SERD_CHECK_PLAIN_LITERAL_DATATYPE, /// Checks that every predicate is defined as an rdf:Property SERD_CHECK_PREDICATE_TYPE, /** Checks that no property is a sub-property of itself, recursively. This ensures that the graph is acyclic with respect to rdfs:subPropertyOf. If this check fails, all further checks are aborted. */ SERD_CHECK_PROPERTY_CYCLE, /** Checks that any instance with a property with an rdfs:domain is in that domain. */ SERD_CHECK_PROPERTY_DOMAIN, /// Checks that every rdf:Property has an rdfs:label SERD_CHECK_PROPERTY_LABEL, /** Checks that the value for any property with an rdfs:range is in that range. */ SERD_CHECK_PROPERTY_RANGE, /** Checks that instances of classes with owl:someValuesFrom property restrictions have at least one matching property value. */ SERD_CHECK_SOME_VALUES_FROM, } SerdValidatorCheck; /** Create a new validator. @return A newly-allocated validator with no checks enabled which must be freed with serd_validator_free(). */ SERD_MALLOC_API SerdValidator* SERD_ALLOCATED serd_validator_new(SerdWorld* SERD_NONNULL world); /// Free `validator` SERD_API void serd_validator_free(SerdValidator* SERD_NULLABLE validator); /// Enable a validator check SERD_API SerdStatus serd_validator_enable_check(SerdValidator* SERD_NONNULL validator, SerdValidatorCheck check); /// Disable a validator check SERD_API SerdStatus serd_validator_disable_check(SerdValidator* SERD_NONNULL validator, SerdValidatorCheck check); /// Enable all validator checks with names that match the given pattern SERD_API SerdStatus serd_validator_enable_checks(SerdValidator* SERD_NONNULL validator, const char* SERD_NONNULL regex); /// Disable all validator checks with names that match the given pattern SERD_API SerdStatus serd_validator_disable_checks(SerdValidator* SERD_NONNULL validator, const char* SERD_NONNULL regex); /** Validate a model. This performs validation based on the XSD, RDF, RDFS, and OWL vocabularies. All necessary data, including those vocabularies and any property/class definitions that use them, are assumed to be in the model. Validation errors are reported to the world's error sink. @param validator Validator configured to run the desired checks. @param model The model to validate. @param graph Optional graph to check. Is this is given, then top-level checks will be initiated only for statements in the given graph. The entire model is still searched while running a check so that, for example, schemas that define classes and properties can be stored in separate graphs. @param env Environment used to shorten URIs in log messages. @return #SERD_SUCCESS if no errors are found, or #SERD_BAD_DATA if validation checks failed. */ SERD_API SerdStatus serd_validate(SerdValidator* SERD_NONNULL const validator, const SerdModel* SERD_NONNULL model, const SerdNode* SERD_NULLABLE graph, const SerdEnv* SERD_NULLABLE env); /** @} @} @} */ #ifdef __cplusplus # if defined(__GNUC__) # pragma GCC diagnostic pop # endif } /* extern "C" */ #endif #endif /* SERD_SERD_H */