//
//------------------ DOK FILE --------------------------------------------------
+Header	core.util.xml
=pkg	core.util.xml
=title	core.util.xml
=short	xml format
=desc
This library contains functions to manipulate xml representations.
	fun testXml()=
		let load ("test.xml")-> src in
		let xmlParse (src, 0 ,false) -> [xml, next] in
		(
			consoleTime next;
			echoLn xmlEncodePretty (xml)
		);;
//
//
//------------------ PROTO ----------------------------------------------------- xmlFilterChilds
+Proto	xmlFilterChilds
=type	fun Xml Str -> list Xml
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function get the list of all childs which are tags of the supplied name.
//
+arg	xml
=type	Xml
=desc	Any Xml value. Should be a [[tagXml]].
//
+arg	tag
=type	Str
=desc	A tag name
//
+arg	result
=type	list Xml
=desc	A list of Xml tags
//
//
//------------------ PROTO ----------------------------------------------------- xmlGetAttribute
+Proto	xmlGetAttribute
=type	fun Xml Str -> Str
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function search for the attribute in the xml tag. It returns the associated value.
//
+arg	xml
=type	Xml
=desc	Any Xml value. Should be a [[tagXml]].
//
+arg	attribute
=type	Str
=desc	An attribute name
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- xmlGetContent
+Proto	xmlGetContent
=type	fun Xml -> Str
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function is a content extractor. It returns nil if the xml value wasn't [[contentXml]].
//
+arg	xml
=type	Xml
=desc	Any Xml value. Should be a [[contentXml]].
//
+arg	result
=type	Str
=desc	A string or nil
//
//
//------------------ PROTO ----------------------------------------------------- xmlGetChilds
+Proto	xmlGetChilds
=type	fun Xml -> list Xml
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function is a child extractor. It returns nil if the xml value wasn't [[tagXml]].
//
+arg	xml
=type	Xml
=desc	Any Xml value. Should be a [[tagXml]].
//
+arg	result
=type	list Xml
=desc	A list of Xml values.
//
//
//------------------ PROTO ----------------------------------------------------- xmlGetAttributes
+Proto	xmlGetAttributes
=type	fun Xml -> list [Str Str]
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function is an attribute extractor. It returns nil if the xml value wasn't [[tagXml]].
//
+arg	xml
=type	Xml
=desc	Any Xml value. Should be a [[tagXml]].
//
+arg	result
=type	list [Str Str]
=desc	A list of tuples [key value]
//
//
//------------------ PROTO ----------------------------------------------------- xmlGetTag
+Proto	xmlGetTag
=type	fun Xml -> Str
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function is a tag extractor. It returns nil if the xml value wasn't [[tagXml]].
//
+arg	xml
=type	Xml
=desc	Any Xml value. Should be a [[tagXml]].
//
+arg	result
=type	Str
=desc	A tag name.
//
//
//------------------ PROTO ----------------------------------------------------- xmlParse
+Proto	xmlParse
=type	fun Str Int Bool -> [Xml Int]
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc
This function assumes that src contains a xml representation starting at position index. It throws an exception when it is not the case.
When it works, it returns a tuple with the Xml value and the index after the last char read from src.
When noMixChild is true, it assumes that only the content of terminal tags is relevant, and it removes any [[contentXml]] element which is not the only child of its parent.
//
+arg	src
=type	Str
=desc	A string with a xml representation.
//
+arg	i0
=type	Int
=desc	An index
//
+arg	noMixChild
=type	Bool
=desc	A boolean
//
+arg	result
=type	[Xml Int]
=desc	A tuple [xml_value next_index]
//
//
//------------------ PROTO ----------------------------------------------------- xmlEncode
+Proto	xmlEncode
=type	fun Xml -> Str
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function returns a string with the xml representation of the supplied value. The result is 'compact', without any space or carriage return.
//
+arg	xml
=type	Xml
=desc	Any Xml value
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- xmlEncodePretty
+Proto	xmlEncodePretty
=type	fun Xml -> Str
=mode	function
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This function returns a string with the xml representation of the supplied value. For readability it adds spaces and carriage returns.
//
+arg	xml
=type	Xml
=desc	Any Xml value
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- Xml
+Proto	Xml
=type	Xml
=mode	sum
=pkg	core.util.xml
=impl	mcy
=link	
=desc
The Xml type is a sum type of constructors [[contentXml]] and [[tagXml]].
Xml content is what is between an opening/closing tag and another opening/closing tag.
//
//
//------------------ PROTO ----------------------------------------------------- contentXml
+Proto	contentXml
=type	fun Str -> Xml
=mode	constructor
=pkg	core.util.xml
=impl	mcy
=link	
=desc	This is the constructor for xml content, as opposed to xml tags.
//
//
//------------------ PROTO ----------------------------------------------------- tagXml
+Proto	tagXml
=type	fun Str list [Str Str] list Xml -> Xml
=mode	constructor
=pkg	core.util.xml
=impl	mcy
=link	
=desc
This is the constructor for xml tag, as opposed to xml content.
An xml tag is made of:
-	a name
-	attributes as a list of tuples [key value]
-	child elements as a list of [[Xml]] tag or content.

	> xmlEncode (tagXml "Body" ["class", "foo"]::["background" "#fc0"]::nil nil)
>-> Str: "<Body class=\\\"foo\\\" background=\\\"#fc0\\\"/>"
	
	> xmlEncode (tagXml "html" nil (tagXml "Body" ["class", "foo"]::["background", "#fc0"]::nil nil):nil)
>-> Str: "<html><Body class=\\\"foo\\\" background=\\\"#fc0\\\"/></html>"
//
//
//------------------ PROTO ----------------------------------------------------- htmlParse
+Proto	htmlParse
=type	fun Str Int Bool -> [Xml Int]
=mode	Function
=pkg	core.util.xml
=impl	native
=link	
=desc	
//
+arg	A
=type	Str
=desc	
//
+arg	B
=type	Int
=desc	
//
+arg	C
=type	Bool
=desc	
//
+arg	result
=type	[Xml Int]
=desc