XML

XML — XML and XML Writer

Types and Values

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.

Functions

raptor_new_xml_element ()

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

Constructor - create a new XML element from a QName

The xml_language and xml_base become owned by the new object.

Parameters

name

The XML element name

 

xml_language

the in-scope XML language (or NULL)

 

xml_base

the in-scope XML base URI (or NULL)

 

Returns

a new raptor_xml_element or NULL on failure


raptor_new_xml_element_from_namespace_local_name ()

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

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

Added in 1.4.16.

Parameters

ns

namespace

 

name

the XML element local name

 

xml_language

the in-scope XML language (or NULL)

 

xml_base

base uri (or NULL)

 

Returns

a new raptor_xml_element or NULL on failure


raptor_free_xml_element ()

void
raptor_free_xml_element (raptor_xml_element *element);

Destructor - destroy a raptor_xml_element object.

Parameters

element

XML Element

 

raptor_xml_element_get_name ()

raptor_qname *
raptor_xml_element_get_name (raptor_xml_element *xml_element);

Get the XML Name of an XML element

Parameters

xml_element

XML Element

 

Returns

The Name.


raptor_xml_element_get_attributes ()

raptor_qname **
raptor_xml_element_get_attributes (raptor_xml_element *xml_element);

Get the array of attributes on the XML element.

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

Parameters

xml_element

XML Element

 

Returns

the array of qnames or NULL if none are present.


raptor_xml_element_get_attributes_count ()

int
raptor_xml_element_get_attributes_count
                               (raptor_xml_element *xml_element);

Get the number of attributes on the XML element.

Parameters

xml_element

XML Element

 

Returns

Integer number of attributes - 0 or more.


raptor_xml_element_set_attributes ()

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

Set the attributes on an XML element.

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

Parameters

xml_element

XML Element

 

attributes

Array of XML Qname attributes with values

 

count

Length of array

 

raptor_xml_element_declare_namespace ()

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

Declare a namespace on the XML Element.

Parameters

xml_element

XML Element

 

nspace

raptor_namespace to declare

 

Returns

non-0 if namespace cannot be declared


raptor_xml_element_is_empty ()

int
raptor_xml_element_is_empty (raptor_xml_element *xml_element);

Check if an XML Element is empty.

Parameters

xml_element

XML Element

 

Returns

non-0 if the element is empty.


raptor_xml_element_get_language ()

const unsigned char *
raptor_xml_element_get_language (raptor_xml_element *xml_element);

Get the XML language of the element.

Parameters

xml_element

XML Element

 

Returns

XML language or NULL if none in scope


raptor_xml_element_write ()

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

Write a formatted XML element to a raptor_iostream

Parameters

element

XML element to format

 

nstack

Namespace stack context to use in formatting

 

is_empty

non-0 if element is empty

 

is_end

non-0 if this is an end element (else is a start element)

 

depth

XML element depth

 

iostr

iostream object

 

Returns

non-0 on failure


raptor_new_xml_writer ()

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

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

Parameters

world

raptor_world object

 

nstack

Namespace stack for the writer to start with (or NULL)

 

iostr

I/O stream to write to

 

Returns

a new raptor_xml_writer object or NULL on failure


raptor_free_xml_writer ()

void
raptor_free_xml_writer (raptor_xml_writer *xml_writer);

Destructor - Free XML Writer

Parameters

xml_writer

XML writer object

 

raptor_xml_writer_empty_element ()

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

Write an empty XML element to the XML writer.

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

Parameters

xml_writer

XML writer object

 

element

XML element object

 

raptor_xml_writer_start_element ()

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

Write a start XML element to the XML writer.

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

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

Parameters

xml_writer

XML writer object

 

element

XML element object

 

raptor_xml_writer_end_element ()

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

Write an end XML element to the XML writer.

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

Parameters

xml_writer

XML writer object

 

element

XML element object

 

raptor_xml_writer_cdata ()

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

Write CDATA XML-escaped to the XML writer.

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

Parameters

xml_writer

XML writer object

 

s

string to XML escape and write

 

raptor_xml_writer_cdata_counted ()

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

Write counted CDATA XML-escaped to the XML writer.

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

Parameters

xml_writer

XML writer object

 

s

string to XML escape and write

 

len

length of string

 

raptor_xml_writer_raw ()

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

Write a string raw to the XML writer.

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

