Serd  0.14.0
Structures | Opaque Types | Enumerations
Serd

Structures

struct  SerdNode
 A syntactic RDF node. More...
struct  SerdChunk
 An unterminated string fragment. More...
struct  SerdURI
 A parsed URI. More...

Opaque Types

typedef struct SerdEnvImpl SerdEnv
typedef struct SerdReaderImpl SerdReader
typedef struct SerdWriterImpl SerdWriter
typedef uint32_t SerdStatementFlags
typedef uint32_t SerdNodeFlags

Enumerations

enum  SerdStatus {
  SERD_SUCCESS, SERD_FAILURE, SERD_ERR_UNKNOWN, SERD_ERR_BAD_SYNTAX,
  SERD_ERR_BAD_ARG, SERD_ERR_NOT_FOUND
}
enum  SerdSyntax { SERD_TURTLE = 1, SERD_NTRIPLES = 2 }
enum  SerdStatementFlag {
  SERD_EMPTY_S = 1 << 1, SERD_EMPTY_O = 1 << 2, SERD_ANON_S_BEGIN = 1 << 3, SERD_ANON_O_BEGIN = 1 << 4,
  SERD_ANON_CONT = 1 << 5, SERD_LIST_S_BEGIN = 1 << 6, SERD_LIST_O_BEGIN = 1 << 7, SERD_LIST_CONT = 1 << 8
}
enum  SerdType {
  SERD_NOTHING = 0, SERD_LITERAL = 1, SERD_URI = 2, SERD_CURIE = 3,
  SERD_BLANK = 4
}
enum  SerdNodeFlag { SERD_HAS_NEWLINE = 1, SERD_HAS_QUOTE = 1 << 1 }
enum  SerdStyle {
  SERD_STYLE_ABBREVIATED = 1, SERD_STYLE_ASCII = 1 << 1, SERD_STYLE_RESOLVED = 1 << 2, SERD_STYLE_CURIED = 1 << 3,
  SERD_STYLE_BULK = 1 << 4
}

String Utilities

const uint8_t * serd_strerror (SerdStatus status)
size_t serd_strlen (const uint8_t *str, size_t *n_bytes, SerdNodeFlags *flags)
double serd_strtod (const char *str, char **endptr)
void * serd_base64_decode (const uint8_t *str, size_t len, size_t *size)

URI

typedef size_t(* SerdSink )(const void *buf, size_t len, void *stream)
static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}}
const uint8_t * serd_uri_to_path (const uint8_t *uri)
uint8_t * serd_file_uri_parse (const uint8_t *uri, uint8_t **hostname)
bool serd_uri_string_has_scheme (const uint8_t *utf8)
SerdStatus serd_uri_parse (const uint8_t *utf8, SerdURI *out)
void serd_uri_resolve (const SerdURI *uri, const SerdURI *base, SerdURI *out)
size_t serd_uri_serialise (const SerdURI *uri, SerdSink sink, void *stream)
size_t serd_uri_serialise_relative (const SerdURI *uri, const SerdURI *base, const SerdURI *root, SerdSink sink, void *stream)

Node

static const SerdNode SERD_NODE_NULL = { 0, 0, 0, 0, SERD_NOTHING }
SerdNode serd_node_from_string (SerdType type, const uint8_t *str)
SerdNode serd_node_copy (const SerdNode *node)
bool serd_node_equals (const SerdNode *a, const SerdNode *b)
SerdNode serd_node_new_uri_from_node (const SerdNode *uri_node, const SerdURI *base, SerdURI *out)
SerdNode serd_node_new_uri_from_string (const uint8_t *str, const SerdURI *base, SerdURI *out)
SerdNode serd_node_new_file_uri (const uint8_t *path, const uint8_t *hostname, SerdURI *out, bool escape)
SerdNode serd_node_new_uri (const SerdURI *uri, const SerdURI *base, SerdURI *out)
SerdNode serd_node_new_decimal (double d, unsigned frac_digits)
SerdNode serd_node_new_integer (int64_t i)
SerdNode serd_node_new_blob (const void *buf, size_t size, bool wrap_lines)
void serd_node_free (SerdNode *node)

Event Handlers

