libraptor(3)libraptor(3)NAMElibraptor - Raptor RDF parser and serializer library
SYNOPSIS
#include <raptor.h>
raptor_init();
raptor_parser *p=raptor_new_parser("rdfxml");
raptor_set_statement_handler(p,NULL,print_triples);
raptor_uri *file_uri=raptor_new_uri("http://example.org/");
raptor_parse_file(p,file_uri,base_uri);
raptor_parse_uri(p,uri,NULL);
raptor_free_parser(p);
raptor_free_uri(file_uri);
raptor_finish();
cc file.c -lraptor
DESCRIPTION
The Raptor library provides a high-level interface to a set of parsers
and serializers that generate Resource Description Framework (RDF)
triples by parsing syntaxes or serialize the triples into syntaxes.
The supported parsing syntaxes are RDF/XML, N-Triples, Turtle, RSS tag
soup including Atom 0.3 and the serializing syntaxes are RDF/XML, N-
Triples and RSS 1.0. The RDF/XML parser can use either expat or libxml
XML parsers for providing the SAX event stream. The library functions
are arranged in an object-oriented style with constructors, destructors
and method calls. The statements and error messages are delivered via
callback functions.
Raptor contains a URI-reference parsing and resolving (not retrieval)
class (raptor_uri) sufficient for dealing with URI-references inside
RDF. This functionality is modular and can be transparently replaced
with another existing and compatible URI implementation.
It also provides a URI-retrieval class (raptor_www) for wrapping exist‐
ing library such as libcurl, libxml2 or BSD libfetch that provides full
or partial retrieval of data from URIs and an I/O stream abstraction
(raptor_iostream) for supportin serializing to a variety of outputs.
Raptor uses Unicode strings for RDF literals and URIs and preserves
them throughout the library. It uses the UTF-8 encoding of Unicode at
the API for passing in or returning Unicode strings. It is intended
that the preservation of Unicode for URIs will support International‐
ized Resource Identifiers (IRIs) which are still under development and
standardisation.
LIBRARY INITIALISATION AND CLEANUPraptor_init()raptor_finish()
Initialise and cleanup the library. These must be called before
any raptor class such as raptor_parser, raptor_uri is created or
used.
PARSER CLASS
This class provides the functionality of turning syntaxes into RDF
triples - RDF parsing.
PARSER CONSTRUCTORS
raptor_parser* raptor_new_parser(name)
Create a new raptor parser object for the parser with name name
currently either "rdfxml", "turtle" or "rss-tag-soup" for the
RSS Tag Soup parser.
raptor_parser* raptor_new_parser_for_content(raptor_uri *uri, const
char *mime_type, const unsigned char *buffer, size_t len, const
unsigned char *identifier)
Create a new raptor parser object for a syntax identified by URI
uri, MIME type mime_type, some initial content buffer of size
len or content with identifier identifier. See the rap‐
tor_guess_parser_name description for further details.
PARSER DESTRUCTOR
void raptor_free_parser(raptor_parser *parser)
Destroy a Raptor parser object.
PARSER MESSAGE CALLBACK METHODS
Several methods can be registered for the parser that return a vari‐
able-argument message in the style of printf(3). These also return a
raptor_locator that can contain URI, file, line, column and byte counts
of where the message is about. This structure can be used with the rap‐
tor_format_locator, raptor_print_locator functions below or the struc‐
tures fields directly, which are defined in raptor.h
void raptor_set_fatal_error_handler(raptor_parser* parser, void
*user_data, raptor_message_handler handler)
Set the parser fatal error handler callback.
void raptor_set_error_handler(raptor_parser* parser, void *user_data,
raptor_message_handler handler)
Set the parser non-fatal error handler callback.
void raptor_set_warning_handler(raptor_parser* parser, void *user_data,
raptor_message_handler handler)
Set the parser warning message handler callback.
raptor_set_namespace_handler(raptor_parser* parser, void* user_data,
raptor_namespace_handler handler)
Set the namespace declaration handler callback.
PARSER STATEMENT CALLBACK METHOD
The parser allows the registration of a callback function to return the
statements to the application.
void raptor_set_statement_handler(raptor_parser* parser, void
*user_data, raptor_statement_handler handler)
Set the statement callback function for the parser. The rap‐
tor_statement structure is defined in raptor.h and includes
fields for the subject, predicate, object of the statements
along with their types and for literals, language and datatype.
PARSER PARSING METHODS
These methods perform the entire parsing in one method. Statements
warnings, errors and fatal errors are delivered via the registered
statement, error etc. handler functions.
In both of these methods, the base URI is required for the RDF/XML
parser (name "rdfxml") and Turtle parser (name "turtle"). The N-
Triples parser (name "ntriples") or RSS Tag Soup parser (name "rss-tag-
soup") do not use this.
int raptor_parse_file(raptor_parser* parser, raptor_uri *uri, rap‐
tor_uri *base_uri)
Parse the given filename (a URI like file:filename) according to
the optional base URI base_uri. If uri is NULL, read from stan‐
dard input and base_uri is then required.
int raptor_parse_file_stream(raptor_parser* parser, FILE* stream, const
char* filename, raptor_uri *base_uri)
Parse the given C FILE* stream according to the base URI
base_uri (required). filename is optional and if given, is used
for error messages via the raptor_locator structure.
int raptor_parse_uri(raptor_parser* parser, raptor_uri* uri, rap‐
tor_uri *base_uri)
Parse the URI according to the base URI base_uri, or NULL if not
needed. If no base URI is given, the uri is used. This method
depends on the raptor_www subsystem (see WWW Class section
below) and an existing underlying URI retrieval implementation
such as libcurl, libxml or BSD libfetch to retrieve the content.
PARSER CHUNKED PARSING METHODS
These methods perform the parsing in parts by working on multiple
chunks of memory passed by the application. Statements warnings,
errors and fatal errors are delivered via the registered statement,
error etc. handler functions.
int raptor_start_parse(raptor_parser* parser, const char *uri)
Start a parse of chunked content with the base URI uri or NULL
if not needed. The base URI is required for the RDF/XML parser
(name "rdfxml") and Turtle parser (name "turtle"). The N-
Triples parser (name "ntriples") or RSS Tag Soup parser (name
"rss-tag-soup") do not use this.
int raptor_parse_chunk(raptor_parser* parser, const unsigned char
*buffer, size_t len, int is_end)
Parse the memory at buffer of size len returning statements via
the statement handler callback. If is_end is non-zero, it indi‐
cates the end of the parsing stream. This method can only be
called after raptor_start_parse.
PARSER UTILITY METHODS
const char* raptor_get_mime_type(raptor_parser* rdf_parser)
Return the MIME type for the parser.
void raptor_set_parser_strict(raptor_parser *parser, int is_strict)
Set the parser to strict (is_strict not zero) or lax (default)
mode. The detail of the strictness can be controlled by rap‐
tor_set_feature.
int raptor_set_feature(raptor_parser *parser, raptor_feature feature,
int value)
Set a parser feature feature to a particular value. Returns non
0 on failure or if the feature is unknown. The current defined
parser features are:
Feature Values
RAPTOR_FEATURE_SCANNING Boolean (non 0 true)
RAPTOR_FEATURE_ASSUME_IS_RDF Boolean (non 0 true)
RAPTOR_FEATURE_ALLOW_NON_NS_ATTRIBUTES Boolean (non 0 true)
RAPTOR_FEATURE_ALLOW_OTHER_PARSETYPES Boolean (non 0 true)
RAPTOR_FEATURE_ALLOW_BAGID Boolean (non 0 true)
RAPTOR_FEATURE_ALLOW_RDF_TYPE_RDF_LIST Boolean (non 0 true)
RAPTOR_FEATURE_NORMALIZE_LANGUAGE Boolean (non 0 true)
RAPTOR_FEATURE_NON_NFC_FATAL Boolean (non 0 true)
RAPTOR_FEATURE_WARN_OTHER_PARSETYPES Boolean (non 0 true)
RAPTOR_FEATURE_CHECK_RDF_ID Boolean (non 0 true)
RAPTOR_FEATURE_RELATIVE_URIS Boolean (non 0 true)
RAPTOR_FEATURE_START_URI Boolean (non 0 true)
RAPTOR_FEATURE_NO_NET Boolean (non 0 true)
APTOR_FEATURE_HTML_TAG_SOUP Boolean (non 0 true)
APTOR_FEATURE_MICROFORMATS Boolean (non 0 true)
APTOR_FEATURE_HTML_LINK Boolean (non 0 true)
APTOR_FEATURE_WWW_TIMEOUT Integer
RAPTOR_FEATURE_RESOURCE_BORDER String
RAPTOR_FEATURE_LITERAL_BORDER String
RAPTOR_FEATURE_BNODE_BORDER String
RAPTOR_FEATURE_RESOURCE_FILL String
RAPTOR_FEATURE_LITERAL_FILL String
RAPTOR_FEATURE_BNODE_FILL String
If the scanning feature is true (default false), then the RDF/XML
parser will look for embedded rdf:RDF elements inside the XML content,
and not require that the XML start with an rdf:RDF root element.
If the assume_is_rdf feature is true (default false), then the RDF/XML
parser will assume the content is RDF/XML, not require that rdf:RDF
root element, and immediately interpret the content as RDF/XML.
If the allow_non_ns_attributes feature is true (default true), then the
RDF/XML parser will allow non-XML namespaced attributes to be accepted
as well as rdf: namespaced ones. For example, 'about' and 'ID' will be
interpreted as if they were rdf:about and rdf:ID respectively.
If the allow_other_parsetypes feature is true (default true) then the
RDF/XML parser will allow unknown parsetypes to be present and will
pass them on to the user. Unimplemented at present.
If the allow_bagid feature is true (default true) then the RDF/XML
parser will support the rdf:bagID attribute that was removed from the
RDF/XML language when it was revised. This support may be removed in
future.
If the allow_rdf_type_rdf_list feature is true (default false) then the
RDF/XML parser will generate the idList rdf:type rdf:List triple in the
handling of rdf:parseType="Collection". This triple was removed during
the revising of RDF/XML after collections were initially added.
If the normalize_language feature is true (default true) then XML lan‐
guage values such as from xml:lang will be normalized to lowercase.
If the non_nfc_fatal feature is true (default false) then illegal Uni‐
code Normal Form C in literals will give a fatal error, otherwise it
gives a warning.
If the check_rdf_id feature is true (default true) then rdf:ID values
will be checked for duplicates and cause an error if found.
If the no_net feature is true (default false) then network requests are
denied.
If the html_tag_soup feature is true (default true), use a lax HTML
parser if an XML parser fails when read HTML for GRDDL parser.
If the microformats feature is true (default true), look for microfor‐
mats for GRDDL parser.
if the html_link feature is true (default true), look for head
<link> to type rdf/xml for GRDDL parser
If the www_timeout feature is set to an integer larger than 0, it sets
the timeout in seconds for internal WWW URI requests for the GRDDL
parser.
raptor_parser_set_feature_string(raptor_parser *parser, raptor_feature
feature, const unsigned char *value)
Set a parser feature feature to a particular string value.
Returns non 0 on failure or if the feature is unknown. The cur‐
rent defined parser features are given in raptor_set_feature and
at present only take integer values. If an integer value feature
is set with this function, value is interpreted as an integer
and then that value is used.
int raptor_get_feature(raptor_parser* parser, raptor_feature feature)
Get parser feature integer values. The allowed feature values
and types are given under raptor_features_enumerate.
const unsigned char* raptor_parser_get_feature_string(raptor_parser
*parser, raptor_feature feature)
Get parser feature string values. The allowed feature values and
types are given under raptor_features_enumerate.
unsigned int raptor_get_feature_count(void)
Get the count of features defined. Prefered to the compile
time-only symbol RAPTOR_FEATURE_LAST which returns the maximum
value, not the count. Added raptor_get_need_base_uri
int raptor_feature_value_type(const raptor_feature feature)
Get a raptor feature value tyype - integer or string.
raptor_locator* raptor_get_locator(raptor_parser* rdf_parser)
Return the current raptor_locator object for the parser. This
is a public structure defined in raptor.h that can be used
directly, or formatted via raptor_print_locator.
void raptor_get_name(raptor_parser *parser)
Return the string short name for the parser.
void raptor_get_label(raptor_parser *parser)
Return a string label for the parser.
void raptor_set_default_generate_id_parameters(raptor_parser*
rdf_parser, char *prefix, int base)
Control the default method for generation of IDs for blank nodes
and bags. The method uses a short string prefix and an integer
base to generate the identifier which is not guaranteed to be a
strict concatenation. If prefix is NULL, the default is used.
If base is less than 1, it is initialised to 1.
void raptor_set_generate_id_handler(raptor_parser* parser, void
*user_data, raptor_generate_id_handler handler)
Allow full customisation of the generated IDs by setting a call‐
back handler and associated user_data that is called whenever a
blank node or bag identifier is required. The memory returned
is deallocated inside raptor. Some systems require this to be
allocated inside the same library, in which case the rap‐
tor_alloc_memory function may be useful.
void raptor_parser_set_uri_filter(raptor_parser* parser, rap‐
tor_uri_filter_func filter, void* user_data)
Set the URI filter function filter for URIs retrieved during
parsing by the the raptor_parser.
int raptor_get_need_base_uri(raptor_parser* rdf_parser)
Get a boolean whether this parser needs a base URI to start
parsing.
unsigned char* raptor_parser_generate_id(raptor_parser* rdf_parser,
raptor_genid_type type)
Generate an ID for a parser of type type, either RAP‐
TOR_GENID_TYPE_BNODEID or RAPTOR_GENID_TYPE_BAGID. This uses
any configuration set by raptor_set_generate_id_handler.
void raptor_set_graph_handler(raptor_parser* parser, void* user_data,
raptor_graph_handler handler)
Set the graph handler callback.
PARSER UTILITY FUNCTIONS
int raptor_parsers_enumerate(const unsigned int counter, const char
**name, const char **label)
Return the parser name/label for a parser with a given integer
counter, returning non-zero if no such parser at that offset
exists. The counter should start from 0 and be incremented by 1
until the function returns non-zero.
int raptor_syntaxes_enumerate(const unsigned int counter, const char
**name, const char **label, const char **mime_type, const unsigned char
**uri-string)
Return the name, label, mime type or URI string (all optional)
for a parser syntax with a given integer counter, returning non-
zero if no such syntax parser at that offset exists. The
counter should start from 0 and be incremented by 1 until the
function returns non-zero.
int raptor_features_enumerate(const raptor_feature feature, const char
**name, raptor_uri **uri, const char **label)
Return the name, URI, string label (all optional) for a parser
feature, returning non-zero if no such feature exists.
Raptor features have URIs that are constructed from the URI http://fea‐
ture.librdf.org/raptor- and the name so for example feature scanForRDF
has URI http://feature.librdf.org/raptor-scanForRDF
int raptor_syntax_name_check(const char *name)
Check name is a known syntax name.
const char* raptor_guess_parser_name(raptor_uri *uri, const char
*mime_type, const unsigned char *buffer, size_t len, const unsigned
char *identifier)
Guess a parser name for a syntax identified by URI uri, MIME
type mime_type, some initial content buffer of size len or with
content identifier identifier. All of these parameters are
optional and only used if not NULL. The parser is chosen by
scoring the hints that are given.
raptor_feature raptor_feature_from_uri(raptor_uri *uri)
Turn a URI uri into a raptor feature identifier, or <0 if the
feature is unknown. The URIs are described below rap‐
tor_set_feature.
STATEMENT UTILITY FUNCTIONS
void raptor_print_statement(const raptor_statement* const statement,
FILE *stream)
Print a raptor statement object in a simple format for debugging
only. The format of this output is not guaranteed to remain the
same between releases.
void raptor_print_statement_as_ntriples(const raptor_statement* state‐
ment, FILE *stream)
Print a raptor statement object in N-Triples format, using all
the escapes as defined in http://www.w3.org/TR/rdf-
testcases/#ntriples ⟨http://www.w3.org/TR/rdf-
testcases/#ntriples⟩
raptor_statement_part_as_counted_string(const void *term, raptor_iden‐
tifier_type type, raptor_uri* literal_datatype, const unsigned char
*literal_language, size_t* len_p)
char* raptor_statement_part_as_string(const void *term, raptor_identi‐
fier_type type, raptor_uri* literal_datatype, const unsigned char *lit‐
eral_language)
Turns part of raptor statement into N-Triples format, using all
the escapes as defined in http://www.w3.org/TR/rdf-
testcases/#ntriples ⟨http://www.w3.org/TR/rdf-
testcases/#ntriples⟩ The part (subject, predicate, object) of
the raptor_statement is passed in as term, the part type (sub‐
ject_type, predicate_type, object_type) is passed in as type.
When the part is a literal, the literal_datatype and lit‐
eral_language fields are set, otherwise NULL (usually
object_datatype, object_literal_language).
If raptor_statement_part_as_counted_string is used, the length
of the returned string is stored in *len_p if not NULL.
LOCATOR UTILITY FUNCTIONS
int raptor_format_locator(char *buffer, size_t length, raptor_locator*
locator)
This method takes a raptor_locator object as passed to an error,
warning or other handler callback and formats it into the buffer
of size length bytes. If buffer is NULL or length is insuffi‐
cient for the size of the formatted locator, returns the number
of additional bytes required in the buffer to write the locator.
In particular, if this form is used:
length=raptor_format_locator(NULL, 0, locator) it will return
in length the size of a buffer that can be allocated for locator
and a second call will perform the formatting:
raptor_format_locator(buffer, length, locator)
void raptor_print_locator(FILE *stream, raptor_locator* locator)
This method takes a raptor_locator object as passed to an error,
warning or other handler callback, formats and prints it to the
given stdio stream.
int raptor_locator_line(raptor_locator *locator)
Returns the line number in a locator structure or <0 if not
available.
int raptor_locator_column(raptor_locator *locator)
Returns the column number in a locator structure or <0 if not
available.
int raptor_locator_byte(raptor_locator *locator)
Returns the byte offset in a locator structure or <0 if not
available.
const char * raptor_locator_file(raptor_locator *locator)
Returns the filename in a locator structure or NULL if not
available. Note the returned pointer is to a shared string that
must be copied if needed.
const char * raptor_locator_uri(raptor_locator *locator)
Returns the URI string in a locator structure or NULL if not
available. Note this does not return a raptor_uri* pointer and
the returned pointer is to a shared string that must be copied
if needed.
N-TRIPLES UTILITY FUNCTIONS
void raptor_print_ntriples_string(FILE* stream, const char* string,
const char delim)
This is a standalone function that prints the given string
according to N-Triples escaping rules, expecting to be termi‐
nated by delimiter delim which is usually either ', " or <. If
a null delimiter \0 is given, no extra escaping is performed.
int raptor_iostream_write_string_ntriples(raptor_iostream *iostr, const
unsigned char *string, size_t len, const char delim)
Write an N-Triples encoded version of the given string to
iostream iostr. If delim is given, that is the ending delimeter
of the encoded string and it will be escaped in the output as
appropriate. Useful delim values are ', " and >. If a null
delimiter \0 is given, no extra escaping is performed.
void raptor_iostream_write_statement_ntriples(raptor_iostream* iostr,
const raptor_statement *statement)
Write an N-Triples encoded version of the raptor_statement
statement to iostream iostr.
void raptor_iostream_write_string_turtle(raptor_iostream* iostr, const
unsigned char* string, size_t len)
Write an UTF-8 string of length len using the Turtle
"longString" triple quoting format to the iostream iostr.
const char* raptor_ntriples_term_as_string (raptor_ntriples_term_type
term)
Deprecated, for internal use.
XML UTILITY FUNCTIONS
int raptor_xml_any_escape_string(const unsigned char* string, size_t
len, unsigned char* buffer, size_t length, char quote, int xml_version,
raptor_simple_message_handler error_handler, void* error_data)
int raptor_xml_escape_string(const unsigned char *string, size_t len,
unsigned char *buffer, size_t length, char quote, raptor_message_han‐
dler error_handler, void *error_data)
Apply the XML escaping rules to the string given in (string,
len) into the buffer of size length. If quote is given, the
escaped content is for an XML attribute and the appropriate
quote character XML element content (CDATA). The error_handler
method along with error_data allow error reporting to be given.
If buffer is NULL, returns the size of the buffer required to
escape. Otherwise the return value is the number of bytes used
or <0 on failure.
When an xml_version argument is present and has a value 10 (XML
1.0) or 11 (XML 1.1) then that version is used. The default
with no argument is to generate XML 1.0.
int raptor_iostream_write_xml_any_escaped_string(raptor_iostream*
iostr, const unsigned char* string, size_t len, char quote, int
xml_version, raptor_simple_message_handler error_handler, void*
error_data)
int raptor_iostream_write_xml_escaped_string(raptor_iostream* iostr,
const unsigned char *string, size_t len, char quote, raptor_simple_mes‐
sage_handler error_handler, void *error_data)
Write an XML-escaped version of the string given in (string,
len) to iostream iostr. If quote is given, the escaped content
is for an XML attribute and the appropriate quote character is
used, otherwise it is XML element content (CDATA). The
error_handler method along with error_data allow error reporting
to be given.
When an xml_version argument is present and has a value 10 (XML
1.0) or 11 (XML 1.1) then that version is used. The default
with no argument is to generate XML 1.0.
int raptor_xml_name_check(const unsigned char *string, size_t length,
int xml_version)
Check that the given string of length bytes is a legal XML name
according to XML 1.0 or XML 1.1. xml_version is set to 10 or 11
respectively. Returns non-zero if the name is legal.
MEMORY UTILITY FUNCTIONS
void raptor_free_memory(void *ptr)
Free memory allocated inside raptor. Some systems require mem‐
ory allocated in a library to be deallocated inside that
library. This function can be used in that situation to free
memory allocated by raptor, such as the result of the _to_ meth‐
ods that return allocated memory such as raptor_uri_to_filename,
raptor_uri_to_string, raptor_uri_to_relative_counted_uri_string,
raptor_uri_to_relative_uri_string or raptor_new_names‐
pace_parts_from_string.
void* raptor_alloc_memory(size_t size)
Allocate memory inside the raptor library. Some systems require
memory allocated in a library to be deallocated inside that
library. This function can be used in that situation to allo‐
cate memory for raptor to free later, such as inside the handler
function declared with raptor_set_generate_id_handler which
returns new memory.
void* raptor_calloc_memory(size_t nmemb, size_t size)
Allocate zeroed array of items inside raptor. Some systems
require memory allocated in a library to be deallocated inside
that library. This function can be used in that situation to
clear an array of allocated memory for raptor to use, for free‐
ing later, such as inside the handler function declared with
raptor_set_generate_id_handler which returns new memory.
UNICODE UTILITY FUNCTIONS
int raptor_unicode_char_to_utf8(raptor_unichar c, unsigned char *out‐
put)
Turn a Unicode character into UTF8 bytes in output of size c
bytes which must be of sufficient size. Returns the number of
bytes encoded or <0 on failure.
int raptor_utf8_to_unicode_char(raptor_unichar *output, const unsigned
char *input, int length)
Decode a sequence UTF8 bytes in input of size length into a Uni‐
code character in output returning the number of bytes used or
<0 on failure.
int raptor_utf8_check(const unsigned char *string, size_t length)
Check that a given string is legal UTF-8 encoding and includes
only legal Unicode characters U+0 to U+0x10ffff inclusive.
Returns non-0 if the string is good.
int raptor_unicode_is_xml11_namestartchar(raptor_unichar c)
int raptor_unicode_is_xml10_namestartchar(raptor_unichar c)
int raptor_unicode_is_xml11_namechar(raptor_unichar c)
int raptor_unicode_is_xml10_namechar(raptor-unichar c)
Check that given Unicode characters are allowed as XML 1.0 or
XML 1.0 names - either as the starting character (*_names‐
tartchar) or continuing character (*_namechar). Returns non-0
if the character is allowed.
MISCELLANEOUS UTILITY FUNCTIONS
char* raptor_vsnprintf(const char *message, va_list arguments)
Compatibility wrapper around vsnprintf.
STATIC VARIABLES
There are several read-only static variables in the raptor library:
const char * const raptor_short_copyright_string
Short copyright string, suitable for one line.
const char * const raptor_copyright_string
Full copyright over several lines including URLs.
const char * const raptor_version_string
The version as a string
const unsigned int raptor_version_major
The major version number as an integer.
const unsigned int raptor_version_minor
The minor version number as an integer.
const unsigned int raptor_version_release
The release version number as an integer.
const unsigned int raptor_version_decimal
The version number as a single decimal.
const char * const raptor_license_string
The license string over several lines including URLs.
const char * const raptor_home_url_string
The home page URL as a string.
SERIALIZER CLASS
This class provides the functionality of turning RDF triples into syn‐
taxes - RDF serializing.
SERIALIZER CONSTRUCTOR
raptor_serializer* raptor_new_serializer(const char *name)
Create a new raptor serializer object for the serializer with
name name currently either "rdfxml" or "ntriples". or "rss-1.0"
for the RSS 1.0 serializer.
SERIALIZER DESTRUCTOR
void raptor_free_serializer(raptor_serializer* rdf_serializer)
Destroy a Raptor serializer object.
SERIALIZER SERIALIZING METHODS
int raptor_serialize_start(raptor_serializer* rdf_serializer, rap‐
tor_uri *uri, raptor_iostream *iostream)
Start to serialize content using the given iostream to write to
with optional base URI uri. Note that some syntaxes may refuse
to serialize without a base URI, such as RDF/XML.
int raptor_serialize_start_to_filename(raptor_serializer* rdf_serial‐
izer, const char *filename)
Start to serialize content to the file filename which is opened
for writing. The base URI is calculated from the file name.
int raptor_serialize_start_to_string(raptor_serializer* rdf_serializer,
raptor_uri *uri, void **string_p, size_t *length_p)
Start to serialize content to a string. string_p must point to
a void* pointer that will be used at the end of serializing to
store the newly allocated string. length_p if not NULL, it will
be used to store the length of the new string. The serializing
is done with optional base URI uri however some syntaxes may
refuse to serialize without a base URI, such as RDF/XML.
int raptor_serialize_start_to_file_handle(raptor_serializer* rdf_seri‐
alizer, raptor_uri *uri, FILE *handle)
Start to serialize content to the already open C Standard I/O
FILE* handle with the base URI uri, which is optional and may be
NULL. Note that some syntaxes may refuse to serialize without a
base URI, such as RDF/XML.
int raptor_serialize_statement(raptor_serializer* rdf_serializer, const
raptor_statement *statement)
Serialize a single statement using the serializer.
int raptor_serialize_end(raptor_serializer* rdf_serializer)
End the serializing. This may close and delete resources used
in serializing. No more calls to raptor_serialize_statement or
raptor_serialize_end may be done at this point.
raptor_iostream* raptor_serializer_get_iostream(raptor_serializer
*serializer)
Return a pointer to the raptor_iostream* used by the serializer.
int raptor_serializer_set_namespace(raptor_serializer* serializer, rap‐
tor_uri *uri, const char *prefix)
Set a suggested namespace URI/prefix mapping for use in serial‐
izing.
SERIALIZER UTILITY METHODS
void raptor_serializer_set_error_handler(raptor_serializer* serializer,
void *user_data, raptor_message_handler handler)
Set the serializer non-fatal error handler callback.
void raptor_serializer_set_warning_handler(raptor_serializer* serial‐
izer, void *user_data, raptor_message_handler handler)
Set the serializer warning message handler callback.
raptor_locator* raptor_serializer_get_locator(raptor_serializer*
rdf_serializer)
Return the current raptor_locator object for the serializer.
This is a public structure defined in raptor.h that can be used
directly, or formatted via raptor_print_locator.
int raptor_serializer_set_feature(raptor_serializer *serializer, rap‐
tor_feature feature, int value)
Set a serializer feature feature to a particular value. Returns
non 0 on failure or if the feature is unknown. The current
defined serializer features are:
Feature Values
RAPTOR_FEATURE_RELATIVE_URIS Boolean (non 0 true)
RAPTOR_FEATURE_START_URI URI String
If the relative_uris feature is true (default false) then when serial‐
ising, preference is given to generating relative URIs where possible.
If the start_uri feature is set to a URI it is used by the serializer
to start serializing from.
int raptor_serializer_get_feature(raptor_serializer* serializer, rap‐
tor_feature feature)
Get serializer features, the allowed feature values are avail‐
able
SERIALIZER UTILITY FUNCTIONS
int raptor_serializers_enumerate(const unsigned int counter, const char
**name, const char **label, const char **mime_type, const unsigned char
**uri_string)
Return the serializer name/label for a serializer with a given
integer counter, returning non-zero if no such parser at that
offset exists. The counter should start from 0 and be incre‐
mented by 1 until the function returns non-zero.
int raptor_serializer_syntax_name_check(const char *name)
Check name is a known serializer syntax name.
URI CLASS
Raptor has a raptor_uri class must be used for manipulating and passing
URI references. The default internal implementation uses char* strings
for URIs, manipulating them and constructing them. This URI implemen‐
tation can be replaced by any other that provides the equivalent func‐
tionality, using the raptor_uri_set_handler function.
URI CONSTRUCTORS
There a several constructors for raptor_uri to build them from char*
strings and existing raptor_uri objects.
raptor_uri* raptor_new_uri(const unsigned char* uri_string)
Create a raptor URI from a string URI-reference uri_string.
raptor_uri* raptor_new_uri_from_uri_local_name(raptor_uri* uri, const
unsigned char* local_name)
Create a raptor URI from a string URI-reference local_name rela‐
tive to an existing URI-reference. This performs concatenation
of the local_name to the uri and not relative URI resolution,
which is done by the raptor_new_uri_relative_to_base construc‐
tor.
raptor_uri* raptor_new_uri_relative_to_base(raptor_uri* base_uri, const
unsigned char* uri_string)
Create a raptor URI from a string URI-reference uri_string using
relative URI resolution to the base_uri.
raptor_uri* raptor_new_uri_from_id(raptor_uri* base_uri, const unsigned
char* id)
Create a raptor URI from a string RDF ID id concatenated to the
base_uri base URI.
raptor_uri* raptor_new_uri_for_rdf_concept(const char* name)
Create a raptor URI for the RDF namespace concept name.
raptor_uri* raptor_new_uri_for_xmlbase(raptor_uri* old_uri))
Create a raptor URI suitable for use with xml:base (throw away
fragment)
URI DESTRUCTOR
void raptor_free_uri(raptor_uri* uri)
Destroy a raptor URI object.
URI METHODS
int raptor_uri_equals(raptor_uri* uri1, raptor_uri* uri2)
Return non-zero if the given URIs are equal.
raptor_uri* raptor_uri_copy(raptor_uri* uri)
Return a copy of the given raptor URI uri.
unsigned char* raptor_uri_as_counted_string(raptor_uri *uri, size_t*
len_p)
unsigned char* raptor_uri_as_string(raptor_uri* uri)
Return a shared pointer to a string representation of the given
raptor URI uri. This string is shared and must not be freed
(otherwise see the raptor_uri_to_* methods below). If rap‐
tor_uri_as_counted_string is used, the length of the returned
string is stored in *len_p if not NULL.
unsigned char* raptor_uri_to_counted_string(raptor_uri *uri, size_t
*len_p)
unsigned char* raptor_uri_to_string(raptor_uri *uri)
Return a to a newly alloced string representation of the given
raptor URI uri. This string must be freed by the caller using
raptor_free_memory. If raptor_uri_to_counted_string is used,
the length of the returned string is stored in *len_p if not
NULL.
unsigned char* raptor_uri_to_relative_counted_uri_string(raptor_uri
*base_uri, raptor_uri *reference_uri, size_t *length_p)
unsigned char* raptor_uri_to_relative_uri_string(raptor_uri *base_uri,
raptor_uri *reference_uri)
Return a new relative URI string of a URI reference_uri against
a base URI base_uri. The returned string must be freed with
raptor_free_memory. If raptor_uri_to_relative_counted_string is
used, the length of the returned string is stored in *len_p if
not NULL.
void raptor_uri_print(const raptor_uri* uri, FILE *stream)
Print URI uri to the file handle stream.
int raptor_iostream_write_uri(raptor_iostream* iostr, raptor_uri* uri)
Write the raptor_uri uri to the iostream ostr.
URI UTILITY FUNCTIONS
void raptor_uri_resolve_uri_reference (const unsigned char* base_uri,
const unsigned char* reference_uri, char unsigned* buffer, size_t
length)
This is a standalone function that resolves the relative URI
reference_uri against the base URI base_uri according to the URI
resolution rules in RFC2396. The resulting URI is stored in
buffer which is of length bytes. If this is too small, no work
will be done.
char *raptor_uri_filename_to_uri_string(const unsigned char* filename)
This is a standalone function that turns a local filename (Win‐
dows or Unix style as appropriate for platform) into a URI
string (file).
The returned string must be freed by the caller. Some systems
require memory allocated in a library to be deallocated inside
that library in which case raptor_free_memory may be used.
char *raptor_uri_uri_string_to_filename(const unsigned char*
uri_string)
char *raptor_uri_uri_string_to_filename(const unsigned char*
uri_string, unsigned char **fragment_p)
These are standalone functions that turn a URI string that rep‐
resents a local filename (file:) into a filename, with optional
URI fragment. If fragment_p is not NULL it points to the loca‐
tion to store a newly allocated string containing the fragment.
The returned strings must be freed by the caller. Some systems
require memory allocated in a library to be deallocated inside
that library in which case raptor_free_memory may be used.
int raptor_uri_is_file_uri(const unsigned char* uri_string)
DEPRECATED in 1.4.9. Returns non-zero if the given URI string
represents a filename. Use raptor_uri_uri_string_is_file_uri in
preference.
int raptor_uri_uri_string_is_file_uri(const unsigned char* uri_string)
Returns non-zero if the given URI string represents a filename.
URI CLASS IMPLEMENTATION
void raptor_uri_set_handler(const raptor_uri_handler *handler, void
*context)
Change the URI class implementation to the functions provided by
the handler URI implementation. The context user data is passed
in to the handler URI implementation calls.
void raptor_uri_get_handler(raptor_uri_handler **handler, void **con‐
text)
Return the current raptor URI class implementation handler and
context
WWW CLASS
This is a small wrapper class around existing WWW libraries in order to
provide HTTP GET or better URI retrieval for Raptor. It is not
intended to be a general purpose WWW retrieval interface.
WWW CLASS INITIALISATION AND CLEANUP
void raptor_www_init(void)
void raptor_www_finish(void)
Initialise or terminate the raptor_www infrastructure. rap‐
tor_www_init and raptor_finish are called by raptor_init and
raptor_finish respecitively, otherwise must be called once each.
NOTE Several of the WWW library implementations require once-only
initialisation and termination functions to be called, however
raptor cannot determine whether this is already done before the
library is initialised in raptor_www_init or terminated in rap‐
tor_www_finish, so always performs it. This can be changed by
raptor_www_no_www_library_init_finish.
void raptor_www_no_www_library_init_finish(void)
If this is called before raptor_www_init, it will not call the
underlying WWW library global initialise or terminate functions.
The application code must perform both operations.
For example with curl, after this function is called, neither
curl_global_init nor curl_global_cleanup will be called during
raptor_www_init or raptor_www_finish respectively.
WWW CONSTRUCTORS
raptor_www *raptor_www_new(void)
raptor_www *raptor_www_new_with_connection(void* connection)
Create a raptor WWW object capable of URI retrieval. If connec‐
tion is given, it must match the connection object of the under‐
lying WWW implementation. At present, this is only for libcurl,
and allows you to re-use an existing curl handle, or use one
which has been set up with some desired qualities.
WWW DESTRUCTOR
void raptor_www_free(raptor_www *www)
Destroy a raptor WWW object.
WWW METHODS
void raptor_www_set_user_agent(raptor_www *www, const char *user_agent)
Set the user agent, for HTTP requests typically.
void raptor_www_set_proxy(raptor_www *www, const char *proxy)
Set the HTTP proxy - usually a string of the form
http://server:port
raptor_www_set_write_bytes_handler(raptor_www *www, rap‐
tor_www_write_bytes_handler handler, void *user_data)
Set the handler to receive bytes written by the raptor_www
implementation.
void raptor_www_set_content_type_handler(raptor_www *www, rap‐
tor_www_content_type_handler handler, void *user_data)
Set the handler to receive the HTTP Content-Type value, when/if
discovered during retrieval by the raptor_www implementation.
void raptor_www_set_http_accept(raptor_www *www, const char *value)
Set the WWW HTTP Accept: header to value. If value is NULL, an
empty header is sent.
void raptor_www_set_error_handler(raptor_www *www, raptor_message_han‐
dler error_handler, void *error_data)
Set the error handler routine for the raptor_www class. This
takes the same arguments as the raptor_parser error, warning
handler methods.
void raptor_www_set_uri_filter(raptor_www* www, raptor_uri_filter_func
filter, void* user_data)
Set the URI filter function filter for URIs retrieved by the
raptor_www object.
void* raptor_www_get_connection(raptor_www *www)
Return the underlying WWW library connection object. For exam‐
ple, for libcurl this is the curl_handle.
void raptor_www_set_connection_timeout(raptor_www* www, int timeout)
Set the WWW connection timeout in seconds.
raptor_uri* raptor_www_get_final_uri(raptor_www* www)
Get the final URI from a WWW retrieval, which may include redi‐
rections.
WWW ACTION METHODS
int raptor_www_fetch(raptor_www *www, raptor_uri *uri)
Retrieve the given URL, returning non zero on failure.
int raptor_www_fetch_to_string(raptor_www *www, raptor_uri *uri, void
**string_p, size_t *length_p, void *(*malloc_handler)(size_t size))
Retrieve the given URL to a string. string_p must point to a
void* pointer that will be used to store the newly allocated
string. length_p if not NULL, it will be used to store the
length of the new string.
void raptor_www_abort(raptor_www *www, const char *reason)
Abort an ongoing raptor WWW operation. Typically used within one
of the raptor WWW handlers.
QNAME CLASS
This is a class for handling XML QNames consisting of the pair of (a
URI from a namespace, a local name) along with an optional value --
useful for XML attributes. This is used with the raptor_names‐
pace_stack and raptor_namespace classes to handle a stack of rap‐
tor_namespace that build on raptor_qname.
QNAME CONSTRUCTORS
There are two constructors for raptor_qname to build qnames with
optional values on a stack of names.
raptor_qname* raptor_new_qname(raptor_namespace_stack *nstack, const
unsigned char *name, const unsigned char *value, raptor_simple_mes‐
sage_handler error_handler, void *error_data)
Create a raptor QName name (a possibly :-separated name) with
name to be resolved against the given nstack namespace stack.
An optional value can be given, and if there is an error, the
error_handler and error_data will be used to invoke the call‐
back.
raptor_qname* raptor_new_qname_from_namespace_local_name (raptor_names‐
pace *ns, const unsigned char *local_name, const unsigned char *value)
Create a raptor QName using the namespace name of the rap‐
tor_namespace ns and the local name local_name, along with
optional value value. Errors are reported using the error han‐
dling and data of the namespace.
raptor_qname* raptor_qname_copy(raptor_qname *qname)
Create a raptor QName from an existing one, returning NULL on
failure.
QNAME DESTRUCTOR
void raptor_free_qname(raptor_qname* name)
Destroy a raptor qname object.
QNAME METHODS
int raptor_qname_equal(raptor_qname* name1, raptor_qname *name2)
Return non-zero if the given QNames are equal.
int raptor_iostream_write_qname(raptor_iostream* iostr, raptor_qname
*qname)
Write the raptor_qname qname to the iostream ostr.
QNAME UTILITY FUNCTIONS
raptor_uri* raptor_qname_string_to_uri(raptor_namespace_stack *nstack,
const unsigned char *name, size_t name_len, raptor_simple_message_han‐
dler error_handler, void *error_data)
Return the URI corresponding to the QName according to the RDF
method; concatenating the namespace's name (URI) with the local
name. Takes the same arguments as raptor_new_qname but does not
create a raptor_qname object.
raptor_namespace* raptor_qname_get_namespace(raptor_qname* name)
Return the raptor_namespace used by the QName. Will never be
NULL even for the default namespace in which case the URI of the
returned namespace object will be NULL.
NAMESPACE CLASS
An XML namespace class - each entry is on a stack and consists of a
name (URI) and prefix. The prefix or the name but not both may be
empty. If the prefix is empty, it defines the default prefix. If the
name is empty, it undefines the given prefix.
NAMESPACE CONSTRUCTORS
raptor_namespace* raptor_new_namespace(raptor_namespace_stack *nstack,
const unsigned char *prefix, const unsigned char *ns_uri_string, int
depth)
raptor_namespace* raptor_new_namespace_from_uri(raptor_namespace_stack
*nstack, const unsigned char *prefix, raptor_uri* ns_uri, int depth)
Create a new raptor_namespace object on the given namespace
stack nstack with prefix prefix and namespace name either from
URI string ns_uri_string or from copying URI ns_uri.
If prefix is NULL, it defines the URI for the default namespace prefix.
If the namespace name (ns_uri_string or ns_uri) is NULL, it undefines
the given prefix in the current scope. Both prefix and URI may be NULL
to undefine the default namespace. depth signifies the position of the
namespace on the stack; 0 is the bottom of the stack and generally the
first depth for user namespace declarations.
Namespaces declared on the same depth (such as on the same XML element,
typically) can be handily freed with raptor_namespaces_end_for_depth
method on the namespace stack class.
NAMESPACE DESTRUCTOR
void raptor_free_namespace(raptor_namespace *ns)
Destroy a raptor namespace object.
NAMESPACE METHODS
raptor_uri* raptor_namespace_get_uri(const raptor_namespace *ns)
Return the namespace name (URI) of the namespace.
const unsigned char* raptor_namespace_get_prefix(const raptor_namespace
*ns)
Return the prefix of the namespace.
const unsigned char* raptor_namespace_get_counted_prefix(const rap‐
tor_namespace* ns, size_t* length_p)
Return the prefix of the namespace as a string with optional
count stored in the variable address length_p if it is not NULL.
unsigned char *raptor_namespaces_format(const raptor_namespace *ns,
size_t *length_p)
Format the namespace as a string and return it as a new string,
returning the length of the resulting string in length_p if it
is not NULL. The string format is suitable for emitting in XML
to declare the namespace.
int raptor_iostream_write_namespace(raptor_iostream* iostr, rap‐
tor_namespace *ns)
Write a formatted namespace declaration like xmlns... to an
iostream iostr.
NAMESPACE UTILITY FUNCTIONS
int raptor_namespace_copy(raptor_namespace_stack *nstack, raptor_names‐
pace *ns, int new_depth)
Copy the namespace from the current stack to the new one, nstack
at depth new_depth.
int raptor_new_namespace_parts_from_string(unsigned char *string,
unsigned char **prefix, unsigned char **uri_string)
Parse string with an XML-style namespace declaration like
xmlns="", xmlns="uri", xmlns:prefix="" or xmlns:prefix="uri"
into the strings pointed to by prefix string and a uri_string.
Empty prefixes or namespace names return NULL pointers.
Returned strings must be freed by the caller using rap‐
tor_free_memory.
NAMESPACE STACK CLASS
A stack of raptor_namespace objects where the namespaces on top of the
stack have wider scope and override earlier (lower) namespace declara‐
tions. Intended to match the XML namespace declaring semantics using
xmlns attributes.
NAMESPACE STACK CONSTRUCTORS
raptor_namespace_stack* raptor_new_namespaces(raptor_uri_handler
*uri_handler, void *uri_context, raptor_simple_message_handler
error_handler, void *error_data, int defaults)
int raptor_namespaces_init(raptor_namespace_stack *nstack, rap‐
tor_uri_handler *handler, void *context, raptor_simple_message_handler
error_handler, void *error_data, int defaults)
Create or initialise a new raptor_namespace_stack object with
the given URI and error handlers. raptor_namespaces_new allo‐
cates new memory for the namespace stack and raptor_names‐
paces_init initialises an existing declared nstack, which could
be statically allocated. Note that raptor_uri_get_handler can
be useful to return the current raptor URI handler/context. The
defaults argument describes which default namespaces are
declared in the empty stack. At present, 0 is none, 1 for just
the XML namespace and 2 is for a typical set of namespaces used
for RDF, RDFS, Dublin Core, OWL, ... that may vary over time.
In versions 1.4.16 or newer this returns an integer result,
non-0 on failure.
NAMESPACE STACK DESTRUCTORS
void raptor_free_namespaces(raptor_namespace_stack *nstack)
Destroy a namespace stack object, freeing the nstack (goes with
raptor_new_namespaces).
void raptor_namespaces_clear(raptor_namespace_stack *nstack)
Clear a statically allocated namespace stack; does not free the
nstack. (goes with raptor_namespaces_init).
NAMESPACE STACK METHODS
void raptor_namespaces_start_namespace(raptor_namespace_stack *nstack,
raptor_namespace *nspace)
Start the given nspace on the stack, at the depth already
defined.
int raptor_namespaces_start_namespace_full(raptor_namespace_stack
*nstack, const unsigned char *prefix, const unsigned char *nspace, int
depth)
Create a new raptor_namespace and start it on the stack. See
raptor_new_namespace for the meaning of the argumens.
void raptor_namespaces_end_for_depth(raptor_namespace_stack *nstack,
int depth)
End (and free) all namespaces on the stack at the given depth.
raptor_namespace* raptor_namespaces_get_default_namespace (rap‐
tor_namespace_stack *nstack)
Return the current default raptor_namespace of the namespace
stack or NULL if there is none.
raptor_namespace* raptor_namespaces_find_namespace_by_uri(raptor_names‐
pace_stack *nstack, raptor_uri *ns_uri)
Find the first namespace on the stack with the given uri ns_uri
or NULL if there is none.
raptor_namespace *raptor_namespaces_find_namespace_by_uri(raptor_names‐
pace_stack *nstack, const unsigned char *prefix, int prefix_length)
Find the first namespace on the stack with the given namespace
prefix or NULL if there is none.
int raptor_namespaces_namespace_in_scope(raptor_namespace_stack
*nstack, const raptor_namespace *nspace)
Return non-zero if the raptor_namespace nspace is declared on
the stack; i.e. in scope if this is a stack of XML namespaces.
NAMESPACE STACK UTILITY FUNCTIONS
raptor_qname* raptor_namespaces_qname_from_uri(raptor_namespace_stack*
nstack, raptor_uri* uri, int xml_version)
Create a raptor QName from the URI uri if the URI is squal one
of the namespace URIs on the namespace stack nstack URIs con‐
catenated to a legal XML name for the given XML version. URIs
are created and errors are reported using the namespace stack
fields. Fails if it cannot be legally described with any of the
namespaces.
SEQUENCE CLASS
A class for ordered sequences of items, adding at either end of the
sequence. The method names should be familiar to Perl users.
SEQUENCE CONSTRUCTOR
raptor_sequence* raptor_new_sequence(raptor_sequence_free_handler*
free_handler, raptor_sequence_print_handler* print_handler)
Create a new empty sequence, with optional handler for freeing
elements (as used by raptor_free_sequence and printing out ele‐
ments (used by raptor_sequence_print).
SEQUENCE DESTRUCTOR
void raptor_free_sequence(raptor_sequence* seq)
Destoy a sequence object, freeing any items if the free handler
was defined in the constructor.
SEQUENCE METHODS
int raptor_sequence_size(raptor_sequence* seq)
Return the number of items in the sequence.
int raptor_sequence_set_at(raptor_sequence* seq, int idx, void *data)
Set the sequence item at index idx to the value data, extending
it if necessary.
int raptor_sequence_push(raptor_sequence* seq, void *data)
Add item data to the end of the sequence.
int raptor_sequence_shift(raptor_sequence* seq, void *data)
Add item data to the start of the sequence.
void* raptor_sequence_get_at(raptor_sequence* seq, int idx)
Get the sequence item at index idx or NULL if no such index
exists.
void* raptor_sequence_pop(raptor_sequence* seq)
Remove and return an item from the end of the sequence, or NULL
if is empty.
void* raptor_sequence_unshift(raptor_sequence* seq)
Remove and return an item from the start of the sequence, or
NULL if is empty.
void raptor_sequence_sort(raptor_sequence* seq, int(*compare)(const
void *, const void *))
Sort the sequence using the given comparison function compare
which is passed to qsort(3) internally.
int raptor_compare_strings(const void *a, const void *b)
Helper function useful with raptor_sequence_sort.
void raptor_sequence_set_print_handler(raptor_sequence *seq, rap‐
tor_sequence_print_handler *print_handler)
Set the print handler for the sequence, an alternative to set‐
ting it in the constructor.
void raptor_sequence_print_string(char *data, FILE *fh)
Helper print handler function useful for printing out sequences
of strings.
void raptor_sequence_print_uri(char *data, FILE *fh)
Helper print handler function useful for printing out sequences
of raptor_uri* objects.
void raptor_sequence_print(raptor_sequence* seq, FILE* fh)
Print out the sequence in a debug format to the given file han‐
dler fh. NOTE: The exact format is not guaranteed to remain the
same between releases.
int raptor_sequence_join(raptor_sequence* dest, raptor_sequence *src)
Join two sequences moving all items from sequence src to the end
of sequence dest. After this operation, sequence src will be
empty (zero size) but will have the same item capacity as
before.
STRINGBUFFER CLASS
A class for growing strings, small chunks at a time.
STRINGBUFFER CONSTRUCTOR
raptor_stringbuffer* raptor_new_stringbuffer(void)
Create a new stringbuffer.
STRINGBUFFER DESTRUCTOR
void raptor_free_stringbuffer(raptor_stringbuffer* stringbuffer)
Destroy a stringbuffer.
STRINGBUFFER METHODS
int raptor_stringbuffer_append_counted_string(raptor_stringbuffer*
stringbuffer, const unsigned char *string, size_t length, int do_copy)
Append a string of length bytes to a stringbuffer, copying it
only if do_copy is non-0.
int raptor_stringbuffer_append_string(raptor_stringbuffer* string‐
buffer, const unsigned char* string, int do_copy)
Append a string to a stringbuffer, copying it only if do_copy is
non-0.
int raptor_stringbuffer_append_decimal(raptor_stringbuffer* string‐
buffer, int integer)
Append a formatted decimal integer to a stringbuffer.
int raptor_stringbuffer_append_stringbuffer(raptor_stringbuffer*
stringbuffer, raptor_stringbuffer* append)
Append a stringbuffer append to a stringbuffer. The append
stringbuffer is emptied but not destroyed.
int raptor_stringbuffer_prepend_counted_string(raptor_stringbuffer*
stringbuffer, const unsigned char* string, size_t length, int do_copy)
Prepend a string of length bytes to the start of a stringbuffer,
copying it only if do_copy is non-0.
int raptor_stringbuffer_prepend_string(raptor_stringbuffer* string‐
buffer, const unsigned char* string, int do_copy)
Prepend a string to the start of a stringbuffer, copying it only
if do_copy is non-0.
unsigned char * raptor_stringbuffer_as_string(raptor_stringbuffer*
stringbuffer)
Return the stringbuffer as a single string. The string is
shared and should be copied if needed.
size_t raptor_stringbuffer_length(raptor_stringbuffer* stringbuffer)
Return the length of the stringbuffer.
int raptor_stringbuffer_copy_to_string(raptor_stringbuffer* string‐
buffer, unsigned char *string, size_t length)
Copy the stringbuffer into a single string buffer string of size
length. Returns non-0 on failure.
IOSTREAM CLASS
This class provides an I/O stream that can write to filenames, FILE*,
strings and user-defined output via callbacks.
IOSTREAM CONSTRUCTOR
raptor_iostream* raptor_new_iostream_from_handler(void* context, const
raptor_iostream_handler *handler)
Create a new raptor iostream from a user-defined rap‐
tor_iostream_handler handler that is called with the passed-in
context for the write operations.
raptor_iostream* raptor_new_iostream_to_sink(void)
Create a new raptor iostream that discards all written output.
raptor_iostream* raptor_new_iostream_to_filename(const char *filename)
Create a new raptor iostream that creates and writes to a new
file filename.
raptor_iostream* raptor_new_iostream_to_file_handle(FILE *handle)
Create a new raptor iostream that creates and writes to an
existing, already opened, C Standard I/O handle FILE* handle.
raptor_iostream* raptor_new_iostream_to_string(void **string_p, size_t
*length_p, void *(*malloc_handler)(size_t size))
Create a new raptor iostream which creates a new string once
raptor_free_iostream is called. The new string pointer is writ‐
ten in string, the length in length_p (if not NULL) and the mem‐
ory allocation is made using the malloc_handler, or if NULL,
raptor's default memory allocator.
IOSTREAM DESTRUCTOR
void raptor_free_iostream(raptor_iostream *iostr)
Destroy a Raptor iostream object.
IOSTREAM METHODS
int raptor_iostream_write_bytes(raptor_iostream *iostr, const void
*ptr, size_t size, size_t nmemb)
Write a counted set of elements to an iostream. Inmemb is the
count of elements of size size, starting at memory ptr. Similar
to fwrite(3) and write(2).
int raptor_iostream_write_byte(raptor_iostream *iostr, const int byte)
Write a single byte an iostream. Similar to fputc(3).
void raptor_iostream_write_end(raptor_iostream *iostr)
Finish writing to an iostream.
int raptor_iostream_write_string(raptor_iostream *iostr, const void
*string)
Write a NUL-terminated string to an iostream. Similar to
fputs(3).
int raptor_iostream_write_counted_string(raptor_iostream *iostr, const
void *string, size_t len)
Write a string of length len to an iostream.
size_t raptor_iostream_get_bytes_written_count(raptor_iostream *iostr)
Return the number of bytes written so far to the iostream.
int raptor_iostream_write_decimal(raptor_iostream *iostr, int integer)
Write a decimal formatted integer integer to the iostream.
int raptor_iostream_format_hexadecimal(raptor_iostream *iostr, unsigned
int integer, int width)
Write a hexadecimal formatted unsigned integer to the iostream,
left-padded with '0's to width columns.
int raptor_iostream_write_stringbuffer(raptor_iostream* iostr, rap‐
tor_stringbuffer *sb)
Write the stringbuffer to an iostream iostr.
XML ELEMENT CLASS
This class provides an XML element that can be used with the XML Writer
Class to generate XML documents.
XML ELEMENT CONSTRUCTORS
raptor_xml_element* raptor_new_xml_element(raptor_qname* name, const
unsigned char* xml_language, raptor_uri* xml_base)
Create a new XML element with the element name name in the con‐
text of xml:lang xml_language and base URI xml_base.
raptor_xml_element* raptor_new_xml_element_from_names‐
pace_local_name(raptor_namespace *ns, const unsigned char *name, const
unsigned char* xml_language, raptor_uri* xml_base
Create a new XML element based on the given XML namespace and
localname in the context of xml:lang xml_language and base URI
xml_base.
XML ELEMENT DESTRUCTOR
void raptor_free_xml_element(raptor_xml_element *element)
Destroy a XML element object.
XML ELEMENT METHODS
raptor_qname* raptor_xml_element_get_name(raptor_xml_element* xml_ele‐
ment)
Get the XML element QName of XML element xml_element.
void raptor_xml_element_set_attributes(raptor_xml_element* xml_element,
raptor_qname **attributes, int count)
Set the attributes on XML element xml_element to the array of
QNames in array attributes of size count.
raptor_qname** raptor_xml_element_get_attributes(raptor_xml_element*
xml_element)
Get the attributes of an XML element xml_element as an array of
QNames. As set by void raptor_xml_element_set_attributes.
int raptor_xml_element_get_attributes_count(raptor_xml_element*
xml_element)
Get the number of attributes of an XML element xml_element as
set by void raptor_xml_element_set_attributes.
int raptor_xml_element_declare_namespace(raptor_xml_element* xml_ele‐
ment, raptor_namespace* nspace)
Declare an XML namespace nspace expliclitly on XML element
xml_element. Namespaces used in the element or attribute names
are automatically declared, this method allows additional ones
to be done.
int raptor_xml_element_is_empty(raptor_xml_element* xml_element)
Return non-0 if the XML element is empty.
int raptor_iostream_write_xml_element(raptor_iostream* iostr, rap‐
tor_xml_element *element, raptor_namespace_stack* nstack, int is_empty,
int is_end, raptor_simple_message_handler error_handler, void*
error_data, int depth)
Write a XML element xml_element to iostream ostr. This is done
in context of an XML namespace stack nstack and at depth depth
in the stack (see Namespace class constructors).
The element may be an empty element if is_empty is non-zero or
may be a close element if is_end is non-zero (else is a start
element). The error_handler method along with error_data allow
error reporting to be given.
XML WRITER CLASS
This class provides the functionality to generate simple XML documents
consisting of elements with attributes, character data and comments.
The documents can be written to an iostream.
XML WRITER CONSTRUCTOR
raptor_xml_writer* raptor_new_xml_writer(raptor_namespace_stack*
nstack, raptor_uri_handler* uri_handler, void* uri_context, rap‐
tor_iostream* iostr, raptor_simple_message_handler error_handler, void
*error_data, int canonicalize)
Create a new XML Writer writing to iostream iostr. The
error_handler method along with error_data allow error reporting
to be given. nstack is either an existing namespace stack to be
used or if NULL, a new one with only the XML namespace defined
is created. Note that raptor_uri_get_handler can be useful to
return the current raptor URI handler/context. canonicalize is
currently unused and should be set to 1 but may allow non-canon‐
ical XML writing to be allowed in future.
XML WRITER DESTRUCTOR
void raptor_free_xml_writer(raptor_xml_writer* xml_writer)
Destroy a XML Writer object.
XML WRITER METHODS
void raptor_xml_writer_empty_element(raptor_xml_writer* xml_writer,
raptor_xml_element *element)
Write XML element element as an empty element (no element con‐
tent) to the XML Writer xml_writer.
void raptor_xml_writer_start_element(raptor_xml_writer* xml_writer,
raptor_xml_element *element)
Write a start element along with an attributes and namespace
declarations for XML element element to the XML Writer
xml_writer.
void raptor_xml_writer_end_element(raptor_xml_writer* xml_writer, rap‐
tor_xml_element *element)
Write an end element form for XML element element to the XML
Writer xml_writer.
void raptor_xml_writer_cdata(raptor_xml_writer* xml_writer, const
unsigned char *str)
Write XML character data in str to the XML Writer xml_writer.
The characters in str will be XML escaped.
void raptor_xml_writer_cdata_counted(raptor_xml_writer* xml_writer,
const unsigned char* str, unsigned int length)
Write XML character data in str of length length to the XML
Writer xml_writer. The characters in str will be XML escaped.
void raptor_xml_writer_raw(raptor_xml_writer* xml_writer, const
unsigned char* str)
Write character data in str length to the XML Writer xml_writer
without XML escaping.
void raptor_xml_writer_raw_counted(raptor_xml_writer* xml_writer, const
unsigned char* str, unsigned int length)
Write character data in str of length length to the XML Writer
xml_writer without XML escaping.
void raptor_xml_writer_comment(raptor_xml_writer* xml_writer, const
unsigned char* str)
Write an XML comment in str to the XML Writer xml_writer.
void raptor_xml_writer_comment_counted(raptor_xml_writer* xml_writer,
const unsigned char* str, unsigned int length)
Write an XML comment in str of length length to the XML Writer
xml_writer.
int raptor_xml_writer_features_enumerate(const raptor_feature feature,
const char **name, raptor_uri **uri, const char **label)
Return the name, URI, string label (all optional) for an XML
write feature, returning non-zero if no such feature exists.
Raptor features have URIs that are constructed from the URI http://fea‐
ture.librdf.org/raptor- and the name so for example feature scanForRDF
has URI http://feature.librdf.org/raptor-scanForRDF
int raptor_xml_writer_set_feature(raptor_xml_writer* xml_writer, rap‐
tor_feature feature, int value)
Set an XML writer feature feature to a particular value.
Returns non 0 on failure or if the feature is unknown. The cur‐
rent defined writer features are:
Feature Values
RAPTOR_FEATURE_WRITER_AUTO_INDENT Boolean (non 0 true)
RAPTOR_FEATURE_WRITER_AUTO_EMPTY Boolean (non 0 true)
RAPTOR_FEATURE_WRITER_INDENT_WIDTH Integer
RAPTOR_FEATURE_WRITER_XML_DECLARATION Boolean (non 0 true)
If the writer_auto_indent feature is set (default true), the XML writer
will automatically indent the output.
If the writer_auto_empty feature is set (default true), the XML writer
will automatically generate empty elements if a start/end element
sequence has no content.
If the writer_indent_width feature is set (default 2) if the XML writer
is outputing indented XML, it will use that many spaces.
If the writer_xml_declaration feature is set (default true) the XML
declaration is written at the start of serialized XML.
int raptor_xml_writer_set_feature_string(raptor_xml_writer *xml_writer,
raptor_feature feature, const unsigned char *value)
Set an XML writer feature feature to a particular string value.
Returns non 0 on failure or if the feature is unknown. The cur‐
rent defined XML writer features are given in rap‐
tor_xml_writer_set_feature and at present only take integer val‐
ues. If an integer value feature is set with this function,
value is interpreted as an integer and then that value is used.
int raptor_xml_writer_get_feature(raptor_xml_writer* xml_writer, rap‐
tor_feature feature)
Get XML writer feature integer values. The allowed feature val‐
ues and types are given under raptor_xml_writer_features_enumer‐
ate.
const unsigned char *raptor_xml_writer_get_feature_string(rap‐
tor_xml_writer* xml_writer, raptor_feature feature)
Get XML writer feature string values. The allowed feature values
and types are given under raptor_xml_writer_features_enumerate.
API CHANGES
1.4.16
raptor_namespaces_init now returns an integer status
Added raptor_new_xml_element_from_namespace_local_name
Added raptor_uri_compare.
Added new features for the 'grddl' parser: RAPTOR_FEA‐
TURE_HTML_TAG_SOUP, RAPTOR_FEATURE_MICROFORMATS and RAPTOR_FEA‐
TURE_HTML_LINK.
Added parser feature RAPTOR_FEATURE_WWW_TIMEOUT
Added raptor_graph_handler typedef and raptor_set_graph_handler
Added raptor_www_final_uri_handler typedef and rap‐
tor_www_set_final_uri_handler
Added raptor_www_set_connection_timeout
Added raptor_www_get_final_uri
1.4.15
No changes.
1.4.14
Add two new exported strings raptor_license_string and rap‐
tor_home_url_string.
Added new features for the 'dot' serializer: RAPTOR_FEA‐
TURE_RESOURCE_BORDER, RAPTOR_FEATURE_LITERAL_BORDER, RAPTOR_FEA‐
TURE_BNODE_BORDER, RAPTOR_FEATURE_RESOURCE_FILL, RAPTOR_FEATURE_LIT‐
ERAL_FILL and RAPTOR_FEATURE_BNODE_FILL
Added raptor_parser_generate_id
Added raptor_iostream_write_string_turtle
1.4.13
No API changes.
1.4.12
No API changes.
1.4.11
Added raptor_get_feature_count
Added raptor_get_need_base_uri
Added parser feature RAPTOR_FEATURE_NO_NET
Added raptor_www_set_uri_filter, raptor_parser_set_uri_filter with fil‐
ter type raptor_uri_filter_func
1.4.10
No API changes.
1.4.9
Added raptor_parser_get_accept_header
Added raptor_xml_element_is_empty
Added raptor_qname_get_namespace
Added raptor_iostream_write_uri
Added raptor_namespaces_qname_from_uri.
Added raptor_namespace_get_counted_prefix
Added raptor_serialize_set_namespace_from_namespace
Deprecated raptor_uri_is_file_uri for new rap‐
tor_uri_string_is_file_uri.
Added raptor_xml_element_get_attributes and raptor_xml_ele‐
ment_get_attributes_count
1.4.8
Added raptor_set_namespace_handler.
Added XML 1.1 serializing support, feature RAPTOR_FEA‐
TURE_WRITER_XML_VERSION with shortname xmlVersion for serializer and
xml writer classes to support it. Added XML writer feature RAPTOR_FEA‐
TURE_WRITER_XML_DECLARATION to control generation of the XML declara‐
tion. Added new functions raptor_xml_any_escape_string and rap‐
tor_iostream_write_xml_any_escaped_string to allow generating XML 1.1
or XML 1.0.
RAPTOR_IDENTIFIER_TYPE_PREDICATE will no longer be generated from ver‐
sion 1.4.9 onwards as the type of returned statement predicates. RAP‐
TOR_IDENTIFIER_TYPE_RESOURCE will be returned.
RAPTOR_IDENTIFIER_TYPE_ORDINAL may no longer be generated from version
1.4.9 onwards, RAPTOR_IDENTIFIER_TYPE_RESOURCE may replace it.
1.4.7
No changes.
1.4.6
No changes.
1.4.5
Deprecated raptor_ntriples_string_as_utf8_string (never documented
above) since it can only work with a raptor_parser object which makes
it rather unusable alone.
Added XML writer features and support functions raptor_xml_writer_fea‐
tures_enumerate, raptor_xml_writer_set_feature, rap‐
tor_xml_writer_set_feature_string, raptor_xml_writer_get_feature and
raptor_xml_writer_get_feature_string
1.4.3
Added XML Writer class (raptor_xml_writer) and XML Element class (rap‐
tor_xml_element)
Added raptor_parser_get_feature_string, raptor_parser_set_fea‐
ture_string, raptor_serializer_set_feature_string, raptor_serial‐
izer_get_feature_string and raptor_feature_value_type.
Added raptor_serializer_set_namespace, raptor_serializer_set_feature
and raptor_serializer_get_feature.
Added raptor_new_namespace_from_uri, raptor_new_names‐
pace_parts_from_string, Added raptor_namespaces_find_namespace_by_uri.
and raptor_iostream_write_namespace to write a namespace declaration to
an iostream.
Added copy constructor raptor_qname_copy and rap‐
tor_iostream_write_qname to write a qname to an iostream.
Added raptor_sequence_join to join two sequences, leaving one empty.
Added raptor_iostream_write_stringbuffer to write a stringbuffer to an
iostream.
Added N-Triples raptor_iostream_write_string_ntriples and rap‐
tor_iostream_write_statement_ntriples utility functions for writing to
raptor_iostreams.
Added raptor_uri_to_relative_counted_uri_string, raptor_uri_to_rela‐
tive_uri_string. raptor_uri_print, raptor_uri_to_counted_string and
raptor_uri_to_string
Added unicode name checking utility functions for XML 1.0 and XML 1.1
name starting character and continued name character. raptor_uni‐
code_is_xml10_namestartchar raptor_unicode_is_xml10_namechar, rap‐
tor_unicode_is_xml11_namechar and raptor_unicode_is_xml11_names‐
tartchar.
Added raptor_xml_name_check to check if a name is a legal XML 1.0 or
1.0 name. and raptor_iostream_write_xml_escaped_string to write an
XML-escaped string to an iostream.
Added UTF8-checking utility function raptor_utf8_check.
1.4.2
No changes.
1.4.1
The raptor_xml_escape_string now returns <0 on failure rather than 0,
so that if an empty string is escaped, 0 bytes required is returned.
1.4.0
Added new raptor_serializer class supporting RDF/XML (name rdfxml) and
N-Triples (name ntriples).
Added new raptor_iostream class
Added raptor_stringbuffer_copy_to_string to allow efficient copy-out of
a constructed string.
Added raptor_www_fetch_to_string to allow retrieving of web content as
a single string.
1.3.3
Added raptor_calloc_memory to provide a calloc inside raptor.
Added feature check_rdf_id (see raptor_set_feature documentation).
1.3.2
Added raptor_alloc_memory to allocate memory inside raptor.
Added accessor functions for the public raptor_locator structure:
raptor_locator_line
raptor_locator_column
raptor_locator_byte
raptor_locator_file
raptor_locator_uri
1.3.1
Correct raptor_print_statement declaration argument statement to have
one less 'const', to match the code.
1.3.0
Added the following parser methods, utility methods and helper func‐
tions:
raptor_new_parser_for_content (Parser class constructor)
raptor_get_mime_type
raptor_get_feature
raptor_syntax_name_check
raptor_guess_parser_name
raptor_features_enumerate
raptor_feature_from_uri
raptor_www_set_http_accept (WWW class)
Changed raptor_set_feature to now return an int success or failure.
Added the following functions:
raptor_free_memory
raptor_unicode_char_to_utf8
raptor_utf8_to_unicode_char
raptor_vsnprintf
Added the raptor_sequence class, its constructor, destructor, methods
and helper functions.
Added the raptor_stringbuffer class and constructor, destructor and
methods.
Deprecated raptor_print_statement_detailed always intended to be inter‐
nal.
1.2.0
Added raptor_syntaxes_enumerate to get full information on syntax mime
type and URIs as well as name and label.
N-Triples Plus parser renamed to Turtle (name turtle)
1.1.0
Added N-Triples Plus parser (name ntriples-plus)
Made URI class constructors, methods and factory methods as well as
some other utility functions using or returning URIs or literals take
unsigned char* rather than char*. The affected calls are:
URI factory methods changed to all take/return unsigned char* for URI
strings:
raptor_new_uri_func
raptor_new_uri_from_local_name_func
raptor_new_uri_relative_to_base_func
raptor_uri_as_string_func
raptor_uri_as_counted_string_func
Constructors and methods changed to take/return unsigned char* for URI
strings:
raptor_statement_part_as_counted_string
raptor_statement_part_as_string
raptor_new_uri
raptor_new_uri_from_uri_local_name
raptor_new_uri_relative_to_base
raptor_uri_as_string
raptor_uri_as_counted_string
raptor_print_ntriples_string
Changed to use unsigned char* for URI strings, char* for filenames:
raptor_uri_resolve_uri_reference
raptor_uri_filename_to_uri_string
raptor_uri_uri_string_to_filename
raptor_uri_uri_string_to_filename_fragment
raptor_uri_is_file_uri
Changed to return unsigned char* for UTF8 string:
raptor_ntriples_string_as_utf8_string
Added raptor_parsers_enumerate to discover supported parsers.
Added raptor_uri_uri_string_to_filename_fragment with fragment arg to
return the URI fragment.
Made the raptor_namespace, raptor_namespace_stack and raptor_qname
class and APIs public.
Added feature non_nfc_fatal (see raptor_set_feature documentation).
1.0.0
Removed the following deprecated methods and functions (see 0.9.6
changes for the new names):
raptor_free, raptor_new, raptor_ntriples_free, raptor_ntriples_new,
raptor_ntriples_parse_file, raptor_ntriples_set_error_handler, rap‐
tor_ntriples_set_fatal_error_handler, raptor_ntriples_set_state‐
ment_handler and raptor_parser_abort.
Added raptor_parse_file_stream for reading FILE* streams without neces‐
sarily having a file.
0.9.12
Added raptor_new_uri_for_retrieval to turn URI references into URIs
suitable for retrieval (no fragments).
0.9.11
Added raptor_get_name and raptor_get_label.
raptor_xml_escape_string now takes error message handler, data pointer,
loses parser argument.
Added raptor_set_default_generate_id_parameters and raptor_set_gener‐
ate_id_handler to control the default generation of IDs, allow full
customisation.
0.9.10
Added raptor_set_parser_strict and raptor_www_no_www_library_init_fin‐
ish.
raptor_xml_escape_string now takes an output string length pointer.
Added raptor_statement_part_as_counted_string, raptor_state‐
ment_part_as_string and raptor_parse_abort.
Deprecated raptor_parser_abort.
0.9.9
Added raptor_www class and all its constructors, destructor, methods,
calls.
Added raptor_parse_uri, raptor_parser_abort, rap‐
tor_ntriples_term_as_string and raptor_xml_escape_string.
0.9.7
raptor_parse_chunk, raptor_new_uri_from_id, arguments are now unsigned
char.
Added raptor_new_uri_for_xmlbase.
0.9.6
In this version, the raptor/ntriples parser calling APIs were modified.
The following table lists the changes:
OLD API NEW API (0.9.6+)
raptor_new() raptor_new_parser("rdfxml")
ntriples_new() raptor_new_parser("ntriples")
raptor_free raptor_free_parser
ntriples_free raptor_ntriples_parser
raptor_ntriples_parse_file raptor_parse_file
raptor_ntriples_set_error_handler raptor_set_error_handler
raptor_ntriples_set_fatal_error_handler raptor_set_fatal_error_handler
raptor_ntriples_set_statement_handler raptor_set_statement_handler
CONFORMING TO
RDF/XML Syntax (Revised), Dave Beckett (ed.) W3C Recommendation,
http://www.w3.org/TR/rdf-syntax-grammar/ ⟨http://www.w3.org/TR/rdf-
syntax-grammar/⟩
N-Triples, in RDF Test Cases, Jan Grant and Dave Beckett (eds.) W3C
Recommendation, http://www.w3.org/TR/rdf-testcases/#ntriples
⟨http://www.w3.org/TR/rdf-testcases/#ntriples⟩
Turtle - Terse RDF Triple Language, Dave Beckett,
http://www.dajobe.org/2004/01/turtle/
⟨http://www.dajobe.org/2004/01/turtle/⟩
RSS 0.91 spec revision 3, Dan Libby, Netscape,
http://my.netscape.com/publish/formats/rss-spec-0.91.html
⟨http://my.netscape.com/publish/formats/rss-spec-0.91.html⟩
RDF Site Summary (RSS) 1.0, http://purl.org/rss/1.0/spec
⟨http://purl.org/rss/1.0/spec⟩
Atom 1.0 syndication format, RFC 4287,
http://www.ietf.org/rfc/rfc4287.txt
⟨http://www.ietf.org/rfc/rfc4287.txt⟩
Gleaning Resource Descriptions from Dialects of Languages (GRDDL), Dan
Connolly (ed.), W3C Recommendation, 2007-09-11,
http://www.w3.org/TR/2007/REC-grddl-20070911/
⟨http://www.w3.org/TR/2007/REC-grddl-20070911/⟩
SEE ALSOrapper(1),raptor-config(1)AUTHOR
Dave Beckett - http://purl.org/net/dajobe/
⟨http://purl.org/net/dajobe/⟩
2007-09-30 libraptor(3)
