section-parser: Raptor RDF Syntax Library Manual

## section-parser section-parser |

## Functions

raptor_parser * | raptor_new_parser ()
raptor_parser * | raptor_new_parser_for_content ()
void | raptor_free_parser ()
void | (*raptor_graph_mark_handler) ()
void | (*raptor_namespace_handler) ()
void | raptor_parser_set_statement_handler ()
void | raptor_parser_set_graph_mark_handler ()
void | raptor_parser_set_namespace_handler ()
const raptor_syntax_description * | raptor_parser_get_description ()
raptor_locator * | raptor_parser_get_locator ()
void | raptor_parser_parse_abort ()
int | raptor_parser_parse_chunk ()
int | raptor_parser_parse_file ()
int | raptor_parser_parse_file_stream ()
int | raptor_parser_parse_iostream ()
int | raptor_parser_parse_start ()
int | raptor_parser_parse_uri ()
int | raptor_parser_parse_uri_with_connection ()
raptor_uri * | raptor_parser_get_graph ()
const char * | raptor_parser_get_name ()
int | raptor_parser_set_option ()
int | raptor_parser_get_option ()
const char * | raptor_parser_get_accept_header ()
void | raptor_parser_set_uri_filter ()
raptor_world * | raptor_parser_get_world ()

## Types and Values

typedef | raptor_parser
enum | raptor_graph_mark_flags

## Description

## Functions

### raptor_new_parser ()

    raptor_parser *
    raptor_new_parser (raptor_world *world,
                       const char *name);

Constructor - create a new raptor_parser object.

#### Parameters

world | world object |
name | the parser name or NULL for default parser |

#### Returns

a new raptor_parser object or NULL on failure

### raptor_new_parser_for_content ()

    raptor_parser *
    raptor_new_parser_for_content (raptor_world *world,
                                   raptor_uri *uri,
                                   const char *mime_type,
                                   const char *buffer,
                                   size_t len,
                                   const unsigned char *identifier);

Constructor - create a new raptor_parser.

Uses `raptor_world_guess_parser_name()` to find a parser by scoring recognition of the syntax by a block of characters, the content identifier or a mime type. The content identifier is typically a filename or URI or some other identifier.

#### Parameters

world | world object |
uri | URI identifying the syntax (or NULL) |
mime_type | mime type identifying the content (or NULL) |
buffer | buffer of content to guess (or NULL) |
len | length of buffer |
identifier | identifier of content (or NULL) |

#### Returns

a new raptor_parser object or NULL on failure

### raptor_free_parser ()

    void
    raptor_free_parser (raptor_parser *parser);

Destructor - destroy a raptor_parser object.

#### Parameters

parser | raptor_parser object |

### raptor_graph_mark_handler ()

    void
    (*raptor_graph_mark_handler) (void *user_data,
                                  raptor_uri *graph,
                                  int flags);

Graph start/end mark handler function.

Records start and end of graphs happening in a stream of generated raptor_statement via the statement handler. The callback starts a graph when `flags` has RAPTOR_GRAPH_MARK_START bit set.

The start and ends may be either declared in the syntax via some keyword or mechanism such as TRiG {} syntax when `flags` has bit RAPTOR_GRAPH_MARK_DECLARED set, or be implied by the start/end of the data in other syntaxes, and the bit will be unset.

#### Parameters

user_data | user data |
graph | graph to report, NULL for the default graph |
flags | bitmask of raptor_graph_mark_flags flags |

### raptor_namespace_handler ()

    void
    (*raptor_namespace_handler) (void *user_data,
                                 raptor_namespace *nspace);

XML Namespace declaration reporting handler set by `raptor_parser_set_namespace_handler()`.

#### Parameters

user_data | user data |
nspace | raptor_namespace declared |

### raptor_parser_set_statement_handler ()

    void
    raptor_parser_set_statement_handler (raptor_parser *parser,
                                         void *user_data,
                                         raptor_statement_handler handler);

Set the statement handler function for the parser.

Use this to set the function to receive statements as the parsing proceeds. The statement argument to `handler` is shared and must be copied by the caller with `raptor_statement_copy()`.

#### Parameters

parser | raptor_parser parser object |
user_data | user data pointer for callback |
handler | new statement callback function |

