section-xml: Raptor RDF Syntax Library Manual

+ + +

section-xml

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+raptor_xml_element * +	+raptor_new_xml_element () +
+raptor_xml_element * +	+raptor_new_xml_element_from_namespace_local_name () +
+void +	+raptor_free_xml_element () +
+raptor_qname * +	+raptor_xml_element_get_name () +
+raptor_qname ** +	+raptor_xml_element_get_attributes () +
+int +	+raptor_xml_element_get_attributes_count () +
+void +	+raptor_xml_element_set_attributes () +
+int +	+raptor_xml_element_declare_namespace () +
+int +	+raptor_xml_element_is_empty () +
const unsigned char * +	+raptor_xml_element_get_language () +
+int +	+raptor_xml_element_write () +
+raptor_xml_writer * +	+raptor_new_xml_writer () +
+void +	+raptor_free_xml_writer () +
+void +	+raptor_xml_writer_empty_element () +
+void +	+raptor_xml_writer_start_element () +
+void +	+raptor_xml_writer_end_element () +
+void +	+raptor_xml_writer_cdata () +
+void +	+raptor_xml_writer_cdata_counted () +
+void +	+raptor_xml_writer_raw () +
+void +	+raptor_xml_writer_raw_counted () +
+void +	+raptor_xml_writer_comment () +
+void +	+raptor_xml_writer_comment_counted () +
+void +	+raptor_xml_writer_flush () +
+void +	+raptor_xml_writer_newline () +
+int +	+raptor_xml_writer_get_depth () +
+int +	+raptor_xml_writer_set_option () +
+int +	+raptor_xml_writer_get_option () +
+int +	+raptor_xml_escape_string_any () +
+int +	+raptor_xml_escape_string_any_write () +
+int +	+raptor_xml_escape_string () +
+int +	+raptor_xml_escape_string_write () +
+int +	+raptor_xml_name_check () +

Types and Values

++++ + + + + + + + + + + +

typedef	raptor_xml_element
typedef	raptor_xml_writer

Description

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 & and < +respectively, preserving other characters.

Text Nodes: + > is turned into > + #xD is turned into 

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

If quote + is given it can be either of '\'' or '\"' +which will be turned into ' or +" 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