.\"
.\" libraptor.3 - Raptor library manual page
.\"
.\" $Id: libraptor.3 11534 2006-10-23 04:06:02Z dajobe $
.\"
.\" Copyright (C) 2002-2006 David Beckett - http://purl.org/net/dajobe/
.\" Copyright (C) 2002-2005 University of Bristol, UK
.\"
.TH libraptor 3 "2006-10-22"
.\" Please adjust this date whenever revising the manpage.
.SH NAME
libraptor \- Raptor RDF parser and serializer library
.SH SYNOPSIS
.nf
.B #include <raptor.h>
.br
.br
.BI raptor_init();
.br
.BI "raptor_parser *" p =raptor_new_parser("rdfxml");
.br
.BI raptor_set_statement_handler( p , NULL , print_triples );
.br
.BI "raptor_uri *" file_uri =raptor_new_uri("http://example.org/");
.br
.BI raptor_parse_file( p , file_uri , base_uri );
.br
.BI raptor_parse_uri( p , uri , NULL );
.br
.BI raptor_free_parser( p );
.br
.BI raptor_free_uri( file_uri );
.br
.BI raptor_finish();
.br
.B cc file.c -lraptor
.br
.fi
.SH DESCRIPTION
The \fIRaptor\fR 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.
.LP
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 \fIexpat\fR or \fIlibxml\fR
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.
.LP
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.
.LP
It also provides a URI-retrieval class (raptor_www) for
wrapping existing 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.
.LP
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 Internationalized Resource Identifiers (IRIs) which are
still under development and standardisation.
.SH LIBRARY INITIALISATION AND CLEANUP
.IP "\fBraptor_init()\fR"
.IP "\fBraptor_finish()\fR"
Initialise and cleanup the library. These must be called before
any raptor class such as raptor_parser, raptor_uri is created or used.
.SH "PARSER CLASS"
This class provides the functionality of turning syntaxes into
RDF triples - RDF parsing.
.SH "PARSER CONSTRUCTORS"
.IP "\fBraptor_parser* raptor_new_parser(name)\fR"
Create a new raptor parser object for the parser with name
\fIname\fR currently either "rdfxml", "turtle" or
"rss-tag-soup" for the RSS Tag Soup parser.
.IP "\fBraptor_parser* raptor_new_parser_for_content(raptor_uri *\fIuri\fP, const char *\fImime_type\fP, const unsigned char *\fIbuffer\fP, size_t \fIlen\fP, const unsigned char *\fIidentifier\fP)\fR"
Create a new raptor parser object for a syntax identified by URI \fIuri\fR,
MIME type \fImime_type\fR, some initial content \fIbuffer\fR of size \fIlen\fR
or content with identifier \fIidentifier\fR. See
the raptor_guess_parser_name description for further details.
.SH "PARSER DESTRUCTOR"
.IP "\fBvoid raptor_free_parser(raptor_parser *\fIparser\fB)\fR"
Destroy a Raptor parser object.
.SH "PARSER MESSAGE CALLBACK METHODS"
Several methods can be registered for the parser that return
a variable-argument message in the style of printf(3). These
also return a \fIraptor_locator\fR
that can contain URI, file, line, column and byte counts of where
the message is about. This structure can be used with
the raptor_format_locator, raptor_print_locator functions below
or the structures fields directly, which are defined in raptor.h
.IP "\fBvoid raptor_set_fatal_error_handler(raptor_parser* \fIparser, void *\fIuser_data, raptor_message_handler handler)\fR"
Set the parser fatal error handler callback.
.IP "\fBvoid raptor_set_error_handler(raptor_parser* \fIparser\fB, void *\fIuser_data\fB, raptor_message_handler \fIhandler\fB)\fR"
Set the parser non-fatal error handler callback.
.IP "\fBvoid raptor_set_warning_handler(raptor_parser* \fIparser\fB, void *\fIuser_data\fB, raptor_message_handler \fIhandler\fB)\fR"
Set the parser warning message handler callback.
.IP "\fBraptor_set_namespace_handler(raptor_parser* \fIparser\fP, void* \fIuser_data\fP, raptor_namespace_handler \fIhandler\fP)\fR"
Set the namespace declaration handler callback.
.SH "PARSER STATEMENT CALLBACK METHOD"
The parser allows the registration of a callback function to return
the statements to the application.
.IP "\fBvoid raptor_set_statement_handler(raptor_parser* \fIparser\fB, void *\fIuser_data\fB, raptor_statement_handler \fIhandler\fB)\fR"
Set the statement callback function for the parser.
The \fIraptor_statement\fR
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.
.SH "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.
.LP
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.
.IP "\fBint raptor_parse_file(raptor_parser* \fIparser\fB, raptor_uri *\fIuri\fB, raptor_uri *\fIbase_uri\fB)\fR"
Parse the given filename (a URI like file:filename)
according to the optional base URI \fIbase_uri\fR. If \fIuri\fR
is NULL, read from standard input and \fIbase_uri\fR is then required.
.IP "\fBint raptor_parse_file_stream(raptor_parser* \fIparser\fB, FILE* \fIstream\fB, const char* \fIfilename\fB, raptor_uri *\fIbase_uri\fB)\fR"
Parse the given C FILE* stream according to the base URI
\fIbase_uri\fR (required). \fIfilename\fR is optional and
if given, is used for error messages via the raptor_locator structure.
.IP "\fBint raptor_parse_uri(raptor_parser* \fIparser\fB, raptor_uri* \fIuri\fB, raptor_uri *\fIbase_uri\fB)\fR"
Parse the URI according to the base URI \fIbase_uri\fR, or NULL if
not needed. If no base URI is given, the \fIuri\fR is used.
This method depends on the raptor_www subsystem (see \fBWWW Class\fR
section below)
and an existing underlying URI retrieval implementation such as
libcurl, libxml or BSD libfetch to retrieve the content.
.SH "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.
.IP "\fBint raptor_start_parse(raptor_parser* \fIparser\fB, const char *\fIuri\fB)\fR"
Start a parse of chunked content with the base URI \fIuri\fR
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.
.IP "\fBint raptor_parse_chunk(raptor_parser* \fIparser\fB, const unsigned char *buffer, size_t \fIlen\fB, int \fIis_end\fB)\fR"
Parse the memory at \fIbuffer\fR of size \fIlen\fR returning
statements via the statement handler callback.
If \fIis_end\fR is non-zero, it indicates the end of the parsing stream.
This method can only be called after raptor_start_parse.
.SH "PARSER UTILITY METHODS"
.IP "\fBconst char* raptor_get_mime_type(raptor_parser* \fIrdf_parser\fB)\fR"
Return the MIME type for the parser.
.IP "\fBvoid raptor_set_parser_strict(raptor_parser *\fIparser\fB, int \fIis_strict\fB)\fR"
Set the parser to strict (\fIis_strict\fR not zero)
or lax (default) mode. The detail of the
strictness can be controlled by raptor_set_feature.
.IP "\fBint raptor_set_feature(raptor_parser *\fIparser\fB, raptor_feature \fIfeature\fB, int \fIvalue\fB)\fR"
Set a parser feature \fIfeature\fR to a particular \fIvalue\fR.
Returns non 0 on failure or if the feature is unknown.
The current defined parser features are:
\fIFeature Values\fR
\fBRAPTOR_FEATURE_SCANNING\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_ASSUME_IS_RDF\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_ALLOW_NON_NS_ATTRIBUTES\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_ALLOW_OTHER_PARSETYPES\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_ALLOW_BAGID\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_ALLOW_RDF_TYPE_RDF_LIST\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_NORMALIZE_LANGUAGE\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_NON_NFC_FATAL\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_CHECK_RDF_ID\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_WARN_OTHER_PARSETYPES\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_CHECK_RDF_ID\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_RELATIVE_URIS\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_START_URI\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_NO_NET\fR Boolean (non 0 true)
.P
If the \fIscanning\fR
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.
.P
If the \fIassume_is_rdf\fR
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.
.P
If the \fIallow_non_ns_attributes\fR
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.
.P
If the \fIallow_other_parsetypes\fR
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.
.P
If the \fIallow_bagid\fR
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.
.P
If the \fIallow_rdf_type_rdf_list\fR
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.
.P
If the \fInormalize_language\fR
feature is true (default true) then XML language values
such as from xml:lang will be normalized to lowercase.
.P
If the \fInon_nfc_fatal\fR
feature is true (default false) then illegal Unicode Normal Form C
in literals will give a fatal error, otherwise it gives a warning.
.P
If the \fIcheck_rdf_id\fR
feature is true (default true) then rdf:ID values will be
checked for duplicates and cause an error if found.
.P
If the \fIno_net\fR
feature is true (default false) then network requests are denied.
.IP "\fBraptor_parser_set_feature_string(raptor_parser *\fIparser\fP, raptor_feature \fIfeature\fP, const unsigned char *\fIvalue\fP)\fR"
Set a parser feature \fIfeature\fR to a particular string \fIvalue\fR.
Returns non 0 on failure or if the feature is unknown.
The current defined parser features are given in
\fBraptor_set_feature\fP and at present only take integer values. If
an integer value feature is set with this function, \fIvalue\fP is
interpreted as an integer and then that value is used.
.IP "\fBint raptor_get_feature(raptor_parser* \fIparser\fB, raptor_feature \fIfeature\fB)\fR"
Get parser feature integer values. The allowed \fIfeature\fP values
and types are given under \fBraptor_features_enumerate\fP.
.IP "\fBconst unsigned char* raptor_parser_get_feature_string(raptor_parser *\fIparser\fP, raptor_feature \fIfeature\fP)\fR"
Get parser feature string values. The allowed \fIfeature\fP values
and types are given under \fBraptor_features_enumerate\fP.
.IP "\fBunsigned int raptor_get_feature_count(void)\fP"
Get the count of features defined.
Prefered to the compile time-only symbol \fBRAPTOR_FEATURE_LAST\fP
which returns the maximum value, not the count.
Added raptor_get_need_base_uri
.IP "\fBint raptor_feature_value_type(const raptor_feature feature)\fR"
Get a raptor feature value tyype - integer or string.
.IP "\fBraptor_locator* raptor_get_locator(raptor_parser* \fIrdf_parser\fB)\fR"
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.
.IP "\fBvoid raptor_get_name(raptor_parser *\fIparser\fB\fB)\fR"
Return the string short name for the parser.
.IP "\fBvoid raptor_get_label(raptor_parser *\fIparser\fB\fB)\fR"
Return a string label for the parser.
.IP "\fBvoid raptor_set_default_generate_id_parameters(raptor_parser* \fIrdf_parser\fB, char *\fIprefix\fB, int \fIbase\fB)\fR"
Control the default method for generation of IDs for blank nodes and
bags. The method uses a short string \fIprefix\fR and an integer
\fIbase\fR to generate the identifier which is not guaranteed to
be a strict concatenation. If \fIprefix\fR is NULL, the
default is used. If base is less than 1, it is initialised to 1.
.IP "\fBvoid raptor_set_generate_id_handler(raptor_parser* \fIparser\fB, void *\fIuser_data\fB, raptor_generate_id_handler \fIhandler\fB)\fR"
Allow full customisation of the generated IDs by setting a callback
\fIhandler\fR and associated \fIuser_data\fR 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
\fBraptor_alloc_memory\fP function may be useful.
.IP "\fBvoid raptor_parser_set_uri_filter(raptor_parser* \fIparser\fP, raptor_uri_filter_func \fIfilter\fP, void* \fIuser_data\fP)\fR"
Set the URI filter function \fIfilter\fP for URIs retrieved
during parsing by the the raptor_parser.
.IP "\fBint raptor_get_need_base_uri(raptor_parser* \fIrdf_parser\fP)\fP"
Get a boolean whether this parser needs a base URI to start parsing.
.SH "PARSER UTILITY FUNCTIONS"
.IP "\fBint raptor_parsers_enumerate(const unsigned int \fIcounter\fB, const char **\fIname\fB, const char **\fIlabel\fB)\fR"
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.
.IP "\fBint raptor_syntaxes_enumerate(const unsigned int \fIcounter\fB, const char **name, const char **\fIlabel\fB, const char **\fImime_type\fB, const unsigned char **\fIuri-string\fB)\fR"
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.
.IP "\fBint raptor_features_enumerate(const raptor_feature \fIfeature\fP, const char **\fIname\fP, raptor_uri **\fIuri\fP, const char **\fIlabel\fP)\fR"
Return the name, URI, string label (all optional)
for a parser \fIfeature\fP, returning non-zero if no such feature exists.
.P
Raptor features have URIs that are constructed from the URI
\fIhttp://feature.librdf.org/raptor-\fP and the \fIname\fP
so for example feature \fIscanForRDF\fP
has URI \fIhttp://feature.librdf.org/raptor-scanForRDF\fP
.IP "\fBint raptor_syntax_name_check(const char *\fIname\fP)\fR"
Check \fIname\fP is a known syntax name.
.IP "\fBconst char* raptor_guess_parser_name(raptor_uri *\fIuri\fP, const char *\fImime_type\fP, const unsigned char *\fIbuffer\fP, size_t \fIlen\fP, const unsigned char *\fIidentifier\fP)\fR"
Guess a parser name for a syntax identified by URI \fIuri\fR,
MIME type \fImime_type\fR, some initial content \fIbuffer\fR of size \fIlen\fR
or with content identifier \fIidentifier\fR. All of these
parameters are optional and only used if not NULL. The parser is
chosen by scoring the hints that are given.
.IP "\fBraptor_feature raptor_feature_from_uri(raptor_uri *\fIuri\fP)\fR"
Turn a URI \fIuri\fR into a raptor feature identifier, or <0 if the
feature is unknown. The URIs are described below raptor_set_feature.
.SH "STATEMENT UTILITY FUNCTIONS"
.IP "\fBvoid raptor_print_statement(const raptor_statement* const \fIstatement\fB, FILE *\fIstream\fB)\fR"
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.
.IP "\fBvoid raptor_print_statement_as_ntriples(const raptor_statement* \fIstatement\fB, FILE *\fIstream\fB)\fR"
Print a raptor statement object in N-Triples format, using all the
escapes as defined in
.UR http://www.w3.org/TR/rdf-testcases/#ntriples
http://www.w3.org/TR/rdf-testcases/#ntriples
.UE
.IP "\fBraptor_statement_part_as_counted_string(const void *\fIterm\fB, raptor_identifier_type \fItype\fB, raptor_uri* \fIliteral_datatype\fB, const unsigned char *\fIliteral_language\fB, size_t* \fIlen_p\fB)\fR"
.IP "\fBchar* raptor_statement_part_as_string(const void *\fIterm\fB, raptor_identifier_type \fItype\fB, raptor_uri* \fIliteral_datatype\fB, const unsigned char *\fIliteral_language\fB)\fR"
Turns part of raptor statement into N-Triples format, using all the
escapes as defined in
.UR http://www.w3.org/TR/rdf-testcases/#ntriples
http://www.w3.org/TR/rdf-testcases/#ntriples
.UE
The part (subject, predicate, object) of the raptor_statement is
passed in as \fIterm\fR, the part type (subject_type, predicate_type,
object_type) is passed in as \fItype\fR. When the part is a literal,
the \fIliteral_datatype\fR and \fIliteral_language\fR fields are set,
otherwise NULL (usually object_datatype, object_literal_language).
.IP
If \fBraptor_statement_part_as_counted_string\fR is used,
the length of the returned string is stored in *\fIlen_p\fR if not NULL.
.SH "LOCATOR UTILITY FUNCTIONS"
.IP "\fBint raptor_format_locator(char *\fIbuffer\fB, size_t \fIlength\fB, raptor_locator* \fIlocator\fB)\fR"
This method takes a \fIraptor_locator\fR object as passed to an
error, warning or other handler callback and formats it into the
\fIbuffer\fR of size \fIlength\fR bytes. If \fIbuffer\fR is NULL or
\fIlength\fR is insufficient 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 \fIlength\fR the size of a buffer that can be allocated for
\fIlocator\fR and a second call will perform the formatting:
raptor_format_locator(buffer, length, locator)
.IP "\fBvoid raptor_print_locator(FILE *\fIstream\fB, raptor_locator* \fIlocator\fB)\fR"
This method takes a \fIraptor_locator\fR object as passed to an
error, warning or other handler callback, formats and prints it to
the given stdio \fIstream\fR.
.IP "\fBint raptor_locator_line(raptor_locator *locator)\fR"
Returns the line number in a locator structure or <0 if not available.
.IP "\fBint raptor_locator_column(raptor_locator *locator)\fR"
Returns the column number in a locator structure or <0 if not available.
.IP "\fBint raptor_locator_byte(raptor_locator *locator)\fR"
Returns the byte offset in a locator structure or <0 if not available.
.IP "\fBconst char * raptor_locator_file(raptor_locator *locator)\fR"
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.
.IP "\fBconst char * raptor_locator_uri(raptor_locator *locator)\fR"
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.
.SH "N-TRIPLES UTILITY FUNCTIONS"
.IP "\fBvoid raptor_print_ntriples_string(FILE* \fIstream\fB, const char* \fIstring\fB, const char \fIdelim\fB)\fR"
This is a standalone function that prints the given string
according to N-Triples escaping rules, expecting to be terminated
by delimiter \fIdelim\fR which is usually either ', \(dq or <. If
a null delimiter \\0 is given, no extra escaping is performed.
.IP "\fBint raptor_iostream_write_string_ntriples(raptor_iostream *\fIiostr\fP, const unsigned char *\fIstring\fP, size_t \fIlen\fP, const char \fIdelim\fP)\fR"
Write an N-Triples encoded version of the given string to iostream
\fIiostr\fP. If \fIdelim\fP 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 ', \(dq and >. If
a null delimiter \\0 is given, no extra escaping is performed.
.IP "\fBvoid raptor_iostream_write_statement_ntriples(raptor_iostream* iostr, const raptor_statement *statement)\fR"
Write an N-Triples encoded version of the raptor_statement
\fIstatement\fP to iostream \fIiostr\fP.
.IP "\fBconst char* raptor_ntriples_term_as_string (raptor_ntriples_term_type \fIterm\fP)\fR"
Deprecated, for internal use.
.SH "XML UTILITY FUNCTIONS"
.IP "\fBint raptor_xml_any_escape_string(const unsigned char* \fIstring\fP, size_t \fIlen\fP, unsigned char* \fIbuffer\fP, size_t \fIlength\fP, char \fIquote\fP, int \fIxml_version\fP, raptor_simple_message_handler \fIerror_handler\fP, void* \fIerror_data\fP)\fR"
.IP "\fBint raptor_xml_escape_string(const unsigned char *\fIstring\fB, size_t \fIlen\fB, unsigned char *\fIbuffer\fB, size_t \fIlength\fB, char \fIquote\fB, raptor_message_handler \fIerror_handler\fB, void *\fIerror_data\fB)\fR"
Apply the XML escaping rules to the string given in (string, len)
into the \fIbuffer\fP of size \fIlength\fP. If \fIquote\fP
is given, the escaped content is for an XML attribute and the
appropriate quote character \" or \' is used, otherwise it is
XML element content (CDATA). The \fIerror_handler\fR method along
with \fIerror_data\fR 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.
.IP
When an \fIxml_version\fP 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.
.IP "\fBint raptor_iostream_write_xml_any_escaped_string(raptor_iostream* \fIiostr\fP, const unsigned char* \fIstring\fP, size_t \fIlen\fP, char \fIquote\fP, int \fIxml_version\fP, raptor_simple_message_handler \fIerror_handler\fP, void* \fIerror_data\fP)\fR"
.IP "\fBint raptor_iostream_write_xml_escaped_string(raptor_iostream* \fIiostr\fB, const unsigned char *\fIstring\fB, size_t \fIlen\fB, char \fIquote\fB, raptor_simple_message_handler \fIerror_handler\fB, void *\fIerror_data\fB)\fR"
Write an XML-escaped version of the string given in (string, len) to
iostream \fIiostr\fP. If \fIquote\fP is given, the escaped content
is for an XML attribute and the appropriate quote character \" or \'
is used, otherwise it is XML element content (CDATA). The
\fIerror_handler\fR method along with \fIerror_data\fR allow error
reporting to be given.
.IP
When an \fIxml_version\fP 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.
.IP "\fBint raptor_xml_name_check(const unsigned char *\fIstring\fP, size_t \fIlength\fP, int xml_version)\fR"
Check that the given \fIstring\fP of \fIlength\fP bytes
is a legal XML name according to XML 1.0 or XML 1.1.
\fIxml_version\fP is set to 10 or 11 respectively.
Returns non-zero if the name is legal.
.SH "MEMORY UTILITY FUNCTIONS"
.IP "\fBvoid raptor_free_memory(void *\fIptr\fP)\fR"
Free memory allocated 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 free memory
allocated by raptor, such as the result of the \fI_to_\fP methods
that return allocated memory such as \fBraptor_uri_to_filename\fP,
\fBraptor_uri_to_string\fP, \fBraptor_uri_to_relative_counted_uri_string\fP,
\fBraptor_uri_to_relative_uri_string\fP or
\fBraptor_new_namespace_parts_from_string\fP.
.IP "\fBvoid* raptor_alloc_memory(size_t \fIsize\fP)\fR"
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 allocate memory
for raptor to free later, such as inside the handler function
declared with \fBraptor_set_generate_id_handler\fP which returns
new memory.
.IP "\fBvoid* raptor_calloc_memory(size_t \fInmemb\fP, size_t \fIsize\fP)\fR"
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 freeing later, such
as inside the handler function declared with
\fBraptor_set_generate_id_handler\fP which returns new memory.
.SH "UNICODE UTILITY FUNCTIONS"
.IP "\fBint raptor_unicode_char_to_utf8(unsigned long \fIc\fP, unsigned char *\fIoutput\fP)\fR"
Turn a Unicode character into UTF8 bytes in \fIoutput\fP of
size \fIc\fP bytes which must be of sufficient size. Returns the
number of bytes encoded or <0 on failure.
.IP "\fBint raptor_utf8_to_unicode_char(unsigned long *\fIoutput\fP, const unsigned char *\fIinput\fP, int \fIlength\fP)\fR"
Decode a sequence UTF8 bytes in \fIinput\fP of size \fIlength\fP
into a Unicode character in \fIoutput\fR returning the number of
bytes used or <0 on failure.
.IP "\fBint raptor_utf8_check(const unsigned char *\fIstring\fP, size_t \fIlen\fPgth)\fR"
Check that a given \fIstring\fP 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.
.IP "\fBint raptor_unicode_is_xml11_namestartchar(long \fIc\fP)\fR"
.IP "\fBint raptor_unicode_is_xml10_namestartchar(long \fIc\fP)\fR"
.IP "\fBint raptor_unicode_is_xml11_namechar(long \fIc\fP)\fR"
.IP "\fBint raptor_unicode_is_xml10_namechar(long \fIc\fP)\fR"
Check that given Unicode characters are allowed as
XML 1.0 or XML 1.0 names - either as the starting character
(\fB*_namestartchar\fP) or continuing character (\fB*_namechar\fP).
Returns non-0 if the character is allowed.
.SH "MISCELLANEOUS UTILITY FUNCTIONS"
.IP "\fBchar* raptor_vsnprintf(const char *message, va_list arguments)\fR"
Compatibility wrapper around vsnprintf.
.SH "STATIC VARIABLES"
There are several read-only static variables in the raptor library:
.IP "\fBconst char * const raptor_short_copyright_string\fR"
Short copyright string, suitable for one line.
.IP "\fBconst char * const raptor_copyright_string\fR"
Full copyright over several lines including URLs.
.IP "\fBconst char * const raptor_version_string\fR"
The version as a string
.IP "\fBconst unsigned int raptor_version_major\fR"
The major version number as an integer.
.IP "\fBconst unsigned int raptor_version_minor\fR"
The minor version number as an integer.
.IP "\fBconst unsigned int raptor_version_release\fR"
The release version number as an integer.
.IP "\fBconst unsigned int raptor_version_decimal\fR"
The version number as a single decimal.
.SH "SERIALIZER CLASS"
This class provides the functionality of turning RDF triples
into syntaxes - RDF serializing.
.SH "SERIALIZER CONSTRUCTOR"
.IP "\fBraptor_serializer* raptor_new_serializer(const char *\fIname\fP)\fR"
Create a new raptor serializer object for the serializer with name
\fIname\fR currently either "rdfxml" or "ntriples".
or "rss-1.0" for the RSS 1.0 serializer.
.SH "SERIALIZER DESTRUCTOR"
.IP "\fBvoid raptor_free_serializer(raptor_serializer* \fIrdf_serializer\fB)\fR"
Destroy a Raptor serializer object.
.SH "SERIALIZER SERIALIZING METHODS"
.IP "\fBint raptor_serialize_start(raptor_serializer* \fIrdf_serializer\fB, raptor_uri *\fIuri\fP, raptor_iostream *\fIiostream\fP)\fR"
Start to serialize content using the given \fIiostream\fR to write
to with optional base URI \fIuri\fR. Note that
some syntaxes may refuse to serialize without a base URI, such as RDF/XML.
.IP "\fBint raptor_serialize_start_to_filename(raptor_serializer* \fIrdf_serializer\fB, const char *\fIfilename\fP)\fR"
Start to serialize content to the file \fIfilename\fR which is opened
for writing. The base URI is calculated from the file name.
.IP "\fBint raptor_serialize_start_to_string(raptor_serializer* \fIrdf_serializer\fB, raptor_uri *\fIuri\fP, void **\fIstring_p\fP, size_t *\fIlength_p\fP)\fR"
Start to serialize content to a string. \fIstring_p\fP must point
to a void* pointer that will be used at the end of serializing to store
the newly allocated string. \fIlength_p\fP if not NULL, it will
be used to store the length of the new string.
The serializing is done with optional base URI \fIuri\fR however
some syntaxes may refuse to serialize without a base URI, such as RDF/XML.
.IP "\fBint raptor_serialize_start_to_file_handle(raptor_serializer* \fIrdf_serializer\fB, raptor_uri *\fIuri\fP, FILE *\fIhandle\fP)\fR"
Start to serialize content to the already open C Standard I/O FILE*
\fIhandle\fR with the base URI \fIuri\fR, which is optional and may be
NULL. Note that some syntaxes may refuse to serialize without a base URI, such
as RDF/XML.
.IP "\fBint raptor_serialize_statement(raptor_serializer* \fIrdf_serializer\fB, const raptor_statement *\fIstatement\fP)\fR"
Serialize a single \fIstatement\fP using the serializer.
.IP "\fBint raptor_serialize_end(raptor_serializer* \fIrdf_serializer\fB)\fR"
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.
.IP "\fBraptor_iostream* raptor_serializer_get_iostream(raptor_serializer *\fIserializer\fP)\fR"
Return a pointer to the raptor_iostream* used by the serializer.
.IP "\fBint raptor_serializer_set_namespace(raptor_serializer* \fIserializer\fP, raptor_uri *\fIuri\fP, const char *\fIprefix\fP)\fR"
Set a suggested namespace URI/prefix mapping for use in serializing.
.SH "SERIALIZER UTILITY METHODS"
.IP "\fBvoid raptor_serializer_set_error_handler(raptor_serializer* \fIserializer\fB, void *\fIuser_data\fB, raptor_message_handler \fIhandler\fB)\fR"
Set the serializer non-fatal error handler callback.
.IP "\fBvoid raptor_serializer_set_warning_handler(raptor_serializer* \fIserializer\fB, void *\fIuser_data\fB, raptor_message_handler \fIhandler\fB)\fR"
Set the serializer warning message handler callback.
.IP "\fBraptor_locator* raptor_serializer_get_locator(raptor_serializer* \fIrdf_serializer\fB)\fR"
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.
.IP "\fBint raptor_serializer_set_feature(raptor_serializer *\fIserializer\fB, raptor_feature \fIfeature\fB, int \fIvalue\fB)\fR"
Set a serializer feature \fIfeature\fR to a particular \fIvalue\fR.
Returns non 0 on failure or if the feature is unknown.
The current defined serializer features are:
\fIFeature Values\fR
\fBRAPTOR_FEATURE_RELATIVE_URIS\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_START_URI\fR URI String
.P
If the \fIrelative_uris\fR
feature is true (default false) then when serialising, preference
is given to generating relative URIs where possible.
.P
If the \fIstart_uri\fR
feature is set to a URI it is used by the serializer to start serializing from.
.IP "\fBint raptor_serializer_get_feature(raptor_serializer* \fIserializer\fB, raptor_feature \fIfeature\fB)\fR"
Get serializer features, the allowed \fIfeature\fP values are available
.SH "SERIALIZER UTILITY FUNCTIONS"
.IP "\fBint raptor_serializers_enumerate(const unsigned \fIint counter\fB, const char **\fIname\fB, const char **\fIlabel\fB, const char **\fImime_type\fB, const unsigned char **\fIuri_string\fB)\fR"
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 incremented by 1
until the function returns non-zero.
.IP "\fBint raptor_serializer_syntax_name_check(const char *\fIname\fB)\fR"
Check \fIname\fP is a known serializer syntax name.
.SH "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 implementation can be replaced by any other that provides the
equivalent functionality, using the \fBraptor_uri_set_handler\fP function.
.SH "URI CONSTRUCTORS"
There a several constructors for raptor_uri to build them from
char* strings and existing raptor_uri objects.
.IP "\fBraptor_uri* raptor_new_uri(const unsigned char* \fIuri_string\fB)\fR"
Create a raptor URI from a string URI-reference
\fIuri_string\fR.
.IP "\fBraptor_uri* raptor_new_uri_from_uri_local_name(raptor_uri* \fIuri\fB, const unsigned char* \fIlocal_name\fB)\fR"
Create a raptor URI from a string URI-reference
\fIlocal_name\fR
relative to an existing URI-reference. This performs concatenation of the
\fIlocal_name\fR
to the
\fIuri\fR
and not relative URI resolution, which is done by the
raptor_new_uri_relative_to_base constructor.
.IP "\fBraptor_uri* raptor_new_uri_relative_to_base(raptor_uri* \fIbase_uri, const unsigned char* \fIuri_string\fB)\fR"
Create a raptor URI from a string URI-reference
\fIuri_string\fR
using relative URI resolution to the
\fIbase_uri\fR.
.IP "\fBraptor_uri* raptor_new_uri_from_id(raptor_uri* \fIbase_uri\fB, const unsigned char* \fIid\fB)\fR"
Create a raptor URI from a string RDF ID
\fIid\fR
concatenated to the
\fIbase_uri\fR
base URI.
.IP "\fBraptor_uri* raptor_new_uri_for_rdf_concept(const char* \fIname\fB)\fR"
Create a raptor URI for the RDF namespace concept
\fIname\fR.
.IP "\fBraptor_uri* raptor_new_uri_for_xmlbase(raptor_uri* \fIold_uri\fB))\fR"
Create a raptor URI suitable for use with xml:base (throw away fragment)
.SH "URI DESTRUCTOR"
.IP "\fBvoid raptor_free_uri(raptor_uri* \fIuri\fB)\fR"
Destroy a raptor URI object.
.SH "URI METHODS"
.IP "\fBint raptor_uri_equals(raptor_uri* \fIuri1\fB, raptor_uri* \fIuri2\fB)\fR"
Return non-zero if the given URIs are equal.
.IP "\fBraptor_uri* raptor_uri_copy(raptor_uri* \fIuri\fB)\fR"
Return a copy of the given raptor URI \fIuri\fP.
.IP "\fBunsigned char* raptor_uri_as_counted_string(raptor_uri *uri, size_t* len_p)\fR"
.IP "\fBunsigned char* raptor_uri_as_string(raptor_uri* \fIuri\fB)\fR"
Return a shared pointer to a string representation of the given raptor URI
\fIuri\fR. This string is shared and must not be freed (otherwise
see the \fBraptor_uri_to_*\fP methods below). If
\fBraptor_uri_as_counted_string\fP is used, the length of the returned
string is stored in *\fIlen_p\fP if not NULL.
.IP "\fBunsigned char* raptor_uri_to_counted_string(raptor_uri *\fIuri\fP, size_t *\fIlen_p\fP)\fR"
.IP "\fBunsigned char* raptor_uri_to_string(raptor_uri *\fIuri\fP)\fR"
Return a to a newly alloced string representation of the given raptor URI
\fIuri\fR. This string must be freed by the caller using
\fBraptor_free_memory\fP. If
\fBraptor_uri_to_counted_string\fP is used, the length of the returned
string is stored in *\fIlen_p\fP if not NULL.
.IP "\fBunsigned char* raptor_uri_to_relative_counted_uri_string(raptor_uri *\fIbase_uri\fB, raptor_uri *\fIreference_uri\fB, size_t *\fIlength_p\fB)\fR"
.IP "\fBunsigned char* raptor_uri_to_relative_uri_string(raptor_uri *\fIbase_uri\fB, raptor_uri *\fIreference_uri\fB)\fR"
Return a new relative URI string of a URI \fIreference_uri\fI against
a base URI \fIbase_uri\fR. The returned string must be freed
with \fBraptor_free_memory\fP.
If \fBraptor_uri_to_relative_counted_string\fP is used, the length of
the returned string is stored in *\fIlen_p\fP if not NULL.
.IP "\fBvoid raptor_uri_print(const raptor_uri* \fIuri\fP, FILE *\fIstream\fP)\fR"
Print URI \fIuri\fP to the file handle \fIstream\fP.
.IP "\fBint raptor_iostream_write_uri(raptor_iostream* \fIiostr\fP, raptor_uri* \fIuri\fP)\fR"
Write the raptor_uri \fIuri\fP to the iostream \fIostr\fP.
.SH "URI UTILITY FUNCTIONS"
.IP "\fBvoid raptor_uri_resolve_uri_reference (const unsigned char* \fIbase_uri\fB, const unsigned char* \fIreference_uri\fB, char unsigned* \fIbuffer\fB, size_t \fIlength\fB)\fR"
This is a standalone function that resolves the relative URI
\fIreference_uri\fR against the base URI \fIbase_uri\fR
according to the URI resolution rules in RFC2396.
The resulting URI is stored in \fIbuffer\fR which is of \fIlength\fR
bytes. If this is too small, no work will be done.
.IP "\fBchar *raptor_uri_filename_to_uri_string(const unsigned char* \fIfilename\fB)\fR"
This is a standalone function that turns a local filename (Windows
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 \fBraptor_free_memory\fP may be used.
.IP "\fBchar *raptor_uri_uri_string_to_filename(const unsigned char* \fIuri_string\fB)\fR"
.IP "\fBchar *raptor_uri_uri_string_to_filename(const unsigned char* \fIuri_string\fB, unsigned char **\fIfragment_p\fP)\fR"
These are standalone functions that turn a URI string that
represents a local filename (file:) into a filename, with optional
URI fragment. If \fIfragment_p\fP is not NULL it points to the
location 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 \fBraptor_free_memory\fP may be used.
.IP "\fBint raptor_uri_is_file_uri(const unsigned char* \fIuri_string\fB)\fR"
DEPRECATED in 1.4.9.
Returns non-zero if the given URI string represents a filename.
Use \fBraptor_uri_uri_string_is_file_uri\fP in preference.
.IP "\fBint raptor_uri_uri_string_is_file_uri(const unsigned char* \fIuri_string\fP)\fR"
Returns non-zero if the given URI string represents a filename.
.SH "URI CLASS IMPLEMENTATION"
.IP "\fBvoid raptor_uri_set_handler(const raptor_uri_handler *\fIhandler\fB, void *\fIcontext\fB)\fR"
Change the URI class implementation to the functions provided by the
\fIhandler\fR
URI implementation.
The
\fIcontext\fR
user data is passed in to the handler URI implementation calls.
.IP "\fBvoid raptor_uri_get_handler(raptor_uri_handler **\fIhandler\fB, void **\fIcontext\fB)\fR"
Return the current raptor URI class implementation
\fIhandler\fR
and
\fIcontext\fR
.SH "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.
.SH "WWW CLASS INITIALISATION AND CLEANUP"
.IP "\fBvoid raptor_www_init(void)\fR"
.IP "\fBvoid raptor_www_finish(void)\fR"
Initialise or terminate the raptor_www infrastructure. raptor_www_init
and raptor_finish are called by raptor_init and raptor_finish
respecitively, otherwise must be called once each.
.IP 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 \fBraptor_www_init\fR or terminated in
\fBraptor_www_finish\fR, so always performs it.
This can be changed by \fBraptor_www_no_www_library_init_finish\fR.
.IP "\fBvoid raptor_www_no_www_library_init_finish(void)\fR"
If this is called before \fBraptor_www_init\fR, it will not call
the underlying WWW library global initialise or terminate functions.
The application code must perform both operations.
.IP
For example with curl, after this function is called, neither
\fBcurl_global_init\fR nor \fBcurl_global_cleanup\fR will be called
during \fBraptor_www_init\fR or \fBraptor_www_finish\fR respectively.
.SH "WWW CONSTRUCTORS"
.IP "\fBraptor_www *raptor_www_new(void)\fR"
.IP "\fBraptor_www *raptor_www_new_with_connection(void* \fIconnection\fB)\fR"
Create a raptor WWW object capable of URI retrieval. If \fIconnection\fR
is given, it must match the connection object of the underlying 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.
.SH "WWW DESTRUCTOR"
.IP "\fBvoid raptor_www_free(raptor_www *\fIwww\fB)\fR"
Destroy a raptor WWW object.
.SH "WWW METHODS"
.IP "\fBvoid raptor_www_set_user_agent(raptor_www *\fIwww\fB, const char *\fIuser_agent\fB)\fR"
Set the user agent, for HTTP requests typically.
.IP "\fBvoid raptor_www_set_proxy(raptor_www *\fIwww\fB, const char *\fIproxy\fB)\fR"
Set the HTTP proxy - usually a string of the form http://server:port
.IP "\fBraptor_www_set_write_bytes_handler(raptor_www *\fIwww\fB, raptor_www_write_bytes_handler \fIhandler\fB, void *\fIuser_data\fB)\fR"
Set the handler to receive bytes written by the raptor_www implementation.
.IP "\fBvoid raptor_www_set_content_type_handler(raptor_www *\fIwww\fB, raptor_www_content_type_handler \fIhandler\fB, void *\fIuser_data\fB)\fR"
Set the handler to receive the HTTP Content-Type value, when/if
discovered during retrieval by the raptor_www implementation.
.IP "\fBvoid raptor_www_set_http_accept(raptor_www *\fIwww\fP, const char *\fIvalue\fP)\fR"
Set the WWW HTTP Accept: header to \fIvalue\fP. If \fIvalue\fP is
NULL, an empty header is sent.
.IP "\fBvoid raptor_www_set_error_handler(raptor_www *www\fB, raptor_message_handler \fIerror_handler\fB, void *\fIerror_data\fB)\fR"
Set the error handler routine for the raptor_www class. This takes the
same arguments as the raptor_parser error, warning handler methods.
.IP "\fBvoid raptor_www_set_uri_filter(raptor_www* \fIwww\fP, raptor_uri_filter_func \fIfilter\fP, void* \fIuser_data\fP)\fR"
Set the URI filter function \fIfilter\fP for URIs retrieved by
the raptor_www object.
.IP "\fBvoid* raptor_www_get_connection(raptor_www *\fIwww\fB)\fR"
Return the underlying WWW library connection object. For example,
for libcurl this is the curl_handle.
.SH "WWW ACTION METHODS"
.IP "\fBint raptor_www_fetch(raptor_www *www, raptor_uri *uri)\fR"
Retrieve the given URL, returning non zero on failure.
.IP "\fBint raptor_www_fetch_to_string(raptor_www *www, raptor_uri *uri, void **string_p, size_t *length_p, void *(*malloc_handler)(size_t size))\fR"
Retrieve the given URL to a string. \fIstring_p\fP must point
to a void* pointer that will be used to store
the newly allocated string. \fIlength_p\fP if not NULL, it will
be used to store the length of the new string.
.IP "\fBvoid raptor_www_abort(raptor_www *www, const char *reason)\fR"
Abort an ongoing raptor WWW operation. Typically used within one of the
raptor WWW handlers.
.SH "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_namespace_stack and raptor_namespace classes to handle a
stack of raptor_namespace that build on raptor_qname.
.SH "QNAME CONSTRUCTORS"
There are two constructors for raptor_qname to build qnames
with optional values on a stack of names.
.IP "\fBraptor_qname* raptor_new_qname(raptor_namespace_stack *\fInstack\fB, const unsigned char *\fIname\fB, const unsigned char *\fIvalue\fB, raptor_simple_message_handler \fIerror_handler\fB, void *\fIerror_data\fB)\fR"
Create a raptor QName \fIname\fR (a possibly :-separated name) with
name to be resolved against the given \fInstack\fR namespace stack.
An optional \fIvalue\fR can be given, and if there is an error,
the \fIerror_handler\fB and \fIerror_data\fR will be used to invoke
the callback.
.IP "\fBraptor_qname* raptor_new_qname_from_namespace_local_name (raptor_namespace *\fIns\fB, const unsigned char *\fIlocal_name\fB, const unsigned char *\fIvalue\fB)\fR"
Create a raptor QName using the namespace name of the
raptor_namespace \fIns\fR and the local name \fIlocal_name\fR, along
with optional value \fIvalue\fR. Errors are reported using
the error handling and data of the namespace.
.IP "\fBraptor_qname* raptor_qname_copy(raptor_qname *\fIqname\fP)\fR"
Create a raptor QName from an existing one, returning NULL on failure.
.SH "QNAME DESTRUCTOR"
.IP "\fBvoid raptor_free_qname(raptor_qname* \fIname\fB)\fR"
Destroy a raptor qname object.
.SH "QNAME METHODS"
.IP "\fBint raptor_qname_equal(raptor_qname* \fIname1\fP, raptor_qname *\fIname2\fP)\fR"
Return non-zero if the given QNames are equal.
.IP "\fBint raptor_iostream_write_qname(raptor_iostream* \fIiostr\fP, raptor_qname *\fIqname\fP)\fR"
Write the raptor_qname \fIqname\fP to the iostream \fIostr\fP.
.SH "QNAME UTILITY FUNCTIONS"
.IP "\fBraptor_uri* raptor_qname_string_to_uri(raptor_namespace_stack *\fInstack\fB, const unsigned char *\fIname\fB, size_t \fIname_len\fB, raptor_simple_message_handler \fIerror_handler\fB, void *\fIerror_data\fB)\fR"
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 \fBraptor_new_qname\fR but
does not create a raptor_qname object.
.IP "\fBraptor_namespace* raptor_qname_get_namespace(raptor_qname* \fIname\fB)\fR"
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.
.SH "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.
.SH "NAMESPACE CONSTRUCTORS"
.IP "\fBraptor_namespace* raptor_new_namespace(raptor_namespace_stack *\fInstack\fP, const unsigned char *\fIprefix\fP, const unsigned char *\fIns_uri_string\fP, int \fIdepth\fP)\fR"
.IP "\fBraptor_namespace* raptor_new_namespace_from_uri(raptor_namespace_stack *\fInstack\fP, const unsigned char *\fIprefix\fP, raptor_uri* \fIns_uri\fP, int \fIdepth\fP)\fR"
Create a new raptor_namespace object on the given namespace stack
\fInstack\fR with prefix \fIprefix\fR and namespace name either
from URI string \fIns_uri_string\fR or from copying URI \fIns_uri\fP.
.P
If \fIprefix\fR is NULL, it defines the URI for the default namespace
prefix. If the namespace name (\fIns_uri_string\fP or \fIns_uri\fP)
is NULL, it undefines the given \fIprefix\fR in the current scope.
Both prefix and URI may be NULL to undefine the default namespace.
\fIdepth\fR 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.
.P
Namespaces declared on the same
depth (such as on the same XML element, typically) can be handily
freed with \fIraptor_namespaces_end_for_depth\fR method on
the namespace stack class.
.SH "NAMESPACE DESTRUCTOR"
.IP "\fBvoid raptor_free_namespace(raptor_namespace *ns)\fR"
Destroy a raptor namespace object.
.SH "NAMESPACE METHODS"
.IP "\fBraptor_uri* raptor_namespace_get_uri(const raptor_namespace *ns)\fR"
Return the namespace name (URI) of the namespace.
.IP "\fBconst unsigned char* raptor_namespace_get_prefix(const raptor_namespace *ns)\fR"
Return the prefix of the namespace.
.IP "\fBconst unsigned char* raptor_namespace_get_counted_prefix(const raptor_namespace* \fIns\fP, size_t* \fIlength_p\fP)\fR"
Return the prefix of the namespace as a string with optional count stored in
the variable address \fIlength_p\fP if it is not NULL.
.IP "\fBunsigned char *raptor_namespaces_format(const raptor_namespace *ns, size_t *length_p)\fR"
Format the namespace as a string and return it as a new string, returning the
length of the resulting string in \fIlength_p\fR if it is not NULL.
The string format is suitable for emitting in XML to declare the
namespace.
.IP "\fBint raptor_iostream_write_namespace(raptor_iostream* \fIiostr\fP, raptor_namespace *\fIns\fP)\fR"
Write a formatted namespace declaration like xmlns... to an
iostream \fIiostr\fP.
.SH "NAMESPACE UTILITY FUNCTIONS"
.IP "\fBint raptor_namespace_copy(raptor_namespace_stack *nstack, raptor_namespace *ns, int new_depth)\fR"
Copy the namespace from the current stack to the new one,
\fInstack\fR at depth \fInew_depth\fR.
.IP "\fBint raptor_new_namespace_parts_from_string(unsigned char *\fIstring\fP, unsigned char **\fIprefix\fP, unsigned char **\fIuri_string\fP)\fR"
Parse \fIstring\fR with an XML-style namespace declaration like
xmlns="", xmlns="uri", xmlns:prefix="" or xmlns:prefix="uri"
into the strings pointed to by \fIprefix\fP string and a \fIuri_string\fP.
Empty prefixes or namespace names return NULL pointers. Returned
strings must be freed by the caller using \fBraptor_free_memory\fP.
.SH "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 declarations.
Intended to match the XML namespace declaring semantics using
xmlns attributes.
.SH "NAMESPACE STACK CONSTRUCTORS"
.IP "\fBraptor_namespace_stack* raptor_new_namespaces(raptor_uri_handler *uri_handler, void *uri_context, raptor_simple_message_handler error_handler, void *error_data, int defaults)\fR"
.IP "\fBvoid raptor_namespaces_init(raptor_namespace_stack *nstack, raptor_uri_handler *handler, void *context, raptor_simple_message_handler error_handler, void *error_data, int defaults)\fR"
Create or initialise a new raptor_namespace_stack object with the given URI and
error handlers. \fBraptor_namespaces_new\fR allocates new memory
for the namespace stack and \fBraptor_namespaces_init\fR initialises an
existing declared \fInstack\fR, which could be statically allocated.
Note that \fBraptor_uri_get_handler\fR can be useful to return the
current raptor URI handler/context. The \fIdefaults\fR 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.
.SH "NAMESPACE STACK DESTRUCTORS"
.IP "\fBvoid raptor_free_namespaces(raptor_namespace_stack *nstack)\fR"
Destroy a namespace stack object, freeing the \fInstack\fR
(goes with \fBraptor_new_namespaces\fR).
.IP "\fBvoid raptor_namespaces_clear(raptor_namespace_stack *nstack)\fR"
Clear a statically allocated namespace stack; does not free the \fInstack\fR.
(goes with \fBraptor_namespaces_init\fR).
.SH "NAMESPACE STACK METHODS"
.IP "\fBvoid raptor_namespaces_start_namespace(raptor_namespace_stack *nstack, raptor_namespace *nspace)\fR"
Start the given \fInspace\fR on the stack, at the depth already defined.
.IP "\fBint raptor_namespaces_start_namespace_full(raptor_namespace_stack *nstack, const unsigned char *prefix, const unsigned char *nspace, int depth)\fR"
Create a new raptor_namespace and start it on the stack.
See \fBraptor_new_namespace\fR for the meaning of the argumens.
.IP "\fBvoid raptor_namespaces_end_for_depth(raptor_namespace_stack *nstack, int depth)\fR"
End (and free) all namespaces on the stack at the given \fIdepth\fR.
.IP "\fBraptor_namespace* raptor_namespaces_get_default_namespace (raptor_namespace_stack *nstack)\fR"
Return the current default raptor_namespace of the namespace stack
or NULL if there is none.
.IP "\fBraptor_namespace* raptor_namespaces_find_namespace_by_uri(raptor_namespace_stack *\fInstack\fP, raptor_uri *\fIns_uri\fP)\fR"
Find the first namespace on the stack with the given uri \fIns_uri\fR
or NULL if there is none.
.IP "\fBraptor_namespace *raptor_namespaces_find_namespace_by_uri(raptor_namespace_stack *nstack, const unsigned char *prefix, int prefix_length)\fR"
Find the first namespace on the stack with the given namespace \fIprefix\fR
or NULL if there is none.
.IP "\fBint raptor_namespaces_namespace_in_scope(raptor_namespace_stack *nstack, const raptor_namespace *nspace)\fR"
Return non-zero if the raptor_namespace \fInspace\fR is declared
on the stack; i.e. in scope if this is a stack of XML namespaces.
.SH "NAMESPACE STACK UTILITY FUNCTIONS"
.IP "\fBraptor_qname* raptor_namespaces_qname_from_uri(raptor_namespace_stack* \fInstack\fP, raptor_uri* \fIuri\fP, int \fIxml_version\fP)\fR"
Create a raptor QName from the URI \fIuri\fP if the URI is squal one
of the namespace URIs on the namespace stack \fInstack\fP URIs
concatenated 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.
.SH "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.
.SH "SEQUENCE CONSTRUCTOR"
.IP "\fBraptor_sequence* raptor_new_sequence(raptor_sequence_free_handler* \fIfree_handler\fP, raptor_sequence_print_handler* \fIprint_handler\fP)\fR"
Create a new empty sequence, with optional handler for freeing elements
(as used by \fBraptor_free_sequence\fP
and printing out elements (used by \fBraptor_sequence_print\fP).
.SH "SEQUENCE DESTRUCTOR"
.IP "\fBvoid raptor_free_sequence(raptor_sequence* \fIseq\fP)\fR"
Destoy a sequence object, freeing any items if the free handler
was defined in the constructor.
.SH "SEQUENCE METHODS"
.IP "\fBint raptor_sequence_size(raptor_sequence* \fIseq\fP)\fR"
Return the number of items in the sequence.
.IP "\fBint raptor_sequence_set_at(raptor_sequence* \fIseq\fP, int \fIidx\fP, void *data)\fR"
Set the sequence item at index \fIidx\fP to the value \fIdata\fP, extending
it if necessary.
.IP "\fBint raptor_sequence_push(raptor_sequence* \fIseq\fP, void *\fIdata\fP)\fR"
Add item \fIdata\fP to the end of the sequence.
.IP "\fBint raptor_sequence_shift(raptor_sequence* \fIseq\fP, void *\fIdata\fP)\fR"
Add item \fIdata\fP to the start of the sequence.
.IP "\fBvoid* raptor_sequence_get_at(raptor_sequence* \fIseq\fP, int \fIidx\fP)\fR"
Get the sequence item at index \fIidx\fP or NULL if no such index exists.
.IP "\fBvoid* raptor_sequence_pop(raptor_sequence* \fIseq\fP)\fR"
Remove and return an item from the end of the sequence, or NULL if is empty.
.IP "\fBvoid* raptor_sequence_unshift(raptor_sequence* \fIseq\fP)\fR"
Remove and return an item from the start of the sequence, or NULL if is empty.
.IP "\fBvoid raptor_sequence_sort(raptor_sequence* \fIseq\fP, int(*\fIcompare\fP)(const void *, const void *))\fR"
Sort the sequence using the given comparison function \fIcompare\fP
which is passed to qsort(3) internally.
.IP "\fBint raptor_compare_strings(const void *\fIa\fP, const void *\fIb\fP)\fR"
Helper function useful with \fBraptor_sequence_sort\fP.
.IP "\fBvoid raptor_sequence_set_print_handler(raptor_sequence *\fIseq\fP, raptor_sequence_print_handler *\fIprint_handler\fP)\fR"
Set the print handler for the sequence, an alternative to setting
it in the constructor.
.IP "\fBvoid raptor_sequence_print_string(char *\fIdata\fP, FILE *\fIfh\fP)\fR"
Helper print handler function useful for printing out sequences of strings.
.IP "\fBvoid raptor_sequence_print_uri(char *\fIdata\fP, FILE *\fIfh\fP)\fR"
Helper print handler function useful for printing out sequences of
raptor_uri* objects.
.IP "\fBvoid raptor_sequence_print(raptor_sequence* \fIseq\fP, FILE* \fIfh\fP)\fR"
Print out the sequence in a debug format to the given file handler
\fIfh\fP. NOTE: The exact format is not guaranteed to remain
the same between releases.
.IP "\fBint raptor_sequence_join(raptor_sequence* \fIdest\fP, raptor_sequence *\fIsrc\fP)\fR"
Join two sequences moving all items from sequence \fIsrc\fP to the
end of sequence \fIdest\fP. After this operation, sequence \fIsrc\fP
will be empty (zero size) but will have the same item capacity as
before.
.SH "STRINGBUFFER CLASS"
A class for growing strings, small chunks at a time.
.SH "STRINGBUFFER CONSTRUCTOR"
.IP "\fBraptor_stringbuffer* raptor_new_stringbuffer(void)\fR"
Create a new stringbuffer.
.SH "STRINGBUFFER DESTRUCTOR"
.IP "\fBvoid raptor_free_stringbuffer(raptor_stringbuffer* \fIstringbuffer\fP)\fR"
Destroy a stringbuffer.
.SH "STRINGBUFFER METHODS"
.IP "\fBint raptor_stringbuffer_append_counted_string(raptor_stringbuffer* \fIstringbuffer\fP, const unsigned char *\fIstring\fP, size_t \fIlength\fP, int \fIdo_copy\fP)\fR"
Append a \fIstring\fP of \fIlength\fP bytes to a stringbuffer, copying it only if
\fIdo_copy\fP is non-0.
.IP "\fBint raptor_stringbuffer_append_string(raptor_stringbuffer* \fIstringbuffer\fP, const unsigned char* \fIstring\fP, int \fIdo_copy\fP)\fR"
Append a \fIstring\fP to a stringbuffer, copying it only if
\fIdo_copy\fP is non-0.
.IP "\fBint raptor_stringbuffer_append_decimal(raptor_stringbuffer* \fIstringbuffer\fP, int \fIinteger\fP)\fR"
Append a formatted decimal \fIinteger\fP to a stringbuffer.
.IP "\fBint raptor_stringbuffer_append_stringbuffer(raptor_stringbuffer* \fIstringbuffer\fP, raptor_stringbuffer* \fIappend\fP)\fR"
Append a stringbuffer \fIappend\fP to a stringbuffer. The append
stringbuffer is emptied but not destroyed.
.IP "\fBint raptor_stringbuffer_prepend_counted_string(raptor_stringbuffer* \fIstringbuffer\fP, const unsigned char* \fIstring\fP, size_t \fIlength\fP, int \fIdo_copy\fP)\fR"
Prepend a \fIstring\fP of \fIlength\fP bytes to the start of a
stringbuffer, copying it only if \fIdo_copy\fP is non-0.
.IP "\fBint raptor_stringbuffer_prepend_string(raptor_stringbuffer* \fIstringbuffer\fP, const unsigned char* \fIstring\fP, int \fIdo_copy\fP)\fR"
Prepend a \fIstring\fP to the start of a stringbuffer, copying it
only if \fIdo_copy\fP is non-0.
.IP "\fBunsigned char * raptor_stringbuffer_as_string(raptor_stringbuffer* \fIstringbuffer\fP)\fR"
Return the stringbuffer as a single string. The string is shared and
should be copied if needed.
.IP "\fBsize_t raptor_stringbuffer_length(raptor_stringbuffer* \fIstringbuffer\fP)\fR"
Return the length of the stringbuffer.
.IP "\fBint raptor_stringbuffer_copy_to_string(raptor_stringbuffer* stringbuffer, unsigned char *\fIstring\fP, size_t \fIlen\fPgth)\fR"
Copy the stringbuffer into a single string buffer \fIstring\fP of
size \fIlength\fP. Returns non-0 on failure.
.SH "IOSTREAM CLASS"
This class provides an I/O stream that can write to filenames, FILE*,
strings and user-defined output via callbacks.
.SH "IOSTREAM CONSTRUCTOR"
.IP "\fBraptor_iostream* raptor_new_iostream_from_handler(void* \fIcontext\fB, const raptor_iostream_handler *\fIhandler\fB)\fR"
Create a new raptor iostream from a user-defined
raptor_iostream_handler \fIhandler\fP that is called with the
passed-in \fIcontext\fP for the write operations.
.IP "\fBraptor_iostream* raptor_new_iostream_to_sink(void)\fR"
Create a new raptor iostream that discards all written output.
.IP "\fBraptor_iostream* raptor_new_iostream_to_filename(const char *\fIfilename\fB)\fR"
Create a new raptor iostream that creates and writes to a new file
\fIfilename\fP.
.IP "\fBraptor_iostream* raptor_new_iostream_to_file_handle(FILE *\fIhandle\fB)\fR"
Create a new raptor iostream that creates and writes to an existing,
already opened, C Standard I/O handle FILE* \fIhandle\fP.
.IP "\fBraptor_iostream* raptor_new_iostream_to_string(void **\fIstring_p\fB, size_t *\fIlength_p\fB, void *(*\fImalloc_handler\fB)(size_t size))\fR"
Create a new raptor iostream which creates a new string
once raptor_free_iostream is called. The new string pointer
is written in \fIstring\fP, the length in \fIlength_p\fP (if not
NULL) and the memory allocation is made using the
\fImalloc_handler\fP, or if NULL, raptor's default memory allocator.
.SH "IOSTREAM DESTRUCTOR"
.IP "\fBvoid raptor_free_iostream(raptor_iostream *\fIiostr\fB)\fR"
Destroy a Raptor iostream object.
.SH "IOSTREAM METHODS"
.IP "\fBint raptor_iostream_write_bytes(raptor_iostream *\fIiostr\fB, const void *\fIptr\fB, size_t \fIsize\fB, size_t \fInmemb\fB)\fR"
Write a counted set of elements to an iostream. \Inmemb\fP is the
count of elements of size \fIsize\fP, starting at memory \fIptr\fP.
Similar to fwrite(3) and write(2).
.IP "\fBint raptor_iostream_write_byte(raptor_iostream *\fIiostr\fB, const int \fIbyte\fB)\fR"
Write a single \fIbyte\fP an iostream. Similar to fputc(3).
.IP "\fBvoid raptor_iostream_write_end(raptor_iostream *\fIiostr\fB)\fR"
Finish writing to an iostream.
.IP "\fBint raptor_iostream_write_string(raptor_iostream *\fIiostr\fB, const void *\fIstring\fB)\fR"
Write a NUL-terminated \fIstring\fP to an iostream. Similar to fputs(3).
.IP "\fBint raptor_iostream_write_counted_string(raptor_iostream *\fIiostr\fB, const void *\fIstring\fB, size_t \fIlen\fB)\fR"
Write a \fIstring\fP of length \fIlen\fP to an iostream.
.IP "\fBsize_t raptor_iostream_get_bytes_written_count(raptor_iostream *\fIiostr\fB)\fR"
Return the number of bytes written so far to the iostream.
.IP "\fBint raptor_iostream_write_decimal(raptor_iostream *\fIiostr\fB, int \fIinteger\fB)\fR"
Write a decimal formatted integer \fIinteger\fP to the iostream.
.IP "\fBint raptor_iostream_format_hexadecimal(raptor_iostream *\fIiostr\fB, unsigned int \fIinteger\fB, int \fIwidth\fB)\fR"
Write a hexadecimal formatted unsigned \fIinteger\fP to the iostream,
left-padded with '0's to \fIwidth\fR columns.
.IP "\fBint raptor_iostream_write_stringbuffer(raptor_iostream* \fIiostr\fB, raptor_stringbuffer *\fIsb\fB)\fR"
Write the stringbuffer to an iostream \fIiostr\fP.
.SH "XML ELEMENT CLASS"
This class provides an XML element that can be used with the
XML Writer Class to generate XML documents.
.SH "XML ELEMENT CONSTRUCTOR"
.IP "\fBraptor_xml_element* raptor_new_xml_element(raptor_qname* \fIname\fP, const unsigned char* \fIxml_language\fP, raptor_uri* \fIxml_base\fP)\fR"
Create a new XML element with the element name \fIname\fP and
in context of xml:lang \fIxml_language\fP and base URI
\fIxml_base\fP.
.SH "XML ELEMENT DESTRUCTOR"
.IP "\fBvoid raptor_free_xml_element(raptor_xml_element *\fIelement\fP)\fR"
Destroy a XML element object.
.SH "XML ELEMENT METHODS"
.IP "\fBraptor_qname* raptor_xml_element_get_name(raptor_xml_element* \fIxml_element\fP)\fR"
Get the XML element QName of XML element \fIxml_element\fP.
.IP "\fBvoid raptor_xml_element_set_attributes(raptor_xml_element* \fIxml_element\fP, raptor_qname **\fIattributes\fP, int \fIcount\fP)\fR"
Set the attributes on XML element \fIxml_element\fP to the
array of QNames in array \fIattributes\fP of size \fIcount\fP.
.IP "\fBraptor_qname** raptor_xml_element_get_attributes(raptor_xml_element* \fIxml_element\fP)\fR"
Get the attributes of an XML element \fIxml_element\fP as an
array of QNames. As set by \fBvoid raptor_xml_element_set_attributes\fP.
.IP "\fBint raptor_xml_element_get_attributes_count(raptor_xml_element* \fIxml_element\fP)\fR"
Get the number of attributes of an XML element \fIxml_element\fP as
set by \fBvoid raptor_xml_element_set_attributes\fP.
.IP "\fBint raptor_xml_element_declare_namespace(raptor_xml_element* \fIxml_element\fP, raptor_namespace* \fInspace\fP)\fR"
Declare an XML namespace \fInspace\fP expliclitly on XML element
\fIxml_element\fP. Namespaces used in the element or attribute
names are automatically declared, this method allows additional ones
to be done.
.IP "\fBint raptor_xml_element_is_empty(raptor_xml_element*\fI xml_element\fP)"
Return non-0 if the XML element is empty.
.IP "\fBint raptor_iostream_write_xml_element(raptor_iostream* \fIiostr\fP, raptor_xml_element *\fIelement\fP, raptor_namespace_stack* \fInstack\fP, int \fIis_empty\fP, int \fIis_end\fP, raptor_simple_message_handler \fIerror_handler\fP, void* \fIerror_data\fP, int \fIdepth\fP)\fR"
Write a XML element \fIxml_element\fP to iostream \fIostr\fP.
This is done in context of an XML namespace stack \fInstack\fP and
at depth \fIdepth\fP in the stack (see Namespace class constructors).
.IP
The element may be an empty element if \fIis_empty\fP is non-zero or may
be a close element if \fIis_end\fP is non-zero (else is a start
element). The \fIerror_handler\fR method along
with \fIerror_data\fR allow error reporting to be given.
.SH "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.
.SH "XML WRITER CONSTRUCTOR"
.IP "\fBraptor_xml_writer* raptor_new_xml_writer(raptor_namespace_stack* \fInstack\fP, raptor_uri_handler* \fIuri_handler\fP, void* \fIuri_context\fP, raptor_iostream* \fIiostr\fP, raptor_simple_message_handler \fIerror_handler\fP, void *\fIerror_data\fP, int \fIcanonicalize\fP)\fR"
Create a new XML Writer writing to iostream \fIiostr\fP.
The \fIerror_handler\fR method along
with \fIerror_data\fR allow error reporting to be given.
\fInstack\fP 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 \fBraptor_uri_get_handler\fR can be useful to return the
current raptor URI handler/context. \fIcanonicalize\fP is currently
unused and should be set to 1 but may allow non-canonical XML writing
to be allowed in future.
.SH "XML WRITER DESTRUCTOR"
.IP "\fBvoid raptor_free_xml_writer(raptor_xml_writer* \fIxml_writer\fP)\fR"
Destroy a XML Writer object.
.SH "XML WRITER METHODS"
.IP "\fBvoid raptor_xml_writer_empty_element(raptor_xml_writer* \fIxml_writer\fP, raptor_xml_element *\fIelement\fP)\fR"
Write XML element \fIelement\fP as an empty element (no element
content) to the XML Writer \fIxml_writer\fP.
.IP "\fBvoid raptor_xml_writer_start_element(raptor_xml_writer* \fIxml_writer\fP, raptor_xml_element *\fIelement\fP)\fR"
Write a start element along with an attributes and namespace
declarations for XML element \fIelement\fP to the XML Writer
\fIxml_writer\fP.
.IP "\fBvoid raptor_xml_writer_end_element(raptor_xml_writer* \fIxml_writer\fP, raptor_xml_element *\fIelement\fP)\fR"
Write an end element form for XML element \fIelement\fP
to the XML Writer \fIxml_writer\fP.
.IP "\fBvoid raptor_xml_writer_cdata(raptor_xml_writer* \fIxml_writer\fP, const unsigned char *str)\fR"
Write XML character data in \fIstr\fP to the XML Writer
\fIxml_writer\fP. The characters in \fIstr\fP will be XML escaped.
.IP "\fBvoid raptor_xml_writer_cdata_counted(raptor_xml_writer* \fIxml_writer\fP, const unsigned char* \fIstr\fP, unsigned int \fIlength\fP)\fR"
Write XML character data in \fIstr\fP of length \fIlength\fP to the XML Writer
\fIxml_writer\fP. The characters in \fIstr\fP will be XML escaped.
.IP "\fBvoid raptor_xml_writer_raw(raptor_xml_writer* \fIxml_writer\fP, const unsigned char* \fIstr\fP)\fR"
Write character data in \fIstr\fP \fIlength\fP to the XML Writer
\fIxml_writer\fP without XML escaping.
.IP "\fBvoid raptor_xml_writer_raw_counted(raptor_xml_writer* \fIxml_writer\fP, const unsigned char* \fIstr\fP, unsigned int \fIlength\fP)\fR"
Write character data in \fIstr\fP of length \fIlength\fP to the XML Writer
\fIxml_writer\fP without XML escaping.
.IP "\fBvoid raptor_xml_writer_comment(raptor_xml_writer* \fIxml_writer\fP, const unsigned char* \fIstr\fP)\fR"
Write an XML comment in \fIstr\fP to the XML Writer \fIxml_writer\fP.
.IP "\fBvoid raptor_xml_writer_comment_counted(raptor_xml_writer* \fIxml_writer\fP, const unsigned char* \fIstr\fP, unsigned int \fIlength\fP)\fR"
Write an XML comment in \fIstr\fP of length \fIlength\fP to the XML
Writer \fIxml_writer\fP.
.IP "\fBint raptor_xml_writer_features_enumerate(const raptor_feature \fIfeature\fP, const char **\fIname\fP, raptor_uri **\fIuri\fP, const char **\fIlabel\fP)\fR"
Return the name, URI, string label (all optional)
for an XML write \fIfeature\fP, returning non-zero if no such feature exists.
.P
Raptor features have URIs that are constructed from the URI
\fIhttp://feature.librdf.org/raptor-\fP and the \fIname\fP
so for example feature \fIscanForRDF\fP
has URI \fIhttp://feature.librdf.org/raptor-scanForRDF\fP
.IP "\fBint raptor_xml_writer_set_feature(raptor_xml_writer* \fIxml_writer\fP, raptor_feature \fIfeature\fP, int \fIvalue\fP)\fR"
Set an XML writer feature \fIfeature\fR to a particular \fIvalue\fR.
Returns non 0 on failure or if the feature is unknown.
The current defined writer features are:
\fIFeature Values\fR
\fBRAPTOR_FEATURE_WRITER_AUTO_INDENT\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_WRITER_AUTO_EMPTY\fR Boolean (non 0 true)
\fBRAPTOR_FEATURE_WRITER_INDENT_WIDTH\fR Integer
\fBRAPTOR_FEATURE_WRITER_XML_DECLARATION\fR Boolean (non 0 true)
.P
If the \fIwriter_auto_indent\fR
feature is set (default true), the XML writer will automatically
indent the output.
.P
If the \fIwriter_auto_empty\fR
feature is set (default true), the XML writer will automatically
generate empty elements if a start/end element sequence has no content.
.P
If the \fIwriter_indent_width\fR
feature is set (default 2) if the XML writer is outputing indented
XML, it will use that many spaces.
.P
If the \fIwriter_xml_declaration\fR
feature is set (default true) the XML declaration is written at the
start of serialized XML.
.IP "\fBint raptor_xml_writer_set_feature_string(raptor_xml_writer *xml_writer, raptor_feature feature, const unsigned char *value)\fR"
Set an XML writer feature \fIfeature\fR to a particular string \fIvalue\fR.
Returns non 0 on failure or if the feature is unknown.
The current defined XML writer features are given in
\fBraptor_xml_writer_set_feature\fP and at present only take integer values. If
an integer value feature is set with this function, \fIvalue\fP is
interpreted as an integer and then that value is used.
.IP "\fBint raptor_xml_writer_get_feature(raptor_xml_writer* \fIxml_writer\fP, raptor_feature \fIfeature\fP)\fR"
Get XML writer feature integer values. The allowed \fIfeature\fP values
and types are given under \fBraptor_xml_writer_features_enumerate\fP.
.IP "\fBconst unsigned char *raptor_xml_writer_get_feature_string(raptor_xml_writer* \fIxml_writer\fP, raptor_feature \fIfeature\fP)\fR"
Get XML writer feature string values. The allowed \fIfeature\fP values
and types are given under \fBraptor_xml_writer_features_enumerate\fP.
.SH API CHANGES
.SS 1.4.13
No API changes.
.SS 1.4.12
No API changes.
.SS 1.4.11
Added \fBraptor_get_feature_count\fP
.LP
Added \fBraptor_get_need_base_uri\fP
.LP
Added parser feature \fBRAPTOR_FEATURE_NO_NET\fP
.LP
Added \fBraptor_www_set_uri_filter\fP, \fBraptor_parser_set_uri_filter\fP
with filter type \fBraptor_uri_filter_func\fP
.SS 1.4.10
No API changes.
.SS 1.4.9
Added \fBraptor_parser_get_accept_header\fP
.LP
Added \fBraptor_xml_element_is_empty\fP
.LP
Added \fBraptor_qname_get_namespace\fP
.LP
Added \fBraptor_iostream_write_uri\fP
.LP
Added \fBraptor_namespaces_qname_from_uri\fP.
.LP
Added \fBraptor_namespace_get_counted_prefix\fP
.LP
Added \fBraptor_serialize_set_namespace_from_namespace\fP
.LP
Deprecated \fBraptor_uri_is_file_uri\fP
for new \fBraptor_uri_string_is_file_uri\fP.
.LP
Added
\fBraptor_xml_element_get_attributes\fP and
\fBraptor_xml_element_get_attributes_count\fP
.SS 1.4.8
Added \fBraptor_set_namespace_handler\fP.
.LP
Added XML 1.1 serializing support, feature
\fBRAPTOR_FEATURE_WRITER_XML_VERSION\fP with shortname
\fIxmlVersion\fP for serializer and xml writer classes to support
it. Added XML writer feature
\fBRAPTOR_FEATURE_WRITER_XML_DECLARATION\fP to control generation
of the XML declaration.
Added new functions \fBraptor_xml_any_escape_string\fP and
\fBraptor_iostream_write_xml_any_escaped_string\fP to allow
generating XML 1.1 or XML 1.0.
.LP
\fBRAPTOR_IDENTIFIER_TYPE_PREDICATE\fP will no longer be generated
from version 1.4.9 onwards as the type of returned statement predicates.
\fBRAPTOR_IDENTIFIER_TYPE_RESOURCE\fP will be returned.
.LP
\fBRAPTOR_IDENTIFIER_TYPE_ORDINAL\fP may no longer be generated
from version 1.4.9 onwards, \fBRAPTOR_IDENTIFIER_TYPE_RESOURCE\fP
may replace it.
.SS 1.4.7
No changes.
.SS 1.4.6
No changes.
.SS 1.4.5
Deprecated \fBraptor_ntriples_string_as_utf8_string\fP (never
documented above) since it can only work with a raptor_parser object
which makes it rather unusable alone.
.P
Added XML writer features and support functions
\fBraptor_xml_writer_features_enumerate\fP,
\fBraptor_xml_writer_set_feature\fP,
\fBraptor_xml_writer_set_feature_string\fP,
\fBraptor_xml_writer_get_feature\fP and
\fBraptor_xml_writer_get_feature_string\fP
.SS 1.4.3
Added XML Writer class (\fBraptor_xml_writer\fP)
and XML Element class (\fBraptor_xml_element\fP)
.P
Added \fBraptor_parser_get_feature_string\fP,
\fBraptor_parser_set_feature_string\fP,
\fBraptor_serializer_set_feature_string\fP,
\fBraptor_serializer_get_feature_string\fP and
\fBraptor_feature_value_type\fP.
.P
Added \fBraptor_serializer_set_namespace\fP,
\fBraptor_serializer_set_feature\fP and
\fBraptor_serializer_get_feature\fP.
.P
Added
\fBraptor_new_namespace_from_uri\fP,
\fBraptor_new_namespace_parts_from_string\fP,
Added \fBraptor_namespaces_find_namespace_by_uri\fP.
and
\fBraptor_iostream_write_namespace\fP to write a namespace
declaration to an iostream.
.P
Added copy constructor \fBraptor_qname_copy\fP
and \fBraptor_iostream_write_qname\fP to write a qname to an iostream.
.P
Added \fBraptor_sequence_join\fP to join two sequences, leaving one empty.
.P
Added \fBraptor_iostream_write_stringbuffer\fP to write a
stringbuffer to an iostream.
.P
Added N-Triples
\fBraptor_iostream_write_string_ntriples\fP and
\fBraptor_iostream_write_statement_ntriples\fP
utility functions for writing to raptor_iostreams.
.P
Added \fBraptor_uri_to_relative_counted_uri_string\fP,
\fBraptor_uri_to_relative_uri_string\fP.
\fBraptor_uri_print\fP,
\fBraptor_uri_to_counted_string\fP and
\fBraptor_uri_to_string\fP
.P
Added unicode name checking utility functions for XML 1.0 and XML 1.1
name starting character and continued name character.
\fBraptor_unicode_is_xml10_namestartchar\fP
\fBraptor_unicode_is_xml10_namechar\fP,
\fBraptor_unicode_is_xml11_namechar\fP and
\fBraptor_unicode_is_xml11_namestartchar\fP.
.P
Added \fBraptor_xml_name_check\fP
to check if a name is a legal XML 1.0 or 1.0 name.
and \fBraptor_iostream_write_xml_escaped_string\fP to write
an XML-escaped string to an iostream.
.P
Added UTF8-checking utility function \fBraptor_utf8_check\fP.
.SS 1.4.2
No changes.
.SS 1.4.1
The \fBraptor_xml_escape_string\fR now returns <0 on failure rather
than 0, so that if an empty string is escaped, 0 bytes required is
returned.
.SS 1.4.0
Added new \fBraptor_serializer\fR class supporting RDF/XML (name
\fBrdfxml\fP) and N-Triples (name \fBntriples\fP).
.br
Added new \fBraptor_iostream\fR class
.br
Added \fBraptor_stringbuffer_copy_to_string\fR to allow efficient
copy-out of a constructed string.
.br
Added \fBraptor_www_fetch_to_string\fR to allow retrieving of
web content as a single string.
.SS 1.3.3
Added \fBraptor_calloc_memory\fR to provide a calloc inside raptor.
.br
Added feature check_rdf_id (see raptor_set_feature documentation).
.SS 1.3.2
Added \fBraptor_alloc_memory\fR to allocate memory inside raptor.
.LP
Added accessor functions for the public raptor_locator structure:
.LP
\fBraptor_locator_line\fR
.br
\fBraptor_locator_column\fR
.br
\fBraptor_locator_byte\fR
.br
\fBraptor_locator_file\fR
.br
\fBraptor_locator_uri\fR
.SS 1.3.1
Correct raptor_print_statement declaration argument statement to have
one less 'const', to match the code.
.SS 1.3.0
Added the following parser methods, utility methods and helper functions:
.LP
\fBraptor_new_parser_for_content (Parser class constructor)\fR
.br
\fBraptor_get_mime_type\fR
.br
\fBraptor_get_feature\fR
.br
\fBraptor_syntax_name_check\fR
.br
\fBraptor_guess_parser_name\fR
.br
\fBraptor_features_enumerate\fR
.br
\fBraptor_feature_from_uri\fR
.br
\fBraptor_www_set_http_accept (WWW class)\fR
.LP
Changed \fBraptor_set_feature\fP to now return an int success or failure.
.LP
Added the following functions:
.br
\fBraptor_free_memory\fR
.br
\fBraptor_unicode_char_to_utf8\fR
.br
\fBraptor_utf8_to_unicode_char\fR
.br
\fBraptor_vsnprintf\fR
.LP
Added the raptor_sequence class, its constructor, destructor, methods
and helper functions.
.LP
Added the raptor_stringbuffer class and constructor, destructor and methods.
.LP
Deprecated \fBraptor_print_statement_detailed\fR always intended to
be internal.
.SS 1.2.0
Added \fBraptor_syntaxes_enumerate\fR to get full information
on syntax mime type and URIs as well as name and label.
.LP
N-Triples Plus parser renamed to Turtle (name turtle)
.SS 1.1.0
Added N-Triples Plus parser (name ntriples-plus)
.LP
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:
.LP
URI factory methods changed to all take/return unsigned char* for URI
strings:
.br
\fBraptor_new_uri_func\fR
.br
\fBraptor_new_uri_from_local_name_func\fR
.br
\fBraptor_new_uri_relative_to_base_func\fR
.br
\fBraptor_uri_as_string_func\fR
.br
\fBraptor_uri_as_counted_string_func\fR
.LP
Constructors and methods changed to take/return unsigned char* for
URI strings:
.br
\fBraptor_statement_part_as_counted_string\fR
.br
\fBraptor_statement_part_as_string\fR
.br
\fBraptor_new_uri\fR
.br
\fBraptor_new_uri_from_uri_local_name\fR
.br
\fBraptor_new_uri_relative_to_base\fR
.br
\fBraptor_uri_as_string\fR
.br
\fBraptor_uri_as_counted_string\fR
.br
\fBraptor_print_ntriples_string\fR
.LP
Changed to use unsigned char* for URI strings, char* for filenames:
.br
\fBraptor_uri_resolve_uri_reference\fR
.br
\fBraptor_uri_filename_to_uri_string\fR
.br
\fBraptor_uri_uri_string_to_filename\fR
.br
\fBraptor_uri_uri_string_to_filename_fragment\fR
.br
\fBraptor_uri_is_file_uri\fR
.LP
Changed to return unsigned char* for UTF8 string:
.br
\fBraptor_ntriples_string_as_utf8_string\fR
.LP
Added \fBraptor_parsers_enumerate\fR to discover supported parsers.
.LP
Added \fBraptor_uri_uri_string_to_filename_fragment\fR with fragment arg to
return the URI fragment.
.LP
Made the raptor_namespace, raptor_namespace_stack and raptor_qname
class and APIs public.
.LP
Added feature non_nfc_fatal (see raptor_set_feature documentation).
.SS 1.0.0
Removed the following deprecated methods and functions (see 0.9.6
changes for the new names):
.br
\fBraptor_free\fR, \fBraptor_new\fR, \fBraptor_ntriples_free\fR,
\fBraptor_ntriples_new\fR, \fBraptor_ntriples_parse_file\fR,
\fBraptor_ntriples_set_error_handler\fR,
\fBraptor_ntriples_set_fatal_error_handler\fR,
\fBraptor_ntriples_set_statement_handler\fR and \fBraptor_parser_abort\fR.
.LP
Added \fBraptor_parse_file_stream\fR
for reading FILE* streams without necessarily having a file.
.SS 0.9.12
Added \fBraptor_new_uri_for_retrieval\fR
to turn URI references into URIs suitable for retrieval (no fragments).
.SS 0.9.11
Added \fBraptor_get_name\fR and \fBraptor_get_label\fR.
.LP
\fBraptor_xml_escape_string\fR now takes error message handler, data
pointer, loses parser argument.
.LP
Added \fBraptor_set_default_generate_id_parameters\fR and
\fBraptor_set_generate_id_handler\fR to control the default
generation of IDs, allow full customisation.
.SS 0.9.10
Added \fBraptor_set_parser_strict\fR
and \fBraptor_www_no_www_library_init_finish\fR.
.LP
\fBraptor_xml_escape_string\fR now takes an output string length pointer.
.LP
Added \fBraptor_statement_part_as_counted_string\fR,
\fBraptor_statement_part_as_string and \fBraptor_parse_abort\fR.
.LP
Deprecated \fBraptor_parser_abort\fR.
.SS 0.9.9
Added raptor_www class and all its constructors, destructor, methods, calls.
.LP
Added \fBraptor_parse_uri\fR, \fBraptor_parser_abort\fR, \fBraptor_ntriples_term_as_string\fR and \fBraptor_xml_escape_string\fR.
.SS 0.9.7
\fBraptor_parse_chunk, \fBraptor_new_uri_from_id\fR, arguments are now unsigned char.
.LP
Added \fBraptor_new_uri_for_xmlbase\fR.
.SS 0.9.6
In this version, the raptor/ntriples parser calling APIs were
modified. The following table lists the changes:
.ta \w'raptor_ntriples_set_fatal_error_handler 'u+\n(Spu
.LP
\fIOLD API NEW API (0.9.6+)\fR
.br
\fBraptor_new()\fR \fBraptor_new_parser("rdfxml")\fR
.br
\fBntriples_new()\fR \fBraptor_new_parser("ntriples")\fR
.br
\fBraptor_free\fR \fBraptor_free_parser\fR
.br
\fBntriples_free\fR \fBraptor_ntriples_parser\fR
.br
\fBraptor_ntriples_parse_file\fR \fBraptor_parse_file\fR
.br
\fBraptor_ntriples_set_error_handler\fR \fBraptor_set_error_handler\fR
.br
\fBraptor_ntriples_set_fatal_error_handler\fR \fBraptor_set_fatal_error_handler\fR
.br
\fBraptor_ntriples_set_statement_handler\fR \fBraptor_set_statement_handler\fR
.br
.SH "CONFORMING TO"
\fIRDF/XML Syntax (Revised)\fR, Dave Beckett (ed.)
W3C Recommendation,
.UR http://www.w3.org/TR/rdf-syntax-grammar/
http://www.w3.org/TR/rdf-syntax-grammar/
.UE
\fIN-Triples\fR, in \fIRDF Test Cases\fR, Jan Grant and Dave Beckett (eds.)
W3C Recommendation,
.UR http://www.w3.org/TR/rdf-testcases/#ntriples
http://www.w3.org/TR/rdf-testcases/#ntriples
.UE
\fITurtle - Terse RDF Triple Language\fR, Dave Beckett,
.UR http://www.dajobe.org/2004/01/turtle/
http://www.dajobe.org/2004/01/turtle/
.UE
\fIRSS 0.91 spec revision 3\fP, Dan Libby, Netscape,
.UR http://my.netscape.com/publish/formats/rss-spec-0.91.html
http://my.netscape.com/publish/formats/rss-spec-0.91.html
.UE
\fIRDF Site Summary (RSS) 1.0\fP,
.UR http://purl.org/rss/1.0/spec
http://purl.org/rss/1.0/spec
.UE
\fIAtom 1.0 syndication format\fP,
RFC 4287,
.UR http://www.ietf.org/rfc/rfc4287.txt
http://www.ietf.org/rfc/rfc4287.txt
.UE
.SH SEE ALSO
.BR rapper(1), raptor-config(1)
.SH AUTHOR
Dave Beckett -
.UR http://purl.org/net/dajobe/
http://purl.org/net/dajobe/
.UE