Module exmpp_xml

The module exmpp_xml is an XML parser based on Expat.

Behaviours: gen_server.

Authors: Jean-Sébastien Pédron (js.pedron@meetic-corp.com).

Description

The module exmpp_xml is an XML parser based on Expat.

It provides a set of functions to prepare a tree of the elements from an XML stream or an XML document. To ease the handling of the tree produced by the parsing, it also export functions to access each parts of an element.

Namespace support is fully tested and is now ready for production use.

A backward compatible layer, built on top of this module, is provided by xml.

Data Types

pathcomponent()

pathcomponent() = {element, Elem_Name} | {element, NS, Elem_Name} | {attribute, Attr_Name} | {attribute, NS, Attr_Name} | cdata | cdata_as_list

Represents a path component. The elem tuple points to an XML element named Elem_Name. The attr tuple points to the value of the Attr_Name attribute. cdata asks for the character data of a node.

xmlattr()

xmlattr() = {xmlattr, NS, Name, Value}

Represents an tag attribute.

xmlattr_old()

xmlattr_old() = {Name, Value}

Represents an tag attribute.

xmlcdata()

xmlcdata() = {xmlcdata, CData}

Record representing characters data inside an XML element.

xmlel()

xmlel() = {xmlel, NS, Declared_NS, Name, Attrs, Children}

Record representing an XML element (or only the opening tag).



Declared_NS lists all the namespaces declared in this element, even if they're not used by it.

xmlel_old()

xmlel_old() = {xmlelement, Name, Attrs, Children}

Record representing an XML tag.

xmlendtag()

xmlendtag() = {xmlendtag, NS, Name}

Record representing an XML end tag, for nodes above the configured root_depth (see xmlparseroption()).

xmlparser()

abstract datatype: xmlparser()

Handler for the Expat parser, initialized with a call to start_parser/0.

xmlparseroption()

xmlparseroption() = Engine | Namespace_Option | Names_Format | Checks | Stanza_Max_Size | Root_Depth | Send_End_Element | Autoload_Known

Options of the form {Key, bool()} can be specified as Key. See proplists.



The engine option allows one to choose the engine to use. Available engines list can be retrived with get_engine_names/0.



The max_size option limits the size in bytes of a stanza to avoid deny of service at the parser level. Actually, this limit is only verified against the length of the data provided and the counter is reset to zero when an element is found. The caveats is that if the limits is, eg., 15 and the data is <foo></foo><bar></bar>, the parser will return an error because the whole chunk is 22 bytes, despite each stanza contains 11 bytes.

Function Index

