section-general: Raptor RDF Syntax Library Manual

## section-general section-general |

## Functions

void | (*raptor_statement_handler) ()
int | raptor_snprintf ()
int | raptor_vasprintf ()
char * | raptor_vsnprintf ()
int | raptor_vsnprintf2 ()
void | raptor_sort_r ()
void | (*raptor_log_handler) ()
const char * | raptor_log_level_get_label ()
const char * | raptor_domain_get_label ()
int | (*raptor_data_compare_handler) ()
int | (*raptor_data_compare_arg_handler) ()
void | (*raptor_data_context_free_handler) ()
int | (*raptor_data_context_print_handler) ()
void | (*raptor_data_free_handler) ()
void * | (*raptor_data_malloc_handler) ()
int | (*raptor_data_print_handler) ()
char * | (*raptor_generate_bnodeid_handler) ()
int | raptor_syntax_description_validate ()

## Types and Values

#define | RAPTOR_VERSION
#define | RAPTOR_VERSION_MAJOR
#define | RAPTOR_VERSION_MINOR
#define | RAPTOR_VERSION_RELEASE
#define | RAPTOR_VERSION_STRING
extern const unsigned int | raptor_version_major
extern const unsigned int | raptor_version_minor
extern const unsigned int | raptor_version_release
extern const unsigned int | raptor_version_decimal
extern const char * const | raptor_copyright_string
extern const char * const | raptor_home_url_string
extern const char * const | raptor_license_string
extern const char * const | raptor_short_copyright_string
extern const char * const | raptor_version_string
extern const unsigned char * const | raptor_owl_namespace_uri
extern const unsigned char * const | raptor_rdf_namespace_uri
extern const unsigned char * const | raptor_rdf_schema_namespace_uri
extern const unsigned char * const | raptor_xml_literal_datatype_uri_string
extern const unsigned char * const | raptor_xml_namespace_uri
extern const unsigned char * const | raptor_xmlschema_datatypes_namespace_uri
| raptor_log_message
enum | raptor_log_level
enum | raptor_domain
enum | raptor_syntax_bitflags
| raptor_syntax_description
| raptor_type_q

## Description

## Functions

### raptor_statement_handler ()

    void
    (*raptor_statement_handler) (void *user_data,
                                 raptor_statement *statement);

Statement (triple) reporting handler function.

This handler function set with `raptor_parser_set_statement_handler()` on a parser receives statements as the parsing proceeds. The `statement` argument to the handler is shared and must be copied by the caller with `raptor_statement_copy()`.

#### Parameters

user_data | user data |
statement | statement to report |

### raptor_snprintf ()

    int
    raptor_snprintf (char *buffer,
                     size_t size,
                     const char *format,
                     ...);

Format output into an allocated sized buffer

This provides a portable version `snprintf()` over variants on different systems.

If `buffer` is NULL, calculates the number of bytes needed to allocate for buffer and do no formatting.

#### Parameters

buffer | buffer (or NULL) |
size | bufer size (or 0) |
format | printf-style format string |
... | format arguments |

#### Returns

number of bytes allocated (excluding NUL) or 0 on failure

### raptor_vasprintf ()

    int
    raptor_vasprintf (char **ret,
                      const char *format,
                      va_list arguments);

Format output into a new buffer and return it

This is a wrapper around the (GNU) vasprintf function that is not always avaiable.

#### Parameters

ret | pointer to store buffer |
format | printf-style format string |
arguments | format arguments list |

#### Returns

number of bytes allocated (excluding NUL) or < 0 on failure

### raptor_vsnprintf ()

    char *
    raptor_vsnprintf (const char *format,
                      va_list arguments);

`raptor_vsnprintf` is deprecated and should not be used in newly-written code.

Format output for a variable arguments list into a newly allocated buffer

`Deprecated` : This does not actually conform to vsnprintf's calling convention and does not return the allocated buffer length. Use `raptor_vsnprintf2()` or `raptor_vasprintf()` instead.

