# 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("rdfxml");

or the name can be discovered from an enumeration as discussed in Querying Functionality

## Serializer features

There are several options that can be set on serializers, called features. The exact list of features can be found via Querying Functionality or in the API reference for `raptor_serializer_set_feature()`.

Features are integer enumerations of the raptor_feature enum and have values that are either integers (often acting as booleans) or strings. The two functions that set features are:

      /* Set an integer (or boolean) valued feature */
      raptor_serializer_set_feature(rdf_serializer, feature, 1);

      /* Set a string valued feature */
      raptor_serializer_set_feature_string(rdf_serializer, feature, "abc");

There are also two corresponding functions for reading the values of serializer features: `raptor_serializer_get_feature()` and `raptor_serializer_get_feature_string()` taken the feature enumeration parameter and returning the integer or string value correspondingly.

## 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_serialize_set_namespace()` using a prefix and URI argument pair like this:

      const unsigned char* prefix="ex";
      raptor_uri* uri=raptor_new_uri("http://example.org");

      raptor_serialize_set_namespace(rdf_serializer, prefix, uri);

or `raptor_serialize_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_set_namespace_handler()`

like this:

      static void
      relay_namespaces(void* user_data, raptor_namespace *nspace)
      {
        raptor_serialize_set_namespace_from_namespace(rdf_serializer, nspace);
      }

      rdf_parser=raptor_new_parser(syntax_name);
      raptor_set_namespace_handler(rdf_parser, rdf_serializer, relay_namespaces);

## Set error and warning handlers

There are several other callback handlers that can be set on serializers. These can be set any time before serializing is started. Errors and warnings from serializing can be returned with functions that all take a callback of type raptor_message_handler and signature:

    void
    message_handler(void *user_data, raptor_locator* locator,
                    const char *message)
    {
      /* do something with the message */
    }

returning the user data given, associated location information as a raptor_locator and the error/warning message itself. The locator structure contains full information on the details of where in the serialized file or URI the message occurred.

The fatal error, error and warning handlers are all set with similar functions that take a handler as follows:

      raptor_serializer_set_error_handler(rdf_serializer, user_data, error_handler);

      raptor_serializer_set_warning_handler(rdf_serializer, user_data, warning_handler);

## 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 (`raptor_serialize_start_to_filename()`)

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_serialize_start_to_filename(rdf_serializer, filename);

### Serialize to a string (`raptor_serialize_start_to_string()`)

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_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("http://example.org/base");
      void *string;  /* destination for string */
      size_t length; /* length of constructed string */

      raptor_serialize_start_to_string(rdf_serializer, uri,
                                       &string, &length);

### Serialize to a FILE* file handle (`raptor_serialize_start_to_file_handle()`)

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("http://example.org/base");
      FILE* fh=fopen("raptor.rdf", "wb");
      raptor_serialize_start_to_file_handle(rdf_serializer, uri, fh);

### Serialize to an raptor_iostream (`raptor_serialize_start_to_iostream()`)

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_serialize_end()`) is called).

      raptor_uri* uri=raptor_new_uri("http://example.org/base");
      raptor_iostream* iostream = /* iostream initialized by some means */ ;

      raptor_serialize_start_to_iostream(rdf_serializer, uri, iostream);

      while( /* got RDF triples */ ) {
        raptor_statement* triple = /* ... triple made from somewhere ... */ ;
        raptor_serialize_statement(rdf_serializer,  triple);
      }
      raptor_serialize_end(rdf_serializer);

      raptor_free_serializer(rdf_serializer);

      /* ... write other stuff to iostream ... */

      raptor_free_iostream(iostream);

### Serialize to an raptor_iostream and close iostream (`raptor_serialize_start()`)

`raptor_serialize_start()` also serializes to an iostream like `raptor_serialize_start_to_iostream()` but it becomes the owner of the passed in raptor_iostream and destroys it at the end of serializing, so no further use of the iostream can be made by the caller.

## Get or construct RDF Triples

An raptor_statement 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 triple has three parts. 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 triple part types are set as fields named like `subject_type` for describing field `subject`. So to initialise the subject of the triple, set the field `statement.subject` to point to a previously allocated raptor_uri* object (for URI) or `char*` (for blank node) and set `statement.subject_type` to `RAPTOR_IDENTIFIER_TYPE_RESOURCE` or `RAPTOR_IDENTIFIER_TYPE_ANONYMOUS` respectively. Triple predicates are always of type `RAPTOR_IDENTIFIER_TYPE_RESOURCE`. Triple objects are all all types given above and also `RAPTOR_IDENTIFIER_TYPE_LITERAL` which takes an `unsigned char*` pointer plus an optional language `char*` pointer in the `object_literal_language` field OR a a `raptor_uri*` literal datatype pointer in the `object_literal_datatype` field. The triple part types are described under raptor_identifier_type.

### `rdfserialize.c`: Serialize 1 triple to RDF/XML (Abbreviated)

Compile it like this:

    $ gcc -o rdfserialize rdfserialize.c `raptor-config --cflags` `raptor-config --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_serialize_statement()` function with a raptor_statement value.

Once all triples are sent, the serializing must be finished with a call to `raptor_serialize_end()`. In particular, only at this point does the raptor_iostream get flushed or any string constructed for `raptor_serialize_start_to_string()`.

      /* start the serializing somehow */
      while( /* got RDF triples */ ) {
        raptor_serialize_statement(rdf_serializer, triple);
      }
      raptor_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

### `rdfcat.c`: Read any RDF syntax and serialize to RDF/XML (Abbreviated)

Compile it like this:

    $ gcc -o rdfcat rdfcat.c `raptor-config --cflags` `raptor-config --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>
    ...