add_known_attrs/2Tell parsers that Attr are known element attributes.
add_known_elems/2Tell parsers that Names_List are known element names.
add_known_nss/2Tell parsers that NS_List are known namespaces.
append_cdata/2Append Child to XML_Element's children list.
append_cdata_to_list/2Append CData to Children list.
append_child/2Append Child to XML_Element's children list.
append_children/2Append every Children to XML_Element's children list.
attribute/2Create an XML attribute with the name Name.
attribute/3Create an XML attribute with the name Name in the namespace NS.
attribute_matches/2Tell if Attr is named Name.
attribute_matches/3Tell if Attr has the namespace NS and is named Name.
cdata/1Create a CData node from a value.
clear_endtag_tuples/1Remove any xmlendtag() from the list of XML elements.
declare_ns_here/3Declare the given namespace in this element.
deindent_document/1Recursively remove text nodes containing only whitespaces.
document_to_binary/1Serialize an XML document to text.
document_to_iolist/1Serialize an XML document to text.
document_to_list/1Serialize an XML document to text.
element/1Create an XML element with the name Name but no namespace.
element/2Create an XML element with the name Name in the namespace NS.
element/4Create an XML element with the name Name in the namespace NS.
element_matches/2Tell if XML_Element is named Name.
element_matches/3Tell if XML_Element has the namespace NS and is named Name.
element_matches_by_ns/2Tell if XML_Element has the namespace NS.
escape_using_cdata/1Escape text using CDATA sections.
escape_using_entities/1Replace sensible characters with entities.
filter/2Remove any children for which Pred(Child) doesn't return true.
fold/3Call Fun for each XML_Element's children and return the last accumulator.
foreach/2Call Fun for each XML_Element's children.
get_attribute/3Return the value of the attribute named Attr_Name.
get_attribute/4Return the value of the attribute named Attr_Name with the NS namespace URI.
get_attribute_as_binary/3Return the value of the attribute named Attr_Name, as a binary().
get_attribute_as_binary/4Return the value of the attribute named Attr_Name with the NS namespace URI, as a binary().
get_attribute_as_list/3Return the value of the attribute named Attr_Name, as a list().
get_attribute_as_list/4Return the value of the attribute named Attr_Name with the NS namespace URI, as a list().
get_attribute_from_list/3Return the value of the attribute named Attr_Name from the list.
get_attribute_from_list/4Return the value of the attribute named Attr_Name from the list with the NS namespace URI.
get_attribute_from_list_as_binary/3Return the value of the attribute named Attr_Name from the list, as a binary().
get_attribute_from_list_as_binary/4Return the value of the attribute named Attr_Name with the NS namespace URI from the list, as a binary().
get_attribute_from_list_as_list/3Return the value of the attribute named Attr_Name from the list, as a list().
get_attribute_from_list_as_list/4Return the value of the attribute named Attr_Name with the NS namespace URI from the list, as a list().
get_attribute_node/2Return the attribute named Attr_Name.
get_attribute_node/3Return the attribute named Attr_Name with the NS namespace URI.
get_attribute_node_from_list/2Return the attribute named Attr_Name from the list.
get_attribute_node_from_list/3Return the attribute named Attr_Name from the list with the NS namespace URI.
get_cdata/1Concatenate and return any character data of the given XML element.
get_cdata_as_list/1Concatenate and return any character data of the given XML element.
get_cdata_from_list/1Concatenate and return any character data from the given children list.
get_cdata_from_list_as_list/1Concatenate and return any character data from the given children list.
get_child_elements/1Get all the element children of the given element, skipping non-element nodes likes cdata.
get_element/2Search in the children of XML_Element an element named Name.
get_element/3Search in the children of XML_Element an element named Name with NS namespace URI.
get_element_by_ns/2Search in the children of XML_Element the first element with NS namespace URI.
get_elements/2Search in the children of XML_Element for all the elements named Name
get_elements/3Search in the children of XML_Element for all the elements named Name with NS namespace URI.
get_engine_driver/1Return the port driver name associated to the given engine.
get_engine_names/0Return the list of XML engines.
get_name_as_atom/1Return the name of an element as atom, regardless of the original encoding.
get_name_as_list/1Return the name of an element as list, regardless of the original encoding.
get_ns_as_atom/1Return the namespace as an atom, regardless of the original encoding.
get_ns_as_list/1Return the namespace as a string, regardless of the original encoding.
get_path/2Follow the given path and return what's pointed by the last component of it.
has_attribute/2Check the presence for attribute Attr_Name in the XML element.
has_attribute/3Check the presence for attribute Attr_Name with namespace NS in the XML element.
has_attribute_in_list/2Check the presence for attribute Attr_Name in the list.
has_attribute_in_list/3Check the presence for attribute Attr_Name with namespace NS in the list.
has_element/2Check the presence for element Name in the children.
has_element/3Check the presence for element Name with NS namespace URI in the children.
has_element_by_ns/2Check the presence for any elements with NS namespace URI in the children.
indent_document/2Add whitespaces text nodes to indent the document.
indent_document/3Add whitespaces text nodes to indent the document.
internal_escaping_function_name/0Tell what escaping function will be used internally.
is_engine_available/1Tell if Engine_Name is available.
is_ns_declared_here/2Tell if NS was declared within this element.
is_whitespace/1Tell if a text node contains only whitespaces.
map/2Apply Fun on each child and replace the original one with the function return value.
node_to_binary/3Serialize an XML node to text.
node_to_iolist/3Serialize an XML node to text.
node_to_list/3Serialize an XML node to text.
normalize_cdata/1Regroup all splitted xmlcdata() in a unique one and remove empty ones.
normalize_cdata_in_list/1Regroup all splitted xmlcdata() in a unique one.
parse/2Parse a chunk from an XML stream.
parse_document/1Parse an entire XML document at once.
parse_document/2Parse an entire XML document at once.
parse_document_fragment/1Parse a fragment of an XML document at once.
parse_document_fragment/2Parse a fragment of an XML document at once.
parse_final/2Parse the last chunk from an XML stream.
prepend_child/2Prepend Child to XML_Element's children list.
prepend_children/2Prepend every Children to XML_Element's children list.
register_engine/2Add a new XML engine.
register_engine/3Add a new XML engine.
remove_attribute/2Remove attribute named Attr_Name and return the new element.
remove_attribute/3Remove attribute named Attr_Name with the NS namespace URI and return the new element.
remove_attribute_from_list/2Remove attribute named Attr_Name and return the new list.
remove_attribute_from_list/3Remove attribute named Attr_Name with the NS namespace URI and return the new list.
remove_cdata/1Remove any character data from the given XML element.
remove_cdata_from_list/1Remove any character data from the given XML element children list.
remove_element/2Remove the first child with the name Name.
remove_element/3Remove the first child with the name Name in the namespace NS.
remove_element_by_ns/2Remove the first child in the namespace NS.
remove_elements/2Remove all children with the name Name.
remove_elements/3Remove all children with the name Name in the namespace NS.
remove_elements_by_ns/2Remove all children in the namespace NS.
remove_whitespaces/1Remove text nodes containing only whitespaces.
remove_whitespaces_deeply/1Remove text nodes containing only whitespaces in every elements in the given tree.
remove_whitespaces_from_list/1Remove text nodes containing only whitespaces.
replace_child/3Replace Old_Child by New_Child in XML_Element children list.
reset_parser/1Reset the parser with the same previous options.
reset_parser/2Reset the parser and update its options.
set_attribute/2Add a new attribute or change the value of an existing attribute with the same name.
set_attribute/3Add a new attribute or change the value of an existing attribute.
set_attribute/4Add a new attribute or change the value of an existing attribute with the same name and the NS namespace URI.
set_attribute_in_list/2Add a new attribute or change the value of an existing attribute with the same name.
set_attribute_in_list/3Add a new attribute or change the value of an existing attribute with the same name.
set_attribute_in_list/4Add a new attribute or change the value of an existing attribute with the same name and the NS namespace URI.
set_attributes/2Set multiple attributes at a time.
set_cdata/2Replace any character data by CData.
set_cdata_in_list/2Replace any character data by CData in the list.
set_children/2Set XML_Element's children list to Children.
start_parser/0Initialize the Expat port driver with default options.
start_parser/1Initialize the Expat port driver with given Options.
stop_parser/1Stop the Expat port driver.
xmlel_to_xmlelement/1Convert an xmlel() to an xmlel_old() tuple.
xmlel_to_xmlelement/3Convert an xmlel() to an xmlel_old() tuple.
xmlelement_to_xmlel/1Convert an xmlel_old() to an xmlel() tuple.
xmlelement_to_xmlel/3Convert an xmlel_old() to an xmlel() tuple.
xmlelement_to_xmlel_and_nss_tables/3Convert an xmlel_old() to an xmlel() tuple.