### raptor_parser_set_graph_mark_handler ()

    void
    raptor_parser_set_graph_mark_handler (raptor_parser *parser,
                                          void *user_data,
                                          raptor_graph_mark_handler handler);

Set the graph mark handler function for the parser.

See raptor_graph_mark_handler and raptor_graph_mark_flags for the marks that may be returned by the handler.

#### Parameters

parser | raptor_parser parser object |
user_data | user data pointer for callback |
handler | new graph callback function |

### raptor_parser_set_namespace_handler ()

    void
    raptor_parser_set_namespace_handler (raptor_parser *parser,
                                         void *user_data,
                                         raptor_namespace_handler handler);

Set the namespace handler function for the parser.

When a prefix/namespace is seen in a parser, call the given `handler` with the prefix string and the raptor_uri namespace URI. Either can be NULL for the default prefix or default namespace.

The handler function does not deal with duplicates so any namespace may be declared multiple times.

#### Parameters

parser | raptor_parser parser object |
user_data | user data pointer for callback |
handler | new namespace callback function |

### raptor_parser_get_description ()

    const raptor_syntax_description *
    raptor_parser_get_description (raptor_parser *rdf_parser);

Get description of the syntaxes of the parser.

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

#### Parameters

rdf_parser | raptor_parser parser object |

#### Returns

description of syntax

### raptor_parser_get_locator ()

    raptor_locator *
    raptor_parser_get_locator (raptor_parser *rdf_parser);

Get the current raptor locator object.

#### Parameters

rdf_parser | raptor parser |

#### Returns

raptor locator

### raptor_parser_parse_abort ()

    void
    raptor_parser_parse_abort (raptor_parser *rdf_parser);

Abort an ongoing parsing.

Causes any ongoing generation of statements by a parser to be terminated and the parser to return controlto the application as soon as draining any existing buffers.

Most useful inside `raptor_parser_parse_file()` or `raptor_parser_parse_uri()` when the Raptor library is directing the parsing and when one of the callback handlers such as as set by `raptor_parser_set_statement_handler()` requires to return to the main application code.

#### Parameters

rdf_parser | raptor_parser parser object |

### raptor_parser_parse_chunk ()

    int
    raptor_parser_parse_chunk (raptor_parser *rdf_parser,
                               const char *buffer,
                               size_t len,
                               int is_end);

Parse a block of content into triples.

This method can only be called after `raptor_parser_parse_start()` has initialised the parser.

#### Parameters

rdf_parser | RDF parser |
buffer | content to parse |
len | length of buffer |
is_end | non-0 if this is the end of the content (such as EOF) |

#### Returns

non-0 on failure.

### raptor_parser_parse_file ()

    int
    raptor_parser_parse_file (raptor_parser *rdf_parser,
                              raptor_uri *uri,
                              raptor_uri *base_uri);

Parse RDF content at a file URI.

If `uri` is NULL (source is stdin), then the `base_uri` is required.

#### Parameters

rdf_parser | parser |
uri | URI of RDF content or NULL to read from standard input |
base_uri | the base URI to use (or NULL if the same) |

#### Returns

non 0 on failure

### raptor_parser_parse_file_stream ()

    int
    raptor_parser_parse_file_stream (raptor_parser *rdf_parser,
                                     FILE *stream,
                                     const char *filename,
                                     raptor_uri *base_uri);

Parse RDF content from a FILE*.

After draining the FILE* stream (EOF), fclose is not called on it.

#### Parameters

rdf_parser | parser |
stream | FILE* of RDF content |
filename | filename of content or NULL if it has no name |
base_uri | the base URI to use |

#### Returns

non 0 on failure

### raptor_parser_parse_iostream ()

    int
    raptor_parser_parse_iostream (raptor_parser *rdf_parser,
                                  raptor_iostream *iostr,
                                  raptor_uri *base_uri);

Parse content from an iostream

If the parser requires a base URI and `base_uri` is NULL, an error will be generated and the function will fail.

#### Parameters

rdf_parser | parser |
iostr | iostream to read from |
base_uri | the base URI to use (or NULL) |

#### Returns

non 0 on failure, <0 if a required base URI was missing

### raptor_parser_parse_start ()

    int
    raptor_parser_parse_start (raptor_parser *rdf_parser,
                               raptor_uri *uri);

Start a parse of content with base URI.