Parameters

xml_writer

XML writer object

 

s

string to write

 

raptor_xml_writer_raw_counted ()

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

Write a counted string raw to the XML writer.

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

Parameters

xml_writer

XML writer object

 

s

string to write

 

len

length of string

 

raptor_xml_writer_comment ()

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

Write an XML comment to the XML writer.

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

Parameters

xml_writer

XML writer object

 

s

comment string to write

 

raptor_xml_writer_comment_counted ()

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

Write a counted XML comment to the XML writer.

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

Parameters

xml_writer

XML writer object

 

s

comment string to write

 

len

length of string

 

raptor_xml_writer_flush ()

void
raptor_xml_writer_flush (raptor_xml_writer *xml_writer);

Finish the XML writer.

Parameters

xml_writer

XML writer object

 

raptor_xml_writer_newline ()

void
raptor_xml_writer_newline (raptor_xml_writer *xml_writer);

Write a newline to the XML writer.

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

Parameters

xml_writer

XML writer object

 

raptor_xml_writer_get_depth ()

int
raptor_xml_writer_get_depth (raptor_xml_writer *xml_writer);

Get the current XML Writer element depth

Parameters

xml_writer

raptor_xml_writer xml writer object

 

Returns

element stack depth


raptor_xml_writer_set_option ()

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

Set xml_writer option.

If string is not NULL and the option type is numeric, the string value is converted to an integer and used in preference to integer .

If string is NULL and the option type is not numeric, an error is returned.

The string values used are copied.

The allowed options are available via raptor_world_get_option_description().

Parameters

xml_writer

raptor_xml_writer xml_writer object

 

option

option to set from enumerated raptor_option values

 

string

string option value (or NULL)

 

integer

integer option value

 

Returns

non 0 on failure or if the option is unknown


raptor_xml_writer_get_option ()

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

Get xml_writer option.

Any string value returned in *string_p is shared and must be copied by the caller.

The allowed options are available via raptor_world_get_option_description().

Parameters

xml_writer

raptor_xml_writer xml_writer object

 

option

option to get value

 

string_p

pointer to where to store string value

 

integer_p

pointer to where to store integer value

 

Returns

option value or < 0 for an illegal option


raptor_xml_escape_string_any ()

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

Return an XML-escaped version a string.

Follows

Canonical XML rules on Text Nodes and Attribute Nodes

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

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

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

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

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

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

Parameters

world

raptor world

 

string

string to XML escape (UTF-8)

 

len

length of string

 

buffer

the buffer to use for new string (UTF-8) or NULL to just calculate expected length

 

length

buffer size

 

quote

optional quote character to escape for attribute content, or 0

 

xml_version

XML 1.0 (10) or XML 1.1 (11)

 

Returns

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


raptor_xml_escape_string_any_write ()

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

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

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

Parameters

string

string to XML escape (UTF-8)

 

len

length of string

 

quote

optional quote character to escape for attribute content, or 0

 

xml_version

XML version - 10 (XML 1.0) or 11 (XML 1.1)

 

iostr

the raptor_iostream to write to

 

Returns

non 0 on failure


raptor_xml_escape_string ()

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

Return an XML 1.0-escaped version a string.

See raptor_xml_escape_string_any() for the conditions on parameters.

Parameters

world

raptor world

 

string

string to XML 1.0 escape (UTF-8)

 

len

length of string

 

buffer

the buffer to use for new string (UTF-8) or NULL to just calculate expected length.

 

length

buffer size

 

quote

optional quote character to escape for attribute content, or 0

 

Returns

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


raptor_xml_escape_string_write ()

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

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

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

Parameters

string

string to XML 1.0 escape (UTF-8)

 

len

length of string

 

quote

optional quote character to escape for attribute content, or 0

 

iostr

the raptor_iostream to write to

 

Returns

non 0 on failure


raptor_xml_name_check ()

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

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

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

Parameters

string

UTF-8 name string

 

length

length of string

 

xml_version

XML version

 

Returns

Non 0 if the string is a legal XML name

Types and Values

raptor_xml_element

raptor_xml_element* raptor_xml_element;

Raptor XML Element class


raptor_xml_writer

raptor_xml_writer* raptor_xml_writer;

Raptor XML Writer class



Navigation: Redland Home Page

Copyright 2000-2023 Dave Beckett