Function Details

add_known_attrs/2

add_known_attrs(List_Name, List) -> ok

Tell parsers that Attr are known element attributes.

If check_attrs is enabled, all occurences of these attributes will be represented as an atom().

add_known_elems/2

add_known_elems(List_Name, List) -> ok

Tell parsers that Names_List are known element names.

If check_elems is enabled, all occurences of these names will be represented as an atom().

add_known_nss/2

add_known_nss(List_Name, List) -> ok

Tell parsers that NS_List are known namespaces.

If check_nss is enabled, all occurences of these namespaces will be represented as an atom().

append_cdata/2

append_cdata(Xmlel::XML_Element, CData) -> New_XML_Element

Append Child to XML_Element's children list.

append_cdata_to_list/2

append_cdata_to_list(Children, CData) -> New_Children

Append CData to Children list.

append_child/2

append_child(Xmlel::XML_Element, Child) -> New_XML_Element

Append Child to XML_Element's children list.

append_children/2

append_children(Xmlel::XML_Element, New_Children::Children) -> New_XML_Element

Append every Children to XML_Element's children list.

attribute/2

attribute(Name, Value) -> Attr

Create an XML attribute with the name Name.

This is almost the same as:
  Attr = #xmlattr{name = Name, value = Value}.

attribute/3

attribute(NS, Name, Value) -> Attr

Create an XML attribute with the name Name in the namespace NS.

This is almost the same as:
  Attr = #xmlattr{ns = NS, name = Name, value = Value}.

attribute_matches/2

attribute_matches(Xmlattr::Attr, Name) -> bool()

Tell if Attr is named Name.

It takes care of comparison between string and atom.

attribute_matches/3

attribute_matches(Xmlattr::Attr, NS, Name) -> bool()

Tell if Attr has the namespace NS and is named Name.

It takes care of comparison between string and atom.

cdata/1

cdata(CData::Value) -> CData

Create a CData node from a value.

clear_endtag_tuples/1

clear_endtag_tuples(XML_Elements) -> Cleaned_XML_Elements

Remove any xmlendtag() from the list of XML elements.

This is primarily designed to work on returned value of parse/2 and parse_final/2 when the no_endtag parser option (see xmlparseroption()) wasn't specified at start_parser/1 time.

declare_ns_here/3

declare_ns_here(Xmlel::XML_Element, NS, Prefix) -> New_XML_Element

Declare the given namespace in this element.

deindent_document/1

deindent_document(Xmlel::XML_Element) -> New_XML_Element

Recursively remove text nodes containing only whitespaces.

See also: is_whitespace/1.

document_to_binary/1

document_to_binary(El::XML_Element) -> XML_Text

Serialize an XML document to text.

Converting to binary is about 15% to 20% faster than converting to a list.

document_to_iolist/1

document_to_iolist(El::XML_Element) -> XML_Text

