Serializer

## Serializer Serializer — RDF serializers - from RDF triples to a syntax |

## Synopsis

    typedef             raptor_serializer;
    raptor_serializer*  raptor_new_serializer               (const char *name);
    void                raptor_free_serializer              (raptor_serializer *rdf_serializer);
    int                 raptor_serialize_start              (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             raptor_iostream *iostream);
    int                 raptor_serialize_start_to_iostream  (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             raptor_iostream *iostream);
    int                 raptor_serialize_start_to_filename  (raptor_serializer *rdf_serializer,
                                                             const char *filename);
    int                 raptor_serialize_start_to_string    (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             void **string_p,
                                                             size_t *length_p);
    int                 raptor_serialize_start_to_file_handle
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             FILE *fh);
    int                 raptor_serialize_set_namespace      (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             unsigned char *prefix);
    int                 raptor_serialize_set_namespace_from_namespace
                                                            (raptor_serializer *rdf_serializer,
                                                             raptor_namespace *nspace);
    int                 raptor_serialize_statement          (raptor_serializer *rdf_serializer,
                                                             const raptor_statement *statement);
    int                 raptor_serialize_end                (raptor_serializer *rdf_serializer);
    raptor_iostream*    raptor_serializer_get_iostream      (raptor_serializer *serializer);
    void                raptor_serializer_set_error_handler (raptor_serializer *serializer,
                                                             void *user_data,
                                                             raptor_message_handler handler);
    void                raptor_serializer_set_warning_handler
                                                            (raptor_serializer *serializer,
                                                             void *user_data,
                                                             raptor_message_handler handler);
    raptor_locator*     raptor_serializer_get_locator       (raptor_serializer *rdf_serializer);
    int                 raptor_serializer_features_enumerate
                                                            (const raptor_feature feature,
                                                             const char **name,
                                                             raptor_uri **uri,
                                                             const char **label);
    int                 raptor_serializer_set_feature       (raptor_serializer *serializer,
                                                             raptor_feature feature,
                                                             int value);
    int                 raptor_serializer_set_feature_string
                                                            (raptor_serializer *serializer,
                                                             raptor_feature feature,
                                                             unsigned char *value);
    int                 raptor_serializer_get_feature       (raptor_serializer *serializer,
                                                             raptor_feature feature);
    const unsigned char * raptor_serializer_get_feature_string
                                                            (raptor_serializer *serializer,
                                                             raptor_feature feature);
    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               (const char *name);

Constructor - create a new raptor_serializer object.

`raptor_init()` MUST have been called before calling this function. Use `raptor_new_serializer_v2()` if using raptor_world APIs.

`name` : | the serializer name
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_serialize_start ()

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

Start serialization with given base URI

The passed in `iostream` becomes owned by the serializer and will be destroyed when the serializing is complete. Compare to `raptor_serialize_start_to_iostream()`. This function will be deprecated for `raptor_serialize_start_to_iostream()` in future.

`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_serialize_start_to_iostream ()

    int                 raptor_serialize_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 becomes owned by the serializer and can be used by the caller after serializing is done. It must be destroyed by the caller. Compare to `raptor_serialize_start()` which will be deprecated in future.

`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_serialize_start_to_filename ()

    int                 raptor_serialize_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_serialize_start_to_string ()

    int                 raptor_serialize_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_serialize_start_to_file_handle ()

    int                 raptor_serialize_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_serialize_set_namespace ()

    int                 raptor_serialize_set_namespace      (raptor_serializer *rdf_serializer,
                                                             raptor_uri *uri,
                                                             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_serialize_set_namespace_from_namespace ()

    int                 raptor_serialize_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_serialize_statement ()

    int                 raptor_serialize_statement          (raptor_serializer *rdf_serializer,
                                                             const 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_serialize_end ()

    int                 raptor_serialize_end                (raptor_serializer *rdf_serializer);

End a serialization.

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

### 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_set_error_handler ()

    void                raptor_serializer_set_error_handler (raptor_serializer *serializer,
                                                             void *user_data,
                                                             raptor_message_handler handler);

Set the serializer error handling function.

The function will receive callbacks when the serializer fails.

`serializer` : | the serializer
`user_data` : | user data to pass to function
`handler` : | pointer to the function

### raptor_serializer_set_warning_handler ()

    void                raptor_serializer_set_warning_handler
                                                            (raptor_serializer *serializer,
                                                             void *user_data,
                                                             raptor_message_handler handler);

Set the serializer warning handling function.

The function will receive callbacks when the serializer fails.

`serializer` : | the serializer
`user_data` : | user data to pass to function
`handler` : | pointer to the function

### 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_features_enumerate ()

    int                 raptor_serializer_features_enumerate
                                                            (const raptor_feature feature,
                                                             const char **name,
                                                             raptor_uri **uri,
                                                             const char **label);

Get list of serializer features.

If uri is not NULL, a pointer toa new raptor_uri is returned that must be freed by the caller with `raptor_free_uri()`.

`raptor_init()` MUST have been called before calling this function. Use `raptor_serializer_features_enumerate_v2()` if using raptor_world APIs.

`feature` : | feature enumeration (0+)
`name` : | pointer to store feature short name (or NULL)
`uri` : | pointer to store feature URI (or NULL)
`label` : | pointer to feature label (or NULL)
Returns : | 0 on success, <0 on failure, >0 if feature is unknown

### raptor_serializer_set_feature ()

    int                 raptor_serializer_set_feature       (raptor_serializer *serializer,
                                                             raptor_feature feature,
                                                             int value);

Set serializer features with integer values.

The allowed features are available via `raptor_features_enumerate()`.

`serializer` : | raptor_serializer serializer object
`feature` : | feature to set from enumerated raptor_feature values
`value` : | integer feature value (0 or larger)
Returns : | non 0 on failure or if the feature is unknown

### raptor_serializer_set_feature_string ()

    int                 raptor_serializer_set_feature_string
                                                            (raptor_serializer *serializer,
                                                             raptor_feature feature,
                                                             unsigned char *value);

Set serializer features with string values.

The allowed features are available via `raptor_serializer_features_enumerate()`. If the feature type is integer, the value is interpreted as an integer.

`serializer` : | raptor_serializer serializer object
`feature` : | feature to set from enumerated raptor_feature values
`value` : | feature value
Returns : | non 0 on failure or if the feature is unknown

### raptor_serializer_get_feature ()

    int                 raptor_serializer_get_feature       (raptor_serializer *serializer,
                                                             raptor_feature feature);

Get various serializer features.

The allowed features are available via `raptor_features_enumerate()`.

Note: no feature value is negative

`serializer` : | raptor_serializer serializer object
`feature` : | feature to get value
Returns : | feature value or < 0 for an illegal feature

### raptor_serializer_get_feature_string ()

    const unsigned char * raptor_serializer_get_feature_string
                                                            (raptor_serializer *serializer,
                                                             raptor_feature feature);

Get serializer features with string values.

The allowed features are available via `raptor_features_enumerate()`.

`serializer` : | raptor_serializer serializer object
`feature` : | feature to get value
Returns : | feature value or NULL for an illegal feature or no value

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