serd.h   serd.h 
/* /*
Copyright 2011 David Robillard <http://drobilla.net> Copyright 2011-2012 David Robillard <http://drobilla.net>
Permission to use, copy, modify, and/or distribute this software for any Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies. copyright notice and this permission notice appear in all copies.
THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
skipping to change at line 24 skipping to change at line 24
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/** /**
@file serd.h API for Serd, a lightweight RDF syntax library. @file serd.h API for Serd, a lightweight RDF syntax library.
*/ */
#ifndef SERD_SERD_H #ifndef SERD_SERD_H
#define SERD_SERD_H #define SERD_SERD_H
#include <stdbool.h>
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
#include <stdio.h> #include <stdio.h>
#ifdef SERD_SHARED #ifdef SERD_SHARED
# ifdef __WIN32__ # ifdef _WIN32
# define SERD_LIB_IMPORT __declspec(dllimport) # define SERD_LIB_IMPORT __declspec(dllimport)
# define SERD_LIB_EXPORT __declspec(dllexport) # define SERD_LIB_EXPORT __declspec(dllexport)
# else # else
# define SERD_LIB_IMPORT __attribute__((visibility("default"))) # define SERD_LIB_IMPORT __attribute__((visibility("default")))
# define SERD_LIB_EXPORT __attribute__((visibility("default"))) # define SERD_LIB_EXPORT __attribute__((visibility("default")))
# endif # endif
# ifdef SERD_INTERNAL # ifdef SERD_INTERNAL
# define SERD_API SERD_LIB_EXPORT # define SERD_API SERD_LIB_EXPORT
# else # else
# define SERD_API SERD_LIB_IMPORT # define SERD_API SERD_LIB_IMPORT
# endif # endif
#else #else
# define SERD_API # define SERD_API
#endif #endif
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#else
# include <stdbool.h>
#endif #endif
/** /**
@defgroup serd Serd @defgroup serd Serd
A lightweight RDF syntax library. A lightweight RDF syntax library.
@{ @{
*/ */
/** /**
Environment. Environment.
skipping to change at line 94 skipping to change at line 95
*/ */
typedef enum { typedef enum {
SERD_SUCCESS, /**< No error */ SERD_SUCCESS, /**< No error */
SERD_FAILURE, /**< Non-fatal failure */ SERD_FAILURE, /**< Non-fatal failure */
SERD_ERR_UNKNOWN, /**< Unknown error */ SERD_ERR_UNKNOWN, /**< Unknown error */
SERD_ERR_BAD_SYNTAX, /**< Invalid syntax */ SERD_ERR_BAD_SYNTAX, /**< Invalid syntax */
SERD_ERR_BAD_ARG, /**< Invalid argument */ SERD_ERR_BAD_ARG, /**< Invalid argument */
SERD_ERR_NOT_FOUND /**< Not found */ SERD_ERR_NOT_FOUND /**< Not found */
} SerdStatus; } SerdStatus;
SERD_API
const uint8_t*
serd_strerror(SerdStatus status);
/** /**
RDF syntax type. RDF syntax type.
*/ */
typedef enum { typedef enum {
/** /**
Turtle - Terse RDF Triple Language (UTF-8). Turtle - Terse RDF Triple Language (UTF-8).
@see <a href="http://www.w3.org/TeamSubmission/turtle/">Turtle</a > @see <a href="http://www.w3.org/TeamSubmission/turtle/">Turtle</a >
*/ */
SERD_TURTLE = 1, SERD_TURTLE = 1,
skipping to change at line 123 skipping to change at line 120
} SerdSyntax; } SerdSyntax;
/** /**
Flags indication inline abbreviation information for a statement. Flags indication inline abbreviation information for a statement.
*/ */
typedef enum { typedef enum {
SERD_EMPTY_S = 1 << 1, /**< Empty blank node subject */ SERD_EMPTY_S = 1 << 1, /**< Empty blank node subject */
SERD_EMPTY_O = 1 << 2, /**< Empty blank node object */ SERD_EMPTY_O = 1 << 2, /**< Empty blank node object */
SERD_ANON_S_BEGIN = 1 << 3, /**< Start of anonymous subject */ SERD_ANON_S_BEGIN = 1 << 3, /**< Start of anonymous subject */
SERD_ANON_O_BEGIN = 1 << 4, /**< Start of anonymous object */ SERD_ANON_O_BEGIN = 1 << 4, /**< Start of anonymous object */
SERD_ANON_CONT = 1 << 5 /**< Continuation of anonymous node */ SERD_ANON_CONT = 1 << 5, /**< Continuation of anonymous node */
SERD_LIST_S_BEGIN = 1 << 6, /**< Start of list subject */
SERD_LIST_O_BEGIN = 1 << 7, /**< Start of list object */
SERD_LIST_CONT = 1 << 8 /**< Continuation of list */
} SerdStatementFlag; } SerdStatementFlag;
/** /**
Bitwise OR of SerdNodeFlag values. Bitwise OR of SerdNodeFlag values.
*/ */
typedef uint32_t SerdStatementFlags; typedef uint32_t SerdStatementFlags;
/** /**
Type of a syntactic RDF node. Type of a syntactic RDF node.
skipping to change at line 246 skipping to change at line 246
The style of the writer output can be controlled by ORing together The style of the writer output can be controlled by ORing together
values from this enumeration. Note that some options are only supported values from this enumeration. Note that some options are only supported
for some syntaxes (e.g. NTriples does not support abbreviation and is for some syntaxes (e.g. NTriples does not support abbreviation and is
always ASCII). always ASCII).
*/ */
typedef enum { typedef enum {
SERD_STYLE_ABBREVIATED = 1, /**< Abbreviate triples when possi ble. */ SERD_STYLE_ABBREVIATED = 1, /**< Abbreviate triples when possi ble. */
SERD_STYLE_ASCII = 1 << 1, /**< Escape all non-ASCII characte rs. */ SERD_STYLE_ASCII = 1 << 1, /**< Escape all non-ASCII characte rs. */
SERD_STYLE_RESOLVED = 1 << 2, /**< Resolve URIs against base URI . */ SERD_STYLE_RESOLVED = 1 << 2, /**< Resolve URIs against base URI . */
SERD_STYLE_CURIED = 1 << 3 /**< Shorten URIs into CURIEs. */ SERD_STYLE_CURIED = 1 << 3, /**< Shorten URIs into CURIEs. */
SERD_STYLE_BULK = 1 << 4 /**< Write output in pages. */
} SerdStyle; } SerdStyle;
/** /**
UTF-8 strlen. @name String Utilities
@{
*/
/**
Return a string describing a status code.
*/
SERD_API
const uint8_t*
serd_strerror(SerdStatus status);
/**
Measure a UTF-8 string.
@return Length of @c str in characters (except NULL). @return Length of @c str in characters (except NULL).
@param str A null-terminated UTF-8 string. @param str A null-terminated UTF-8 string.
@param n_bytes (Output) Set to the size of @c str in bytes (except NULL) . @param n_bytes (Output) Set to the size of @c str in bytes (except NULL) .
@param flags (Output) Set to the applicable flags. @param flags (Output) Set to the applicable flags.
*/ */
SERD_API SERD_API
size_t size_t
serd_strlen(const uint8_t* str, size_t* n_bytes, SerdNodeFlags* flags); serd_strlen(const uint8_t* str, size_t* n_bytes, SerdNodeFlags* flags);
/** /**
Parse a string to a double.
The API of this function is identical to the standard C strtod function,
except this function is locale-independent and always matches the lexica
l
format used in the Turtle grammar (the decimal point is always ".").
*/
SERD_API
double
serd_strtod(const char* str, char** endptr);
/**
Decode a base64 string.
This function can be used to deserialise a blob node created with
serd_node_new_blob().
@param str Base64 string to decode.
@param len The length of @c str.
@param size Set to the size of the returned blob in bytes.
@return A newly allocated blob which must be freed with free().
*/
SERD_API
void*
serd_base64_decode(const uint8_t* str, size_t len, size_t* size);
/**
@}
@name URI @name URI
@{ @{
*/ */
static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}}; static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}};
/** /**
Return the local path for @c uri, or NULL if @c uri is not a file URI. Return the local path for @c uri, or NULL if @c uri is not a file URI.
Note this (inappropriately named) function only removes the file scheme
if
necessary, and returns @c uri unmodified if it is an absolute path. Per
cent
encoding and other issues are not handled, to properly convert a file UR
I to
a path, use serd_file_uri_parse().
*/ */
SERD_API SERD_API
const uint8_t* const uint8_t*
serd_uri_to_path(const uint8_t* uri); serd_uri_to_path(const uint8_t* uri);
/** /**
Get the unescaped path and hostname from a file URI.
@param uri A file URI.
@param hostname If non-NULL, set to the hostname, if present.
@return The path component of the URI.
Both the returned path and @c hostname (if applicable) are owned by the
caller and must be freed with free().
*/
SERD_API
uint8_t*
serd_file_uri_parse(const uint8_t* uri, uint8_t** hostname);
/**
Return true iff @c utf8 starts with a valid URI scheme. Return true iff @c utf8 starts with a valid URI scheme.
*/ */
SERD_API SERD_API
bool bool
serd_uri_string_has_scheme(const uint8_t* utf8); serd_uri_string_has_scheme(const uint8_t* utf8);
/** /**
Parse @c utf8, writing result to @c out. Parse @c utf8, writing result to @c out.
*/ */
SERD_API SERD_API
skipping to change at line 308 skipping to change at line 364
typedef size_t (*SerdSink)(const void* buf, size_t len, void* stream); typedef size_t (*SerdSink)(const void* buf, size_t len, void* stream);
/** /**
Serialise @c uri with a series of calls to @c sink. Serialise @c uri with a series of calls to @c sink.
*/ */
SERD_API SERD_API
size_t size_t
serd_uri_serialise(const SerdURI* uri, SerdSink sink, void* stream); serd_uri_serialise(const SerdURI* uri, SerdSink sink, void* stream);
/** /**
Serialise @c uri relative to @c base with a series of calls to @c sink.
The @c uri is written as a relative URI iff if it a child of @c base and
@c
root. The optional @c root parameter must be a prefix of @c base and ca
n be
used keep up-references ("../") within a certain namespace.
*/
SERD_API
size_t
serd_uri_serialise_relative(const SerdURI* uri,
const SerdURI* base,
const SerdURI* root,
SerdSink sink,
void* stream);
/**
@} @}
@name Node @name Node
@{ @{
*/ */
static const SerdNode SERD_NODE_NULL = { 0, 0, 0, 0, SERD_NOTHING }; static const SerdNode SERD_NODE_NULL = { 0, 0, 0, 0, SERD_NOTHING };
/** /**
Make a (shallow) node from @c str. Make a (shallow) node from @c str.
skipping to change at line 359 skipping to change at line 430
/** /**
Simple wrapper for serd_node_new_uri to resolve a URI string. Simple wrapper for serd_node_new_uri to resolve a URI string.
*/ */
SERD_API SERD_API
SerdNode SerdNode
serd_node_new_uri_from_string(const uint8_t* str, serd_node_new_uri_from_string(const uint8_t* str,
const SerdURI* base, const SerdURI* base,
SerdURI* out); SerdURI* out);
/** /**
Create a new file URI node from a file system path and optional hostname
.
Backslashes in Windows paths will be converted and '%' will always be
percent encoded. If @c escape is true, all other invalid characters wil
l be
percent encoded as well.
If @c path is relative, @c hostname is ignored.
If @c out is not NULL, it will be set to the parsed URI.
*/
SERD_API
SerdNode
serd_node_new_file_uri(const uint8_t* path,
const uint8_t* hostname,
SerdURI* out,
bool escape);
/**
Create a new node by serialising @c uri into a new string. Create a new node by serialising @c uri into a new string.
@param uri The URI to parse and serialise. @param uri The URI to parse and serialise.
@param base Base URI to resolve @c uri against (or NULL for no resolutio n). @param base Base URI to resolve @c uri against (or NULL for no resolutio n).
@param out Set to the parsing of the new URI (i.e. points only to @param out Set to the parsing of the new URI (i.e. points only to
memory owned by the new returned node). memory owned by the new returned node).
*/ */
SERD_API SERD_API
SerdNode SerdNode
serd_node_new_uri(const SerdURI* uri, const SerdURI* base, SerdURI* out); serd_node_new_uri(const SerdURI* uri, const SerdURI* base, SerdURI* out);
/** /**
Create a new node by serialising @c d into an xsd:decimal string.
The resulting node will always contain a `.', start with a digit, and en
d
with a digit (i.e. will have a leading and/or trailing `0' if necessary)
.
It will never be in scientific notation. A maximum of @c frac_digits di
gits
will be written after the decimal point, but trailing zeros will
automatically be omitted (except one if @c d is a round integer).
Note that about 16 and 8 fractional digits are required to precisely
represent a double and float, respectively.
@param d The value for the new node.
@param frac_digits The maximum number of digits after the decimal place.
*/
SERD_API
SerdNode
serd_node_new_decimal(double d, unsigned frac_digits);
/**
Create a new node by serialising @c i into an xsd:integer string.
*/
SERD_API
SerdNode
serd_node_new_integer(int64_t i);
/**
Create a node by serialising @c buf into an xsd:base64Binary string.
This function can be used to make a serialisable node out of arbitrary
binary data, which can be decoded using serd_base64_decode().
@param buf Raw binary input data.
@param size Size of @c buf.
@param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
*/
SERD_API
SerdNode
serd_node_new_blob(const void* buf, size_t size, bool wrap_lines);
/**
Free any data owned by @c node. Free any data owned by @c node.
Note that if @c node is itself dynamically allocated (which is not the c ase Note that if @c node is itself dynamically allocated (which is not the c ase
for nodes created internally by serd), it will not be freed. for nodes created internally by serd), it will not be freed.
*/ */
SERD_API SERD_API
void void
serd_node_free(SerdNode* node); serd_node_free(SerdNode* node);
/** /**
skipping to change at line 561 skipping to change at line 688
could cause conflicts where two non-equivalent blank nodes are merged, could cause conflicts where two non-equivalent blank nodes are merged,
resulting in corrupt data. By setting a unique blank node prefix for ea ch resulting in corrupt data. By setting a unique blank node prefix for ea ch
parsed file, this can be avoided, while preserving blank node names. parsed file, this can be avoided, while preserving blank node names.
*/ */
SERD_API SERD_API
void void
serd_reader_add_blank_prefix(SerdReader* reader, serd_reader_add_blank_prefix(SerdReader* reader,
const uint8_t* prefix); const uint8_t* prefix);
/** /**
Set the URI of the default graph.
If this is set, the reader will emit quads with the graph set to the giv
en
node for any statements that are not in a named graph (which is currentl
y
all of them since Serd currently does not support any graph syntaxes).
*/
SERD_API
void
serd_reader_set_default_graph(SerdReader* reader,
const SerdNode* graph);
/**
Read a file at a given @c uri. Read a file at a given @c uri.
*/ */
SERD_API SERD_API
SerdStatus SerdStatus
serd_reader_read_file(SerdReader* reader, serd_reader_read_file(SerdReader* reader,
const uint8_t* uri); const uint8_t* uri);
/** /**
Read @c file. Read @c file.
*/ */
skipping to change at line 617 skipping to change at line 756
void* stream); void* stream);
/** /**
Free @c writer. Free @c writer.
*/ */
SERD_API SERD_API
void void
serd_writer_free(SerdWriter* writer); serd_writer_free(SerdWriter* writer);
/** /**
Return the env used by @c writer.
*/
SERD_API
SerdEnv*
serd_writer_get_env(SerdWriter* writer);
/**
A convenience sink function for writing to a FILE*.
This function can be used as a SerdSink when writing to a FILE*. The
@c stream parameter must be a FILE* opened for writing.
*/
SERD_API
size_t
serd_file_sink(const void* buf, size_t len, void* stream);
/**
A convenience sink function for writing to a string.
This function can be used as a SerdSink to write to a SerdChunk which is
resized as necessary with realloc(). The @c stream parameter must point
to
an initialized SerdChunk. When the write is finished, the string should
be
retrieved with serd_chunk_sink_finish().
*/
SERD_API
size_t
serd_chunk_sink(const void* buf, size_t len, void* stream);
/**
Finish a serialisation to a chunk with serd_chunk_sink().
The returned string is the result of the serialisation, which is NULL
terminated (by this function) and owned by the caller.
*/
SERD_API
uint8_t*
serd_chunk_sink_finish(SerdChunk* stream);
/**
Set a prefix to be removed from matching blank node identifiers. Set a prefix to be removed from matching blank node identifiers.
*/ */
SERD_API SERD_API
void void
serd_writer_chop_blank_prefix(SerdWriter* writer, serd_writer_chop_blank_prefix(SerdWriter* writer,
const uint8_t* prefix); const uint8_t* prefix);
/** /**
Set the current output base URI (and emit directive if applicable). Set the current output base URI (and emit directive if applicable).
Note this function can be safely casted to SerdBaseSink. Note this function can be safely casted to SerdBaseSink.
*/ */
SERD_API SERD_API
SerdStatus SerdStatus
serd_writer_set_base_uri(SerdWriter* writer, serd_writer_set_base_uri(SerdWriter* writer,
const SerdNode* uri); const SerdNode* uri);
/** /**
Set the current root URI.
The root URI should be a prefix of the base URI. The path of the root U
RI
is the highest path any relative up-reference can refer to. For example
,
with root <file:///foo/root> and base <file:///foo/root/base>,
<file:///foo/root> will be written as <../>, but <file:///foo> will be
written non-relatively as <file:///foo>. If the root is not explicitly
set,
it defaults to the base URI, so no up-references will be created at all.
*/
SERD_API
SerdStatus
serd_writer_set_root_uri(SerdWriter* writer,
const SerdNode* uri);
/**
Set a namespace prefix (and emit directive if applicable). Set a namespace prefix (and emit directive if applicable).
Note this function can be safely casted to SerdPrefixSink. Note this function can be safely casted to SerdPrefixSink.
*/ */
SERD_API SERD_API
SerdStatus SerdStatus
serd_writer_set_prefix(SerdWriter* writer, serd_writer_set_prefix(SerdWriter* writer,
const SerdNode* name, const SerdNode* name,
const SerdNode* uri); const SerdNode* uri);
 End of changes. 17 change blocks. 
10 lines changed or deleted 221 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/