From 4038ab95a094b363f1748f3dcb51511a1217475d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 07:40:05 +0200 Subject: Adding upstream version 2.0.16. Signed-off-by: Daniel Baumann --- docs/raptor-tutorial-serializing.xml | 402 +++++++++++++++++++++++++++++++++++ 1 file changed, 402 insertions(+) create mode 100644 docs/raptor-tutorial-serializing.xml (limited to 'docs/raptor-tutorial-serializing.xml') 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 @@ + + +Serializing RDF triples to a syntax + +
+Introduction + + +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. + + +
+ + +
+Create the Serializer object + +The serializer can be created directly from a known name using +raptor_new_serializer() +such as rdfxml for the W3C Recommendation RDF/XML syntax: + + raptor_serializer* rdf_serializer; + + rdf_serializer = raptor_new_serializer(world, "rdfxml"); + +or the name can be discovered from an description +as discussed in +Querying Functionality + +
+ + +
+Serializer options + +There are several options that can be set on serializers. +The exact list of options can be found at run time via the +Querying Functionality +or in the API reference for +raptor_option. + + +Options are integer enumerations of the +raptor_option enum and have +values that are either booleans, integers or strings. +The function that sets options for serializers is: +raptor_serializer_set_option() +used as follows: + + /* 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); + + + + +There is a corresponding function for reading the values of serializer +option +raptor_serializer_get_option() +which takes the option enumeration parameter and returns the boolean / +integer or string value correspondingly into the appropriate pointer +argument. + + /* Get a boolean or integer option value */ + int int_var; + raptor_serializer_get_option(rdf_serializer, option, NULL, &int_var); + + /* Get a string option value */ + char* string_var; + raptor_serializer_get_option(rdf_serializer, option, &string_var, NULL); + + + +
+ + +
+Declare namespaces + +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 raptor_serializer_set_namespace() +using a prefix and URI argument pair like this: + + const unsigned char* prefix = "ex"; + raptor_uri* uri = raptor_new_uri(world, "http://example.org"); + + raptor_serializer_set_namespace(rdf_serializer, prefix, uri); + + + +or +raptor_serializer_set_namespace_from_namespace() +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 +raptor_parser_set_namespace_handler() + +like this: + + 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); + + +
+ + +
+Set error and warning handlers + +Any time before serializing is started, a log handler can be set +on the world object via the +raptor_world_set_log_handler() +method to report errors and warnings from parsing. +The method takes a user data argument plus a handler callback of type +raptor_log_handler +with a signature that looks like this: + +void +message_handler(void *user_data, raptor_log_message* message) +{ + /* do something with the message */ +} + +The handler gets the user data pointer as well as a +raptor_log_handler +pointer that includes associated location information, such as the +log level, +raptor_locator, +and the log message itself. The locator +structure contains full information on the details of where in the +file or URI the message occurred. + + +
+ + +
+Provide a destination for the serialized syntax + +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 +raptor_iostream +which can be entirely user-constructed. + +
+Serialize to a filename (<link linkend="raptor-serializer-start-to-filename"><function>raptor_serializer_start_to_filename()</function></link>) + +Serialize to a new filename +(using raptor_new_iostream_to_filename() internally) +and uses asf base URI, the file's URI. + + const char *filename = "raptor.rdf"; + raptor_serializer_start_to_filename(rdf_serializer, filename); + + +
+ +
+Serialize to a string (<link linkend="raptor-serializer-start-to-string"><function>raptor_serializer_start_to_string()</function></link>) + +Serialize to a string that is allocated by the serializer +(using raptor_new_iostream_to_string() internally). The +resulting string is only constructed after raptor_serializer_serialize_end() 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. + + 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, + &string, &length); + + + +
+ + +
+Serialize to a FILE* file handle (<link linkend="raptor-serializer-start-to-file-handle"><function>raptor_serializer_start_to_file_handle()</function></link>) + +Serialize to an existing open C FILE* file handle +(using raptor_new_iostream_to_file_handle() internally). The handle is not closed after serializing is finished. This function +takes an optional base URI but may be required by some serializers. + + 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); + + +
+ +
+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>) + +This is the most flexible serializing method as it allows +writing to any +raptor_iostream +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 +raptor_serializer_serialize_end()) is called). + + 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); + + +
+ + +
+ + +
+Get or construct RDF Statements (Triples) + +An raptor_statement +containing the triple terms and optional graph term +can be made either by receiving them from a +raptor_parser +via parsing or can be constructed by hand. + +When constructing by hand, +the raptor_statement +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. + +The statement terms are all instances of +raptor_term +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. + + + +<filename>rdfserialize.c</filename>: Serialize 1 triple to RDF/XML (Abbreviated) + + + + +Compile it like this: + +$ gcc -o rdfserialize rdfserialize.c `pkg-config raptor2 --cflags --libs` + +and run it with an optional base URI argument + +$ ./rdfserialize +<?xml version="1.0" encoding="utf-8"?> +<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <rdf:Description rdf:about="http://example.org/subject"> + <ns0:predicate xmlns:ns0="http://example.org/" xml:lang="en">An example</ns0:predicate> + </rdf:Description> +</rdf:RDF> + + + + + +
+ +
+Send RDF Triples to serializer + + +Once the serializer has been started, RDF triples can be sent to it +via the +raptor_serializer_serialize_statement() +function with a +raptor_statement +value. + + +Once all triples are sent, the serializing must be finished +with a call to +raptor_serializer_serialize_end(). +In particular, only at this point does the +raptor_iostream +get flushed or any string constructed for +raptor_serializer_start_to_string(). + + /* 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) */ + + + +
+ + +
+Querying serializer run-time information + + +raptor_serializer_get_iostream() +gets the current serializer's raptor_iostream. + + + +raptor_serializer_get_locator() +returns the raptor_locator +for the current position in the output stream. The locator +structure contains full information on the details of where in the +file or URI the current serializer has reached. + +
+ + +
+Destroy the serializer + + +To tidy up, delete the serializer object as follows: + + raptor_free_serializer(rdf_serializer); + + + +
+ +
+Serializing example code + + +<filename>rdfcat.c</filename>: Read any RDF syntax and serialize to RDF/XML (Abbreviated) + + + + +Compile it like this: + +$ gcc -o rdfcat rdfcat.c `pkg-config raptor2 --cflags --libs` + +and run it on an RDF file as: + +$ ./rdfcat raptor.rdf +<?xml version="1.0" encoding="utf-8"?> +<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#"> + <rdf:Description rdf:about=""> + <foaf:maker> + <foaf:Person> + <foaf:name>Dave Beckett</foaf:name> +... + + + + + +
+ + + + + -- cgit v1.2.3