Serialize an XML document to text.

document_to_list/1

document_to_list(El::XML_Element) -> XML_Text

Serialize an XML document to text.

element/1

element(Name) -> XML_Element

Create an XML element with the name Name but no namespace.

Caution: be sure you do not want to set a namespace: it won't be inherited from the parent node!

This is the same as:
  XML_Element = #xmlel{name = Name}.

element/2

element(NS, Name) -> XML_Element

Create an XML element with the name Name in the namespace NS.

This is the same as:
  XML_Element = #xmlel{ns = NS, name = Name}.

element/4

element(NS, Name, Attrs, Children) -> XML_Element

Create an XML element with the name Name in the namespace NS.

This is the same as:
  XML_Element = #xmlel{ns = NS, name = Name}.

element_matches/2

element_matches(Xmlel::XML_Element, Name) -> bool()

Tell if XML_Element is named Name.

It takes care of comparison between string and atom.

element_matches/3

element_matches(Xmlel::XML_Element, NS, Name) -> bool()

Tell if XML_Element has the namespace NS and is named Name.

It takes care of comparison between string and atom.

element_matches_by_ns/2

element_matches_by_ns(Xmlel::XML_Element, NS) -> bool()

Tell if XML_Element has the namespace NS.

It takes care of comparison between string and atom.

escape_using_cdata/1

escape_using_cdata(CData) -> Escaped_CData

Escape text using CDATA sections.

escape_using_entities/1

escape_using_entities(CData) -> Escaped_CData

Replace sensible characters with entities.

Processed characters are &, <, >, ", '.

filter/2

filter(Pred, Xmlel::XML_Element) -> New_XML_Element

Remove any children for which Pred(Child) doesn't return true.

Pred has the following prototype:
  fun(XML_Element, Child) -> bool()
If children is undefined, the function isn't called.

fold/3

fold(Fun, Acc0, Xmlel::XML_Element) -> Acc1

Call Fun for each XML_Element's children and return the last accumulator.

Fun has the following prototype:
  fun(Acc_In, XML_Element, Child) -> Acc_Out

foreach/2

foreach(Fun, Xmlel::XML_Element) -> ok

Call Fun for each XML_Element's children.

Fun return value is ignored.

Fun has the following prototype:
  fun(XML_Element, Child) -> Ignored

get_attribute/3

