section-xml: Raptor RDF Syntax Library Manual

## section-xml section-xml |

## Functions

raptor_xml_element * | raptor_new_xml_element ()
raptor_xml_element * | raptor_new_xml_element_from_namespace_local_name ()
void | raptor_free_xml_element ()
raptor_qname * | raptor_xml_element_get_name ()
raptor_qname ** | raptor_xml_element_get_attributes ()
int | raptor_xml_element_get_attributes_count ()
void | raptor_xml_element_set_attributes ()
int | raptor_xml_element_declare_namespace ()
int | raptor_xml_element_is_empty ()
const unsigned char * | raptor_xml_element_get_language ()
int | raptor_xml_element_write ()
raptor_xml_writer * | raptor_new_xml_writer ()
void | raptor_free_xml_writer ()
void | raptor_xml_writer_empty_element ()
void | raptor_xml_writer_start_element ()
void | raptor_xml_writer_end_element ()
void | raptor_xml_writer_cdata ()
void | raptor_xml_writer_cdata_counted ()
void | raptor_xml_writer_raw ()
void | raptor_xml_writer_raw_counted ()
void | raptor_xml_writer_comment ()
void | raptor_xml_writer_comment_counted ()
void | raptor_xml_writer_flush ()
void | raptor_xml_writer_newline ()
int | raptor_xml_writer_get_depth ()
int | raptor_xml_writer_set_option ()
int | raptor_xml_writer_get_option ()
int | raptor_xml_escape_string_any ()
int | raptor_xml_escape_string_any_write ()
int | raptor_xml_escape_string ()
int | raptor_xml_escape_string_write ()
int | raptor_xml_name_check ()

## Types and Values

typedef | raptor_xml_element
typedef | raptor_xml_writer

## Description

## Functions

### raptor_new_xml_element ()

    raptor_xml_element *
    raptor_new_xml_element (raptor_qname *name,
                            const unsigned char *xml_language,
                            raptor_uri *xml_base);

Constructor - create a new XML element from a QName

The `xml_language` and `xml_base` become owned by the new object.

#### Parameters

name | The XML element name |
xml_language | the in-scope XML language (or NULL) |
xml_base | the in-scope XML base URI (or NULL) |

#### Returns

a new raptor_xml_element or NULL on failure

### raptor_new_xml_element_from_namespace_local_name ()

    raptor_xml_element *
    raptor_new_xml_element_from_namespace_local_name
                                   (raptor_namespace *ns,
                                    const char *name,
                                    const unsigned char *xml_language,
                                    raptor_uri *xml_base);

Constructor - create a new XML element from an XML namespace and a local name

Added in 1.4.16.

#### Parameters

ns | namespace |
name | the XML element local name |
xml_language | the in-scope XML language (or NULL) |
xml_base | base uri (or NULL) |

#### Returns

a new raptor_xml_element or NULL on failure

### raptor_free_xml_element ()

    void
    raptor_free_xml_element (raptor_xml_element *element);

Destructor - destroy a raptor_xml_element object.

#### Parameters

element | XML Element |

### raptor_xml_element_get_name ()

    raptor_qname *
    raptor_xml_element_get_name (raptor_xml_element *xml_element);

Get the XML Name of an XML element

#### Parameters

xml_element | XML Element |

#### Returns

The Name.

### raptor_xml_element_get_attributes ()

    raptor_qname **
    raptor_xml_element_get_attributes (raptor_xml_element *xml_element);

Get the array of attributes on the XML element.

Use `raptor_xml_element_get_attributes_count()` to get the count of the array size.

#### Parameters

xml_element | XML Element |

#### Returns

the array of qnames or NULL if none are present.

### raptor_xml_element_get_attributes_count ()

    int
    raptor_xml_element_get_attributes_count
                                   (raptor_xml_element *xml_element);

Get the number of attributes on the XML element.

#### Parameters

xml_element | XML Element |

#### Returns

Integer number of attributes - 0 or more.

### raptor_xml_element_set_attributes ()

    void
    raptor_xml_element_set_attributes (raptor_xml_element *xml_element,
                                       raptor_qname **attributes,
                                       int count);

Set the attributes on an XML element.

The `attributes` array becomes owned by the element after this function.

#### Parameters

xml_element | XML Element |
attributes | Array of XML Qname attributes with values |
count | Length of array |

### raptor_xml_element_declare_namespace ()

    int
    raptor_xml_element_declare_namespace (raptor_xml_element *xml_element,
                                          raptor_namespace *nspace);

Declare a namespace on the XML Element.

#### Parameters

xml_element | XML Element |
nspace | raptor_namespace to declare |

#### Returns

non-0 if namespace cannot be declared