#### Parameters

format | printf-style format string |
arguments | variable arguments list |

#### Returns

a newly allocated string as the formatted result or NULL on failure

### raptor_vsnprintf2 ()

    int
    raptor_vsnprintf2 (char *buffer,
                       size_t size,
                       const char *format,
                       va_list arguments);

Format output for a variable arguments list into an allocated sized buffer.

This is a wrapper around system versions of vsnprintf with different call and return conventions.

If `buffer` is NULL or size is 0 or the buffer size is too small, returns the number of bytes that would be needed for buffer

#### Parameters

buffer | buffer (or NULL) |
size | size of buffer (or 0) |
format | printf-style format string |
arguments | variable arguments list |

#### Returns

number of bytes allocated (excluding NUL) or <0 on failure

### raptor_sort_r ()

    void
    raptor_sort_r (void *base,
                   size_t nel,
                   size_t width,
                   raptor_data_compare_arg_handler compar,
                   void *user_data);

Sort an array with an extra user data arg for the comparison funciton.

Sorts data at `base` of `nel` elememnts of width `width` using comparison function `comp` that takes args (void* data1, void* data2, `user_data` ) and returns <0, 0, or >0 for object comparison.

#### Parameters

base | the array to be sorted |
nel | the number of elements in the array |
width | the size in bytes of each element of the array |
compar | comparison function |
user_data | a pointer to be passed to the comparison function |

### raptor_log_handler ()

    void
    (*raptor_log_handler) (void *user_data,
                           raptor_log_message *message);

Handler function for log messages with location

Used during parsing and serializing for errors and warnings that may include location information. Handlers may be set by `raptor_world_set_log_handler()`.

#### Parameters

user_data | user data |
message | log message |

### raptor_log_level_get_label ()

    const char *
    raptor_log_level_get_label (raptor_log_level level);

Get label for a log message level

#### Parameters

level | log message level |

#### Returns

label string or NULL if level is not valid

### raptor_domain_get_label ()

    const char *
    raptor_domain_get_label (raptor_domain domain);

Get label for a domain

#### Parameters

domain | domain |

#### Returns

label string or NULL if domain is not valid

### raptor_data_compare_handler ()

    int
    (*raptor_data_compare_handler) (const void *data1,
                                    const void *data2);

Function to compare two data objects - signature like `strcmp()` and function pssed to `qsort()`

Designed to be passed into generic data structure constructors like `raptor_new_avltree()`.

#### Parameters

data1 | first data object |
data2 | second data object |

#### Returns

compare value <0 if `data1` is before `data2` , =0 if equal, >0 if `data1` is after `data2`

### raptor_data_compare_arg_handler ()

    int
    (*raptor_data_compare_arg_handler) (const void *data1,
                                        const void *data2,
                                        void *user_data);

Function to compare two data objects with a user data argument

Designed to be used with `raptor_sort_r()` and compatible functions such as `raptor_sequence_sort_r()` which uses it.

#### Parameters

data1 | first object |
data2 | second object |
user_data | user data argument |

#### Returns

compare value <0 if `data1` is before `data2` , =0 if equal, >0 if `data1` is after `data2`

### raptor_data_context_free_handler ()

    void
    (*raptor_data_context_free_handler) (void *context,
                                         void *object);

Handler function for freeing a sequence item with a contextual pointer.

Set by `raptor_new_sequence_with_context()`.

#### Parameters

context | context data for the free function |
object | object to free |

### raptor_data_context_print_handler ()

    int
    (*raptor_data_context_print_handler) (void *context,
                                          void *object,
                                          FILE *fh);

Function function for printing an object with data context to a stream.

Set by `raptor_new_sequence_with_context()`

#### Parameters

context | context data for the print function |
object | object to print |
fh | FILE* to print to |

#### Returns

non-0 on failure

### raptor_data_free_handler ()

    void
    (*raptor_data_free_handler) (void *data);

Typedef for function to free a data object - signature like `free()`

