XML

## XML XML — XML and XML Writer |

## Synopsis

    typedef     raptor_xml_element;
    raptor_xml_element* raptor_new_xml_element  (raptor_qname *name,
                                                 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);
    raptor_xml_writer* raptor_new_xml_writer    (raptor_namespace_stack *nstack,
                                                 raptor_uri_handler *uri_handler,
                                                 void *uri_context,
                                                 raptor_iostream *iostr,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data,
                                                 int canonicalize);
    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,
                                                 unsigned char *s);
    void        raptor_xml_writer_cdata_counted (raptor_xml_writer *xml_writer,
                                                 unsigned char *s,
                                                 unsigned int len);
    void        raptor_xml_writer_raw           (raptor_xml_writer *xml_writer,
                                                 unsigned char *s);
    void        raptor_xml_writer_raw_counted   (raptor_xml_writer *xml_writer,
                                                 unsigned char *s,
                                                 unsigned int len);
    void        raptor_xml_writer_comment       (raptor_xml_writer *xml_writer,
                                                 unsigned char *s);
    void        raptor_xml_writer_comment_counted
                                                (raptor_xml_writer *xml_writer,
                                                 unsigned char *s,
                                                 unsigned int len);
    int         raptor_xml_writer_features_enumerate
                                                (const raptor_feature feature,
                                                 const char **name,
                                                 raptor_uri **uri,
                                                 const char **label);
    int         raptor_xml_writer_set_feature   (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature,
                                                 int value);
    int         raptor_xml_writer_set_feature_string
                                                (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature,
                                                 unsigned char *value);
    int         raptor_xml_writer_get_feature   (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature);
    const unsigned char* raptor_xml_writer_get_feature_string
                                                (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature);
    int         raptor_iostream_write_xml_element
                                                (raptor_iostream *iostr,
                                                 raptor_xml_element *element,
                                                 raptor_namespace_stack *nstack,
                                                 int is_empty,
                                                 int is_end,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data,
                                                 int depth);
    typedef     raptor_xml_writer;
    int         raptor_xml_any_escape_string    (unsigned char *string,
                                                 size_t len,
                                                 unsigned char *buffer,
                                                 size_t length,
                                                 char quote,
                                                 int xml_version,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);
    int         raptor_xml_escape_string        (unsigned char *string,
                                                 size_t len,
                                                 unsigned char *buffer,
                                                 size_t length,
                                                 char quote,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);
    int         raptor_iostream_write_xml_any_escaped_string
                                                (raptor_iostream *iostr,
                                                 unsigned char *string,
                                                 size_t len,
                                                 char quote,
                                                 int xml_version,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);
    int         raptor_iostream_write_xml_escaped_string
                                                (raptor_iostream *iostr,
                                                 unsigned char *string,
                                                 size_t len,
                                                 char quote,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);
    int         raptor_xml_name_check           (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,
                                                 unsigned char *xml_language,
                                                 raptor_uri *xml_base);

Constructor - create a new XML element

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

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

    raptor_xml_writer* raptor_new_xml_writer    (raptor_namespace_stack *nstack,
                                                 raptor_uri_handler *uri_handler,
                                                 void *uri_context,
                                                 raptor_iostream *iostr,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data,
                                                 int canonicalize);

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

`nstack` : | Namespace stack for the writer to start with (or NULL)
`uri_handler` : | URI handler function
`uri_context` : | URI handler context data
`iostr` : | I/O stream to write to
`error_handler` : | error handler function
`error_data` : | error handler data
`canonicalize` : | unused
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 feature 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 feature AUTO_EMPTY is enabled.

Indents the start element if XML writer feature 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 feature 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,
                                                 unsigned char *s);

Write CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer feature 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,
                                                 unsigned char *s,
                                                 unsigned int len);

Write counted CDATA XML-escaped to the XML writer.

Closes any previous empty element if XML writer feature 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,
                                                 unsigned char *s);

Write a string raw to the XML writer.

Closes any previous empty element if XML writer feature 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,
                                                 unsigned char *s,
                                                 unsigned int len);

Write a counted string raw to the XML writer.

Closes any previous empty element if XML writer feature 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,
                                                 unsigned char *s);

Write an XML comment to the XML writer.

Closes any previous empty element if XML writer feature 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,
                                                 unsigned char *s,
                                                 unsigned int len);

Write a counted XML comment to the XML writer.

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

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

### raptor_xml_writer_features_enumerate ()

    int         raptor_xml_writer_features_enumerate
                                                (const raptor_feature feature,
                                                 const char **name,
                                                 raptor_uri **uri,
                                                 const char **label);

Get list of xml_writer features.

If uri is not NULL, a pointer toa new raptor_uri is returned that must be freed by the caller with `raptor_free_uri()`.

