## XML

XML — XML and XML Writer

## Synopsis

    typedef             raptor_xml_element;
    raptor_xml_element *  raptor_new_xml_element            (raptor_qname *name,
                                                             const unsigned char *xml_language,
                                                             raptor_uri *xml_base);
    raptor_xml_element *  raptor_new_xml_element_from_namespace_local_name
                                                            (raptor_namespace *ns,
                                                             const unsigned char *name,
                                                             const unsigned char *xml_language,
                                                             raptor_uri *xml_base);
    void                raptor_free_xml_element             (raptor_xml_element *element);
    raptor_qname *      raptor_xml_element_get_name         (raptor_xml_element *xml_element);
    raptor_qname **     raptor_xml_element_get_attributes   (raptor_xml_element *xml_element);
    int                 raptor_xml_element_get_attributes_count
                                                            (raptor_xml_element *xml_element);
    void                raptor_xml_element_set_attributes   (raptor_xml_element *xml_element,
                                                             raptor_qname **attributes,
                                                             int count);
    int                 raptor_xml_element_declare_namespace
                                                            (raptor_xml_element *xml_element,
                                                             raptor_namespace *nspace);
    int                 raptor_xml_element_is_empty         (raptor_xml_element *xml_element);
    const unsigned char *  raptor_xml_element_get_language  (raptor_xml_element *xml_element);
    int                 raptor_xml_element_write            (raptor_xml_element *element,
                                                             raptor_namespace_stack *nstack,
                                                             int is_empty,
                                                             int is_end,
                                                             int depth,
                                                             raptor_iostream *iostr);
    raptor_xml_writer *  raptor_new_xml_writer              (raptor_world *world,
                                                             raptor_namespace_stack *nstack,
                                                             raptor_iostream *iostr);
    void                raptor_free_xml_writer              (raptor_xml_writer *xml_writer);
    void                raptor_xml_writer_empty_element     (raptor_xml_writer *xml_writer,
                                                             raptor_xml_element *element);
    void                raptor_xml_writer_start_element     (raptor_xml_writer *xml_writer,
                                                             raptor_xml_element *element);
    void                raptor_xml_writer_end_element       (raptor_xml_writer *xml_writer,
                                                             raptor_xml_element *element);
    void                raptor_xml_writer_cdata             (raptor_xml_writer *xml_writer,
                                                             const unsigned char *s);
    void                raptor_xml_writer_cdata_counted     (raptor_xml_writer *xml_writer,
                                                             const unsigned char *s,
                                                             unsigned int len);
    void                raptor_xml_writer_raw               (raptor_xml_writer *xml_writer,
                                                             const unsigned char *s);
    void                raptor_xml_writer_raw_counted       (raptor_xml_writer *xml_writer,
                                                             const unsigned char *s,
                                                             unsigned int len);
    void                raptor_xml_writer_comment           (raptor_xml_writer *xml_writer,
                                                             const unsigned char *s);
    void                raptor_xml_writer_comment_counted   (raptor_xml_writer *xml_writer,
                                                             const unsigned char *s,
                                                             unsigned int len);
    void                raptor_xml_writer_flush             (raptor_xml_writer *xml_writer);
    void                raptor_xml_writer_newline           (raptor_xml_writer *xml_writer);
    int                 raptor_xml_writer_get_depth         (raptor_xml_writer *xml_writer);
    int                 raptor_xml_writer_set_option        (raptor_xml_writer *xml_writer,
                                                             raptor_option option,
                                                             char *string,
                                                             int integer);
    int                 raptor_xml_writer_get_option        (raptor_xml_writer *xml_writer,
                                                             raptor_option option,
                                                             char **string_p,
                                                             int *integer_p);
    typedef             raptor_xml_writer;
    int                 raptor_xml_escape_string_any        (raptor_world *world,
                                                             const unsigned char *string,
                                                             size_t len,
                                                             unsigned char *buffer,
                                                             size_t length,
                                                             char quote,
                                                             int xml_version);
    int                 raptor_xml_escape_string_any_write  (const unsigned char *string,
                                                             size_t len,
                                                             char quote,
                                                             int xml_version,
                                                             raptor_iostream *iostr);
    int                 raptor_xml_escape_string            (raptor_world *world,
                                                             const unsigned char *string,
                                                             size_t len,
                                                             unsigned char *buffer,
                                                             size_t length,
                                                             char quote);
    int                 raptor_xml_escape_string_write      (const unsigned char *string,
                                                             size_t len,
                                                             char quote,
                                                             raptor_iostream *iostr);
    int                 raptor_xml_name_check               (const unsigned char *string,
                                                             size_t length,
                                                             int xml_version);

## Description

XML elements with optional attributes and an XML Writer class that can format raptor_xml_element into output forms, with optional "pretty printing" features such as indenting and collapsing empty elements.

Also includes a utility function raptor_xml_name_check for checking a name is legal in some XML version.

## Details

### raptor_xml_element

    raptor_xml_element* raptor_xml_element;

Raptor XML Element class

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

`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 unsigned 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.

`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.

`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

`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.

`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.

`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.

`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.

`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.

`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.

`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

`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

`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

`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.

`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.

`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.

`xml_writer` : | XML writer object
`element` : | XML element object

### raptor_xml_writer_cdata ()

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

Write CDATA XML-escaped to the XML writer.

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

`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 unsigned 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.

`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 unsigned char *s);

Write a string raw to the XML writer.

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

`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 unsigned 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.

`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 unsigned char *s);

Write an XML comment to the XML writer.

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

`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 unsigned 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.

`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.

`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.

`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

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

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

`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_writer

    raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class

### raptor_xml_escape_string_any ()

    int                 raptor_xml_escape_string_any        (raptor_world *world,
                                                             const unsigned 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.

`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 unsigned 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.

`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 unsigned 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.

`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 unsigned 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`.

`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 unsigned 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.

`string` : | UTF-8 name string
`length` : | length of string
`xml_version` : | XML version
Returns : | Non 0 if the string is a legal XML name