XML
3
RAPTOR Library

# 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);
    raptor_xml_element* raptor_new_xml_element_from_namespace_local_name
                                                            (raptor_namespace *ns,
                                                             unsigned char *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);
    const unsigned char* raptor_xml_element_get_language    (raptor_xml_element *xml_element);
    raptor_xml_writer*  raptor_new_xml_writer               (raptor_namespace_stack *nstack,
                                                             const 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);
    void                raptor_xml_writer_flush             (raptor_xml_writer *xml_writer);
    void                raptor_xml_writer_newline           (raptor_xml_writer *xml_writer);
    int                 raptor_xml_writer_features_enumerate
                                                            (const raptor_feature feature,
                                                             const char **name,
                                                             raptor_uri **uri,
                                                             const char **label);
    int                 raptor_xml_writer_get_depth         (raptor_xml_writer *xml_writer);
    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 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,
                                                             unsigned char *name,
                                                             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_new_xml_writer ()

    raptor_xml_writer*  raptor_new_xml_writer               (raptor_namespace_stack *nstack,
                                                             const 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_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 feature AUTO_INDENT is enabled.

`xml_writer` :

  XML writer object

### 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 to a 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_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_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 xml writer 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 xml writer 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