## Query Results Formatter

Query Results Formatter — Query results formatted into a syntax.

## Synopsis

    int                 rasqal_query_results_formats_check  (rasqal_world *world,
                                                             const char *name,
                                                             raptor_uri *uri,
                                                             const char *mime_type);
    #define             RASQAL_QUERY_RESULTS_FORMAT_FLAG_READER
    #define             RASQAL_QUERY_RESULTS_FORMAT_FLAG_WRITER
    int                 rasqal_query_results_formats_enumerate
                                                            (rasqal_world *world,
                                                             unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             unsigned char **uri_string,
                                                             const char **mime_type,
                                                             int *flags);
    typedef             rasqal_query_results_formatter;
    rasqal_query_results_formatter* rasqal_new_query_results_formatter
                                                            (rasqal_world *world,
                                                             const char *name,
                                                             raptor_uri *format_uri);
    rasqal_query_results_formatter* rasqal_new_query_results_formatter_by_mime_type
                                                            (rasqal_world *world,
                                                             const char *mime_type);
    void                rasqal_free_query_results_formatter (rasqal_query_results_formatter *formatter);
    const char*         rasqal_query_results_formatter_get_mime_type
                                                            (rasqal_query_results_formatter *formatter);
    int                 rasqal_query_results_formatter_read (rasqal_world *world,
                                                             raptor_iostream *iostr,
                                                             rasqal_query_results_formatter *formatter,
                                                             rasqal_query_results *results,
                                                             raptor_uri *base_uri);
    int                 rasqal_query_results_formatter_write
                                                            (raptor_iostream *iostr,
                                                             rasqal_query_results_formatter *formatter,
                                                             rasqal_query_results *results,
                                                             raptor_uri *base_uri);

## Description

Variable bindings and boolean query results can be formatted into different syntaxes such as SPARQL Query Results Format or JSON. The rasqal_query_results_formatter class allows choosing a formatter for a particular syntax and writing the syntax to a raptor_iostream which allows turning the syntax into a string, writing to a file handle or other custom destination.

## Details

### rasqal_query_results_formats_check ()

    int                 rasqal_query_results_formats_check  (rasqal_world *world,
                                                             const char *name,
                                                             raptor_uri *uri,
                                                             const char *mime_type);

Check if a query results formatter exists for the requested format.

`world` : | rasqal_world object
`name` : | the query results format name (or NULL)
`uri` : | raptor_uri query results format uri (or NULL)
`mime_type` : | mime type name
Returns : | non-0 if a formatter exists.

### RASQAL_QUERY_RESULTS_FORMAT_FLAG_READER

    #define RASQAL_QUERY_RESULTS_FORMAT_FLAG_READER 1

Flag for `rasqal_query_results_formats_enumerate()` to get query results formats that can be read.

### RASQAL_QUERY_RESULTS_FORMAT_FLAG_WRITER

    #define RASQAL_QUERY_RESULTS_FORMAT_FLAG_WRITER 2

Flag for `rasqal_query_results_formats_enumerate()` to get query results formats that can be written.

### rasqal_query_results_formats_enumerate ()

    int                 rasqal_query_results_formats_enumerate
                                                            (rasqal_world *world,
                                                             unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             unsigned char **uri_string,
                                                             const char **mime_type,
                                                             int *flags);

Get information on query result syntaxes.

The current list of format names/URI is given below however the results of this function will always return the latest.

SPARQL XML Results 2007-06-14 (default format when `counter` is 0) name '`xml`' with URIs http://www.w3.org/TR/2006/WD-rdf-sparql-XMLres-20070614/ or http://www.w3.org/2005/sparql-results#

JSON name '`json`' and URI http://www.w3.org/2001/sw/DataAccess/json-sparql/

All returned strings are shared and must be copied if needed to be used dynamically.

`world` : | rasqal_world object
`counter` : | index into the list of query result syntaxes
`name` : | pointer to store the name of the query result syntax (or NULL)
`label` : | pointer to store query result syntax readable label (or NULL)
`uri_string` : | pointer to store query result syntax URI string (or NULL)
`mime_type` : | pointer to store query result syntax mime type string (or NULL)
`flags` : | pointer to store query result syntax flags (or NULL)
Returns : | non 0 on failure of if counter is out of range

### rasqal_query_results_formatter

    rasqal_graph_query_results_formatter* query_results_formatter;

Rasqal query results formatter class.

### rasqal_new_query_results_formatter ()

    rasqal_query_results_formatter* rasqal_new_query_results_formatter
                                                            (rasqal_world *world,
                                                             const char *name,
                                                             raptor_uri *format_uri);

Constructor - create a new rasqal_query_results_formatter object by identified format.

A query results format can be named or identified by a URI, both of which are optional. The default query results format will be used if both are NULL. `rasqal_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

`world` : | rasqal_world object
`name` : | the query results format name (or NULL)
`format_uri` : | raptor_uri query results format uri (or NULL)
Returns : | a new rasqal_query_results_formatter object or NULL on failure

### rasqal_new_query_results_formatter_by_mime_type ()

    rasqal_query_results_formatter* rasqal_new_query_results_formatter_by_mime_type
                                                            (rasqal_world *world,
                                                             const char *mime_type);

Constructor - create a new rasqal_query_results_formatter object by mime type.

A query results format generates a syntax with a mime type which may be requested with this constructor.

Note that there may be several formatters that generate the same MIME Type (such as SPARQL XML results format drafts) and in thot case the `rasqal_new_query_results_formatter()` constructor allows selecting of a specific one by name or URI.

`world` : | rasqal_world object
`mime_type` : | mime type name
Returns : | a new rasqal_query_results_formatter object or NULL on failure

### rasqal_free_query_results_formatter ()

    void                rasqal_free_query_results_formatter (rasqal_query_results_formatter *formatter);

Destructor - destroy a rasqal_query_results_formatter object.

`formatter` : | rasqal_query_results_formatter object

### rasqal_query_results_formatter_get_mime_type ()

    const char*         rasqal_query_results_formatter_get_mime_type
                                                            (rasqal_query_results_formatter *formatter);

Get the mime type of the syntax being formatted.

`formatter` : | rasqal_query_results_formatter object
Returns : | a shared mime type string

### rasqal_query_results_formatter_read ()

    int                 rasqal_query_results_formatter_read (rasqal_world *world,
                                                             raptor_iostream *iostr,
                                                             rasqal_query_results_formatter *formatter,
                                                             rasqal_query_results *results,
                                                             raptor_uri *base_uri);

Read the query results using the given formatter from an iostream

See `rasqal_query_results_formats_enumerate()` to get the list of syntax URIs and their description.

`world` : | rasqal world object
`iostr` : | raptor_iostream to read the query from
`formatter` : | rasqal_query_results_formatter object
`results` : | rasqal_query_results query results format
`base_uri` : | raptor_uri base URI of the input format
Returns : | non-0 on failure

### rasqal_query_results_formatter_write ()

    int                 rasqal_query_results_formatter_write
                                                            (raptor_iostream *iostr,
                                                             rasqal_query_results_formatter *formatter,
                                                             rasqal_query_results *results,
                                                             raptor_uri *base_uri);

Write the query results using the given formatter to an iostream

See `rasqal_query_results_formats_enumerate()` to get the list of syntax URIs and their description.

`iostr` : | raptor_iostream to write the query to
`formatter` : | rasqal_query_results_formatter object
`results` : | rasqal_query_results query results format
`base_uri` : | raptor_uri base URI of the output format
Returns : | non-0 on failure