Designed to be passed into generic data structure constructors like `raptor_new_avltree()`. If `data` is NULL, nothing should be done.

#### Parameters

data | data object or NULL |

### raptor_data_malloc_handler ()

    void *
    (*raptor_data_malloc_handler) (size_t size);

Typedef for a function to allocate memory - signature like `malloc()`

Designed to be passed into constructors like raptor_www_fetch_to_string

#### Parameters

size | data size |

#### Returns

pointer to newly allocated memory or NULL on failure

### raptor_data_print_handler ()

    int
    (*raptor_data_print_handler) (void *object,
                                  FILE *fh);

Handler function for printing an object to a stream.

Set by `raptor_new_sequence()`

#### Parameters

object | object to print |
fh | FILE* to print to |

#### Returns

non-0 on failure

### raptor_generate_bnodeid_handler ()

    char *
    (*raptor_generate_bnodeid_handler) (void *user_data,
                                        unsigned char *user_bnodeid);

Generate a blank node identifier handler function.

#### Parameters

user_data | user data |
user_bnodeid | a user-specified ID or NULL if none available. |

#### Returns

new blank node ID to use

### raptor_syntax_description_validate ()

    int
    raptor_syntax_description_validate (raptor_syntax_description *desc);

Validate a syntax description has the required fields (name, labels) and update counts

#### Parameters

desc | description |

#### Returns

non-0 on failure

## Types and Values

### RAPTOR_VERSION

    #define RAPTOR_VERSION 20016

Raptor library version number

Format: major * 10000 + minor * 100 + release

### RAPTOR_VERSION_MAJOR

    #define RAPTOR_VERSION_MAJOR 2

Raptor library major version

### RAPTOR_VERSION_MINOR

    #define RAPTOR_VERSION_MINOR 0

Raptor library minor version

### RAPTOR_VERSION_RELEASE

    #define RAPTOR_VERSION_RELEASE 16

Raptor library release

### RAPTOR_VERSION_STRING

    #define RAPTOR_VERSION_STRING "2.0.16"

Raptor library version string

### raptor_version_major

    extern const unsigned int raptor_version_major;

Library major version number as a decimal integer.

### raptor_version_minor

    extern const unsigned int raptor_version_minor;

Library minor version number as a decimal integer.

### raptor_version_release

    extern const unsigned int raptor_version_release;

Library release version number as a decimal integer.

### raptor_version_decimal

    extern const unsigned int raptor_version_decimal;

Library full version as a decimal integer.

See also raptor_version_string.

### raptor_copyright_string

    extern const char * const raptor_copyright_string;

Copyright string (multiple lines).

### raptor_home_url_string

    extern const char * const raptor_home_url_string;

Raptor home page URL.

### raptor_license_string

    extern const char * const raptor_license_string;

Raptor license string.

### raptor_short_copyright_string

    extern const char * const raptor_short_copyright_string;

Short copyright string (one line).

### raptor_version_string

    extern const char * const raptor_version_string;

Library full version as a string.

See also raptor_version_decimal.

### raptor_owl_namespace_uri

    extern const unsigned char * const raptor_owl_namespace_uri;

OWL (owl:) Namespace URI string.

### raptor_rdf_namespace_uri

    extern const unsigned char * const raptor_rdf_namespace_uri;

RDF Namespace (rdf:) URI string.

### raptor_rdf_schema_namespace_uri

    extern const unsigned char * const raptor_rdf_schema_namespace_uri;

RDF Schema (rdfs:) Namespace URI string.

### raptor_xml_literal_datatype_uri_string

    extern const unsigned char * const raptor_xml_literal_datatype_uri_string;

XML Literal datatype (rdf:XMLLiteral) URI string.

### raptor_xml_namespace_uri

    extern const unsigned char * const raptor_xml_namespace_uri;

XML Namespace (xml:) URI string.

### raptor_xmlschema_datatypes_namespace_uri

    extern const unsigned char * const raptor_xmlschema_datatypes_namespace_uri;

