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