get_attribute(Xmlel::XML_Element, Name::Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name.

The return type depends on attributes type in XML_Element: Return Default if the attribute isn't found.

get_attribute/4

get_attribute(Xmlel::XML_Element, NS, Name::Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name with the NS namespace URI.

Return Default if the attribute isn't found.

get_attribute_as_binary/3

get_attribute_as_binary(Xmlel::XML_Element, Name::Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name, as a binary().

Return Default if the attribute isn't found.

get_attribute_as_binary/4

get_attribute_as_binary(Xmlel::XML_Element, NS, Name::Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name with the NS namespace URI, as a binary().

Return Default if the attribute isn't found.

get_attribute_as_list/3

get_attribute_as_list(Xmlel::XML_Element, Name::Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name, as a list().

Return Default if the attribute isn't found.

get_attribute_as_list/4

get_attribute_as_list(Xmlel::XML_Element, NS, Name::Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name with the NS namespace URI, as a list().

Return Default if the attribute isn't found.

get_attribute_from_list/3

get_attribute_from_list(Attrs, Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name from the list.

The return type depends on Attrs type: Return Default if the attribute isn't found.

get_attribute_from_list/4

get_attribute_from_list(Attrs, NS, Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name from the list with the NS namespace URI.

Return Default if the attribute isn't found.

get_attribute_from_list_as_binary/3

get_attribute_from_list_as_binary(Attrs, Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name from the list, as a binary().

Return Default if the attribute isn't found.

get_attribute_from_list_as_binary/4

get_attribute_from_list_as_binary(Attrs, NS, Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name with the NS namespace URI from the list, as a binary().

Return Default if the attribute isn't found.

get_attribute_from_list_as_list/3

get_attribute_from_list_as_list(Attrs, Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name from the list, as a list().

Return Default if the attribute isn't found.

get_attribute_from_list_as_list/4

get_attribute_from_list_as_list(Attrs, NS, Attr_Name, Default) -> Attr_Value | Default

Return the value of the attribute named Attr_Name with the NS namespace URI from the list, as a list().

Return Default if the attribute isn't found.

get_attribute_node/2

get_attribute_node(Xmlel::XML_Element, Name::Attr_Name) -> Attr | undefined

Return the attribute named Attr_Name.

Return undefined if the attribute isn't found.

get_attribute_node/3

get_attribute_node(Xmlel::XML_Element, NS, Name::Attr_Name) -> Attr | undefined

Return the attribute named Attr_Name with the NS namespace URI.

Return undefined if the attribute isn't found.

get_attribute_node_from_list/2

get_attribute_node_from_list(Rest::Attrs, Name::Attr_Name) -> Attr | undefined

Return the attribute named Attr_Name from the list.

Return undefined if the attribute isn't found.

get_attribute_node_from_list/3

get_attribute_node_from_list(Rest::Attrs, NS, Name::Attr_Name) -> Attr | undefined

Return the attribute named Attr_Name from the list with the NS namespace URI.

Return undefined if the attribute isn't found.

get_cdata/1

get_cdata(Xmlel::XML_Element) -> CData

Concatenate and return any character data of the given XML element.

This function is get_tag_cdata/1 renamed in get_cdata/1. It doesn't take a list of children like the old get_cdata/1, use get_cdata_from_list/1 for this purpose!

get_cdata_as_list/1

get_cdata_as_list(XML_Element) -> CData

Concatenate and return any character data of the given XML element.

get_cdata_from_list/1

get_cdata_from_list(Children) -> CData

Concatenate and return any character data from the given children list.

get_cdata_from_list_as_list/1

get_cdata_from_list_as_list(Children) -> CData

Concatenate and return any character data from the given children list.

get_child_elements/1

get_child_elements(Xmlel::XML_Element) -> [XML_Subelement]

Get all the element children of the given element, skipping non-element nodes likes cdata.

get_element/2

get_element(Xmlel::XML_Element, Name) -> XML_Subelement | undefined

Search in the children of XML_Element an element named Name.

If no element with the given name is found, it returns undefined. This will only search among direct children.

get_element/3

get_element(Xmlel::XML_Element, NS, Name) -> XML_Subelement | undefined

Search in the children of XML_Element an element named Name with NS namespace URI.

If no element with the given name is found, it returns undefined. This will only search among direct children.

get_element_by_ns/2

get_element_by_ns(Xmlel::XML_Element, NS) -> XML_Subelement | undefined

Search in the children of XML_Element the first element with NS namespace URI.

If no element with the given namespace is found, it returns undefined. This will only search among direct children.

This function is particularly usefull to extract XMPP error codes.

get_elements/2

get_elements(Xmlel::XML_Element, Name) -> [XML_Subelement]

Search in the children of XML_Element for all the elements named Name

This will only search among direct children.

get_elements/3

get_elements(Xmlel::XML_Element, NS, Name) -> [XML_Subelement]

Search in the children of XML_Element for all the elements named Name with NS namespace URI.

This will only search among direct children.

get_engine_driver/1

get_engine_driver(Engine_Name) -> Driver_Name

Return the port driver name associated to the given engine.

get_engine_names/0

get_engine_names() -> [Engine_Name]

Return the list of XML engines.

get_name_as_atom/1

get_name_as_atom(Xmlel::XML_Element) -> Name

Return the name of an element as atom, regardless of the original encoding.

get_name_as_list/1

get_name_as_list(Xmlel::XML_Element) -> Name

Return the name of an element as list, regardless of the original encoding.

get_ns_as_atom/1

get_ns_as_atom(Xmlel::XML_Element) -> NS | undefined

Return the namespace as an atom, regardless of the original encoding.

get_ns_as_list/1

get_ns_as_list(Xmlel::XML_Element) -> NS | undefined

Return the namespace as a string, regardless of the original encoding.

get_path/2

get_path(XML_Element, Path) -> XML_Subelement | Attr_Value | CData | Not_Found

throws {xml, path, ending_component_not_at_the_end, Path} | {xml, path, invalid_component, Path}

Follow the given path and return what's pointed by the last component of it.

Path is a list of path components. If a component points to an xmlel() or xmlel_old(), the function will look for this element and will use it as a base for the next path component. If a component points to an attribute, the function will look for this attribute in the current element and return its value (see get_attribute/2 for the possible return values). If a component asks for character data, the function will return character data for the current element (see get_cdata/1 for possible return values). A path will not be followed further after an attribute or a character data component. If an XML element isn't found while walking through the path, an empty string is returned.

has_attribute/2

has_attribute(Xmlel::XML_Element, Name::Attr_Name) -> bool()

Check the presence for attribute Attr_Name in the XML element.

has_attribute/3

has_attribute(Xmlel::XML_Element, NS, Name::Attr_Name) -> bool()

Check the presence for attribute Attr_Name with namespace NS in the XML element.

has_attribute_in_list/2

has_attribute_in_list(Attrs, Name::Attr_Name) -> bool()

Check the presence for attribute Attr_Name in the list.

has_attribute_in_list/3

has_attribute_in_list(Attrs, NS, Name::Attr_Name) -> bool()

Check the presence for attribute Attr_Name with namespace NS in the list.

has_element/2

has_element(XML_Element, Name) -> bool()

Check the presence for element Name in the children.

has_element/3

has_element(XML_Element, NS, Name) -> bool()

Check the presence for element Name with NS namespace URI in the children.

has_element_by_ns/2

has_element_by_ns(XML_Element, NS) -> bool()

Check the presence for any elements with NS namespace URI in the children.

indent_document/2

indent_document(El::XML_Element, Indent) -> New_XML_Element

Add whitespaces text nodes to indent the document.

Indentation of xmlendtag() isn't supported yet.

indent_document/3

indent_document(El::XML_Element, Indent, Previous_Total) -> New_XML_Element

Add whitespaces text nodes to indent the document.

Indentation of xmlendtag() isn't supported yet.

internal_escaping_function_name/0

internal_escaping_function_name() -> escape_using_entities | escape_using_cdata

Tell what escaping function will be used internally.

is_engine_available/1

is_engine_available(Engine_Name) -> bool()

Tell if Engine_Name is available.

is_ns_declared_here/2

is_ns_declared_here(Xmlel::XML_Element, NS) -> bool()

Tell if NS was declared within this element.

is_whitespace/1

is_whitespace(Xmlcdata::CData) -> bool()

Tell if a text node contains only whitespaces.

Of course, if an XML element is given in argument, it will return false.

Whitespaces are \s, \t, \n and \r.

map/2

map(Fun, Xmlel) -> any()

Apply Fun on each child and replace the original one with the function return value.

Fun has the following prototype:
  fun(XML_Element, Child) -> New_Child
If children is undefined, the function isn't called.

node_to_binary/3

node_to_binary(El, Default_NS, Prefixed_NS) -> XML_Text

Serialize an XML node to text.

Converting to binary is about 15% to 20% faster than converting to a list.

node_to_iolist/3

node_to_iolist(El::XML_Element, Default_NS, Prefixed_NS) -> XML_Text

Serialize an XML node to text.

Converting to iolist is about 40% to 50% faster than converting to a list.

node_to_list/3

node_to_list(El::XML_Element, Default_NS, Prefixed_NS) -> XML_Text

Serialize an XML node to text.

Default_NS and Prefixed_NS contain namespace declaration which occured above this node in the tree. The order in the first list is important: declarations are sorted from the most recent one to the oldest one.

normalize_cdata/1

normalize_cdata(Xmlel::XML_Element) -> New_XML_Element

Regroup all splitted xmlcdata() in a unique one and remove empty ones.

One caveats is the reconstructed xmlcdata() is appended at the end of the children list.

normalize_cdata_in_list/1

normalize_cdata_in_list(Children) -> New_Children

Regroup all splitted xmlcdata() in a unique one.

parse/2

parse(Parser, Data) -> [XML_Element] | continue

throws {xml_parser, parsing, Reason, Details}

Parse a chunk from an XML stream.

This may be called multiple times with a new chunk of data. However the entire data must represent at most one and only one XML document. If you want to process the last chunk of data, you should call parser_final/2. If you can't know when the end of the document occurs, you may use this function to process data, then you call parse_final/2 with an empty string. Here is an example:
  fun (Parser) ->
      xml:parse(Parser, "<stream ver"),
      xml:parse(Parser, "sion='1."),
      xml:parse(Parser, "0'></stream>"),
      xml:parser_final(Parser, "").

parse_document/1

parse_document(Document) -> [XML_Element] | done

Parse an entire XML document at once.

Initializing a parser with start_parser/1 isn't necessary, this function will take care of it. It'll use default options; see start_parser/1 for any related informations.

parse_document/2

parse_document(Document, Parser_Options) -> [XML_Element] | done

Parse an entire XML document at once.

Initializing a parser with start_parser/1 isn't necessary, this function will take care of it. Parser_Options is passed to the parser; see start_parser/1 for any related informations.

Return values are the same as parse_final/2.

parse_document_fragment/1

parse_document_fragment(Fragment) -> [XML_Element] | continue

Parse a fragment of an XML document at once.

This function is useful if you do not have a complete and valid XML document. For instance, something like this:
  <element>content</elem
Initializing a parser with start_parser/1 isn't necessary, this function will take care of it. It'll use default options, but will set {root_depth, none} (which can be overriden); see start_parser/1 for any related informations.

parse_document_fragment/2

parse_document_fragment(Fragment, Parser_Options) -> [XML_Element] | continue

Parse a fragment of an XML document at once.

This function is useful if you do not have a complete and valid XML document. For instance, something like this:
  <element>content</elem

Initializing a parser with start_parser/1 isn't necessary, this function will take care of it. Parser_Options is passed to the parser but {root_depth, none} is prepended (this can be overriden); see start_parser/1 for any related informations.

Return values are the same as parse_final/2.

parse_final/2

parse_final(Parser, Data) -> [XML_Element] | done

throws {xml_parser, parsing, Reason, Details}

Parse the last chunk from an XML stream.

This is used when you know there won't be any more data to process. This last chunk must provide the end of the XML document or the parser will return an error. This function may also be used to process an entire XML document in one pass.

See also: parse/2 for an example.

prepend_child/2

prepend_child(Xmlel::XML_Element, Child) -> New_XML_Element

Prepend Child to XML_Element's children list.

prepend_children/2

prepend_children(Xmlel::XML_Element, New_Children::Children) -> New_XML_Element

Prepend every Children to XML_Element's children list.

register_engine/2

register_engine(Name, Driver) -> ok

Add a new XML engine.

register_engine/3

register_engine(Name, Driver_Path, Driver) -> ok

Add a new XML engine.

remove_attribute/2

remove_attribute(Xmlel::XML_Element, Name::Attr_Name) -> New_XML_Element

Remove attribute named Attr_Name and return the new element.

If Attr_Name doesn't exist, this function has no effect (it won't return an error).

remove_attribute/3

remove_attribute(Xmlel::XML_Element, NS, Name::Attr_Name) -> New_XML_Element

Remove attribute named Attr_Name with the NS namespace URI and return the new element.

If Attr_Name doesn't exist, this function has no effect (it won't return an error).

remove_attribute_from_list/2

remove_attribute_from_list(Attrs, Name::Attr_Name) -> New_Attrs

Remove attribute named Attr_Name and return the new list.

If Attr_Name doesn't exist, this function has no effect (it won't return an error).

remove_attribute_from_list/3

remove_attribute_from_list(Attrs, NS, Name::Attr_Name) -> New_Attrs

Remove attribute named Attr_Name with the NS namespace URI and return the new list.

If Attr_Name doesn't exist, this function has no effect (it won't return an error).

remove_cdata/1

remove_cdata(Xmlel::XML_Element) -> New_XML_Element

Remove any character data from the given XML element.

This function doesn't take a list of children like the old remove_cdata/1, use remove_cdata_from_list/1 for this purpose!

remove_cdata_from_list/1

remove_cdata_from_list(Children) -> New_Children

Remove any character data from the given XML element children list.

remove_element/2

remove_element(Xmlel::XML_Element, Name) -> New_XML_Element

Remove the first child with the name Name.

remove_element/3

remove_element(Xmlel::XML_Element, NS, Name) -> New_XML_Element

Remove the first child with the name Name in the namespace NS.

remove_element_by_ns/2

remove_element_by_ns(Xmlel::XML_Element, NS) -> New_XML_Element

Remove the first child in the namespace NS.

remove_elements/2

remove_elements(Xmlel::XML_Element, Name) -> New_XML_Element

Remove all children with the name Name.

remove_elements/3

remove_elements(Xmlel::XML_Element, NS, Name) -> New_XML_Element

Remove all children with the name Name in the namespace NS.

remove_elements_by_ns/2

remove_elements_by_ns(Xmlel::XML_Element, NS) -> New_XML_Element

Remove all children in the namespace NS.

remove_whitespaces/1

remove_whitespaces(Xmlel::XML_Element) -> New_XML_Element

Remove text nodes containing only whitespaces.

See also: is_whitespace/1.

remove_whitespaces_deeply/1

remove_whitespaces_deeply(Xmlel::XML_Element) -> New_XML_Element

Remove text nodes containing only whitespaces in every elements in the given tree.

See also: is_whitespace/1.

remove_whitespaces_from_list/1

remove_whitespaces_from_list(Children) -> New_Children

Remove text nodes containing only whitespaces.

See also: is_whitespace/1.

replace_child/3

replace_child(Xmlel::XML_Element, Old_Child, New_Child) -> New_XML_Element

Replace Old_Child by New_Child in XML_Element children list.

reset_parser/1

reset_parser(Parser) -> New_Parser

Reset the parser with the same previous options.

reset_parser/2

reset_parser(Xml_parser::Parser, Options) -> New_Parser

Reset the parser and update its options.

set_attribute/2

set_attribute(Xmlel::XML_Element, Attr) -> New_XML_Element

Add a new attribute or change the value of an existing attribute with the same name.

If a match is found, Attr will replace the old attribute as is, regardless of the format of the latter.

set_attribute/3

set_attribute(Xmlel::XML_Element, Name::Attr_Name, Value::Attr_Value) -> New_XML_Element

Add a new attribute or change the value of an existing attribute.

set_attribute/4

set_attribute(Xmlel::XML_Element, NS, Name::Attr_Name, Value::Attr_Value) -> New_XML_Element

Add a new attribute or change the value of an existing attribute with the same name and the NS namespace URI.

set_attribute_in_list/2

set_attribute_in_list(Attrs, Xmlattr::Attr) -> New_Attrs

Add a new attribute or change the value of an existing attribute with the same name.

If a match is found, Attr will replace the old attribute as is, regardless of the format of the latter.

set_attribute_in_list/3

set_attribute_in_list(Attrs, Name::Attr_Name, Value::Attr_Value) -> New_Attrs

Add a new attribute or change the value of an existing attribute with the same name.

If the attribute is to be added, this function use the xmlattr() record if it can't determine the type from the other attributes.

set_attribute_in_list/4

set_attribute_in_list(Attrs, NS, Name::Attr_Name, Value::Attr_Value) -> New_Attrs

Add a new attribute or change the value of an existing attribute with the same name and the NS namespace URI.

If the attribute is to be added, this function use the xmlattr() record.

set_attributes/2

set_attributes(XML_Element, Rest::Attrs_Spec) -> New_XML_Element

Set multiple attributes at a time.

Existing attributes are not completly overwritten by the ones present in Attrs_Spec. They are simply updated.

set_cdata/2

set_cdata(Xmlel::XML_Element, CData) -> New_XML_Element

Replace any character data by CData.

The new CData is placed at the end of the children list.

set_cdata_in_list/2

set_cdata_in_list(Children, CData) -> New_Children

Replace any character data by CData in the list.

The new CData is placed at the end of the children list.

set_children/2

set_children(Xmlel::XML_Element, New_Children::Children) -> New_XML_Element

Set XML_Element's children list to Children.

Any existing child is removed.

start_parser/0

start_parser() -> Parser

Initialize the Expat port driver with default options.

Default options are:
  [
    {max_size, infinity},
    {root_depth, 0},
    names_as_atom,
    {emit_endtag, false}
  ].

See also: xmlparseroption(), start_parser/1.

start_parser/1

start_parser(Options) -> Parser

throws {xml_parser, options, Reason, Infos}

Initialize the Expat port driver with given Options.

You must call this function before any use of functions parse/2 or parse_final/2. The returned Parser must be given as the first argument for those functions. When finished, you must free this parser with the stop_parser/1. Here is an example:
  fun() ->
      Parser = xml:start_parser(),
      xml:parse(Parser, "<stream version='1.0'><presence/></stream>"),
      xml:stop_parser(Parser).

stop_parser/1

stop_parser(Xml_parser::Parser) -> ok

Stop the Expat port driver.

This must be called when you are done with the Parser returned by start_parser/0.

See also: start_parser/0 for an example.

xmlel_to_xmlelement/1

xmlel_to_xmlelement(XML_Element::XML_NS_Element) -> XML_Element

Convert an xmlel() to an xmlel_old() tuple.

Other tuples are ignored.

xmlel_to_xmlelement/3

xmlel_to_xmlelement(Xmlel::XML_NS_Element, Default_NS, Prefixed_NS) -> XML_Element

Convert an xmlel() to an xmlel_old() tuple.

Other tuples are ignored.

Default_NS and Prefixed_NS contain namespace declaration which occured above this fragment in the tree. The order in the first list is important: declarations are sorted from the most recent one to the oldest one.

This may be useful in XMPP context where a majority of clients or servers expects a stream prefix for the <stream> tag and the default namespace declaration in this same element.

Default_NS may be a list of equivalent namespaces. This is useful when stanzas go to and from streams with compatible but different namespaces. Here is an example with jabber:client, jabber:server and jabber:component:accept:
  exmpp_stanza:to_list(El,
    [?NS_JABBER_CLIENT, ?NS_JABBER_SERVER, ?NS_COMPONENT_ACCEPT]).

xmlelement_to_xmlel/1

xmlelement_to_xmlel(XML_Element) -> XML_NS_Element

Convert an xmlel_old() to an xmlel() tuple.

Other tuples are ignored.

xmlelement_to_xmlel/3

xmlelement_to_xmlel(XML_El::XML_Element, Default_NS, Prefixed_NS) -> XML_NS_Element

Convert an xmlel_old() to an xmlel() tuple.

Other tuples are ignored.

See xmlel_to_xmlelement/3 for a description of Default_NS and Prefixed_NS.

xmlelement_to_xmlel_and_nss_tables/3

xmlelement_to_xmlel_and_nss_tables(Xmlelement::XML_Element, Default_NS, Prefixed_NS) -> {XML_NS_Element, New_Default_NS, New_Prefixed_NS}

Convert an xmlel_old() to an xmlel() tuple.

Other tuples are ignored.

See xmlel_to_xmlelement/3 for a description of Default_NS and Prefixed_NS.

This function will returned updated namespaces tables New_Default_NS and New_Prefixed_NS which can be used for future calls.


Generated by EDoc, Jan 21 2011, 01:43:51.