## Serializer

Serializer — RDF serializers - from RDF triples to a syntax

## Synopsis

    typedef             raptor_serializer;
    raptor_serializer *  raptor_new_serializer              (raptor_world *world,
                                                             const char *name);
    void                raptor_free_serializer              (raptor_serializer *rdf_serializer);
    int                 raptor_serializer_start_to_iostream (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             raptor_iostream *iostream);
    int                 raptor_serializer_start_to_filename (raptor_serializer *rdf_serializer,
                                                             const char *filename);
    int                 raptor_serializer_start_to_string   (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             void **string_p,
                                                             size_t *length_p);
    int                 raptor_serializer_start_to_file_handle
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             FILE *fh);
    int                 raptor_serializer_set_namespace     (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             const unsigned char *prefix);
    int                 raptor_serializer_set_namespace_from_namespace
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_namespace *nspace);
    int                 raptor_serializer_serialize_statement
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_statement *statement);
    int                 raptor_serializer_serialize_end     (raptor_serializer *rdf_serializer);
    int                 raptor_serializer_flush             (raptor_serializer *rdf_serializer);
    const raptor_syntax_description *  raptor_serializer_get_description
                                                            (raptor_serializer *rdf_serializer);
    raptor_iostream *   raptor_serializer_get_iostream      (raptor_serializer *serializer);
    raptor_locator *    raptor_serializer_get_locator       (raptor_serializer *rdf_serializer);
    int                 raptor_serializer_set_option        (raptor_serializer *serializer,
                                                             raptor_option option,
                                                             const char *string,
                                                             int integer);
    int                 raptor_serializer_get_option        (raptor_serializer *serializer,
                                                             raptor_option option,
                                                             char **string_p,
                                                             int *integer_p);
    raptor_world *      raptor_serializer_get_world         (raptor_serializer *rdf_serializer);

## Description

The serializing class that allows creating a serializer for writing a particular syntax to an output string, file, file handle or user function (via raptor_iostream).

There are also methods to deal with handling errors, warnings and returned triples as well as setting options (features) that can adjust how serializing is performed.

## Details

### raptor_serializer

    raptor_serializer* raptor_serializer;

Raptor Serializer class

### raptor_new_serializer ()

    raptor_serializer *  raptor_new_serializer              (raptor_world *world,
                                                             const char *name);

Constructor - create a new raptor_serializer object.

`world` : | raptor_world object
`name` : | the serializer name or NULL for default syntax
Returns : | a new raptor_serializer object or NULL on failure

### raptor_free_serializer ()

    void                raptor_free_serializer              (raptor_serializer *rdf_serializer);

Destructor - destroy a raptor_serializer object.

`rdf_serializer` : | raptor_serializer object

### raptor_serializer_start_to_iostream ()

    int                 raptor_serializer_start_to_iostream (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             raptor_iostream *iostream);

Start serialization to an iostream with given base URI

The passed in `iostream` does not become owned by the serializer and can be used by the caller after serializing is done. It must be destroyed by the caller.

`rdf_serializer` : | the raptor_serializer
`uri` : | base URI or NULL if no base URI is required
`iostream` : | raptor_iostream to write serialization to
Returns : | non-0 on failure.

### raptor_serializer_start_to_filename ()

    int                 raptor_serializer_start_to_filename (raptor_serializer *rdf_serializer,
                                                             const char *filename);

Start serializing to a filename.

`rdf_serializer` : | the raptor_serializer
`filename` : | filename to serialize to
Returns : | non-0 on failure.

### raptor_serializer_start_to_string ()

    int                 raptor_serializer_start_to_string   (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             void **string_p,
                                                             size_t *length_p);

Start serializing to a string.

`rdf_serializer` : | the raptor_serializer
`uri` : | base URI or NULL if no base URI is required
`string_p` : | pointer to location to hold string
`length_p` : | pointer to location to hold length of string (or NULL)
Returns : | non-0 on failure.

### raptor_serializer_start_to_file_handle ()

    int                 raptor_serializer_start_to_file_handle
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             FILE *fh);

Start serializing to a FILE*.

NOTE: This does not fclose the handle when it is finished.