typedef SerdStatus(* SerdBaseSink )(void *handle, const SerdNode *uri)
typedef SerdStatus(* SerdPrefixSink )(void *handle, const SerdNode *name, const SerdNode *uri)
typedef SerdStatus(* SerdStatementSink )(void *handle, SerdStatementFlags flags, const SerdNode *graph, const SerdNode *subject, const SerdNode *predicate, const SerdNode *object, const SerdNode *object_datatype, const SerdNode *object_lang)
typedef SerdStatus(* SerdEndSink )(void *handle, const SerdNode *node)

Environment

SerdEnvserd_env_new (const SerdNode *base_uri)
void serd_env_free (SerdEnv *env)
const SerdNodeserd_env_get_base_uri (const SerdEnv *env, SerdURI *out)
SerdStatus serd_env_set_base_uri (SerdEnv *env, const SerdNode *uri)
SerdStatus serd_env_set_prefix (SerdEnv *env, const SerdNode *name, const SerdNode *uri)
SerdStatus serd_env_set_prefix_from_strings (SerdEnv *env, const uint8_t *name, const uint8_t *uri)
bool serd_env_qualify (const SerdEnv *env, const SerdNode *uri, SerdNode *prefix, SerdChunk *suffix)
SerdStatus serd_env_expand (const SerdEnv *env, const SerdNode *curie, SerdChunk *uri_prefix, SerdChunk *uri_suffix)
SerdNode serd_env_expand_node (const SerdEnv *env, const SerdNode *node)
void serd_env_foreach (const SerdEnv *env, SerdPrefixSink func, void *handle)

Reader

SerdReaderserd_reader_new (SerdSyntax syntax, void *handle, void(*free_handle)(void *), SerdBaseSink base_sink, SerdPrefixSink prefix_sink, SerdStatementSink statement_sink, SerdEndSink end_sink)
void * serd_reader_get_handle (const SerdReader *reader)
void serd_reader_add_blank_prefix (SerdReader *reader, const uint8_t *prefix)
void serd_reader_set_default_graph (SerdReader *reader, const SerdNode *graph)
SerdStatus serd_reader_read_file (SerdReader *reader, const uint8_t *uri)
SerdStatus serd_reader_read_file_handle (SerdReader *reader, FILE *file, const uint8_t *name)
SerdStatus serd_reader_read_string (SerdReader *me, const uint8_t *utf8)
void serd_reader_free (SerdReader *reader)

Writer

SerdWriterserd_writer_new (SerdSyntax syntax, SerdStyle style, SerdEnv *env, const SerdURI *base_uri, SerdSink sink, void *stream)
void serd_writer_free (SerdWriter *writer)
SerdEnvserd_writer_get_env (SerdWriter *writer)
size_t serd_file_sink (const void *buf, size_t len, void *stream)
size_t serd_chunk_sink (const void *buf, size_t len, void *stream)
uint8_t * serd_chunk_sink_finish (SerdChunk *stream)
void serd_writer_chop_blank_prefix (SerdWriter *writer, const uint8_t *prefix)
SerdStatus serd_writer_set_base_uri (SerdWriter *writer, const SerdNode *uri)
SerdStatus serd_writer_set_root_uri (SerdWriter *writer, const SerdNode *uri)
SerdStatus serd_writer_set_prefix (SerdWriter *writer, const SerdNode *name, const SerdNode *uri)
SerdStatus serd_writer_write_statement (SerdWriter *writer, SerdStatementFlags flags, const SerdNode *graph, const SerdNode *subject, const SerdNode *predicate, const SerdNode *object, const SerdNode *object_datatype, const SerdNode *object_lang)
SerdStatus serd_writer_end_anon (SerdWriter *writer, const SerdNode *node)
SerdStatus serd_writer_finish (SerdWriter *writer)

Detailed Description

A lightweight RDF syntax library.

Typedef Documentation

typedef struct SerdEnvImpl SerdEnv

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.

typedef struct SerdReaderImpl SerdReader

RDF reader.

Parses RDF by calling user-provided sink functions as input is consumed (much like an XML SAX parser).

typedef struct SerdWriterImpl SerdWriter

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.

typedef uint32_t SerdStatementFlags

Bitwise OR of SerdNodeFlag values.

typedef uint32_t SerdNodeFlags

Bitwise OR of SerdNodeFlag values.

typedef size_t(* SerdSink)(const void *buf, size_t len, void *stream)

Sink function for raw string output.

typedef SerdStatus(* SerdBaseSink)(void *handle, const SerdNode *uri)

Sink (callback) for base URI changes.

