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