`rdf_serializer` : | the raptor_serializer
`uri` : | base URI or NULL if no base URI is required
`fh` : | FILE* to serialize to
Returns : | non-0 on failure.

### raptor_serializer_set_namespace ()

    int                 raptor_serializer_set_namespace     (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             const unsigned char *prefix);

set a namespace uri/prefix mapping for serializing.

`rdf_serializer` : | the raptor_serializer
`uri` : | raptor_uri of namespace or NULL
`prefix` : | prefix to use or NULL
Returns : | non-0 on failure.

### raptor_serializer_set_namespace_from_namespace ()

    int                 raptor_serializer_set_namespace_from_namespace
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_namespace *nspace);

Set a namespace uri/prefix mapping for serializing from an existing namespace.

`rdf_serializer` : | the raptor_serializer
`nspace` : | raptor_namespace to set
Returns : | non-0 on failure.

### raptor_serializer_serialize_statement ()

    int                 raptor_serializer_serialize_statement
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_statement *statement);

Serialize a statement.

`rdf_serializer` : | the raptor_serializer
`statement` : | raptor_statement to serialize to a syntax
Returns : | non-0 on failure.

### raptor_serializer_serialize_end ()

    int                 raptor_serializer_serialize_end     (raptor_serializer *rdf_serializer);

End a serialization.

`rdf_serializer` : | the raptor_serializer
Returns : | non-0 on failure.

### raptor_serializer_flush ()

    int                 raptor_serializer_flush             (raptor_serializer *rdf_serializer);

Flush the current serializer output and free any pending state

In serializers that can generate blocks of content, this causes the writing of any current pending block. For example in Turtle this may write all pending triples.

`rdf_serializer` : | raptor serializer
Returns : | non-0 on failure

### raptor_serializer_get_description ()

    const raptor_syntax_description *  raptor_serializer_get_description
                                                            (raptor_serializer *rdf_serializer);

Get description of the syntaxes of the serializer.

The returned description is static and lives as long as the raptor library (raptor world).

`rdf_serializer` : | raptor_serializer serializer object
Returns : | description of syntax

### raptor_serializer_get_iostream ()

    raptor_iostream *   raptor_serializer_get_iostream      (raptor_serializer *serializer);

Get the current serializer iostream.

`serializer` : | raptor_serializer object
Returns : | the serializer's current iostream or NULL if

### raptor_serializer_get_locator ()

    raptor_locator *    raptor_serializer_get_locator       (raptor_serializer *rdf_serializer);

Get the serializer raptor locator object.

`rdf_serializer` : | raptor serializer
Returns : | raptor locator

### raptor_serializer_set_option ()

    int                 raptor_serializer_set_option        (raptor_serializer *serializer,
                                                             raptor_option option,
                                                             const char *string,
                                                             int integer);

Set serializer option.

If `string` is not NULL and the option type is numeric, the string value is converted to an integer and used in preference to `integer`.

If `string` is NULL and the option type is not numeric, an error is returned.

The `string` values used are copied.

The allowed options are available via `raptor_world_get_option_description()`.

`serializer` : | raptor_serializer serializer object
`option` : | option to set from enumerated raptor_option values
`string` : | string option value (or NULL)
`integer` : | integer option value
Returns : | non 0 on failure or if the option is unknown

### raptor_serializer_get_option ()

    int                 raptor_serializer_get_option        (raptor_serializer *serializer,
                                                             raptor_option option,
                                                             char **string_p,
                                                             int *integer_p);

Get serializer option.

Any string value returned in *`string_p` is shared and must be copied by the caller.

The allowed options are available via `raptor_world_get_option_description()`.

`serializer` : | raptor_serializer serializer object
`option` : | option to get value
`string_p` : | pointer to where to store string value
`integer_p` : | pointer to where to store integer value
Returns : | option value or < 0 for an illegal option

### raptor_serializer_get_world ()

    raptor_world *      raptor_serializer_get_world         (raptor_serializer *rdf_serializer);

Get the raptor_world object associated with a serializer.

`rdf_serializer` : | raptor serializer
Returns : | raptor_world* pointer