cannam@85: /* cannam@85: Copyright 2011-2012 David Robillard cannam@85: cannam@85: Permission to use, copy, modify, and/or distribute this software for any cannam@85: purpose with or without fee is hereby granted, provided that the above cannam@85: copyright notice and this permission notice appear in all copies. cannam@85: cannam@85: THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES cannam@85: WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF cannam@85: MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR cannam@85: ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES cannam@85: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN cannam@85: ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF cannam@85: OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. cannam@85: */ cannam@85: cannam@85: /** cannam@85: @file serd.h API for Serd, a lightweight RDF syntax library. cannam@85: */ cannam@85: cannam@85: #ifndef SERD_SERD_H cannam@85: #define SERD_SERD_H cannam@85: cannam@85: #include cannam@85: #include cannam@85: #include cannam@85: #include cannam@85: cannam@85: #ifdef SERD_SHARED cannam@85: # ifdef _WIN32 cannam@85: # define SERD_LIB_IMPORT __declspec(dllimport) cannam@85: # define SERD_LIB_EXPORT __declspec(dllexport) cannam@85: # else cannam@85: # define SERD_LIB_IMPORT __attribute__((visibility("default"))) cannam@85: # define SERD_LIB_EXPORT __attribute__((visibility("default"))) cannam@85: # endif cannam@85: # ifdef SERD_INTERNAL cannam@85: # define SERD_API SERD_LIB_EXPORT cannam@85: # else cannam@85: # define SERD_API SERD_LIB_IMPORT cannam@85: # endif cannam@85: #else cannam@85: # define SERD_API cannam@85: #endif cannam@85: cannam@85: #ifdef __cplusplus cannam@85: extern "C" { cannam@85: #else cannam@85: # include cannam@85: #endif cannam@85: cannam@85: /** cannam@85: @defgroup serd Serd cannam@85: A lightweight RDF syntax library. cannam@85: @{ cannam@85: */ cannam@85: cannam@85: /** cannam@85: Environment. cannam@85: cannam@85: Represents the state required to resolve a CURIE or relative URI, e.g. the cannam@85: base URI and set of namespace prefixes at a particular point. cannam@85: */ cannam@85: typedef struct SerdEnvImpl SerdEnv; cannam@85: cannam@85: /** cannam@85: RDF reader. cannam@85: cannam@85: Parses RDF by calling user-provided sink functions as input is consumed cannam@85: (much like an XML SAX parser). cannam@85: */ cannam@85: typedef struct SerdReaderImpl SerdReader; cannam@85: cannam@85: /** cannam@85: RDF writer. cannam@85: cannam@85: Provides a number of functions to allow writing RDF syntax out to some cannam@85: stream. These functions are deliberately compatible with the sink functions cannam@85: used by SerdReader, so a reader can be directly connected to a writer to cannam@85: re-serialise a document with minimal overhead. cannam@85: */ cannam@85: typedef struct SerdWriterImpl SerdWriter; cannam@85: cannam@85: /** cannam@85: Return status code. cannam@85: */ cannam@85: typedef enum { cannam@85: SERD_SUCCESS, /**< No error */ cannam@85: SERD_FAILURE, /**< Non-fatal failure */ cannam@85: SERD_ERR_UNKNOWN, /**< Unknown error */ cannam@85: SERD_ERR_BAD_SYNTAX, /**< Invalid syntax */ cannam@85: SERD_ERR_BAD_ARG, /**< Invalid argument */ cannam@85: SERD_ERR_NOT_FOUND, /**< Not found */ cannam@85: SERD_ERR_ID_CLASH, /**< Encountered clashing blank node IDs */ cannam@85: SERD_ERR_BAD_CURIE, /**< Invalid CURIE (e.g. prefix does not exist) */ cannam@85: SERD_ERR_INTERNAL /**< Unexpected internal error (should not happen) */ cannam@85: } SerdStatus; cannam@85: cannam@85: /** cannam@85: RDF syntax type. cannam@85: */ cannam@85: typedef enum { cannam@85: /** cannam@85: Turtle - Terse RDF Triple Language (UTF-8). cannam@85: @see Turtle cannam@85: */ cannam@85: SERD_TURTLE = 1, cannam@85: cannam@85: /** cannam@85: NTriples - Line-based RDF triples (ASCII). cannam@85: @see NTriples cannam@85: */ cannam@85: SERD_NTRIPLES = 2 cannam@85: } SerdSyntax; cannam@85: cannam@85: /** cannam@85: Flags indication inline abbreviation information for a statement. cannam@85: */ cannam@85: typedef enum { cannam@85: SERD_EMPTY_S = 1 << 1, /**< Empty blank node subject */ cannam@85: SERD_EMPTY_O = 1 << 2, /**< Empty blank node object */ cannam@85: SERD_ANON_S_BEGIN = 1 << 3, /**< Start of anonymous subject */ cannam@85: SERD_ANON_O_BEGIN = 1 << 4, /**< Start of anonymous object */ cannam@85: SERD_ANON_CONT = 1 << 5, /**< Continuation of anonymous node */ cannam@85: SERD_LIST_S_BEGIN = 1 << 6, /**< Start of list subject */ cannam@85: SERD_LIST_O_BEGIN = 1 << 7, /**< Start of list object */ cannam@85: SERD_LIST_CONT = 1 << 8 /**< Continuation of list */ cannam@85: } SerdStatementFlag; cannam@85: cannam@85: /** cannam@85: Bitwise OR of SerdNodeFlag values. cannam@85: */ cannam@85: typedef uint32_t SerdStatementFlags; cannam@85: cannam@85: /** cannam@85: Type of a syntactic RDF node. cannam@85: cannam@85: This is more precise than the type of an abstract RDF node. An abstract cannam@85: node is either a resource, literal, or blank. In syntax there are two ways cannam@85: to refer to a resource (by URI or CURIE) and two ways to refer to a blank cannam@85: (by ID or anonymously). Anonymous (inline) blank nodes are expressed using cannam@85: SerdStatementFlags rather than this type. cannam@85: */ cannam@85: typedef enum { cannam@85: /** cannam@85: The type of a nonexistent node. cannam@85: cannam@85: This type is useful as a sentinel, but is never emitted by the reader. cannam@85: */ cannam@85: SERD_NOTHING = 0, cannam@85: cannam@85: /** cannam@85: Literal value. cannam@85: cannam@85: A literal optionally has either a language, or a datatype (not both). cannam@85: */ cannam@85: SERD_LITERAL = 1, cannam@85: cannam@85: /** cannam@85: URI (absolute or relative). cannam@85: cannam@85: Value is an unquoted URI string, which is either a relative reference cannam@85: with respect to the current base URI (e.g. "foo/bar"), or an absolute cannam@85: URI (e.g. "http://example.org/foo"). cannam@85: @see RFC3986. cannam@85: */ cannam@85: SERD_URI = 2, cannam@85: cannam@85: /** cannam@85: CURIE, a shortened URI. cannam@85: cannam@85: Value is an unquoted CURIE string relative to the current environment, cannam@85: e.g. "rdf:type". cannam@85: @see CURIE Syntax 1.0 cannam@85: */ cannam@85: SERD_CURIE = 3, cannam@85: cannam@85: /** cannam@85: A blank node. cannam@85: cannam@85: Value is a blank node ID, e.g. "id3", which is meaningful only within cannam@85: this serialisation. cannam@85: @see Turtle cannam@85: nodeID cannam@85: */ cannam@85: SERD_BLANK = 4, cannam@85: cannam@85: } SerdType; cannam@85: cannam@85: /** cannam@85: Flags indicating certain string properties relevant to serialisation. cannam@85: */ cannam@85: typedef enum { cannam@85: SERD_HAS_NEWLINE = 1, /**< Contains line breaks ('\\n' or '\\r') */ cannam@85: SERD_HAS_QUOTE = 1 << 1 /**< Contains quotes ('"') */ cannam@85: } SerdNodeFlag; cannam@85: cannam@85: /** cannam@85: Bitwise OR of SerdNodeFlag values. cannam@85: */ cannam@85: typedef uint32_t SerdNodeFlags; cannam@85: cannam@85: /** cannam@85: A syntactic RDF node. cannam@85: */ cannam@85: typedef struct { cannam@85: const uint8_t* buf; /**< Value string */ cannam@85: size_t n_bytes; /**< Size in bytes (not including null) */ cannam@85: size_t n_chars; /**< Length in characters (not including null)*/ cannam@85: SerdNodeFlags flags; /**< Node flags (e.g. string properties) */ cannam@85: SerdType type; /**< Node type */ cannam@85: } SerdNode; cannam@85: cannam@85: /** cannam@85: An unterminated string fragment. cannam@85: */ cannam@85: typedef struct { cannam@85: const uint8_t* buf; /**< Start of chunk */ cannam@85: size_t len; /**< Length of chunk in bytes */ cannam@85: } SerdChunk; cannam@85: cannam@85: /** cannam@85: An error description. cannam@85: */ cannam@85: typedef struct { cannam@85: SerdStatus status; /**< Error code */ cannam@85: const uint8_t* filename; /**< File where error was encountered, or NULL */ cannam@85: unsigned line; /**< Line where error was encountered, or 0 */ cannam@85: unsigned col; /**< Column where error was encountered */ cannam@85: const char* fmt; /**< Message format string (printf style) */ cannam@85: va_list* args; /**< Arguments for fmt */ cannam@85: } SerdError; cannam@85: cannam@85: /** cannam@85: A parsed URI. cannam@85: cannam@85: This struct directly refers to chunks in other strings, it does not own any cannam@85: memory itself. Thus, URIs can be parsed and/or resolved against a base URI cannam@85: in-place without allocating memory. cannam@85: */ cannam@85: typedef struct { cannam@85: SerdChunk scheme; /**< Scheme */ cannam@85: SerdChunk authority; /**< Authority */ cannam@85: SerdChunk path_base; /**< Path prefix if relative */ cannam@85: SerdChunk path; /**< Path suffix */ cannam@85: SerdChunk query; /**< Query */ cannam@85: SerdChunk fragment; /**< Fragment */ cannam@85: } SerdURI; cannam@85: cannam@85: /** cannam@85: Syntax style options. cannam@85: cannam@85: The style of the writer output can be controlled by ORing together cannam@85: values from this enumeration. Note that some options are only supported cannam@85: for some syntaxes (e.g. NTriples does not support abbreviation and is cannam@85: always ASCII). cannam@85: */ cannam@85: typedef enum { cannam@85: SERD_STYLE_ABBREVIATED = 1, /**< Abbreviate triples when possible. */ cannam@85: SERD_STYLE_ASCII = 1 << 1, /**< Escape all non-ASCII characters. */ cannam@85: SERD_STYLE_RESOLVED = 1 << 2, /**< Resolve URIs against base URI. */ cannam@85: SERD_STYLE_CURIED = 1 << 3, /**< Shorten URIs into CURIEs. */ cannam@85: SERD_STYLE_BULK = 1 << 4 /**< Write output in pages. */ cannam@85: } SerdStyle; cannam@85: cannam@85: /** cannam@85: @name String Utilities cannam@85: @{ cannam@85: */ cannam@85: cannam@85: /** cannam@85: Return a string describing a status code. cannam@85: */ cannam@85: SERD_API cannam@85: const uint8_t* cannam@85: serd_strerror(SerdStatus status); cannam@85: cannam@85: /** cannam@85: Measure a UTF-8 string. cannam@85: @return Length of @c str in characters (except NULL). cannam@85: @param str A null-terminated UTF-8 string. cannam@85: @param n_bytes (Output) Set to the size of @c str in bytes (except NULL). cannam@85: @param flags (Output) Set to the applicable flags. cannam@85: */ cannam@85: SERD_API cannam@85: size_t cannam@85: serd_strlen(const uint8_t* str, size_t* n_bytes, SerdNodeFlags* flags); cannam@85: cannam@85: /** cannam@85: Parse a string to a double. cannam@85: cannam@85: The API of this function is identical to the standard C strtod function, cannam@85: except this function is locale-independent and always matches the lexical cannam@85: format used in the Turtle grammar (the decimal point is always "."). cannam@85: */ cannam@85: SERD_API cannam@85: double cannam@85: serd_strtod(const char* str, char** endptr); cannam@85: cannam@85: /** cannam@85: Decode a base64 string. cannam@85: This function can be used to deserialise a blob node created with cannam@85: serd_node_new_blob(). cannam@85: cannam@85: @param str Base64 string to decode. cannam@85: @param len The length of @c str. cannam@85: @param size Set to the size of the returned blob in bytes. cannam@85: @return A newly allocated blob which must be freed with free(). cannam@85: */ cannam@85: SERD_API cannam@85: void* cannam@85: serd_base64_decode(const uint8_t* str, size_t len, size_t* size); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @name URI cannam@85: @{ cannam@85: */ cannam@85: cannam@85: static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}}; cannam@85: cannam@85: /** cannam@85: Return the local path for @c uri, or NULL if @c uri is not a file URI. cannam@85: Note this (inappropriately named) function only removes the file scheme if cannam@85: necessary, and returns @c uri unmodified if it is an absolute path. Percent cannam@85: encoding and other issues are not handled, to properly convert a file URI to cannam@85: a path, use serd_file_uri_parse(). cannam@85: */ cannam@85: SERD_API cannam@85: const uint8_t* cannam@85: serd_uri_to_path(const uint8_t* uri); cannam@85: cannam@85: /** cannam@85: Get the unescaped path and hostname from a file URI. cannam@85: @param uri A file URI. cannam@85: @param hostname If non-NULL, set to the hostname, if present. cannam@85: @return The path component of the URI. cannam@85: cannam@85: Both the returned path and @c hostname (if applicable) are owned by the cannam@85: caller and must be freed with free(). cannam@85: */ cannam@85: SERD_API cannam@85: uint8_t* cannam@85: serd_file_uri_parse(const uint8_t* uri, uint8_t** hostname); cannam@85: cannam@85: /** cannam@85: Return true iff @c utf8 starts with a valid URI scheme. cannam@85: */ cannam@85: SERD_API cannam@85: bool cannam@85: serd_uri_string_has_scheme(const uint8_t* utf8); cannam@85: cannam@85: /** cannam@85: Parse @c utf8, writing result to @c out. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_uri_parse(const uint8_t* utf8, SerdURI* out); cannam@85: cannam@85: /** cannam@85: Set @c out to @c uri resolved against @c base. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_uri_resolve(const SerdURI* uri, const SerdURI* base, SerdURI* out); cannam@85: cannam@85: /** cannam@85: Sink function for raw string output. cannam@85: */ cannam@85: typedef size_t (*SerdSink)(const void* buf, size_t len, void* stream); cannam@85: cannam@85: /** cannam@85: Serialise @c uri with a series of calls to @c sink. cannam@85: */ cannam@85: SERD_API cannam@85: size_t cannam@85: serd_uri_serialise(const SerdURI* uri, SerdSink sink, void* stream); cannam@85: cannam@85: /** cannam@85: Serialise @c uri relative to @c base with a series of calls to @c sink. cannam@85: cannam@85: The @c uri is written as a relative URI iff if it a child of @c base and @c cannam@85: root. The optional @c root parameter must be a prefix of @c base and can be cannam@85: used keep up-references ("../") within a certain namespace. cannam@85: */ cannam@85: SERD_API cannam@85: size_t cannam@85: serd_uri_serialise_relative(const SerdURI* uri, cannam@85: const SerdURI* base, cannam@85: const SerdURI* root, cannam@85: SerdSink sink, cannam@85: void* stream); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @name Node cannam@85: @{ cannam@85: */ cannam@85: cannam@85: static const SerdNode SERD_NODE_NULL = { 0, 0, 0, 0, SERD_NOTHING }; cannam@85: cannam@85: /** cannam@85: Make a (shallow) node from @c str. cannam@85: cannam@85: This measures, but does not copy, @c str. No memory is allocated. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_from_string(SerdType type, const uint8_t* str); cannam@85: cannam@85: /** cannam@85: Make a deep copy of @c node. cannam@85: cannam@85: @return a node that the caller must free with @ref serd_node_free. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_copy(const SerdNode* node); cannam@85: cannam@85: /** cannam@85: Return true iff @c a is equal to @c b. cannam@85: */ cannam@85: SERD_API cannam@85: bool cannam@85: serd_node_equals(const SerdNode* a, const SerdNode* b); cannam@85: cannam@85: /** cannam@85: Simple wrapper for serd_node_new_uri to resolve a URI node. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_uri_from_node(const SerdNode* uri_node, cannam@85: const SerdURI* base, cannam@85: SerdURI* out); cannam@85: cannam@85: /** cannam@85: Simple wrapper for serd_node_new_uri to resolve a URI string. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_uri_from_string(const uint8_t* str, cannam@85: const SerdURI* base, cannam@85: SerdURI* out); cannam@85: cannam@85: /** cannam@85: Create a new file URI node from a file system path and optional hostname. cannam@85: cannam@85: Backslashes in Windows paths will be converted and '%' will always be cannam@85: percent encoded. If @c escape is true, all other invalid characters will be cannam@85: percent encoded as well. cannam@85: cannam@85: If @c path is relative, @c hostname is ignored. cannam@85: If @c out is not NULL, it will be set to the parsed URI. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_file_uri(const uint8_t* path, cannam@85: const uint8_t* hostname, cannam@85: SerdURI* out, cannam@85: bool escape); cannam@85: cannam@85: /** cannam@85: Create a new node by serialising @c uri into a new string. cannam@85: cannam@85: @param uri The URI to parse and serialise. cannam@85: cannam@85: @param base Base URI to resolve @c uri against (or NULL for no resolution). cannam@85: cannam@85: @param out Set to the parsing of the new URI (i.e. points only to cannam@85: memory owned by the new returned node). cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_uri(const SerdURI* uri, const SerdURI* base, SerdURI* out); cannam@85: cannam@85: /** cannam@85: Create a new node by serialising @c d into an xsd:decimal string. cannam@85: cannam@85: The resulting node will always contain a `.', start with a digit, and end cannam@85: with a digit (i.e. will have a leading and/or trailing `0' if necessary). cannam@85: It will never be in scientific notation. A maximum of @c frac_digits digits cannam@85: will be written after the decimal point, but trailing zeros will cannam@85: automatically be omitted (except one if @c d is a round integer). cannam@85: cannam@85: Note that about 16 and 8 fractional digits are required to precisely cannam@85: represent a double and float, respectively. cannam@85: cannam@85: @param d The value for the new node. cannam@85: @param frac_digits The maximum number of digits after the decimal place. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_decimal(double d, unsigned frac_digits); cannam@85: cannam@85: /** cannam@85: Create a new node by serialising @c i into an xsd:integer string. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_integer(int64_t i); cannam@85: cannam@85: /** cannam@85: Create a node by serialising @c buf into an xsd:base64Binary string. cannam@85: This function can be used to make a serialisable node out of arbitrary cannam@85: binary data, which can be decoded using serd_base64_decode(). cannam@85: cannam@85: @param buf Raw binary input data. cannam@85: @param size Size of @c buf. cannam@85: @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_node_new_blob(const void* buf, size_t size, bool wrap_lines); cannam@85: cannam@85: /** cannam@85: Free any data owned by @c node. cannam@85: cannam@85: Note that if @c node is itself dynamically allocated (which is not the case cannam@85: for nodes created internally by serd), it will not be freed. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_node_free(SerdNode* node); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @name Event Handlers cannam@85: @{ cannam@85: */ cannam@85: cannam@85: /** cannam@85: Sink (callback) for errors. cannam@85: cannam@85: @param handle Handle for user data. cannam@85: @param error Error description. cannam@85: */ cannam@85: typedef SerdStatus (*SerdErrorSink)(void* handle, cannam@85: const SerdError* error); cannam@85: cannam@85: /** cannam@85: Sink (callback) for base URI changes. cannam@85: cannam@85: Called whenever the base URI of the serialisation changes. cannam@85: */ cannam@85: typedef SerdStatus (*SerdBaseSink)(void* handle, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Sink (callback) for namespace definitions. cannam@85: cannam@85: Called whenever a prefix is defined in the serialisation. cannam@85: */ cannam@85: typedef SerdStatus (*SerdPrefixSink)(void* handle, cannam@85: const SerdNode* name, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Sink (callback) for statements. cannam@85: cannam@85: Called for every RDF statement in the serialisation. cannam@85: */ cannam@85: typedef SerdStatus (*SerdStatementSink)(void* handle, cannam@85: SerdStatementFlags flags, cannam@85: const SerdNode* graph, cannam@85: const SerdNode* subject, cannam@85: const SerdNode* predicate, cannam@85: const SerdNode* object, cannam@85: const SerdNode* object_datatype, cannam@85: const SerdNode* object_lang); cannam@85: cannam@85: /** cannam@85: Sink (callback) for anonymous node end markers. cannam@85: cannam@85: This is called to indicate that the anonymous node with the given cannam@85: @c value will no longer be referred to by any future statements cannam@85: (i.e. the anonymous serialisation of the node is finished). cannam@85: */ cannam@85: typedef SerdStatus (*SerdEndSink)(void* handle, cannam@85: const SerdNode* node); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @name Environment cannam@85: @{ cannam@85: */ cannam@85: cannam@85: /** cannam@85: Create a new environment. cannam@85: */ cannam@85: SERD_API cannam@85: SerdEnv* cannam@85: serd_env_new(const SerdNode* base_uri); cannam@85: cannam@85: /** cannam@85: Free @c ns. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_env_free(SerdEnv* env); cannam@85: cannam@85: /** cannam@85: Get the current base URI. cannam@85: */ cannam@85: SERD_API cannam@85: const SerdNode* cannam@85: serd_env_get_base_uri(const SerdEnv* env, cannam@85: SerdURI* out); cannam@85: cannam@85: /** cannam@85: Set the current base URI. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_env_set_base_uri(SerdEnv* env, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Set a namespace prefix. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_env_set_prefix(SerdEnv* env, cannam@85: const SerdNode* name, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Set a namespace prefix. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_env_set_prefix_from_strings(SerdEnv* env, cannam@85: const uint8_t* name, cannam@85: const uint8_t* uri); cannam@85: cannam@85: /** cannam@85: Qualify @c uri into a CURIE if possible. cannam@85: */ cannam@85: SERD_API cannam@85: bool cannam@85: serd_env_qualify(const SerdEnv* env, cannam@85: const SerdNode* uri, cannam@85: SerdNode* prefix, cannam@85: SerdChunk* suffix); cannam@85: cannam@85: /** cannam@85: Expand @c curie. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_env_expand(const SerdEnv* env, cannam@85: const SerdNode* curie, cannam@85: SerdChunk* uri_prefix, cannam@85: SerdChunk* uri_suffix); cannam@85: cannam@85: /** cannam@85: Expand @c node, which must be a CURIE or URI, to a full URI. cannam@85: */ cannam@85: SERD_API cannam@85: SerdNode cannam@85: serd_env_expand_node(const SerdEnv* env, cannam@85: const SerdNode* node); cannam@85: cannam@85: /** cannam@85: Call @c func for each prefix defined in @c env. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_env_foreach(const SerdEnv* env, cannam@85: SerdPrefixSink func, cannam@85: void* handle); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @name Reader cannam@85: @{ cannam@85: */ cannam@85: cannam@85: /** cannam@85: Create a new RDF reader. cannam@85: */ cannam@85: SERD_API cannam@85: SerdReader* cannam@85: serd_reader_new(SerdSyntax syntax, cannam@85: void* handle, cannam@85: void (*free_handle)(void*), cannam@85: SerdBaseSink base_sink, cannam@85: SerdPrefixSink prefix_sink, cannam@85: SerdStatementSink statement_sink, cannam@85: SerdEndSink end_sink); cannam@85: cannam@85: /** cannam@85: Set a function to be called when errors occur during reading. cannam@85: cannam@85: The @p error_sink will be called with @p handle as its first argument. If cannam@85: no error function is set, errors are printed to stderr in GCC style. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_reader_set_error_sink(SerdReader* reader, cannam@85: SerdErrorSink error_sink, cannam@85: void* handle); cannam@85: cannam@85: /** cannam@85: Return the @c handle passed to @ref serd_reader_new. cannam@85: */ cannam@85: SERD_API cannam@85: void* cannam@85: serd_reader_get_handle(const SerdReader* reader); cannam@85: cannam@85: /** cannam@85: Set a prefix to be added to all blank node identifiers. cannam@85: cannam@85: This is useful when multiple files are to be parsed into the same output cannam@85: (e.g. a store, or other files). Since Serd preserves blank node IDs, this cannam@85: could cause conflicts where two non-equivalent blank nodes are merged, cannam@85: resulting in corrupt data. By setting a unique blank node prefix for each cannam@85: parsed file, this can be avoided, while preserving blank node names. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_reader_add_blank_prefix(SerdReader* reader, cannam@85: const uint8_t* prefix); cannam@85: cannam@85: /** cannam@85: Set the URI of the default graph. cannam@85: cannam@85: If this is set, the reader will emit quads with the graph set to the given cannam@85: node for any statements that are not in a named graph (which is currently cannam@85: all of them since Serd currently does not support any graph syntaxes). cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_reader_set_default_graph(SerdReader* reader, cannam@85: const SerdNode* graph); cannam@85: cannam@85: /** cannam@85: Read a file at a given @c uri. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_reader_read_file(SerdReader* reader, cannam@85: const uint8_t* uri); cannam@85: cannam@85: /** cannam@85: Start an incremental read from a file handle. cannam@85: cannam@85: Iff @p bulk is true, @p file will be read a page at a time. This is more cannam@85: efficient, but uses a page of memory and means that an entire page of input cannam@85: must be ready before any callbacks will fire. To react as soon as input cannam@85: arrives, set @p bulk to false. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_reader_start_stream(SerdReader* me, cannam@85: FILE* file, cannam@85: const uint8_t* name, cannam@85: bool bulk); cannam@85: cannam@85: /** cannam@85: Read a single "chunk" of data during an incremental read. cannam@85: cannam@85: This function will read a single top level description, and return. This cannam@85: may be a directive, statement, or several statements; essentially it reads cannam@85: until a '.' is encountered. This is particularly useful for reading cannam@85: directly from a pipe or socket. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_reader_read_chunk(SerdReader* me); cannam@85: cannam@85: /** cannam@85: Finish an incremental read from a file handle. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_reader_end_stream(SerdReader* me); cannam@85: cannam@85: /** cannam@85: Read @c file. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_reader_read_file_handle(SerdReader* reader, cannam@85: FILE* file, cannam@85: const uint8_t* name); cannam@85: cannam@85: /** cannam@85: Read @c utf8. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_reader_read_string(SerdReader* me, const uint8_t* utf8); cannam@85: cannam@85: /** cannam@85: Free @c reader. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_reader_free(SerdReader* reader); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @name Writer cannam@85: @{ cannam@85: */ cannam@85: cannam@85: /** cannam@85: Create a new RDF writer. cannam@85: */ cannam@85: SERD_API cannam@85: SerdWriter* cannam@85: serd_writer_new(SerdSyntax syntax, cannam@85: SerdStyle style, cannam@85: SerdEnv* env, cannam@85: const SerdURI* base_uri, cannam@85: SerdSink sink, cannam@85: void* stream); cannam@85: cannam@85: /** cannam@85: Free @c writer. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_writer_free(SerdWriter* writer); cannam@85: cannam@85: /** cannam@85: Return the env used by @c writer. cannam@85: */ cannam@85: SERD_API cannam@85: SerdEnv* cannam@85: serd_writer_get_env(SerdWriter* writer); cannam@85: cannam@85: /** cannam@85: A convenience sink function for writing to a FILE*. cannam@85: cannam@85: This function can be used as a SerdSink when writing to a FILE*. The cannam@85: @c stream parameter must be a FILE* opened for writing. cannam@85: */ cannam@85: SERD_API cannam@85: size_t cannam@85: serd_file_sink(const void* buf, size_t len, void* stream); cannam@85: cannam@85: /** cannam@85: A convenience sink function for writing to a string. cannam@85: cannam@85: This function can be used as a SerdSink to write to a SerdChunk which is cannam@85: resized as necessary with realloc(). The @c stream parameter must point to cannam@85: an initialized SerdChunk. When the write is finished, the string should be cannam@85: retrieved with serd_chunk_sink_finish(). cannam@85: */ cannam@85: SERD_API cannam@85: size_t cannam@85: serd_chunk_sink(const void* buf, size_t len, void* stream); cannam@85: cannam@85: /** cannam@85: Finish a serialisation to a chunk with serd_chunk_sink(). cannam@85: cannam@85: The returned string is the result of the serialisation, which is NULL cannam@85: terminated (by this function) and owned by the caller. cannam@85: */ cannam@85: SERD_API cannam@85: uint8_t* cannam@85: serd_chunk_sink_finish(SerdChunk* stream); cannam@85: cannam@85: /** cannam@85: Set a function to be called when errors occur during writing. cannam@85: cannam@85: The @p error_sink will be called with @p handle as its first argument. If cannam@85: no error function is set, errors are printed to stderr. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_writer_set_error_sink(SerdWriter* writer, cannam@85: SerdErrorSink error_sink, cannam@85: void* handle); cannam@85: cannam@85: /** cannam@85: Set a prefix to be removed from matching blank node identifiers. cannam@85: */ cannam@85: SERD_API cannam@85: void cannam@85: serd_writer_chop_blank_prefix(SerdWriter* writer, cannam@85: const uint8_t* prefix); cannam@85: cannam@85: /** cannam@85: Set the current output base URI (and emit directive if applicable). cannam@85: cannam@85: Note this function can be safely casted to SerdBaseSink. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_writer_set_base_uri(SerdWriter* writer, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Set the current root URI. cannam@85: cannam@85: The root URI should be a prefix of the base URI. The path of the root URI cannam@85: is the highest path any relative up-reference can refer to. For example, cannam@85: with root and base , cannam@85: will be written as <../>, but will be cannam@85: written non-relatively as . If the root is not explicitly set, cannam@85: it defaults to the base URI, so no up-references will be created at all. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_writer_set_root_uri(SerdWriter* writer, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Set a namespace prefix (and emit directive if applicable). cannam@85: cannam@85: Note this function can be safely casted to SerdPrefixSink. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_writer_set_prefix(SerdWriter* writer, cannam@85: const SerdNode* name, cannam@85: const SerdNode* uri); cannam@85: cannam@85: /** cannam@85: Write a statement. cannam@85: cannam@85: Note this function can be safely casted to SerdStatementSink. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_writer_write_statement(SerdWriter* writer, cannam@85: SerdStatementFlags flags, cannam@85: const SerdNode* graph, cannam@85: const SerdNode* subject, cannam@85: const SerdNode* predicate, cannam@85: const SerdNode* object, cannam@85: const SerdNode* object_datatype, cannam@85: const SerdNode* object_lang); cannam@85: cannam@85: /** cannam@85: Mark the end of an anonymous node's description. cannam@85: cannam@85: Note this function can be safely casted to SerdEndSink. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_writer_end_anon(SerdWriter* writer, cannam@85: const SerdNode* node); cannam@85: cannam@85: /** cannam@85: Finish a write. cannam@85: */ cannam@85: SERD_API cannam@85: SerdStatus cannam@85: serd_writer_finish(SerdWriter* writer); cannam@85: cannam@85: /** cannam@85: @} cannam@85: @} cannam@85: */ cannam@85: cannam@85: #ifdef __cplusplus cannam@85: } /* extern "C" */ cannam@85: #endif cannam@85: cannam@85: #endif /* SERD_SERD_H */