Called whenever the base URI of the serialisation changes.

typedef SerdStatus(* SerdPrefixSink)(void *handle, const SerdNode *name, const SerdNode *uri)

Sink (callback) for namespace definitions.

Called whenever a prefix is defined in the serialisation.

typedef SerdStatus(* SerdStatementSink)(void *handle, SerdStatementFlags flags, const SerdNode *graph, const SerdNode *subject, const SerdNode *predicate, const SerdNode *object, const SerdNode *object_datatype, const SerdNode *object_lang)

Sink (callback) for statements.

Called for every RDF statement in the serialisation.

typedef SerdStatus(* SerdEndSink)(void *handle, const SerdNode *node)

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).

Enumeration Type Documentation

enum SerdStatus

Return status code.

Enumerator:
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.

enum SerdSyntax

RDF syntax type.

Enumerator:
SERD_TURTLE 

Turtle - Terse RDF Triple Language (UTF-8).

See Also
Turtle
SERD_NTRIPLES 

NTriples - Line-based RDF triples (ASCII).

See Also
NTriples

Flags indication inline abbreviation information for a statement.

Enumerator:
SERD_EMPTY_S 

Empty blank node subject.

SERD_EMPTY_O 

Empty blank node object.

SERD_ANON_S_BEGIN 

Start of anonymous subject.

SERD_ANON_O_BEGIN 

Start of anonymous object.

SERD_ANON_CONT 

Continuation of anonymous node.

SERD_LIST_S_BEGIN 

Start of list subject.

SERD_LIST_O_BEGIN 

Start of list object.

SERD_LIST_CONT 

Continuation of list.

enum SerdType

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 to refer to a resource (by URI or CURIE) and two ways to refer to a blank (by ID or anonymously). Anonymous (inline) blank nodes are expressed using SerdStatementFlags rather than this type.

Enumerator:
SERD_NOTHING 

The type of a nonexistent node.

This type is useful as a sentinel, but is never emitted by the reader.

SERD_LITERAL 

Literal value.

A literal optionally has either a language, or a datatype (not both).

SERD_URI 

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 Also
RFC3986.
SERD_CURIE 

CURIE, a shortened URI.

Value is an unquoted CURIE string relative to the current environment, e.g. "rdf:type".

See Also
CURIE Syntax 1.0
SERD_BLANK 

A blank node.

Value is a blank node ID, e.g. "id3", which is meaningful only within this serialisation.

See Also
Turtle nodeID

Flags indicating certain string properties relevant to serialisation.

Enumerator:
SERD_HAS_NEWLINE 

Contains line breaks ('\n' or '\r')

SERD_HAS_QUOTE 

Contains quotes ('"')

enum SerdStyle

Syntax 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 for some syntaxes (e.g. NTriples does not support abbreviation and is always ASCII).

Enumerator:
SERD_STYLE_ABBREVIATED 

Abbreviate triples when possible.

SERD_STYLE_ASCII 

Escape all non-ASCII characters.

SERD_STYLE_RESOLVED 

Resolve URIs against base URI.

SERD_STYLE_CURIED 

Shorten URIs into CURIEs.

SERD_STYLE_BULK 

Write output in pages.

Function Documentation

const uint8_t* serd_strerror ( SerdStatus  status)

Return a string describing a status code.

size_t serd_strlen ( const uint8_t *  str,
size_t *  n_bytes,
SerdNodeFlags flags 
)

Measure a UTF-8 string.

Returns
Length of str in characters (except NULL).
Parameters
strA null-terminated UTF-8 string.
n_bytes(Output) Set to the size of str in bytes (except NULL).
flags(Output) Set to the applicable flags.
double serd_strtod ( const char *  str,
char **  endptr 
)

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 lexical format used in the Turtle grammar (the decimal point is always ".").

void* serd_base64_decode ( const uint8_t *  str,
size_t  len,
size_t *  size 
)

Decode a base64 string.

This function can be used to deserialise a blob node created with serd_node_new_blob().

Parameters
strBase64 string to decode.
lenThe length of str.
sizeSet to the size of the returned blob in bytes.
Returns
A newly allocated blob which must be freed with free().
const uint8_t* serd_uri_to_path ( const uint8_t *  uri)

Return the local path for uri, or NULL if uri is not a file URI.