XML Schema datatypes (xsd:) namespace URI string.

### raptor_log_message

    typedef struct {
      int code;
      raptor_domain domain;
      raptor_log_level level;
      raptor_locator *locator;
      const char *text;
    } raptor_log_message;

Log message.

#### Members

int `code`; | error code or < 0 if not used or known |
raptor_domain `domain`; | message domain or RAPTOR_DOMAIN_NONE if not used or known |
raptor_log_level `level`; | log message level |
raptor_locator *`locator`; | location associated with message or NULL if not known |
const char *`text`; | message string |

### enum raptor_log_level

Log levels

#### Members

RAPTOR_LOG_LEVEL_NONE | Internal |
RAPTOR_LOG_LEVEL_TRACE | very fine-grained tracing messages information |
RAPTOR_LOG_LEVEL_DEBUG | fine-grained tracing messages suitable for debugging |
RAPTOR_LOG_LEVEL_INFO | coarse-grained information messages |
RAPTOR_LOG_LEVEL_WARN | warning messages of potentially harmful problems |
RAPTOR_LOG_LEVEL_ERROR | error messages where the application can continue |
RAPTOR_LOG_LEVEL_FATAL | fatal error message where the application will likely abort |
RAPTOR_LOG_LEVEL_LAST | Internal |

### enum raptor_domain

Log domain

#### Members

RAPTOR_DOMAIN_NONE | Internal |
RAPTOR_DOMAIN_IOSTREAM | I/O stream |
RAPTOR_DOMAIN_NAMESPACE | XML Namespace / namespace stack |
RAPTOR_DOMAIN_PARSER | RDF Parser |
RAPTOR_DOMAIN_QNAME | XML QName |
RAPTOR_DOMAIN_SAX2 | XML SAX2 |
RAPTOR_DOMAIN_SERIALIZER | RDF Serializer |
RAPTOR_DOMAIN_TERM | RDF Term |
RAPTOR_DOMAIN_TURTLE_WRITER | Turtle Writer |
RAPTOR_DOMAIN_URI | RDF Uri |
RAPTOR_DOMAIN_WORLD | RDF world |
RAPTOR_DOMAIN_WWW | WWW |
RAPTOR_DOMAIN_XML_WRITER | XML Writer |
RAPTOR_DOMAIN_LAST | Internal |

### enum raptor_syntax_bitflags

Bit flags for raptor_syntax_description flags field

#### Members

RAPTOR_SYNTAX_NEED_BASE_URI | the syntax requires a base URI |

### raptor_syntax_description

    typedef struct {
      const char* names;
      unsigned int names_count;

      const char* label;

      const raptor_type_q* mime_types;
      unsigned int mime_types_count;

      const char* uri_strings;
      unsigned int uri_strings_count;

      unsigned int flags;
    } raptor_syntax_description;

Description of a syntax or file format.

#### Members

const char *`names`; | array of syntax names - the first one (required) is the public name, the rest are aliases. The array is NULL terminated. |
unsigned int `names_count`; | size of `names` array |
const char *`label`; | long descriptive label for syntax |
const raptor_type_q *`mime_types`; | Array of (MIME type, Q) values associated with the syntax (or NULL). If present the array is NULL terminated. |
unsigned int `mime_types_count`; | size of `mime_types` array |
const char *`uri_strings`; | array of URIs identifying the syntax (or NULL). The first one if present is the main URI, the rest are aliases. The array is NULL terminated. |
unsigned int `uri_strings_count`; | size of `uri_strings` array |
unsigned int `flags`; | See raptor_syntax_bitflags for the bits |

### raptor_type_q

    typedef struct {
      const char* mime_type;
      size_t mime_type_len;
      unsigned char q;
    } raptor_type_q;

(MIME Type, Q) pair

#### Members

const char *`mime_type`; | MIME type string |
size_t `mime_type_len`; | length of `mime_type` |
unsigned char `q`; | Q value 0-10 standing for decimal 0.0-1.0 |