summaryrefslogtreecommitdiffstats
path: root/docs/raptor-tutorial-serializing.xml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 05:40:05 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 05:40:05 +0000
commit4038ab95a094b363f1748f3dcb51511a1217475d (patch)
tree7f393d66a783f91ddd263c78d681e485cf4f45ca /docs/raptor-tutorial-serializing.xml
parentInitial commit. (diff)
downloadraptor2-4038ab95a094b363f1748f3dcb51511a1217475d.tar.xz
raptor2-4038ab95a094b363f1748f3dcb51511a1217475d.zip
Adding upstream version 2.0.16.upstream/2.0.16upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/raptor-tutorial-serializing.xml')
-rw-r--r--docs/raptor-tutorial-serializing.xml402
1 files changed, 402 insertions, 0 deletions
diff --git a/docs/raptor-tutorial-serializing.xml b/docs/raptor-tutorial-serializing.xml
new file mode 100644
index 0000000..f27b7f5
--- /dev/null
+++ b/docs/raptor-tutorial-serializing.xml
@@ -0,0 +1,402 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<chapter id="tutorial-serializing" xmlns:xi="http://www.w3.org/2003/XInclude">
+<title>Serializing RDF triples to a syntax</title>
+
+<section id="tutorial-serializing-intro">
+<title>Introduction</title>
+
+<para>
+The typical sequence of operations to serialize is to create a
+serializer object, set various callback and features, start the
+serializing, send some RDF triples to the serializer object,
+finish the serializing and destroy the serializer object.
+</para>
+
+</section>
+
+
+<section id="tutorial-serializer-create">
+<title>Create the Serializer object</title>
+
+<para>The serializer can be created directly from a known name using
+<link linkend="raptor-new-serializer"><function>raptor_new_serializer()</function></link>
+such as <literal>rdfxml</literal> for the W3C Recommendation RDF/XML syntax:
+<programlisting>
+ raptor_serializer* rdf_serializer;
+
+ rdf_serializer = raptor_new_serializer(world, "rdfxml");
+</programlisting>
+or the name can be discovered from an <emphasis>description</emphasis>
+as discussed in
+<link linkend="tutorial-querying-functionality">Querying Functionality</link>
+</para>
+</section>
+
+
+<section id="tutorial-serializer-features">
+<title>Serializer options</title>
+
+<para>There are several options that can be set on serializers.
+The exact list of options can be found at run time via the
+<link linkend="tutorial-querying-functionality">Querying Functionality</link>
+or in the API reference for
+<link linkend="raptor-option"><literal>raptor_option</literal></link>.
+</para>
+
+<para>Options are integer enumerations of the
+<link linkend="raptor-option"><type>raptor_option</type></link> enum and have
+values that are either booleans, integers or strings.
+The function that sets options for serializers is:
+<link linkend="raptor-serializer-set-option">raptor_serializer_set_option()</link>
+used as follows:
+<programlisting>
+ /* Set a boolean or integer valued option to value 1 */
+ raptor_serializer_set_option(rdf_serializer, option, NULL, 1);
+
+ /* Set a string valued option to value "abc" */
+ raptor_serializer_set_option(rdf_serializer, option, "abc", -1);
+</programlisting>
+</para>
+
+<para>
+There is a corresponding function for reading the values of serializer
+option
+<link linkend="raptor-serializer-get-option"><function>raptor_serializer_get_option()</function></link>
+which takes the option enumeration parameter and returns the boolean /
+integer or string value correspondingly into the appropriate pointer
+argument.
+<programlisting>
+ /* Get a boolean or integer option value */
+ int int_var;
+ raptor_serializer_get_option(rdf_serializer, option, NULL, &amp;int_var);
+
+ /* Get a string option value */
+ char* string_var;
+ raptor_serializer_get_option(rdf_serializer, option, &amp;string_var, NULL);
+</programlisting>
+</para>
+
+</section>
+
+
+<section id="tutorial-serializer-declare-namespace">
+<title>Declare namespaces</title>
+
+<para>Raptor can use namespace prefix/URIs to abbreviate syntax
+in some syntaxes such as Turtle or any XML syntax including RDF/XML,
+RSS1.0 and Atom 1.0. These are declared
+with <link linkend="raptor-serializer-set-namespace"><function>raptor_serializer_set_namespace()</function></link>
+using a prefix and URI argument pair like this:
+<programlisting>
+ const unsigned char* prefix = "ex";
+ raptor_uri* uri = raptor_new_uri(world, "http://example.org");
+
+ raptor_serializer_set_namespace(rdf_serializer, prefix, uri);
+</programlisting>
+</para>
+
+<para>or
+<link linkend="raptor-serializer-set-namespace-from-namespace"><function>raptor_serializer_set_namespace_from_namespace()</function></link>
+from an existing namespace. This can be useful when connected up the
+the namespace declarations that are generated from a parser via a
+namespace handler set with
+<link linkend="raptor-parser-set-namespace-handler"><function>raptor_parser_set_namespace_handler()</function></link>
+</para>
+like this:
+<programlisting>
+ static void
+ relay_namespaces(void* user_data, raptor_namespace *nspace)
+ {
+ raptor_serializer_set_namespace_from_namespace(rdf_serializer, nspace);
+ }
+
+ ...
+
+ rdf_parser = raptor_new_parser(world, syntax_name);
+ raptor_parser_set_namespace_handler(rdf_parser, rdf_serializer, relay_namespaces);
+</programlisting>
+
+</section>
+
+
+<section id="tutorial-serializer-set-error-warning-handlers">
+<title>Set error and warning handlers</title>
+
+<para>Any time before serializing is started, a log handler can be set
+on the world object via the
+<link linkend="raptor-world-set-log-handler"><function>raptor_world_set_log_handler()</function></link>
+method to report errors and warnings from parsing.
+The method takes a user data argument plus a handler callback of type
+<link linkend="raptor-log-handler"><type>raptor_log_handler</type></link>
+with a signature that looks like this:
+<programlisting>
+void
+message_handler(void *user_data, raptor_log_message* message)
+{
+ /* do something with the message */
+}
+</programlisting>
+The handler gets the user data pointer as well as a
+<link linkend="raptor-log-message"><type>raptor_log_handler</type></link>
+pointer that includes associated location information, such as the
+log level,
+<link linkend="raptor-locator"><type>raptor_locator</type></link>,
+and the log message itself. The <emphasis>locator</emphasis>
+structure contains full information on the details of where in the
+file or URI the message occurred.
+</para>
+
+</section>
+
+
+<section id="tutorial-serializer-to-destination">
+<title>Provide a destination for the serialized syntax</title>
+
+<para>The operation of turning RDF triples into a syntax has several
+alternatives from functions that do most of the work writing to a file
+or string to functions that allow passing in a
+<link linkend="raptor-iostream"><type>raptor_iostream</type></link>
+which can be entirely user-constructed.</para>
+
+<section id="serialize-to-filename">
+<title>Serialize to a filename (<link linkend="raptor-serializer-start-to-filename"><function>raptor_serializer_start_to_filename()</function></link>)</title>
+
+<para>Serialize to a new filename
+(using <link linkend="raptor-new-iostream-to-filename"><function>raptor_new_iostream_to_filename()</function></link> internally)
+and uses asf base URI, the file's URI.
+<programlisting>
+ const char *filename = "raptor.rdf";
+ raptor_serializer_start_to_filename(rdf_serializer, filename);
+</programlisting>
+</para>
+</section>
+
+<section id="serialize-to-string">
+<title>Serialize to a string (<link linkend="raptor-serializer-start-to-string"><function>raptor_serializer_start_to_string()</function></link>)</title>
+
+<para>Serialize to a string that is allocated by the serializer
+(using <link linkend="raptor-new-iostream-to-string"><function>raptor_new_iostream_to_string()</function></link> internally). The
+resulting string is only constructed after <link linkend="raptor-serializer-serialize-end"><function>raptor_serializer_serialize_end()</function></link> is called and at that
+point it is assigned to the string pointer passed in, with the length
+written to the optional length pointer. This function
+takes an optional base URI but may be required by some serializers.
+<programlisting>
+ raptor_uri* uri = raptor_new_uri(world, "http://example.org/base");
+ void *string; /* destination for string */
+ size_t length; /* length of constructed string */
+ raptor_serializer* rdf_serializer = /* serializer created by some means */ ;
+
+ raptor_serializer_start_to_string(rdf_serializer, uri,
+ &amp;string, &amp;length);
+</programlisting>
+</para>
+
+</section>
+
+
+<section id="serialize-to-filehandle">
+<title>Serialize to a FILE* file handle (<link linkend="raptor-serializer-start-to-file-handle"><function>raptor_serializer_start_to_file_handle()</function></link>)</title>
+
+<para>Serialize to an existing open C FILE* file handle
+(using <link linkend="raptor-new-iostream-to-file-handle"><function>raptor_new_iostream_to_file_handle()</function></link> internally). The handle is not closed after serializing is finished. This function
+takes an optional base URI but may be required by some serializers.
+<programlisting>
+ raptor_uri* uri = raptor_new_uri(world, "http://example.org/base");
+ FILE* fh = fopen("raptor.rdf", "wb");
+ raptor_serializer* rdf_serializer = /* serializer created by some means */ ;
+
+ raptor_serializer_start_to_file_handle(rdf_serializer, uri, fh);
+</programlisting>
+</para>
+</section>
+
+<section id="serialize-to-iostream">
+<title>Serialize to an <link linkend="raptor-iostream"><type>raptor_iostream</type></link> (<link linkend="raptor-serializer-start-to-iostream"><function>raptor_serializer_start_to_iostream()</function></link>)</title>
+
+<para>This is the most flexible serializing method as it allows
+writing to any
+<link linkend="raptor-iostream"><type>raptor_iostream</type></link>
+which can be constructed to build any form of user-generated structure
+via callbacks. The iostream remains owned by the caller that can continue
+to write to it after the serializing is finished (after
+<link linkend="raptor-serializer-serialize-end"><function>raptor_serializer_serialize_end()</function></link>) is called).
+<programlisting>
+ raptor_uri* uri = raptor_new_uri(world, "http://example.org/base");
+ raptor_iostream* iostream = /* iostream initialized by some means */ ;
+ raptor_serializer* rdf_serializer = /* serializer created by some means */ ;
+
+ raptor_serializer_start_to_iostream(rdf_serializer, uri, iostream);
+
+ while( /* got RDF triples */ ) {
+ raptor_statement* triple = /* ... triple made from somewhere ... */ ;
+ raptor_serializer_serialize_statement(rdf_serializer, triple);
+ }
+ raptor_serializer_serialize_end(rdf_serializer);
+
+ raptor_free_serializer(rdf_serializer);
+
+ /* ... write other stuff to iostream ... */
+
+ raptor_free_iostream(iostream);
+</programlisting>
+</para>
+</section>
+
+
+</section>
+
+
+<section id="tutorial-serializer-get-triples">
+<title>Get or construct RDF Statements (Triples)</title>
+<para>
+An <link linkend="raptor-statement"><type>raptor_statement</type></link>
+containing the triple terms and optional graph term
+can be made either by receiving them from a
+<link linkend="raptor-parser"><type>raptor_parser</type></link>
+via parsing or can be constructed by hand.</para>
+
+<para>When constructing by hand,
+the <link linkend="raptor-statement"><type>raptor_statement</type></link>
+structure should be allocated by the application and the fields
+filled in. Each statement has three triple terms (subject,
+predicate, object) and an optional graph term. The subject can be a
+URI or blank node, the predicate can only be a URI and the object can
+be a URI, blank node or RDF literal. RDF literals can have either
+just a Unicode string, a Unicode string and a language or a Unicode
+string and a datatype URI.</para>
+
+<para>The statement terms are all instances of
+<link linkend="raptor-term"><type>raptor_term</type></link>
+objects constructed with the appropriate constructor for
+the URI, blank node or rdf literal types. The graph term
+of the statement is typically a URI or blank node.
+</para>
+
+<example id="raptor-example-rdfserialize">
+<title><filename>rdfserialize.c</filename>: Serialize 1 triple to RDF/XML (Abbreviated)</title>
+<programlisting>
+<xi:include href="rdfserialize.c" parse="text"/>
+</programlisting>
+
+<para>Compile it like this:
+<screen>
+$ gcc -o rdfserialize rdfserialize.c `pkg-config raptor2 --cflags --libs`
+</screen>
+and run it with an optional base URI argument
+<screen>
+$ ./rdfserialize
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"&gt;
+ &lt;rdf:Description rdf:about="http://example.org/subject"&gt;
+ &lt;ns0:predicate xmlns:ns0="http://example.org/" xml:lang="en"&gt;An example&lt;/ns0:predicate&gt;
+ &lt;/rdf:Description&gt;
+&lt;/rdf:RDF&gt;
+</screen>
+</para>
+
+</example>
+
+</section>
+
+<section id="tutorial-serializer-send-triples">
+<title>Send RDF Triples to serializer</title>
+
+<para>
+Once the serializer has been started, RDF triples can be sent to it
+via the
+<link linkend="raptor-serializer-serialize-statement"><function>raptor_serializer_serialize_statement()</function></link>
+function with a
+<link linkend="raptor-statement"><type>raptor_statement</type></link>
+value.
+</para>
+
+<para>Once all triples are sent, the serializing must be finished
+with a call to
+<link linkend="raptor-serializer-serialize-end"><function>raptor_serializer_serialize_end()</function></link>.
+In particular, only at this point does the
+<link linkend="raptor-iostream"><type>raptor_iostream</type></link>
+get flushed or any string constructed for
+<link linkend="raptor-serializer-start-to-string"><function>raptor_serializer_start_to_string()</function></link>.
+<programlisting>
+ /* start the serializing somehow */
+ while( /* got RDF triples */ ) {
+ raptor_serializer_serialize_statement(rdf_serializer, triple);
+ }
+ raptor_serializer_serialize_end(rdf_serializer);
+ /* now can use the serializing result (FILE, string, raptor_iostream) */
+</programlisting>
+
+</para>
+</section>
+
+
+<section id="tutorial-serializer-runtime-info">
+<title>Querying serializer run-time information</title>
+
+<para>
+<link linkend="raptor-serializer-get-iostream"><function>raptor_serializer_get_iostream()</function></link>
+gets the current serializer's raptor_iostream.
+</para>
+
+<para>
+<link linkend="raptor-serializer-get-locator"><function>raptor_serializer_get_locator()</function></link>
+returns the <link linkend="raptor-locator"><type>raptor_locator</type></link>
+for the current position in the output stream. The <emphasis>locator</emphasis>
+structure contains full information on the details of where in the
+file or URI the current serializer has reached.
+</para>
+</section>
+
+
+<section id="tutorial-serializer-destroy">
+<title>Destroy the serializer</title>
+
+<para>
+To tidy up, delete the serializer object as follows:
+<programlisting>
+ raptor_free_serializer(rdf_serializer);
+</programlisting>
+</para>
+
+</section>
+
+<section id="tutorial-serializer-example">
+<title>Serializing example code</title>
+
+<example id="raptor-example-rdfcat">
+<title><filename>rdfcat.c</filename>: Read any RDF syntax and serialize to RDF/XML (Abbreviated)</title>
+<programlisting>
+<xi:include href="rdfcat.c" parse="text"/>
+</programlisting>
+
+<para>Compile it like this:
+<screen>
+$ gcc -o rdfcat rdfcat.c `pkg-config raptor2 --cflags --libs`
+</screen>
+and run it on an RDF file as:
+<screen>
+$ ./rdfcat raptor.rdf
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;rdf:RDF xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://usefulinc.com/ns/doap#"&gt;
+ &lt;rdf:Description rdf:about=""&gt;
+ &lt;foaf:maker&gt;
+ &lt;foaf:Person&gt;
+ &lt;foaf:name&gt;Dave Beckett&lt;/foaf:name&gt;
+...
+</screen>
+</para>
+
+</example>
+
+</section>
+
+</chapter>
+
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("raptor-docs.xml" "book" "part")
+End:
+-->