Note this (inappropriately named) function only removes the file scheme if necessary, and returns uri unmodified if it is an absolute path. Percent encoding and other issues are not handled, to properly convert a file URI to a path, use serd_file_uri_parse().

uint8_t* serd_file_uri_parse ( const uint8_t *  uri,
uint8_t **  hostname 
)

Get the unescaped path and hostname from a file URI.

Parameters
uriA file URI.
hostnameIf non-NULL, set to the hostname, if present.
Returns
The path component of the URI.

Both the returned path and hostname (if applicable) are owned by the caller and must be freed with free().

bool serd_uri_string_has_scheme ( const uint8_t *  utf8)

Return true iff utf8 starts with a valid URI scheme.

SerdStatus serd_uri_parse ( const uint8_t *  utf8,
SerdURI out 
)

Parse utf8, writing result to out.

void serd_uri_resolve ( const SerdURI uri,
const SerdURI base,
SerdURI out 
)

Set out to uri resolved against base.

size_t serd_uri_serialise ( const SerdURI uri,
SerdSink  sink,
void *  stream 
)

Serialise uri with a series of calls to sink.

size_t serd_uri_serialise_relative ( const SerdURI uri,
const SerdURI base,
const SerdURI root,
SerdSink  sink,
void *  stream 
)

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 root. The optional root parameter must be a prefix of base and can be used keep up-references ("../") within a certain namespace.

SerdNode serd_node_from_string ( SerdType  type,
const uint8_t *  str 
)

Make a (shallow) node from str.

This measures, but does not copy, str. No memory is allocated.

SerdNode serd_node_copy ( const SerdNode node)

Make a deep copy of node.

Returns
a node that the caller must free with serd_node_free.
bool serd_node_equals ( const SerdNode a,
const SerdNode b 
)

Return true iff a is equal to b.

SerdNode serd_node_new_uri_from_node ( const SerdNode uri_node,
const SerdURI base,
SerdURI out 
)

Simple wrapper for serd_node_new_uri to resolve a URI node.

SerdNode serd_node_new_uri_from_string ( const uint8_t *  str,
const SerdURI base,
SerdURI out 
)

Simple wrapper for serd_node_new_uri to resolve a URI string.

SerdNode serd_node_new_file_uri ( const uint8_t *  path,
const uint8_t *  hostname,
SerdURI out,
bool  escape 
)

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 escape is true, all other invalid characters will be percent encoded as well.

If path is relative, hostname is ignored. If out is not NULL, it will be set to the parsed URI.

SerdNode serd_node_new_uri ( const SerdURI uri,
const SerdURI base,
SerdURI out 
)

Create a new node by serialising uri into a new string.

Parameters
uriThe URI to parse and serialise.
baseBase URI to resolve uri against (or NULL for no resolution).
outSet to the parsing of the new URI (i.e. points only to memory owned by the new returned node).
SerdNode serd_node_new_decimal ( double  d,
unsigned  frac_digits 
)

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). It will never be in scientific notation. A maximum of frac_digits digits will be written after the decimal point, but trailing zeros will automatically be omitted (except one if d is a round integer).

Note that about 16 and 8 fractional digits are required to precisely represent a double and float, respectively.

Parameters
dThe value for the new node.
frac_digitsThe maximum number of digits after the decimal place.
SerdNode serd_node_new_integer ( int64_t  i)

Create a new node by serialising i into an xsd:integer string.

SerdNode serd_node_new_blob ( const void *  buf,
size_t  size,
bool  wrap_lines 
)

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().