Parsers that need a base URI can be identified using a syntax description returned by `raptor_world_get_parser_description()` statically or `raptor_parser_get_description()` on a constructed parser.

#### Parameters

rdf_parser | RDF parser |
uri | base URI or may be NULL if no base URI is required |

#### Returns

non-0 on failure, <0 if a required base URI was missing

### raptor_parser_parse_uri ()

    int
    raptor_parser_parse_uri (raptor_parser *rdf_parser,
                             raptor_uri *uri,
                             raptor_uri *base_uri);

Parse the RDF content at URI.

Sends an HTTP Accept: header whent the URI is of the HTTP protocol, see `raptor_parser_parse_uri_with_connection()` for details including how the `base_uri` is used.

#### Parameters

rdf_parser | parser |
uri | URI of RDF content |
base_uri | the base URI to use (or NULL if the same) |

#### Returns

non 0 on failure

### raptor_parser_parse_uri_with_connection ()

    int
    raptor_parser_parse_uri_with_connection
                                   (raptor_parser *rdf_parser,
                                    raptor_uri *uri,
                                    raptor_uri *base_uri,
                                    void *connection);

Parse RDF content at URI using existing WWW connection.

If `base_uri` is not given and during resolution of the URI, a protocol redirection occurs, the final resolved URI will be used as the base URI. If redirection does not occur, the base URI will be `uri` .

If `base_uri` is given, it overrides the process above.

When `connection` is NULL and a MIME Type exists for the parser type, this type is sent in an HTTP Accept: header in the form Accept: MIME-TYPE along with a wildcard of 0.1 quality, so MIME-TYPE is prefered rather than the sole answer. The latter part may not be necessary but should ensure an HTTP 200 response.

#### Parameters

rdf_parser | parser |
uri | URI of RDF content |
base_uri | the base URI to use (or NULL if the same) |
connection | connection object pointer or NULL to create a new one |

#### Returns

non 0 on failure

### raptor_parser_get_graph ()

    raptor_uri *
    raptor_parser_get_graph (raptor_parser *rdf_parser);

Get the current graph for the parser

The returned URI is owned by the caller and must be freed with `raptor_free_uri()`

#### Parameters

rdf_parser | parser |

#### Returns

raptor_uri* graph name or NULL for the default graph

### raptor_parser_get_name ()

    const char *
    raptor_parser_get_name (raptor_parser *rdf_parser);

Get the name of a parser.

Use `raptor_parser_get_description()` to get the alternate names and aliases as well as other descriptive values.

#### Parameters

rdf_parser | raptor_parser parser object |

#### Returns

the short name for the parser.

### raptor_parser_set_option ()

    int
    raptor_parser_set_option (raptor_parser *parser,
                              raptor_option option,
                              const char *string,
                              int integer);

Set parser 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()`.

#### Parameters

parser | raptor_parser parser 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_parser_get_option ()

    int
    raptor_parser_get_option (raptor_parser *parser,
                              raptor_option option,
                              char **string_p,
                              int *integer_p);

Get parser 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()`.

#### Parameters

parser | raptor_parser parser 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_parser_get_accept_header ()

    const char *
    raptor_parser_get_accept_header (raptor_parser *rdf_parser);

Get an HTTP Accept value for the parser.

The returned string must be freed by the caller such as with `raptor_free_memory()`.

#### Parameters

rdf_parser | parser |

#### Returns

a new Accept: header string or NULL on failure

### raptor_parser_set_uri_filter ()

    void
    raptor_parser_set_uri_filter (raptor_parser *parser,
                                  raptor_uri_filter_func filter,
                                  void *user_data);

Set URI filter function for WWW retrieval.

#### Parameters

parser | parser object |
filter | URI filter function |
user_data | User data to pass to filter function |

### raptor_parser_get_world ()

    raptor_world *
    raptor_parser_get_world (raptor_parser *rdf_parser);

Get the raptor_world object associated with a parser.

#### Parameters

rdf_parser | parser |

#### Returns

raptor_world* pointer

## Types and Values

### raptor_parser

    raptor_parser* raptor_parser;

Raptor Parser class

### enum raptor_graph_mark_flags

Graph mark handler bitmask flags

#### Members

RAPTOR_GRAPH_MARK_START | mark is start of graph (otherwise is end) |
RAPTOR_GRAPH_MARK_DECLARED | mark was declared in syntax rather than implict |