### raptor_xml_element_is_empty ()

    int
    raptor_xml_element_is_empty (raptor_xml_element *xml_element);

Check if an XML Element is empty.

#### Parameters

xml_element | XML Element |

#### Returns

non-0 if the element is empty.

### raptor_xml_element_get_language ()

    const unsigned char *
    raptor_xml_element_get_language (raptor_xml_element *xml_element);

Get the XML language of the element.

#### Parameters

xml_element | XML Element |

#### Returns

XML language or NULL if none in scope

### raptor_xml_element_write ()

    int
    raptor_xml_element_write (raptor_xml_element *element,
                              raptor_namespace_stack *nstack,
                              int is_empty,
                              int is_end,
                              int depth,
                              raptor_iostream *iostr);

Write a formatted XML element to a raptor_iostream

#### Parameters

element | XML element to format |
nstack | Namespace stack context to use in formatting |
is_empty | non-0 if element is empty |
is_end | non-0 if this is an end element (else is a start element) |
depth | XML element depth |
iostr | iostream object |

#### Returns

non-0 on failure

### raptor_new_xml_writer ()

    raptor_xml_writer *
    raptor_new_xml_writer (raptor_world *world,
                           raptor_namespace_stack *nstack,
                           raptor_iostream *iostr);

Constructor - Create a new XML Writer writing XML to a raptor_iostream

#### Parameters

world | raptor_world object |
nstack | Namespace stack for the writer to start with (or NULL) |
iostr | I/O stream to write to |

#### Returns

a new raptor_xml_writer object or NULL on failure

### raptor_free_xml_writer ()

    void
    raptor_free_xml_writer (raptor_xml_writer *xml_writer);

Destructor - Free XML Writer

#### Parameters

xml_writer | XML writer object |

### raptor_xml_writer_empty_element ()

    void
    raptor_xml_writer_empty_element (raptor_xml_writer *xml_writer,
                                     raptor_xml_element *element);

Write an empty XML element to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
element | XML element object |

### raptor_xml_writer_start_element ()

    void
    raptor_xml_writer_start_element (raptor_xml_writer *xml_writer,
                                     raptor_xml_element *element);

Write a start XML element to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

Indents the start element if XML writer option AUTO_INDENT is enabled.

#### Parameters

xml_writer | XML writer object |
element | XML element object |

### raptor_xml_writer_end_element ()

    void
    raptor_xml_writer_end_element (raptor_xml_writer *xml_writer,
                                   raptor_xml_element *element);

Write an end XML element to the XML writer.

Indents the end element if XML writer option AUTO_INDENT is enabled.

#### Parameters

xml_writer | XML writer object |
element | XML element object |

### raptor_xml_writer_cdata ()

    void
    raptor_xml_writer_cdata (raptor_xml_writer *xml_writer,
                             const char *s);

Write CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
s | string to XML escape and write |

### raptor_xml_writer_cdata_counted ()

    void
    raptor_xml_writer_cdata_counted (raptor_xml_writer *xml_writer,
                                     const char *s,
                                     unsigned int len);

Write counted CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
s | string to XML escape and write |
len | length of string |

### raptor_xml_writer_raw ()

    void
    raptor_xml_writer_raw (raptor_xml_writer *xml_writer,
                           const char *s);

Write a string raw to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
s | string to write |

### raptor_xml_writer_raw_counted ()

    void
    raptor_xml_writer_raw_counted (raptor_xml_writer *xml_writer,
                                   const char *s,
                                   unsigned int len);

Write a counted string raw to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
s | string to write |
len | length of string |

### raptor_xml_writer_comment ()

    void
    raptor_xml_writer_comment (raptor_xml_writer *xml_writer,
                               const char *s);

Write an XML comment to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
s | comment string to write |

### raptor_xml_writer_comment_counted ()

    void
    raptor_xml_writer_comment_counted (raptor_xml_writer *xml_writer,
                                       const char *s,
                                       unsigned int len);

Write a counted XML comment to the XML writer.

Closes any previous empty element if XML writer option AUTO_EMPTY is enabled.

#### Parameters

xml_writer | XML writer object |
s | comment string to write |
len | length of string |

### raptor_xml_writer_flush ()

    void
    raptor_xml_writer_flush (raptor_xml_writer *xml_writer);

Finish the XML writer.

#### Parameters

xml_writer | XML writer object |

### raptor_xml_writer_newline ()

    void
    raptor_xml_writer_newline (raptor_xml_writer *xml_writer);

Write a newline to the XML writer.

Indents the next line if XML writer option AUTO_INDENT is enabled.

#### Parameters

xml_writer | XML writer object |

### raptor_xml_writer_get_depth ()

    int
    raptor_xml_writer_get_depth (raptor_xml_writer *xml_writer);