Parameters
bufRaw binary input data.
sizeSize of buf.
wrap_linesWrap lines at 76 characters to conform to RFC 2045.
void serd_node_free ( 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.

SerdEnv* serd_env_new ( const SerdNode base_uri)

Create a new environment.

void serd_env_free ( SerdEnv env)

Free ns.

const SerdNode* serd_env_get_base_uri ( const SerdEnv env,
SerdURI out 
)

Get the current base URI.

SerdStatus serd_env_set_base_uri ( SerdEnv env,
const SerdNode uri 
)

Set the current base URI.

SerdStatus serd_env_set_prefix ( SerdEnv env,
const SerdNode name,
const SerdNode uri 
)

Set a namespace prefix.

SerdStatus serd_env_set_prefix_from_strings ( SerdEnv env,
const uint8_t *  name,
const uint8_t *  uri 
)

Set a namespace prefix.

bool serd_env_qualify ( const SerdEnv env,
const SerdNode uri,
SerdNode prefix,
SerdChunk suffix 
)

Qualify uri into a CURIE if possible.

SerdStatus serd_env_expand ( const SerdEnv env,
const SerdNode curie,
SerdChunk uri_prefix,
SerdChunk uri_suffix 
)

Expand curie.

SerdNode serd_env_expand_node ( const SerdEnv env,
const SerdNode node 
)

Expand node, which must be a CURIE or URI, to a full URI.

void serd_env_foreach ( const SerdEnv env,
SerdPrefixSink  func,
void *  handle 
)

Call func for each prefix defined in env.

SerdReader* serd_reader_new ( SerdSyntax  syntax,
void *  handle,
void(*)(void *)  free_handle,
SerdBaseSink  base_sink,
SerdPrefixSink  prefix_sink,
SerdStatementSink  statement_sink,
SerdEndSink  end_sink 
)

Create a new RDF reader.

void* serd_reader_get_handle ( const SerdReader reader)

Return the handle passed to serd_reader_new.

void serd_reader_add_blank_prefix ( SerdReader reader,
const uint8_t *  prefix 
)

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 could cause conflicts where two non-equivalent blank nodes are merged, resulting in corrupt data. By setting a unique blank node prefix for each parsed file, this can be avoided, while preserving blank node names.

void serd_reader_set_default_graph ( SerdReader reader,
const SerdNode graph 
)

Set the URI of the default graph.

If this is set, the reader will emit quads with the graph set to the given node for any statements that are not in a named graph (which is currently all of them since Serd currently does not support any graph syntaxes).

SerdStatus serd_reader_read_file ( SerdReader reader,
const uint8_t *  uri 
)

Read a file at a given uri.

SerdStatus serd_reader_read_file_handle ( SerdReader reader,
FILE *  file,
const uint8_t *  name 
)

Read file.

SerdStatus serd_reader_read_string ( SerdReader me,
const uint8_t *  utf8 
)

Read utf8.

void serd_reader_free ( SerdReader reader)

Free reader.

SerdWriter* serd_writer_new ( SerdSyntax  syntax,
SerdStyle  style,
SerdEnv env,
const SerdURI base_uri,
SerdSink  sink,
void *  stream 
)

Create a new RDF writer.

void serd_writer_free ( SerdWriter writer)

Free writer.

SerdEnv* serd_writer_get_env ( SerdWriter writer)

Return the env used by writer.

size_t serd_file_sink ( const void *  buf,
size_t  len,
void *  stream 
)

A convenience sink function for writing to a FILE*.

This function can be used as a SerdSink when writing to a FILE*. The stream parameter must be a FILE* opened for writing.

size_t serd_chunk_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 stream parameter must point to an initialized SerdChunk. When the write is finished, the string should be retrieved with serd_chunk_sink_finish().

uint8_t* serd_chunk_sink_finish ( SerdChunk 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.

void serd_writer_chop_blank_prefix ( SerdWriter writer,
const uint8_t *  prefix 
)

Set a prefix to be removed from matching blank node identifiers.

SerdStatus serd_writer_set_base_uri ( SerdWriter writer,
const SerdNode uri 
)

Set the current output base URI (and emit directive if applicable).

Note this function can be safely casted to SerdBaseSink.

SerdStatus serd_writer_set_root_uri ( SerdWriter writer,
const SerdNode 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, 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.

SerdStatus serd_writer_set_prefix ( SerdWriter writer,
const SerdNode name,
const SerdNode uri 
)

Set a namespace prefix (and emit directive if applicable).

Note this function can be safely casted to SerdPrefixSink.

SerdStatus serd_writer_write_statement ( SerdWriter writer,
SerdStatementFlags  flags,
const SerdNode graph,
const SerdNode subject,
const SerdNode predicate,
const SerdNode object,
const SerdNode object_datatype,
const SerdNode object_lang 
)

Write a statement.

Note this function can be safely casted to SerdStatementSink.

SerdStatus serd_writer_end_anon ( SerdWriter writer,
const SerdNode node 
)

Mark the end of an anonymous node's description.

Note this function can be safely casted to SerdEndSink.

SerdStatus serd_writer_finish ( SerdWriter writer)

Finish a write.

Variable Documentation

const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}}
static
const SerdNode SERD_NODE_NULL = { 0, 0, 0, 0, SERD_NOTHING }
static