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