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);
    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_xml_element

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

### raptor_free_xml_element ()

    void        raptor_free_xml_element         (raptor_xml_element *element);

Destructor - destroy a raptor_xml_element object.

element :

  XML Element

raptor_free_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_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

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

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

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

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

### raptor_free_xml_writer ()

    void        raptor_free_xml_writer          (raptor_xml_writer *xml_writer);

Destructor - Free XML Writer

xml_writer :

  XML writer object

raptor_free_xml_writer

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### raptor_xml_writer

    raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class

raptor_xml_writer

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

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

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

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

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

raptor_xml_name_check