aboutsummaryrefslogtreecommitdiffstats
path: root/serd
diff options
context:
space:
mode:
Diffstat (limited to 'serd')
-rw-r--r--serd/serd.h673
1 files changed, 222 insertions, 451 deletions
diff --git a/serd/serd.h b/serd/serd.h
index 6f9360cc..9b3e35f6 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -14,9 +14,7 @@
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
#define SERD_SERD_H
@@ -50,136 +48,73 @@ extern "C" {
/**
@defgroup serd Serd
- A lightweight RDF syntax library.
+ A lightweight RDF syntax library
@{
*/
-/**
- World.
-
- The World represents all library state shared between various objects.
-*/
+/// Global library state
typedef struct SerdWorldImpl SerdWorld;
-/**
- Nodes.
-
- A hashing container for nodes that can be used for interning and simplified
- memory management.
-*/
+/// Hashing node container for interning and simplified memory management
typedef struct SerdNodesImpl SerdNodes;
-/**
- Statement.
-
- A subject, predicate, and object, with optional graph context.
-*/
+/// A subject, predicate, and object, with optional graph context
typedef struct SerdStatementImpl SerdStatement;
-/**
- Cursor, the origin of a statement in a document.
-*/
+/// The origin of a statement in a document
typedef struct SerdCursorImpl SerdCursor;
-/**
- Environment.
-
- Represents the state required to resolve a CURIE or relative URI, e.g. the
- base URI and set of namespace prefixes at a particular point.
-*/
+/// Lexical environment for relative URIs or CURIEs (base URI and namespaces)
typedef struct SerdEnvImpl SerdEnv;
-/**
- RDF reader.
-
- Parses RDF by calling user-provided sink functions as input is consumed
- (much like an XML SAX parser).
-*/
+/// Streaming parser that reads a text stream and writes to a statement sink
typedef struct SerdReaderImpl SerdReader;
-/**
- RDF writer.
-
- Provides a number of functions to allow writing RDF syntax out to some
- stream. These functions are deliberately compatible with the sink functions
- used by SerdReader, so a reader can be directly connected to a writer to
- re-serialise a document with minimal overhead.
-*/
+/// Streaming serialiser that writes a text stream as statements are pushed
typedef struct SerdWriterImpl SerdWriter;
-/**
- An interface that receives a stream of RDF data.
-*/
+/// An interface that receives a stream of RDF data
typedef struct SerdSinkImpl SerdSink;
-/**
- A sink for bytes that receives string output.
-*/
+/// A sink for bytes that receives string output
typedef struct SerdByteSinkImpl SerdByteSink;
-/**
- Return status code.
-*/
+/// Return status code
typedef enum {
- SERD_SUCCESS, /**< No error */
- SERD_FAILURE, /**< Non-fatal failure */
- SERD_ERR_UNKNOWN, /**< Unknown error */
- SERD_ERR_BAD_SYNTAX, /**< Invalid syntax */
- SERD_ERR_BAD_ARG, /**< Invalid argument */
- SERD_ERR_NOT_FOUND, /**< Not found */
- SERD_ERR_ID_CLASH, /**< Encountered clashing blank node IDs */
- SERD_ERR_BAD_CURIE, /**< Invalid CURIE (e.g. prefix does not exist) */
- SERD_ERR_INTERNAL, /**< Unexpected internal error (should not happen) */
- SERD_ERR_OVERFLOW /**< Stack overflow */
+ SERD_SUCCESS, ///< No error
+ SERD_FAILURE, ///< Non-fatal failure
+ SERD_ERR_UNKNOWN, ///< Unknown error
+ SERD_ERR_BAD_SYNTAX, ///< Invalid syntax
+ SERD_ERR_BAD_ARG, ///< Invalid argument
+ SERD_ERR_NOT_FOUND, ///< Not found
+ SERD_ERR_ID_CLASH, ///< Encountered clashing blank node IDs
+ SERD_ERR_BAD_CURIE, ///< Invalid CURIE (e.g. prefix does not exist)
+ SERD_ERR_INTERNAL, ///< Unexpected internal error (should not happen)
+ SERD_ERR_OVERFLOW ///< Stack overflow
} SerdStatus;
-/**
- RDF syntax type.
-*/
+/// RDF syntax type
typedef enum {
- /**
- Turtle - Terse RDF Triple Language (UTF-8).
- @see <a href="http://www.w3.org/TeamSubmission/turtle/">Turtle</a>
- */
- SERD_TURTLE = 1,
-
- /**
- NTriples - Line-based RDF triples (ASCII).
- @see <a href="http://www.w3.org/TR/rdf-testcases#ntriples">NTriples</a>
- */
- SERD_NTRIPLES = 2,
-
- /**
- NQuads - Line-based RDF quads (UTF-8).
- @see <a href="https://www.w3.org/TR/n-quads/">NQuads</a>
- */
- SERD_NQUADS = 3,
-
- /**
- TriG - Terse RDF quads (UTF-8).
- @see <a href="https://www.w3.org/TR/trig/">Trig</a>
- */
- SERD_TRIG = 4
+ SERD_TURTLE = 1, ///< Terse triples http://www.w3.org/TR/turtle
+ SERD_NTRIPLES = 2, ///< Line-based triples http://www.w3.org/TR/n-triples/
+ SERD_NQUADS = 3, ///< Line-based quads http://www.w3.org/TR/n-quads/
+ SERD_TRIG = 4 ///< Terse quads http://www.w3.org/TR/trig/
} SerdSyntax;
-/**
- Flags indicating inline abbreviation information for a statement.
-*/
+/// Flags indicating inline abbreviation information for a statement
typedef enum {
- SERD_EMPTY_S = 1 << 0, /**< Empty blank node subject */
- SERD_ANON_S = 1 << 1, /**< Start of anonymous subject */
- SERD_ANON_O = 1 << 2, /**< Start of anonymous object */
- SERD_LIST_S = 1 << 3, /**< Start of list subject */
- SERD_LIST_O = 1 << 4 /**< Start of list object */
+ SERD_EMPTY_S = 1 << 0, ///< Empty blank node subject
+ SERD_ANON_S = 1 << 1, ///< Start of anonymous subject
+ SERD_ANON_O = 1 << 2, ///< Start of anonymous object
+ SERD_LIST_S = 1 << 3, ///< Start of list subject
+ SERD_LIST_O = 1 << 4 ///< Start of list object
} SerdStatementFlag;
-/**
- Bitwise OR of SerdStatementFlag values.
-*/
+/// Bitwise OR of SerdStatementFlag values
typedef uint32_t SerdStatementFlags;
/**
- Type of a syntactic RDF node.
+ Type of a syntactic RDF node
This is more precise than the type of an abstract RDF node. An abstract
node is either a resource, literal, or blank. In syntax there are two ways
@@ -189,133 +124,115 @@ typedef uint32_t SerdStatementFlags;
*/
typedef enum {
/**
- The type of a nonexistent node.
+ The type of a nonexistent node
This type is useful as a sentinel, but is never emitted by the reader.
*/
SERD_NOTHING = 0,
/**
- Literal value.
+ Literal value
A literal optionally has either a language, or a datatype (not both).
*/
SERD_LITERAL = 1,
/**
- URI (absolute or relative).
+ URI (absolute or relative)
Value is an unquoted URI string, which is either a relative reference
with respect to the current base URI (e.g. "foo/bar"), or an absolute
URI (e.g. "http://example.org/foo").
- @see <a href="http://tools.ietf.org/html/rfc3986">RFC3986</a>.
+ @see [RFC3986](http://tools.ietf.org/html/rfc3986)
*/
SERD_URI = 2,
/**
- CURIE, a shortened URI.
+ CURIE, a shortened URI
Value is an unquoted CURIE string relative to the current environment,
- e.g. "rdf:type".
- @see <a href="http://www.w3.org/TR/curie">CURIE Syntax 1.0</a>
+ e.g. "rdf:type". @see [CURIE Syntax 1.0](http://www.w3.org/TR/curie)
*/
SERD_CURIE = 3,
/**
- A blank node.
+ A blank node
- Value is a blank node ID, e.g. "id3", which is meaningful only within
- this serialisation.
- @see <a href="http://www.w3.org/TeamSubmission/turtle#nodeID">Turtle
- <tt>nodeID</tt></a>
+ Value is a blank node ID without any syntactic prefix, like "id3", which
+ is meaningful only within this serialisation. @see [RDF 1.1
+ Turtle](http://www.w3.org/TR/turtle/#grammar-production-BLANK_NODE_LABEL)
*/
SERD_BLANK = 4
} SerdNodeType;
-/**
- Flags indicating certain string properties relevant to serialisation.
-*/
+/// Flags indicating certain string properties relevant to serialisation
typedef enum {
- SERD_HAS_NEWLINE = 1, /**< Contains line breaks ('\\n' or '\\r') */
- SERD_HAS_QUOTE = 1 << 1, /**< Contains quotes ('"') */
- SERD_HAS_DATATYPE = 1 << 2, /**< Literal node has datatype */
- SERD_HAS_LANGUAGE = 1 << 3 /**< Literal node has language */
+ SERD_HAS_NEWLINE = 1, ///< Contains line breaks ('\\n' or '\\r')
+ SERD_HAS_QUOTE = 1 << 1, ///< Contains quotes ('"')
+ SERD_HAS_DATATYPE = 1 << 2, ///< Literal node has datatype
+ SERD_HAS_LANGUAGE = 1 << 3 ///< Literal node has language
} SerdNodeFlag;
-/**
- Field in a statement.
-*/
+/// Bitwise OR of SerdNodeFlag values
+typedef uint32_t SerdNodeFlags;
+
+/// Field in a statement
typedef enum {
- SERD_SUBJECT = 0, /**< Subject */
- SERD_PREDICATE = 1, /**< Predicate ("key") */
- SERD_OBJECT = 2, /**< Object ("value") */
- SERD_GRAPH = 3 /**< Graph ("context") */
+ SERD_SUBJECT = 0, ///< Subject
+ SERD_PREDICATE = 1, ///< Predicate ("key")
+ SERD_OBJECT = 2, ///< Object ("value")
+ SERD_GRAPH = 3 ///< Graph ("context")
} SerdField;
-/**
- Bitwise OR of SerdNodeFlag values.
-*/
-typedef uint32_t SerdNodeFlags;
-
-/**
- A syntactic RDF node.
-*/
+/// A syntactic RDF node
typedef struct SerdNodeImpl SerdNode;
-/**
- An unterminated immutable slice of a string.
-*/
+/// An unterminated immutable slice of a string
typedef struct {
- const char* buf; /**< Start of chunk */
- size_t len; /**< Length of chunk in bytes */
+ const char* buf; ///< Start of chunk
+ size_t len; ///< Length of chunk in bytes
} SerdStringView;
-/**
- A mutable buffer in memory.
-*/
+/// A mutable buffer in memory
typedef struct {
- void* buf; /**< Buffer */
- size_t len; /**< Size of buffer in bytes */
+ void* buf; ///< Buffer
+ size_t len; ///< Size of buffer in bytes
} SerdBuffer;
-/**
- Log message level.
-*/
+/// Log message level
typedef enum {
- SERD_LOG_LEVEL_INFO = 0, /**< Normal informative message */
- SERD_LOG_LEVEL_WARNING = 1, /**< Warning */
- SERD_LOG_LEVEL_ERROR = 2, /**< Error */
+ SERD_LOG_LEVEL_INFO = 0, ///< Normal informative message
+ SERD_LOG_LEVEL_WARNING = 1, ///< Warning
+ SERD_LOG_LEVEL_ERROR = 2, ///< Error
} SerdLogLevel;
-/**
- A message description.
-*/
+/// A message description
typedef struct {
- SerdStatus status; /**< Status code */
- SerdLogLevel level; /**< Log level */
- const SerdCursor* cursor; /**< Origin of message, or NULL */
- const char* fmt; /**< Message format string (printf style) */
- va_list* args; /**< Arguments for fmt */
+ SerdStatus status; ///< Status code
+ SerdLogLevel level; ///< Log level
+ const SerdCursor* cursor; ///< Origin of message, or NULL
+ const char* fmt; ///< Message format string (printf style)
+ va_list* args; ///< Arguments for fmt
} SerdMessage;
/**
- A parsed URI.
+ A parsed URI
This struct directly refers to slices in other strings, it does not own any
memory itself. Thus, URIs can be parsed and/or resolved against a base URI
in-place without allocating memory.
*/
typedef struct {
- SerdStringView scheme; /**< Scheme */
- SerdStringView authority; /**< Authority */
- SerdStringView path_base; /**< Path prefix if relative */
- SerdStringView path; /**< Path suffix */
- SerdStringView query; /**< Query */
- SerdStringView fragment; /**< Fragment */
+ SerdStringView scheme; ///< Scheme
+ SerdStringView authority; ///< Authority
+ SerdStringView path_base; ///< Path prefix if relative
+ SerdStringView path; ///< Path suffix
+ SerdStringView query; ///< Query
+ SerdStringView fragment; ///< Fragment
} SerdURI;
/**
- Writer style options.
+ Writer style options
The style of the writer output can be controlled by ORing together
values from this enumeration. Note that some options are only supported
@@ -323,16 +240,14 @@ typedef struct {
always ASCII).
*/
typedef enum {
- SERD_STYLE_ASCII = 1 << 0, /**< Escape all non-ASCII characters. */
+ SERD_STYLE_ASCII = 1 << 0, ///< Escape all non-ASCII characters
} SerdWriterFlag;
-/**
- Bitwise OR of SerdWriterFlag values.
-*/
+/// Bitwise OR of SerdWriterFlag values
typedef uint32_t SerdWriterFlags;
/**
- Free memory allocated by Serd.
+ Free memory allocated by Serd
This function exists because some systems require memory allocated by a
library to be freed by code in the same library. It is otherwise equivalent
@@ -347,15 +262,14 @@ serd_free(void* ptr);
@{
*/
-/**
- Return a string describing a status code.
-*/
+/// Return a string describing a status code
SERD_API
const char*
serd_strerror(SerdStatus status);
/**
- Measure a UTF-8 string.
+ Measure a UTF-8 string
+
@return Length of `str` in bytes.
@param str A null-terminated UTF-8 string.
@param flags (Output) Set to the applicable flags.
@@ -365,7 +279,7 @@ size_t
serd_strlen(const char* str, SerdNodeFlags* flags);
/**
- Parse a string to a double.
+ Parse a string to a double
The API of this function is similar to the standard C strtod function,
except this function is locale-independent and always matches the lexical
@@ -384,7 +298,7 @@ serd_strtod(const char* str, size_t* end);
*/
/**
- Return the number of bytes required to encode `size` bytes in base64.
+ Return the number of bytes required to encode `size` bytes in base64
@param size The number of input (binary) bytes to encode.
@param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
@@ -395,7 +309,7 @@ size_t
serd_base64_encoded_length(size_t size, bool wrap_lines);
/**
- Return the maximum number of bytes required to decode `size` bytes of base64.
+ Return the maximum number of bytes required to decode `size` bytes of base64
@param len The number of input (text) bytes to decode.
@return The required buffer size to decode `size` bytes of base64.
@@ -405,7 +319,7 @@ size_t
serd_base64_decoded_size(size_t len);
/**
- Encode `size` bytes of `buf` into `str`, which must be large enough.
+ Encode `size` bytes of `buf` into `str`, which must be large enough
@param str Output buffer of at least serd_base64_encoded_length(size) bytes.
@param buf Input binary data.
@@ -418,7 +332,7 @@ bool
serd_base64_encode(char* str, const void* buf, size_t size, bool wrap_lines);
/**
- Decode a base64 string.
+ Decode a base64 string
This function can be used to deserialise a blob node created with
serd_new_blob().
@@ -439,7 +353,7 @@ serd_base64_decode(void* buf, size_t* size, const char* str, size_t len);
*/
/**
- Function to detect I/O stream errors.
+ Function to detect I/O stream errors
Identical semantics to `ferror`.
@@ -448,7 +362,7 @@ serd_base64_decode(void* buf, size_t* size, const char* str, size_t len);
typedef int (*SerdStreamErrorFunc)(void* stream);
/**
- Source function for raw string input.
+ Source function for raw string input
Identical semantics to `fread`, but may set errno for more informative error
reporting than supported by SerdStreamErrorFunc.
@@ -465,7 +379,7 @@ typedef size_t (*SerdReadFunc)(void* buf,
void* stream);
/**
- Sink function for raw string output.
+ Sink function for raw string output
Identical semantics to `fwrite`, but may set errno for more informative
error reporting than supported by SerdStreamErrorFunc.
@@ -482,7 +396,7 @@ typedef size_t (*SerdWriteFunc)(const void* buf,
void* stream);
/**
- Create a new byte sink.
+ Create a new byte sink
@param write_func Function called with bytes to consume.
@param stream Context parameter passed to `sink`.
@@ -493,7 +407,7 @@ SerdByteSink*
serd_byte_sink_new(SerdWriteFunc write_func, void* stream, size_t block_size);
/**
- Write to `sink`.
+ Write to `sink`
Compatible with SerdWriteFunc.
*/
@@ -504,16 +418,12 @@ serd_byte_sink_write(const void* buf,
size_t nmemb,
SerdByteSink* sink);
-/**
- Flush any pending output in `sink` to the underlying write function.
-*/
+/// Flush any pending output in `sink` to the underlying write function
SERD_API
void
serd_byte_sink_flush(SerdByteSink* sink);
-/**
- Free `sink`.
-*/
+/// Free `sink`
SERD_API
void
serd_byte_sink_free(SerdByteSink* sink);
@@ -525,7 +435,7 @@ serd_byte_sink_free(SerdByteSink* sink);
*/
/**
- Get a syntax by name.
+ Get a syntax by name
Case-insensitive, supports "Turtle", "NTriples", "NQuads", and "TriG". Zero
is returned if the name is not recognized.
@@ -535,7 +445,7 @@ SerdSyntax
serd_syntax_by_name(const char* name);
/**
- Guess a syntax from a filename.
+ Guess a syntax from a filename
This uses the file extension to guess the syntax of a file. Zero is
returned if the extension is not recognized.
@@ -545,7 +455,7 @@ SerdSyntax
serd_guess_syntax(const char* filename);
/**
- Guess a syntax from a filename.
+ Guess a syntax from a filename
This uses the file extension to guess the syntax of a file. Zero is
returned if the extension is not recognized.
@@ -565,49 +475,44 @@ static const SerdURI SERD_URI_NULL = {
};
/**
- Get the unescaped path and hostname from a file URI.
+ Get the unescaped path and hostname from a file URI
+
+ The returned path and `*hostname` must be freed with serd_free().
+
@param uri A file URI.
@param hostname If non-NULL, set to the hostname, if present.
@return The path component of the URI.
-
- The returned path and `*hostname` must be freed with serd_free().
*/
SERD_API
char*
serd_file_uri_parse(const char* uri, char** hostname);
-/**
- Return true iff `utf8` starts with a valid URI scheme.
-*/
+/// Return true iff `utf8` starts with a valid URI scheme
SERD_API
bool
serd_uri_string_has_scheme(const char* utf8);
-/**
- Parse `utf8`, writing result to `out`.
-*/
+/// Parse `utf8`, writing result to `out`
SERD_API
SerdStatus
serd_uri_parse(const char* utf8, SerdURI* out);
/**
- Set target `t` to reference `r` resolved against `base`.
+ Set target `t` to reference `r` resolved against `base`
- @see http://tools.ietf.org/html/rfc3986#section-5.2.2
+ @see [RFC3986 5.2.2](http://tools.ietf.org/html/rfc3986#section-5.2.2)
*/
SERD_API
void
serd_uri_resolve(const SerdURI* r, const SerdURI* base, SerdURI* t);
-/**
- Serialise `uri` with a series of calls to `sink`.
-*/
+/// Serialise `uri` with a series of calls to `sink`
SERD_API
size_t
serd_uri_serialise(const SerdURI* uri, SerdWriteFunc sink, void* stream);
/**
- Serialise `uri` relative to `base` with a series of calls to `sink`.
+ Serialise `uri` relative to `base` with a series of calls to `sink`
The `uri` is written as a relative URI iff if it a child of `base` and @c
root. The optional `root` parameter must be a prefix of `base` and can be
@@ -627,15 +532,13 @@ serd_uri_serialise_relative(const SerdURI* uri,
@{
*/
-/**
- Create a new plain literal string node from `str`.
-*/
+/// Create a new plain literal string node from `str`
SERD_API
SerdNode*
serd_new_string(const char* str);
/**
- Create a new plain literal node from `str`.
+ Create a new plain literal node from `str`
A plain literal has no datatype, but may have a language tag. The `lang`
may be NULL, in which case this is equivalent to `serd_new_string()`.
@@ -645,7 +548,7 @@ SerdNode*
serd_new_plain_literal(const char* str, const char* lang);
/**
- Create a new typed literal node from `str`.
+ Create a new typed literal node from `str`
A typed literal has no language tag, but may have a datatype. The
`datatype` may be NULL, in which case this is equivalent to
@@ -655,36 +558,28 @@ SERD_API
SerdNode*
serd_new_typed_literal(const char* str, const SerdNode* datatype);
-/**
- Create a new blank node.
-*/
+/// Create a new blank node
SERD_API
SerdNode*
serd_new_blank(const char* str);
-/**
- Create a new CURIE node.
-*/
+/// Create a new CURIE node
SERD_API
SerdNode*
serd_new_curie(const char* str);
-/**
- Return a deep copy of `node`.
-*/
+/// Return a deep copy of `node`
SERD_API
SerdNode*
serd_node_copy(const SerdNode* node);
-/**
- Return true iff `a` is equal to `b`.
-*/
+/// Return true iff `a` is equal to `b`
SERD_API
bool
serd_node_equals(const SerdNode* a, const SerdNode* b);
/**
- Compare two nodes.
+ Compare two nodes
Returns less than, equal to, or greater than zero if `a` is less than, equal
to, or greater than `b`, respectively. NULL is treated as less than any
@@ -694,22 +589,18 @@ SERD_API
int
serd_node_compare(const SerdNode* a, const SerdNode* b);
-/**
- Create a new URI from a string.
-*/
+/// Create a new URI from a string
SERD_API
SerdNode*
serd_new_uri(const char* str);
-/**
- Create a new URI from a string, resolved against a base URI.
-*/
+/// Create a new URI from a string, resolved against a base URI
SERD_API
SerdNode*
serd_new_resolved_uri(const char* str, const SerdNode* base);
/**
- Resolve `node` against `base`.
+ Resolve `node` against `base`
If `node` is not a relative URI, an equivalent new node is returned.
*/
@@ -718,7 +609,7 @@ SerdNode*
serd_node_resolve(const SerdNode* node, const SerdNode* base);
/**
- Create a new file URI node from a file system path and optional hostname.
+ Create a new file URI node from a file system path and optional hostname
Backslashes in Windows paths will be converted, and other characters will be
percent encoded as necessary.
@@ -731,17 +622,15 @@ SerdNode*
serd_new_file_uri(const char* path, const char* hostname);
/**
- Create a new URI from a string, relative to a base URI.
-
- @param str URI string.
-
- @param base Base URI to make `str` relative to, if possible.
-
- @param root Optional root URI for resolution.
+ Create a new URI from a string, relative to a base URI
The URI is made relative iff if it a child of `base` and `root`. The
optional `root` parameter must be a prefix of `base` and can be used keep
up-references ("../") within a certain namespace.
+
+ @param str URI string.
+ @param base Base URI to make `str` relative to, if possible.
+ @param root Optional root URI for resolution.
*/
SERD_API
SerdNode*
@@ -750,7 +639,7 @@ serd_new_relative_uri(const char* str,
const SerdNode* root);
/**
- Create a new node by serialising `d` into an xsd:decimal string.
+ Create a new node by serialising `d` into an xsd:decimal string
The resulting node will always contain a `.', start with a digit, and end
with a digit (i.e. will have a leading and/or trailing `0' if necessary).
@@ -762,41 +651,33 @@ serd_new_relative_uri(const char* str,
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.
-
- @param datatype Datatype of node, may be NULL in which case the node has
- type xsd:decimal.
+ @param datatype Datatype of node, or NULL for xsd:decimal.
*/
SERD_API
SerdNode*
serd_new_decimal(double d, unsigned frac_digits, const SerdNode* datatype);
/**
- Create a new node by serialising `i` into an xsd:integer string.
+ Create a new node by serialising `i` into an xsd:integer string
@param i Integer value to serialise.
-
- @param datatype Datatype of node, may be NULL in which case the node has
- type xsd:integer.
+ @param datatype Datatype of node, or NULL for xsd:integer.
*/
SERD_API
SerdNode*
serd_new_integer(int64_t i, const SerdNode* datatype);
/**
- Create a node by serialising `buf` into an xsd:base64Binary string.
+ Create a node by serialising `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 `buf`.
-
@param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
-
- @param datatype Datatype of node, may be NULL in which case the node has
- type xsd:base64Binary.
+ @param datatype Datatype of node, or NULL for xsd:base64Binary.
*/
SERD_API
SerdNode*
@@ -805,54 +686,37 @@ serd_new_blob(const void* buf,
bool wrap_lines,
const SerdNode* datatype);
-/**
- Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL).
-*/
+/// Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL)
SERD_API
SerdNodeType
serd_node_get_type(const SerdNode* node);
-/**
- Return the string value of a node.
-*/
+/// Return the string value of a node
SERD_API
const char*
serd_node_get_string(const SerdNode* node);
-/**
- Return the length of the string value of a node in bytes.
-*/
+/// Return the length of the string value of a node in bytes
SERD_API
size_t
serd_node_get_length(const SerdNode* node);
-/**
- Return the datatype of a literal node, or NULL.
-*/
+/// Return the datatype of a literal node, or NULL
SERD_API
const SerdNode*
serd_node_get_datatype(const SerdNode* node);
-/**
- Return the language tag of a literal node, or NULL.
-*/
+/// Return the language tag of a literal node, or NULL
SERD_API
const SerdNode*
serd_node_get_language(const SerdNode* node);
-/**
- Return the flags (string properties) of a node.
-*/
+/// Return the flags (string properties) of a node
SERD_API
SerdNodeFlags
serd_node_get_flags(const SerdNode* node);
-/**
- Free any data owned by `node`.
-
- Note that if `node` is itself dynamically allocated (which is not the case
- for nodes created internally by serd), it will not be freed.
-*/
+/// Free `node`
SERD_API
void
serd_node_free(SerdNode* node);
@@ -864,24 +728,22 @@ serd_node_free(SerdNode* node);
*/
/**
- Sink (callback) for log messages.
+ Sink (callback) for log messages
@param handle Handle for user data.
@param msg Message description.
*/
-typedef SerdStatus (*SerdMessageSink)(void* handle,
- const SerdMessage* msg);
+typedef SerdStatus (*SerdMessageSink)(void* handle, const SerdMessage* msg);
/**
- Sink (callback) for base URI changes.
+ Sink (callback) for base URI changes
Called whenever the base URI of the serialisation changes.
*/
-typedef SerdStatus (*SerdBaseSink)(void* handle,
- const SerdNode* uri);
+typedef SerdStatus (*SerdBaseSink)(void* handle, const SerdNode* uri);
/**
- Sink (callback) for namespace definitions.
+ Sink (callback) for namespace definitions
Called whenever a prefix is defined in the serialisation.
*/
@@ -890,7 +752,7 @@ typedef SerdStatus (*SerdPrefixSink)(void* handle,
const SerdNode* uri);
/**
- Sink (callback) for statements.
+ Sink (callback) for statements
Called for every RDF statement in the serialisation.
*/
@@ -899,14 +761,13 @@ typedef SerdStatus (*SerdStatementSink)(void* handle,
const SerdStatement* statement);
/**
- Sink (callback) for anonymous node end markers.
+ Sink (callback) for anonymous node end markers
This is called to indicate that the anonymous node with the given
`value` will no longer be referred to by any future statements
(i.e. the anonymous serialisation of the node is finished).
*/
-typedef SerdStatus (*SerdEndSink)(void* handle,
- const SerdNode* node);
+typedef SerdStatus (*SerdEndSink)(void* handle, const SerdNode* node);
/**
@}
@@ -915,7 +776,7 @@ typedef SerdStatus (*SerdEndSink)(void* handle,
*/
/**
- Create a new Serd World.
+ Create a new World
It is safe to use multiple worlds in one process, though no objects can be
shared between worlds.
@@ -924,15 +785,13 @@ SERD_API
SerdWorld*
serd_world_new(void);
-/**
- Free `world`.
-*/
+/// Free `world`
SERD_API
void
serd_world_free(SerdWorld* world);
/**
- Return the nodes cache in `world`.
+ Return the nodes cache in `world`
The returned cache is owned by the world and contains various nodes used
frequently by the implementation. For convenience, it may be used to store
@@ -943,7 +802,7 @@ SerdNodes*
serd_world_get_nodes(SerdWorld* world);
/**
- Return a unique blank node.
+ Return a unique blank node
The returned node is valid only until the next time serd_world_get_blank()
is called or the world is destroyed.
@@ -953,7 +812,7 @@ const SerdNode*
serd_world_get_blank(SerdWorld* world);
/**
- Set a function to be called with log messages (typically errors).
+ Set a function to be called with log messages (typically errors)
The `msg_sink` will be called with `handle` as its first argument. If
no sink is set, messages are printed to stderr.
@@ -970,58 +829,42 @@ serd_world_set_message_sink(SerdWorld* world,
@{
*/
-/**
- Create a new environment.
-*/
+/// Create a new environment
SERD_API
SerdEnv*
serd_env_new(const SerdNode* base_uri);
-/**
- Copy an environment.
-*/
+/// Copy an environment
SERD_API
SerdEnv*
serd_env_copy(const SerdEnv* env);
-/**
- Return true iff `a` is equal to `b`.
-*/
+/// Return true iff `a` is equal to `b`
SERD_API
bool
serd_env_equals(const SerdEnv* a, const SerdEnv* b);
-/**
- Free `ns`.
-*/
+/// Free `env`
SERD_API
void
serd_env_free(SerdEnv* env);
-/**
- Get the current base URI.
-*/
+/// Get the current base URI
SERD_API
const SerdNode*
serd_env_get_base_uri(const SerdEnv* env);
-/**
- Set the current base URI.
-*/
+/// Set the current base URI
SERD_API
SerdStatus
serd_env_set_base_uri(SerdEnv* env, const SerdNode* uri);
-/**
- Set a namespace prefix.
-*/
+/// Set a namespace prefix
SERD_API
SerdStatus
serd_env_set_prefix(SerdEnv* env, const SerdNode* name, const SerdNode* uri);
-/**
- Set a namespace prefix.
-*/
+/// Set a namespace prefix
SERD_API
SerdStatus
serd_env_set_prefix_from_strings(SerdEnv* env,
@@ -1029,7 +872,7 @@ serd_env_set_prefix_from_strings(SerdEnv* env,
const char* uri);
/**
- Qualify `uri` into a CURIE if possible.
+ Qualify `uri` into a CURIE if possible
Returns null if `node` can not be qualified.
*/
@@ -1038,7 +881,9 @@ SerdNode*
serd_env_qualify(const SerdEnv* env, const SerdNode* uri);
/**
- Expand `node`, which must be a CURIE or URI, to a full URI.
+ Expand `node`, transforming CURIEs into URIs
+
+ If `node` is a literal, its datatype is expanded if necessary.
Returns null if `node` can not be expanded.
*/
@@ -1046,9 +891,7 @@ SERD_API
SerdNode*
serd_env_expand(const SerdEnv* env, const SerdNode* node);
-/**
- Write all prefixes in `env` to `sink`.
-*/
+/// Write all prefixes in `env` to `sink`
SERD_API
void
serd_env_write_prefixes(const SerdEnv* env, const SerdSink* sink);
@@ -1060,7 +903,7 @@ serd_env_write_prefixes(const SerdEnv* env, const SerdSink* sink);
*/
/**
- Create a new sink.
+ Create a new sink
Initially, the sink has no set functions and will do nothing. Use the
serd_sink_set_*_func functions to set handlers for various events.
@@ -1072,84 +915,56 @@ SERD_API
SerdSink*
serd_sink_new(void* handle, SerdEnv* env);
-/**
- Free `sink`.
-*/
+/// Free `sink`
SERD_API
void
serd_sink_free(SerdSink* sink);
-/**
- Return the env used by `writer`.
-*/
+/// Return the env used by `sink`
SERD_API
const SerdEnv*
serd_sink_get_env(const SerdSink* sink);
-/**
- Set a function to be called when the base URI changes.
-*/
+/// Set a function to be called when the base URI changes
SERD_API
SerdStatus
serd_sink_set_base_func(SerdSink* sink, SerdBaseSink base_func);
-/**
- Set a function to be called when a namespace prefix is defined.
-*/
+/// Set a function to be called when a namespace prefix is defined
SERD_API
SerdStatus
serd_sink_set_prefix_func(SerdSink* sink, SerdPrefixSink prefix_func);
-/**
- Set a function to be called when a statement is emitted.
-*/
+/// Set a function to be called when a statement is emitted
SERD_API
SerdStatus
serd_sink_set_statement_func(SerdSink* sink, SerdStatementSink statement_func);
-/**
- Set a function to be called when an anonymous node ends.
-*/
+/// Set a function to be called when an anonymous node ends
SERD_API
SerdStatus
serd_sink_set_end_func(SerdSink* sink, SerdEndSink end_func);
-/**
- Set the base URI.
-
- Simple wrapper for the `SerdBaseSink` of `sink`.
-*/
+/// Set the base URI
SERD_API
SerdStatus
serd_sink_write_base(const SerdSink* sink, const SerdNode* uri);
-/**
- Set a namespace prefix.
-
- Simple wrapper for the `SerdPrefixSink` of `sink`.
-*/
+/// Set a namespace prefix
SERD_API
SerdStatus
serd_sink_write_prefix(const SerdSink* sink,
const SerdNode* name,
const SerdNode* uri);
-/**
- Write a statement.
-
- Simple wrapper for the `SerdStatementSink` of `sink`.
-*/
+/// Write a statement
SERD_API
SerdStatus
serd_sink_write_statement(const SerdSink* sink,
SerdStatementFlags flags,
const SerdStatement* statement);
-/**
- Write a statement from individual nodes.
-
- Simple wrapper for the `SerdStatementSink` of `sink`.
-*/
+/// Write a statement from individual nodes
SERD_API
SerdStatus
serd_sink_write(const SerdSink* sink,
@@ -1159,11 +974,7 @@ serd_sink_write(const SerdSink* sink,
const SerdNode* object,
const SerdNode* graph);
-/**
- Mark the end of an anonymous node.
-
- Simple wrapper for the `SerdEndSink` of `sink`.
-*/
+/// Mark the end of an anonymous node
SERD_API
SerdStatus
serd_sink_write_end(const SerdSink* sink, const SerdNode* node);
@@ -1174,9 +985,7 @@ serd_sink_write_end(const SerdSink* sink, const SerdNode* node);
@{
*/
-/**
- Create a new RDF reader.
-*/
+/// Create a new RDF reader
SERD_API
SerdReader*
serd_reader_new(SerdWorld* world,
@@ -1185,7 +994,7 @@ serd_reader_new(SerdWorld* world,
size_t stack_size);
/**
- Enable or disable strict parsing.
+ Enable or disable strict parsing
The reader is non-strict (lax) by default, which will tolerate URIs with
invalid characters. Setting strict will fail when parsing such files. An
@@ -1196,7 +1005,7 @@ void
serd_reader_set_strict(SerdReader* reader, bool strict);
/**
- Set a prefix to be added to all blank node identifiers.
+ Set a prefix to be added to all blank node identifiers
This is useful when multiple files are to be parsed into the same output
(e.g. a store, or other files). Since Serd preserves blank node IDs, this
@@ -1206,18 +1015,15 @@ serd_reader_set_strict(SerdReader* reader, bool strict);
*/
SERD_API
void
-serd_reader_add_blank_prefix(SerdReader* reader,
- const char* prefix);
+serd_reader_add_blank_prefix(SerdReader* reader, const char* prefix);
-/**
- Prepare to read from the file at a local file `uri`.
-*/
+/// Prepare to read from the file at a local file `uri`
SERD_API
SerdStatus
serd_reader_start_file(SerdReader* reader, const char* uri, bool bulk);
/**
- Prepare to read from a stream.
+ Prepare to read from a stream
The `read_func` is guaranteed to only be called for `page_size` elements
with size 1 (i.e. `page_size` bytes).
@@ -1231,9 +1037,7 @@ serd_reader_start_stream(SerdReader* reader,
const SerdNode* name,
size_t page_size);
-/**
- Prepare to read from a string.
-*/
+/// Prepare to read from a string
SERD_API
SerdStatus
serd_reader_start_string(SerdReader* reader,
@@ -1241,7 +1045,7 @@ serd_reader_start_string(SerdReader* reader,
const SerdNode* name);
/**
- Read a single "chunk" of data during an incremental read.
+ Read a single "chunk" of data during an incremental read
This function will read a single top level description, and return. This
may be a directive, statement, or several statements; essentially it reads
@@ -1253,7 +1057,7 @@ SerdStatus
serd_reader_read_chunk(SerdReader* reader);
/**
- Read a complete document from the source.
+ Read a complete document from the source
This function will continue pulling from the source until a complete
document has been read. Note that this may block when used with streams,
@@ -1264,7 +1068,7 @@ SerdStatus
serd_reader_read_document(SerdReader* reader);
/**
- Finish reading from the source.
+ Finish reading from the source
This will close the open file, if applicable, and ensure the reader has
processed all input.
@@ -1274,7 +1078,7 @@ SerdStatus
serd_reader_finish(SerdReader* reader);
/**
- Free `reader`.
+ Free `reader`
The reader will be finished via `serd_reader_finish()` if necessary.
*/
@@ -1288,9 +1092,7 @@ serd_reader_free(SerdReader* reader);
@{
*/
-/**
- Create a new RDF writer.
-*/
+/// Create a new RDF writer
SERD_API
SerdWriter*
serd_writer_new(SerdWorld* world,
@@ -1300,29 +1102,23 @@ serd_writer_new(SerdWorld* world,
SerdWriteFunc write_func,
void* stream);
-/**
- Free `writer`.
-*/
+/// Free `writer`
SERD_API
void
serd_writer_free(SerdWriter* writer);
-/**
- Return a sink interface that emits statements via `writer`.
-*/
+/// Return a sink interface that emits statements via `writer`
SERD_API
const SerdSink*
serd_writer_get_sink(SerdWriter* writer);
-/**
- Return the env used by `writer`.
-*/
+/// Return the env used by `writer`
SERD_API
SerdEnv*
serd_writer_get_env(SerdWriter* writer);
/**
- A convenience sink function for writing to a string.
+ A convenience sink function for writing to a string
This function can be used as a SerdSink to write to a SerdBuffer which is
resized as necessary with realloc(). The `stream` parameter must point to
@@ -1334,35 +1130,31 @@ size_t
serd_buffer_sink(const void* buf, size_t size, size_t nmemb, void* stream);
/**
- Finish a serialisation to a buffer with serd_buffer_sink().
+ Finish a serialisation to a buffer with serd_buffer_sink()
- The returned string is the result of the serialisation, which is NULL
+ The returned string is the result of the serialisation, which is null
terminated (by this function) and owned by the caller.
*/
SERD_API
char*
serd_buffer_sink_finish(SerdBuffer* 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
void
-serd_writer_chop_blank_prefix(SerdWriter* writer,
- const char* prefix);
+serd_writer_chop_blank_prefix(SerdWriter* writer, const char* 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.
*/
SERD_API
SerdStatus
-serd_writer_set_base_uri(SerdWriter* writer,
- const SerdNode* uri);
+serd_writer_set_base_uri(SerdWriter* writer, const SerdNode* uri);
/**
- Set the current root URI.
+ Set the current root URI
The root URI should be a prefix of the base URI. The path of the root URI
is the highest path any relative up-reference can refer to. For example,
@@ -1373,12 +1165,9 @@ serd_writer_set_base_uri(SerdWriter* writer,
*/
SERD_API
SerdStatus
-serd_writer_set_root_uri(SerdWriter* writer,
- const SerdNode* uri);
+serd_writer_set_root_uri(SerdWriter* writer, const SerdNode* uri);
-/**
- Finish a write.
-*/
+/// Finish a write
SERD_API
SerdStatus
serd_writer_finish(SerdWriter* writer);
@@ -1389,15 +1178,13 @@ serd_writer_finish(SerdWriter* writer);
@{
*/
-/**
- Create a new node set.
-*/
+/// Create a new node set
SERD_API
SerdNodes*
serd_nodes_new(void);
/**
- Free `nodes` and all nodes that are stored in it.
+ Free `nodes` and all nodes that are stored in it
Note that this invalidates any pointers previously returned from
`serd_nodes_intern()` or `serd_nodes_manage()` calls on `nodes`.
@@ -1407,7 +1194,7 @@ void
serd_nodes_free(SerdNodes* nodes);
/**
- Intern `node`.
+ Intern `node`
Multiple calls with equivalent nodes will return the same pointer.
@@ -1418,7 +1205,7 @@ const SerdNode*
serd_nodes_intern(SerdNodes* nodes, const SerdNode* node);
/**
- Manage `node`.
+ Manage `node`
Like `serd_nodes_intern`, but takes ownership of `node`, freeing it and
returning a previously interned/managed equivalent node if necessary.
@@ -1430,7 +1217,7 @@ const SerdNode*
serd_nodes_manage(SerdNodes* nodes, SerdNode* node);
/**
- Dereference `node`.
+ Dereference `node`
Decrements the reference count of `node`, and frees the internally stored
equivalent node if this was the last reference. Does nothing if no node
@@ -1446,44 +1233,32 @@ serd_nodes_deref(SerdNodes* nodes, const SerdNode* node);
@{
*/
-/**
- Return the given node in `statement`.
-*/
+/// Return the given node in `statement`
SERD_API
const SerdNode*
serd_statement_get_node(const SerdStatement* statement, SerdField field);
-/**
- Return the subject in `statement`.
-*/
+/// Return the subject in `statement`
SERD_API
const SerdNode*
serd_statement_get_subject(const SerdStatement* statement);
-/**
- Return the predicate in `statement`.
-*/
+/// Return the predicate in `statement`
SERD_API
const SerdNode*
serd_statement_get_predicate(const SerdStatement* statement);
-/**
- Return the object in `statement`.
-*/
+/// Return the object in `statement`
SERD_API
const SerdNode*
serd_statement_get_object(const SerdStatement* statement);
-/**
- Return the graph in `statement`.
-*/
+/// Return the graph in `statement`
SERD_API
const SerdNode*
serd_statement_get_graph(const SerdStatement* statement);
-/**
- Return the source location where `statement` originated, or NULL.
-*/
+/// Return the source location where `statement` originated, or NULL
SERD_API
const SerdCursor*
serd_statement_get_cursor(const SerdStatement* statement);
@@ -1529,7 +1304,7 @@ bool
serd_cursor_equals(const SerdCursor* lhs, const SerdCursor* rhs);
/**
- Return the document name.
+ Return the document name
This is typically a file URI, but may be a descriptive string node for
statements that originate from streams.
@@ -1538,16 +1313,12 @@ SERD_API
const SerdNode*
serd_cursor_get_name(const SerdCursor* cursor);
-/**
- Return the one-relative line number in the document.
-*/
+/// Return the one-relative line number in the document
SERD_API
unsigned
serd_cursor_get_line(const SerdCursor* cursor);
-/**
- Return the zero-relative column number in the line.
-*/
+/// Return the zero-relative column number in the line
SERD_API
unsigned
serd_cursor_get_column(const SerdCursor* cursor);