libraptor (3)
NAME
libraptor - Raptor RDF parser toolkit library
SYNOPSIS
#include <raptor.h>
raptor_init();
raptor_parser *p=raptor_new_parser("rdfxml");
raptor_set_statement_handler(p,NULL,print_statements);
raptor_uri *file_uri=raptor_new_uri("http://example.org/");
raptor_parse_file(p,file_uri,base_uri);
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 RDF for-
mat parsers, presently RDF/XML and N-Triples. The parsers turn the
syntax into a sequence of RDF statements (or triples). The RDF/XML
parser uses either expat or libxml XML parser 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 also provides a small URI-reference parsing and resolving (not
retrieval) library sufficient for dealing with URI-references inside
RDF. This functionality is modular and can be transparently replaced
with an existing URI implementation.
LIBRARY INITIALISATION AND CLEANUP
raptor_init()
raptor_finish()
Initialise and cleanup the library. These must be called before
any raptor_parser or raptor_uri is created or used.
PARSER CONSTRUCTORS
raptor_parser* raptor_new_parser(name)
Create a new raptor parser object for the parser with name name
currently either "rdfxml" or "ntriples"
PARSER DESTRUCTORS
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_warning_handler(raptor_parser* parser, void *user_data,
raptor_message_handler handler)
Set warning message 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 parsing either in one method or by working on
multiple chunks of memory passed by the application. These methods run
and by callbacks deliver, warnings, errors, fatal errors and statements
via the registered statement handler callback.
int raptor_parse_file(raptor_parser* parser, const char *filename,
const char *base_uri)
Parse the given filename (a URI like file:filename) according to
the base URI base_uri, or NULL if not needed.
int raptor_parse_start(raptor_parser* parser, const char *uri)
Start a parse of content with the base URI uri (or NULL if not
needed)
int raptor_parse_chunk(raptor_parser* parser, const 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_parse_start.
PARSER UTILITY METHODS
void raptor_set_feature(raptor_parser *parser, raptor_feature feature,
int value)
Set a parser feature feature to a particular value. The current
defined 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)
If the scanning feature is true, 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, 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, then the RDF/XML parser
will allow non-XML namespaced attributes to be accepted as well as rdf:
is a public structure defined in raptor.h that can be used
directly, or formatted via raptor_print_locator.
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-test-
cases/#ntriples
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.
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 delimited
by the character delim which is usually either " or <
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.
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
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 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.
URI DESTRUCTOR
void raptor_free_uri(raptor_uri* uri)
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.
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.
URI UTILITY FUNCTIONS
void raptor_uri_resolve_uri_reference (const char* base_uri, const
char* reference_uri, char* 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 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.
char *raptor_uri_uri_string_to_filename(const char* uri_string)
This is a standalone function that turns a URI string that rep-
resents a local filename (file:) into a filename. The returned
string must be freed by the caller.
int raptor_uri_is_file_uri(const char* uri_string)
Returns non-zero if the given URI string represents a filename,
is a file: URI.
URI CLASS IMPLEMENTATION
void raptor_uri_set_handler(raptor_uri_handler *handler, void *context)
Change the URI class implementation to the functions provided by
In version 0.9.6, the raptor/ntriples parser calling APIs were modi-
fied. 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_han-
dler
raptor_ntriples_set_statement_handler raptor_set_statement_handler
CONFORMING TO
RDF/XML Syntax (Revised), W3C Working Draft (work in progress),
http://www.w3.org/TR/rdf-syntax-grammar/
N-Triples, W3C Working Draft (work in progress),
http://www.w3.org/TR/rdf-testcases/#ntriples
SEE ALSO
rdfdump(1)
AUTHOR
Dave Beckett - http://purl.org/net/dajobe/
Institute for Learning and Research Technology (ILRT)
http://www.ilrt.bristol.ac.uk/
University of Bristol http://www.bristol.ac.uk/
2002-11-02 libraptor(3)