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.

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

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);

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);

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.

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 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 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 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);

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);

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. 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>

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) */

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.

To tidy up, delete the serializer object as follows: raptor_free_serializer(rdf_serializer);

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> ...