Get the current XML Writer element depth

#### Parameters

xml_writer | raptor_xml_writer xml writer object |

#### Returns

element stack depth

### raptor_xml_writer_set_option ()

    int
    raptor_xml_writer_set_option (raptor_xml_writer *xml_writer,
                                  raptor_option option,
                                  char *string,
                                  int integer);

Set xml_writer 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

xml_writer | raptor_xml_writer xml_writer 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_xml_writer_get_option ()

    int
    raptor_xml_writer_get_option (raptor_xml_writer *xml_writer,
                                  raptor_option option,
                                  char **string_p,
                                  int *integer_p);

Get xml_writer 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

xml_writer | raptor_xml_writer xml_writer 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_xml_escape_string_any ()

    int
    raptor_xml_escape_string_any (raptor_world *world,
                                  const char *string,
                                  size_t len,
                                  unsigned char *buffer,
                                  size_t length,
                                  char quote,
                                  int xml_version);

Return an XML-escaped version a string.

Follows

Canonical XML rules on Text Nodes and Attribute Nodes

Both: Replaces `&` and `<` with `&amp;` and `&lt;` respectively, preserving other characters.

Text Nodes: `>` is turned into `&gt;` #xD is turned into `&#xD;`

Attribute Nodes: `>` is generated not `&gt`. #x9, #xA and #xD are turned into `&#x9;`, `&#xA;` and `&#xD;` entities.

If `quote` is given it can be either of '\'' or '\"' which will be turned into `&apos;` or `&quot;` respectively. ASCII NUL ('\0') or any other character will not be escaped.

If `buffer` is NULL, no work is done but the size of buffer required is returned. The output in buffer remains in UTF-8.

If the input `string` is empty, a single NUL will be written to the buffer.

#### Parameters

world | raptor world |
string | string to XML escape (UTF-8) |
len | length of string |
buffer | the buffer to use for new string (UTF-8) or NULL to just calculate expected length |
length | buffer size |
quote | optional quote character to escape for attribute content, or 0 |
xml_version | XML 1.0 (10) or XML 1.1 (11) |

#### Returns

the number of bytes required / used or <0 on failure.

### raptor_xml_escape_string_any_write ()

    int
    raptor_xml_escape_string_any_write (const char *string,
                                        size_t len,
                                        char quote,
                                        int xml_version,
                                        raptor_iostream *iostr);

Write an XML-escaped version of a string to an iostream.

See `raptor_xml_escape_string()` for the escapes performed and the conditions on `quote` and `string` . XML 1.1 allows additional characters in XML such as U+0001 to U+001F inclusive.

#### Parameters

string | string to XML escape (UTF-8) |
len | length of string |
quote | optional quote character to escape for attribute content, or 0 |
xml_version | XML version - 10 (XML 1.0) or 11 (XML 1.1) |
iostr | the raptor_iostream to write to |

#### Returns

non 0 on failure

### raptor_xml_escape_string ()

    int
    raptor_xml_escape_string (raptor_world *world,
                              const char *string,
                              size_t len,
                              unsigned char *buffer,
                              size_t length,
                              char quote);

Return an XML 1.0-escaped version a string.

See `raptor_xml_escape_string_any()` for the conditions on parameters.

#### Parameters

world | raptor world |
string | string to XML 1.0 escape (UTF-8) |
len | length of string |
buffer | the buffer to use for new string (UTF-8) or NULL to just calculate expected length. |
length | buffer size |
quote | optional quote character to escape for attribute content, or 0 |

#### Returns

the number of bytes required / used or <0 on failure.

### raptor_xml_escape_string_write ()

    int
    raptor_xml_escape_string_write (const char *string,
                                    size_t len,
                                    char quote,
                                    raptor_iostream *iostr);

Write an XML 1.0-escaped version of a string to an iostream.

See `raptor_xml_escape_string_any_write()` for the escapes performed and the conditions on `quote` and `string` .

#### Parameters

string | string to XML 1.0 escape (UTF-8) |
len | length of string |
quote | optional quote character to escape for attribute content, or 0 |
iostr | the raptor_iostream to write to |

#### Returns

non 0 on failure

### raptor_xml_name_check ()

    int
    raptor_xml_name_check (const char *string,
                           size_t length,
                           int xml_version);

Check a string is a legal XML name (and legal UTF8).

xml_version is either 10 (for XML 1.0) or 11 for (XML 1.1). Any other version fails.

#### Parameters

string | UTF-8 name string |
length | length of string |
xml_version | XML version |

#### Returns

Non 0 if the string is a legal XML name

## Types and Values

### raptor_xml_element

    raptor_xml_element* raptor_xml_element;

Raptor XML Element class

### raptor_xml_writer

    raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class