`feature` : | feature enumeration (0+)
`name` : | pointer to store feature short name (or NULL)
`uri` : | pointer to store feature URI (or NULL)
`label` : | pointer to feature label (or NULL)
Returns : | 0 on success, <0 on failure, >0 if feature is unknown

### raptor_xml_writer_set_feature ()

    int         raptor_xml_writer_set_feature   (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature,
                                                 int value);

Set xml_writer features with integer values.

The allowed features are available via `raptor_features_enumerate()`.

`xml_writer` : | raptor_xml_writer xml_writer object
`feature` : | feature to set from enumerated raptor_feature values
`value` : | integer feature value (0 or larger)
Returns : | non 0 on failure or if the feature is unknown

### raptor_xml_writer_set_feature_string ()

    int         raptor_xml_writer_set_feature_string
                                                (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature,
                                                 unsigned char *value);

Set xml_writer features with string values.

The allowed features are available via `raptor_xml_writer_features_enumerate()`. If the feature type is integer, the value is interpreted as an integer.

`xml_writer` : | raptor_xml_writer xml_writer object
`feature` : | feature to set from enumerated raptor_feature values
`value` : | feature value
Returns : | non 0 on failure or if the feature is unknown

### raptor_xml_writer_get_feature ()

    int         raptor_xml_writer_get_feature   (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature);

Get various xml_writer features.

The allowed features are available via `raptor_features_enumerate()`.

Note: no feature value is negative

`xml_writer` : | raptor_xml_writer serializer object
`feature` : | feature to get value
Returns : | feature value or < 0 for an illegal feature

### raptor_xml_writer_get_feature_string ()

    const unsigned char* raptor_xml_writer_get_feature_string
                                                (raptor_xml_writer *xml_writer,
                                                 raptor_feature feature);

Get xml_writer features with string values.

The allowed features are available via `raptor_features_enumerate()`.

`xml_writer` : | raptor_xml_writer serializer object
`feature` : | feature to get value
Returns : | feature value or NULL for an illegal feature or no value

### raptor_iostream_write_xml_element ()

    int         raptor_iostream_write_xml_element
                                                (raptor_iostream *iostr,
                                                 raptor_xml_element *element,
                                                 raptor_namespace_stack *nstack,
                                                 int is_empty,
                                                 int is_end,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data,
                                                 int depth);

Write a formatted XML element to a raptor_iostream

`iostr` : | iostream object
`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)
`error_handler` : | error handler function
`error_data` : | error handler function data
`depth` : | XML element depth
Returns : | non-0 on failure

### raptor_xml_writer

    raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class

### raptor_xml_any_escape_string ()

    int         raptor_xml_any_escape_string    (unsigned char *string,
                                                 size_t len,
                                                 unsigned char *buffer,
                                                 size_t length,
                                                 char quote,
                                                 int xml_version,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);

Return an XML-escaped version a string.

Follows Canonical XML rules on Text Nodes and Attribute Nodes http://www.w3.org/TR/xml-c14nProcessingModel

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.

`string` : | string to XML escape (UTF-8)
`len` : | length of string
`buffer` : | the buffer to use for new string (UTF-8)
`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)
`error_handler` : | error handler function
`error_data` : | error handler user data
Returns : | the number of bytes required / used or <0 on failure.

### raptor_xml_escape_string ()

    int         raptor_xml_escape_string        (unsigned char *string,
                                                 size_t len,
                                                 unsigned char *buffer,
                                                 size_t length,
                                                 char quote,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);

Return an XML 1.0-escaped version a string.

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

`string` : | string to XML 1.0 escape (UTF-8)
`len` : | length of string
`buffer` : | the buffer to use for new string (UTF-8)
`length` : | buffer size
`quote` : | optional quote character to escape for attribute content, or 0
`error_handler` : | error handler function
`error_data` : | error handler user data
Returns : | the number of bytes required / used or <0 on failure.

### raptor_iostream_write_xml_any_escaped_string ()

    int         raptor_iostream_write_xml_any_escaped_string
                                                (raptor_iostream *iostr,
                                                 unsigned char *string,
                                                 size_t len,
                                                 char quote,
                                                 int xml_version,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);

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.

`iostr` : | the raptor_iostream to write to
`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)
`error_handler` : | error handler function
`error_data` : | error handler data
Returns : | non 0 on failure

### raptor_iostream_write_xml_escaped_string ()

    int         raptor_iostream_write_xml_escaped_string
                                                (raptor_iostream *iostr,
                                                 unsigned char *string,
                                                 size_t len,
                                                 char quote,
                                                 raptor_simple_message_handler error_handler,
                                                 void *error_data);

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

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

`iostr` : | the raptor_iostream to write to
`string` : | string to XML 1.0 escape (UTF-8)
`len` : | length of string
`quote` : | optional quote character to escape for attribute content, or 0
`error_handler` : | error handler function
`error_data` : | error handler data
Returns : | non 0 on failure

### raptor_xml_name_check ()

    int         raptor_xml_name_check           (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