This is XML.info, produced by Macaulay2, version 1.25.05

XML -- an XML parser
********************

Description
===========

This experimental and tentative package provides an interface to the library
libxml2 (see http://www.xmlsoft.org/), which is a parser for XML files (see
http://en.wikipedia.org/wiki/XML).  The package offers two ways of representing
the result: as an object of class LibxmlNode, which is a
pointer to the internal structure created and accessed by the library; or as a
hashtable of class XMLnode, (which currently represents only
elements, attributes, and nodes).

This package was written to support the packages OpenMath,
and SCSCP.

Author
======

  * Daniel R. Grayson (see http://www.math.uiuc.edu/~dan/ ) <dan@math.uiuc.edu>

Version
=======

This documentation describes version 1.1 of XML.

Citation
========

If you have used this package in your research, please cite it as follows:

+----------------------------------------------------------------------------+
|@misc{XMLSource,                                                            |
|  title = {{XML: an XML parser. Version~1.1}},                              |
|  author = {Daniel R. Grayson},                                             |
|  howpublished = {A \emph{Macaulay2} package available at                   |
|    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}}|
|}                                                                           |
|                                                                            |
+----------------------------------------------------------------------------+

Exports
=======

  * Types
      * LibxmlAttribute -- the class of all XML
        attributes created by the library libxml
      * LibxmlNode -- the class of all XML nodes created by
        libxml2
      * XMLnode -- the class of all XML trees created by the
        library libxml2
  * Functions and commands
      * "getAttributes" -- see getAttributes(LibxmlNode),
        -- get the list of attributes of an XML
        node
      * getChildren -- get the list of children of an XML
        node
      * "parse" -- see parse(String), -- parse XML
      * "toLibxmlNode" -- see toLibxmlNode(XMLnode),
        -- convert a hashtable of type XMLnode to an
        object of type LibxmlNode
      * "toXMLnode" -- see toXMLnode(LibxmlNode),
        -- convert an object of type LibxmlNode to a
        hashtable of type XMLnode
      * "xmlAddAttribute" -- see
        xmlAddAttribute(LibxmlNode,String,String),
        -- add an attribute
        to an XML node
      * "xmlAddElement" -- see xmlAddElement(LibxmlNode,String),
        -- add an element to an XML
        node
      * "xmlAddText" -- see xmlAddText(LibxmlNode,String),
        -- add text to an XML node
      * xmlDocDump -- dump a document
      * "xmlFirstAttribute" -- see xmlFirstAttribute(LibxmlNode),
        -- get the first attribute of an XML
        node
      * xmlFirstChild -- get the first child of an XML
        node or attribute
      * "xmlGetContent" -- see xmlGetContent(LibxmlNode),
        -- get the string content of an XML text
        node
      * xmlGetName -- get the name of an XML node or
        attribute
      * xmlGetNext -- get the next XML node or attribute
      * "xmlIsElement" -- see xmlIsElement(LibxmlNode),
        -- whether an XML node is an element
      * "xmlIsText" -- see xmlIsText(LibxmlNode),
        -- whether an XML node is text
      * "xmlNewRoot" -- see xmlNewRoot(String),
        -- create the root node of an XML document
      * "xmlParse" -- see xmlParse(String), --
        parse a string containing XML
      * "xmlType" -- see xmlType(LibxmlNode), --
        the type code for an XML node
      * "xmlTypeDescription" -- see xmlTypeDescription(LibxmlNode),
        -- the type description for an XML
        node
      * xmlTypes -- a hash table of descriptions for XML node
        type codes
  * Methods
      * getAttributes(LibxmlNode) -- get
        the list of attributes of an XML node
      * "getChildren(LibxmlAttribute)" -- see getChildren,
        -- get the list of children of an XML node
      * "getChildren(LibxmlNode)" -- see getChildren, -- get
        the list of children of an XML node
      * parse(String) -- parse XML
      * toLibxmlNode(XMLnode) -- convert a
        hashtable of type XMLnode to an object of type LibxmlNode
      * toXMLnode(LibxmlNode) -- convert an
        object of type LibxmlNode to a hashtable of type XMLnode
      * xmlAddAttribute(LibxmlNode,String,String)
        -- add an attribute
        to an XML node
      * xmlAddElement(LibxmlNode,String)
        -- add an element to an XML
        node
      * xmlAddText(LibxmlNode,String)
        -- add text to an XML node
      * xmlFirstAttribute(LibxmlNode),
        -- get the first attribute of an XML node
      * "xmlFirstChild(LibxmlAttribute)" -- see xmlFirstChild,
        -- get the first child of an XML node or attribute
      * "xmlFirstChild(LibxmlNode)" -- see xmlFirstChild,
        -- get the first child of an XML node or attribute
      * xmlGetContent(LibxmlNode) -- get
        the string content of an XML text node
      * "xmlGetName(LibxmlAttribute)" -- see xmlGetName, --
        get the name of an XML node or attribute
      * "xmlGetName(LibxmlNode)" -- see xmlGetName, -- get
        the name of an XML node or attribute
      * "xmlGetNext(LibxmlAttribute)" -- see xmlGetNext, --
        get the next XML node or attribute
      * "xmlGetNext(LibxmlNode)" -- see xmlGetNext, -- get
        the next XML node or attribute
      * xmlIsElement(LibxmlNode), --
        whether an XML node is an element
      * xmlIsText(LibxmlNode) -- whether an
        XML node is text
      * xmlNewRoot(String) -- create the root
        node of an XML document
      * xmlParse(String) -- parse a string
        containing XML
      * xmlType(LibxmlNode) -- the type code
        for an XML node
      * xmlTypeDescription(LibxmlNode)
        -- the type description for an XML
        node
      * "xmlTypes(Sequence)" -- see xmlTypes, -- a hash table
        of descriptions for XML node type codes
  * Symbols
      * children
      * tag
      * Trim
  * Other things
      * xmlTypeIndex -- get XML type code from its
        description
      * xmlTypeTable -- a hash table of descriptions for
        XML node type codes

For the programmer
==================

The object XML, is a package (Macaulay2Doc), defined
in XML.m2.

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

children
********

Description
===========

This symbol is used as a key in hash tables of type XMLnode.

See also
========

  * XMLnode -- the class of all XML trees created by the
    library libxml2
  * parse -- parse XML
  * toXMLnode -- convert an object of type
    LibxmlNode to a hashtable of type XMLnode

For the programmer
==================

The object children, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

getAttributes(LibxmlNode) -- get the list of attributes of an XML node
**********************************************************************

  * Function: getAttributes,

Description
===========

+-------------------------------------------------------+
|i1 : xmlParse ///<bar id="foo" name="too">asdf</bar>///|
|                                                       |
|o1 = <bar id="foo" name="too">asdf</bar>               |
|                                                       |
|o1 : LibxmlNode (xmlTypeDescription)                   |
+-------------------------------------------------------+
|i2 : a = getAttributes oo                              |
|                                                       |
|o2 = {id = "foo"  }                                    |
|     {name = "too"}                                    |
|                                                       |
|o2 : VerticalList                                      |
+-------------------------------------------------------+
|i3 : class \ a                                         |
|                                                       |
|o3 = {LibxmlAttribute}                                 |
|     {LibxmlAttribute}                                 |
|                                                       |
|o3 : VerticalList                                      |
+-------------------------------------------------------+

Ways to use this method:
========================

  * getAttributes(LibxmlNode) -- get the
    list of attributes of an XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

getChildren -- get the list of children of an XML node
******************************************************

  * Usage:
        getChildren n
  * Inputs:
      * n, an instance of the type LibxmlNode, or an instance
        of the type LibxmlAttribute,
  * Outputs:
      * the list of children of n

Description
===========

+----------------------------------------------------------------------+
|i1 : xmlParse ///<foo>aabc<bar id="foo" name="too">asdf</bar></foo>///|
|                                                                      |
|o1 = <foo>aabc<bar id="foo" name="too">asdf</bar></foo>               |
|                                                                      |
|o1 : LibxmlNode (xmlTypeDescription)                                  |
+----------------------------------------------------------------------+
|i2 : c = getChildren oo                                               |
|                                                                      |
|o2 = {"aabc"                             }                            |
|     {<bar id="foo" name="too">asdf</bar>}                            |
|                                                                      |
|o2 : VerticalList                                                     |
+----------------------------------------------------------------------+
|i3 : class \ c                                                        |
|                                                                      |
|o3 = {LibxmlNode}                                                     |
|     {LibxmlNode}                                                     |
|                                                                      |
|o3 : VerticalList                                                     |
+----------------------------------------------------------------------+
|i4 : xmlIsText \ c                                                    |
|                                                                      |
|o4 = {true }                                                          |
|     {false}                                                          |
|                                                                      |
|o4 : VerticalList                                                     |
+----------------------------------------------------------------------+
|i5 : xmlIsElement \ c                                                 |
|                                                                      |
|o5 = {false}                                                          |
|     {true }                                                          |
|                                                                      |
|o5 : VerticalList                                                     |
+----------------------------------------------------------------------+

Ways to use getChildren:
========================

  * "getChildren(LibxmlAttribute)"
  * "getChildren(LibxmlNode)"

For the programmer
==================

The object getChildren, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

LibxmlAttribute -- the class of all XML attributes created by the library libxml
********************************************************************************

Functions and methods returning an object of class LibxmlAttribute:
===================================================================

  * xmlAddAttribute(LibxmlNode,String,String)
    -- add an attribute to
    an XML node
  * xmlFirstAttribute(LibxmlNode), --
    get the first attribute of an XML node
  * "xmlGetNext(LibxmlAttribute)" -- see xmlGetNext, -- get
    the next XML node or attribute

Methods that use an object of class LibxmlAttribute:
====================================================

  * "getChildren(LibxmlAttribute)" -- see getChildren, --
    get the list of children of an XML node
  * "xmlFirstChild(LibxmlAttribute)" -- see xmlFirstChild,
    -- get the first child of an XML node or attribute
  * "xmlGetName(LibxmlAttribute)" -- see xmlGetName, -- get
    the name of an XML node or attribute

For the programmer
==================

The object LibxmlAttribute, is a type (Macaulay2Doc),
with ancestor class Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

LibxmlNode -- the class of all XML nodes created by libxml2
***********************************************************

Description
===========

Each XML node created by libxml2 has: if it is an element (as determined by
xmlIsElement), an optional element name,
which is a string and is obtained with xmlGetName,; if it is
text (as determined by xmlIsText), an
optional content string, obtained with xmlGetContent,;
a linked list of attributes of type
LibxmlAttribute,; a linked list of children (which are XML
nodes), obtained with xmlFirstChild,; and a pointer its
next sibling, obtained with xmlGetNext.

XML nodes are mutable.

Internally, a pointer to the XML document containing the node accompanies the
node.

Let's use xmlParse, to make an XML node.

+-----------------------------------------------------------------------------+
|i1 : n = xmlParse ///<foo> aabc <bar id="foo" name="too"> asdf </bar><coo/>< |
|                                                                             |
|o1 = <foo> aabc <bar id="foo" name="too"> asdf </bar><coo/><coo>hi</coo><coo |
|                                                                             |
|o1 : LibxmlNode (xmlTypeDescription)                                         |
|-----------------------------------------------------------------------------|
|coo>hi</coo><coo a="b">hi</coo></foo>///                                     |
|                                                                             |
| a="b">hi</coo></foo>                                                        |
+-----------------------------------------------------------------------------+
|i2 : xmlIsElement n, xmlIsText n                                             |
|                                                                             |
|o2 = (true, false)                                                           |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Since it is an element, we may use xmlGetName, to get its
name.

+-----------------+
|i3 : xmlGetName n|
|                 |
|o3 = foo         |
+-----------------+

We use xmlFirstChild, to get the first node in the linked
list of children, which happens to be text:

+------------------------------------+
|i4 : c = xmlFirstChild n            |
|                                    |
|o4 = " aabc "                       |
|                                    |
|o4 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+
|i5 : xmlIsElement c, xmlIsText c    |
|                                    |
|o5 = (false, true)                  |
|                                    |
|o5 : Sequence                       |
+------------------------------------+

We may follow the linked list of children of n.

+------------------------------------------+
|i6 : c                                    |
|                                          |
|o6 = " aabc "                             |
|                                          |
|o6 : LibxmlNode (xmlTypeDescription)      |
+------------------------------------------+
|i7 : bar = xmlGetNext oo                  |
|                                          |
|o7 = <bar id="foo" name="too"> asdf </bar>|
|                                          |
|o7 : LibxmlNode (xmlTypeDescription)      |
+------------------------------------------+
|i8 : xmlGetNext oo                        |
|                                          |
|o8 = <coo/>                               |
|                                          |
|o8 : LibxmlNode (xmlTypeDescription)      |
+------------------------------------------+
|i9 : xmlGetNext oo                        |
|                                          |
|o9 = <coo>hi</coo>                        |
|                                          |
|o9 : LibxmlNode (xmlTypeDescription)      |
+------------------------------------------+
|i10 : xmlGetNext oo                       |
|                                          |
|o10 = <coo a="b">hi</coo>                 |
|                                          |
|o10 : LibxmlNode (xmlTypeDescription)     |
+------------------------------------------+
|i11 : xmlGetNext oo                       |
+------------------------------------------+

Let's examine the attributes of bar.

+---------------------------+
|i12 : xmlFirstAttribute bar|
|                           |
|o12 = id = "foo"           |
|                           |
|o12 : LibxmlAttribute      |
+---------------------------+
|i13 : a = xmlGetNext oo    |
|                           |
|o13 = name = "too"         |
|                           |
|o13 : LibxmlAttribute      |
+---------------------------+
|i14 : xmlGetNext oo        |
+---------------------------+

We may disassemble an attribute as follows.

+-------------------------------------+
|i15 : xmlGetName a                   |
|                                     |
|o15 = name                           |
+-------------------------------------+
|i16 : b = xmlFirstChild a            |
|                                     |
|o16 = "too"                          |
|                                     |
|o16 : LibxmlNode (xmlTypeDescription)|
+-------------------------------------+
|i17 : xmlGetNext oo                  |
+-------------------------------------+
|i18 : xmlIsText b                    |
|                                     |
|o18 = true                           |
+-------------------------------------+
|i19 : toString b                     |
|                                     |
|o19 = too                            |
+-------------------------------------+

There are other functions that retrieve the entire list of attributes or
children.

+---------------------------------------------+
|i20 : getChildren n                          |
|                                             |
|o20 = {" aabc "                             }|
|      {<bar id="foo" name="too"> asdf </bar>}|
|      {<coo/>                               }|
|      {<coo>hi</coo>                        }|
|      {<coo a="b">hi</coo>                  }|
|                                             |
|o20 : VerticalList                           |
+---------------------------------------------+
|i21 : class \ oo                             |
|                                             |
|o21 = {LibxmlNode}                           |
|      {LibxmlNode}                           |
|      {LibxmlNode}                           |
|      {LibxmlNode}                           |
|      {LibxmlNode}                           |
|                                             |
|o21 : VerticalList                           |
+---------------------------------------------+
|i22 : getAttributes bar                      |
|                                             |
|o22 = {id = "foo"  }                         |
|      {name = "too"}                         |
|                                             |
|o22 : VerticalList                           |
+---------------------------------------------+
|i23 : class \ oo                             |
|                                             |
|o23 = {LibxmlAttribute}                      |
|      {LibxmlAttribute}                      |
|                                             |
|o23 : VerticalList                           |
+---------------------------------------------+

Functions and methods returning an object of class LibxmlNode:
==============================================================

  * "toLibxmlNode" -- see toLibxmlNode(XMLnode),
    -- convert a hashtable of type XMLnode to an
    object of type LibxmlNode
  * xmlAddElement(LibxmlNode,String)
    -- add an element to an XML node
  * xmlAddText(LibxmlNode,String),
    -- add text to an XML node
  * "xmlFirstChild(LibxmlAttribute)" -- see xmlFirstChild,
    -- get the first child of an XML node or attribute
  * "xmlFirstChild(LibxmlNode)" -- see xmlFirstChild, --
    get the first child of an XML node or attribute
  * "xmlGetNext(LibxmlNode)" -- see xmlGetNext, -- get the
    next XML node or attribute
  * xmlNewRoot(String) -- create the root node
    of an XML document
  * xmlParse(String) -- parse a string containing
    XML

Methods that use an object of class LibxmlNode:
===============================================

  * getAttributes(LibxmlNode) -- get the
    list of attributes of an XML node
  * "getChildren(LibxmlNode)" -- see getChildren, -- get the
    list of children of an XML node
  * toXMLnode(LibxmlNode) -- convert an
    object of type LibxmlNode to a hashtable of type XMLnode
  * xmlAddAttribute(LibxmlNode,String,String)
    -- add an attribute to
    an XML node
  * xmlFirstAttribute(LibxmlNode), --
    get the first attribute of an XML node
  * xmlGetContent(LibxmlNode) -- get the
    string content of an XML text node
  * "xmlGetName(LibxmlNode)" -- see xmlGetName, -- get the
    name of an XML node or attribute
  * xmlIsElement(LibxmlNode) -- whether an
    XML node is an element
  * xmlIsText(LibxmlNode) -- whether an XML
    node is text
  * xmlType(LibxmlNode) -- the type code for an
    XML node
  * xmlTypeDescription(LibxmlNode),
    -- the type description for an XML node

For the programmer
==================

The object LibxmlNode, is a type (Macaulay2Doc),
with ancestor class Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

parse(String) -- parse XML
**************************

  * Function: parse,
  * Usage:
        parse s
  * Inputs:
      * s, a string (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Trim => ..., default value true
  * Outputs:
      * an instance of the type XMLnode, a tree of hash tables
        resulting from parsing the contents of s as XML

Description
===========

This function parses XML into a tree of hash tables of type XMLnode.

+-------------------------------------------------------------+
|i1 : x = parse ///<foo a="hi there">ho there<bar/></foo>///  |
|                                                             |
|o1 = <foo a="hi there"                                       |
|       "ho there"                                            |
|       <bar                                                  |
|                                                             |
|o1 : XMLnode                                                 |
+-------------------------------------------------------------+
|i2 : peek'_3 x                                               |
|                                                             |
|o2 = XMLnode{"a" => "hi there"                              }|
|             children => {"ho there", XMLnode{tag => "bar"}} |
|             tag => "foo"                                    |
+-------------------------------------------------------------+
|i3 : x#"a"                                                   |
|                                                             |
|o3 = hi there                                                |
+-------------------------------------------------------------+
|i4 : x.children                                              |
|                                                             |
|o4 = {ho there, <bar}                                        |
|                                                             |
|o4 : List                                                    |
+-------------------------------------------------------------+
|i5 : class \ oo                                              |
|                                                             |
|o5 = {String, XMLnode}                                       |
|                                                             |
|o5 : List                                                    |
+-------------------------------------------------------------+
|i6 : x.tag                                                   |
|                                                             |
|o6 = foo                                                     |
+-------------------------------------------------------------+

Ways to use this method:
========================

  * parse(String) -- parse XML
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

tag
***

Description
===========

This symbol is used as a key in hash tables of type XMLnode.

See also
========

  * XMLnode -- the class of all XML trees created by the
    library libxml2
  * parse -- parse XML
  * toXMLnode -- convert an object of type
    LibxmlNode to a hashtable of type XMLnode

For the programmer
==================

The object tag, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

toLibxmlNode(XMLnode) -- convert a hashtable of type XMLnode to an object of type LibxmlNode
********************************************************************************************

  * Function: toLibxmlNode,
  * Usage:
        toLibxmlNode x
  * Inputs:
      * x, an instance of the type XMLnode,
  * Outputs:
      * an instance of the type LibxmlNode,

Description
===========

+---------------------------------------------------------+
|i1 : new XMLnode from {                                  |
|          tag => "foo",                                  |
|          children => {                                  |
|               new XMLnode from {                        |
|                    tag => "bar",                        |
|                    children => { " chicken coop " } },  |
|               " hi there ",                             |
|               new XMLnode from { tag => "bar" } } }     |
|                                                         |
|o1 = <foo                                                |
|       <bar " chicken coop "                             |
|       " hi there "                                      |
|       <bar                                              |
|                                                         |
|o1 : XMLnode                                             |
+---------------------------------------------------------+
|i2 : toLibxmlNode oo                                     |
|                                                         |
|o2 = <foo><bar> chicken coop </bar> hi there <bar/></foo>|
|                                                         |
|o2 : LibxmlNode (xmlTypeDescription)                     |
+---------------------------------------------------------+

Ways to use this method:
========================

  * toLibxmlNode(XMLnode) -- convert a
    hashtable of type XMLnode to an object of type LibxmlNode
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

toXMLnode(LibxmlNode) -- convert an object of type LibxmlNode to a hashtable of type XMLnode
********************************************************************************************

  * Function: toXMLnode,
  * Usage:
        toXMLnode n
  * Inputs:
      * n, an instance of the type LibxmlNode,
  * Optional inputs (Macaulay2Doc),:
      * Trim => ..., default value true
  * Outputs:
      * an instance of the type XMLnode, a representation of
        the XML tree represented by n
      * Trim => a Boolean value (Macaulay2Doc), default value
        true, whether to trim leading and trailing spaces from the lines in
        text nodes

Description
===========

This function translates an XML tree created by the libxml library into a tree
of hash tables of type XMLnode.

+------------------------------------------------------------------+
|i1 : n = xmlParse ///<foo a="hi there">  ho there  <bar/></foo>///|
|                                                                  |
|o1 = <foo a="hi there">  ho there  <bar/></foo>                   |
|                                                                  |
|o1 : LibxmlNode (xmlTypeDescription)                              |
+------------------------------------------------------------------+
|i2 : x = toXMLnode n                                              |
|                                                                  |
|o2 = <foo a="hi there"                                            |
|       "ho there"                                                 |
|       <bar                                                       |
|                                                                  |
|o2 : XMLnode                                                      |
+------------------------------------------------------------------+
|i3 : peek'_3 x                                                    |
|                                                                  |
|o3 = XMLnode{"a" => "hi there"                              }     |
|             children => {"ho there", XMLnode{tag => "bar"}}      |
|             tag => "foo"                                         |
+------------------------------------------------------------------+
|i4 : x#"a"                                                        |
|                                                                  |
|o4 = hi there                                                     |
+------------------------------------------------------------------+
|i5 : x.children                                                   |
|                                                                  |
|o5 = {ho there, <bar}                                             |
|                                                                  |
|o5 : List                                                         |
+------------------------------------------------------------------+
|i6 : class \ oo                                                   |
|                                                                  |
|o6 = {String, XMLnode}                                            |
|                                                                  |
|o6 : List                                                         |
+------------------------------------------------------------------+
|i7 : x.tag                                                        |
|                                                                  |
|o7 = foo                                                          |
+------------------------------------------------------------------+
|i8 : x = toXMLnode(n,Trim=>false)                                 |
|                                                                  |
|o8 = <foo a="hi there"                                            |
|       "  ho there  "                                             |
|       <bar                                                       |
|                                                                  |
|o8 : XMLnode                                                      |
+------------------------------------------------------------------+

See also
========

  * xmlParse -- parse a string containing XML

Ways to use this method:
========================

  * toXMLnode(LibxmlNode) -- convert an
    object of type LibxmlNode to a hashtable of type XMLnode
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

Trim
****

Functions with optional argument named Trim:
============================================

  * "parse(...,Trim=>...)" -- see parse(String), --
    parse XML
  * "toXMLnode(...,Trim=>...)" -- see toXMLnode(LibxmlNode),
    -- convert an object of type LibxmlNode to a
    hashtable of type XMLnode

For the programmer
==================

The object Trim, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlAddAttribute(LibxmlNode,String,String) -- add an attribute to an XML node
****************************************************************************

  * Function: xmlAddAttribute,
  * Usage:
        p = xmlAddAttribute(n,a,x)
  * Inputs:
      * n, an instance of the type LibxmlNode,
      * a, a string (Macaulay2Doc),
      * x, a string (Macaulay2Doc),
  * Outputs:
      * p, an instance of the type LibxmlAttribute, a
        new attribute with name given by a and content given by x
  * Consequences:
      * p is added to the list of attributes of n

Description
===========

+---------------------------------------------+
|i1 : n = xmlParse ///<bar>asdf</bar>///      |
|                                             |
|o1 = <bar>asdf</bar>                         |
|                                             |
|o1 : LibxmlNode (xmlTypeDescription)         |
+---------------------------------------------+
|i2 : a = xmlAddAttribute(n,"foo","the value")|
|                                             |
|o2 = foo = "the value"                       |
|                                             |
|o2 : LibxmlAttribute                         |
+---------------------------------------------+
|i3 : xmlGetName a                            |
|                                             |
|o3 = foo                                     |
+---------------------------------------------+
|i4 : n                                       |
|                                             |
|o4 = <bar foo="the value">asdf</bar>         |
|                                             |
|o4 : LibxmlNode (xmlTypeDescription)         |
+---------------------------------------------+

Ways to use this method:
========================

  * xmlAddAttribute(LibxmlNode,String,String)
    -- add an attribute to
    an XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlAddElement(LibxmlNode,String) -- add an element to an XML node
*****************************************************************

  * Function: xmlAddElement,
  * Usage:
        m = xmlAddElement(n,s)
  * Inputs:
      * n, an instance of the type LibxmlNode,
      * s, a string (Macaulay2Doc),
  * Outputs:
      * m, an instance of the type LibxmlNode, a new node
        named s
  * Consequences:
      * The new node m is attached as the last child of n.

Description
===========

+------------------------------------+
|i1 : n = xmlParse ///<bar></bar>/// |
|                                    |
|o1 = <bar/>                         |
|                                    |
|o1 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+
|i2 : xmlAddElement(n,"a")           |
|                                    |
|o2 = <a/>                           |
|                                    |
|o2 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+
|i3 : xmlAddElement(n,"b")           |
|                                    |
|o3 = <b/>                           |
|                                    |
|o3 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+
|i4 : xmlAddElement(oo,"b1")         |
|                                    |
|o4 = <b1/>                          |
|                                    |
|o4 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+
|i5 : n                              |
|                                    |
|o5 = <bar>                          |
|           <a/>                     |
|           <b>                      |
|             <b1/>                  |
|           </b>                     |
|         </bar>                     |
|                                    |
|o5 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+

Ways to use this method:
========================

  * xmlAddElement(LibxmlNode,String)
    -- add an element to an XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlAddText(LibxmlNode,String) -- add text to an XML node
********************************************************

  * Function: xmlAddText,
  * Usage:
        m = xmlAddText(n,s)
  * Inputs:
      * n, an instance of the type LibxmlNode,
      * s, a string (Macaulay2Doc),
  * Outputs:
      * m, an instance of the type LibxmlNode, a new text
        node containing the string s.
  * Consequences:
      * The new node m is attached as the last child of n.

Description
===========

+-------------------------------------------------------+
|i1 : n = xmlParse ///<bar id="foo" name="too"></bar>///|
|                                                       |
|o1 = <bar id="foo" name="too"/>                        |
|                                                       |
|o1 : LibxmlNode (xmlTypeDescription)                   |
+-------------------------------------------------------+
|i2 : xmlAddText(n,"hi there")                          |
|                                                       |
|o2 = "hi there"                                        |
|                                                       |
|o2 : LibxmlNode (xmlTypeDescription)                   |
+-------------------------------------------------------+
|i3 : xmlIsText oo                                      |
|                                                       |
|o3 = true                                              |
+-------------------------------------------------------+
|i4 : n                                                 |
|                                                       |
|o4 = <bar id="foo" name="too">hi there</bar>           |
|                                                       |
|o4 : LibxmlNode (xmlTypeDescription)                   |
+-------------------------------------------------------+

Caveat
======

The list of children should not contain two adjacent text nodes.

Ways to use this method:
========================

  * xmlAddText(LibxmlNode,String),
    -- add text to an XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlDocDump -- dump a document
*****************************

Description
===========

+--------------------------------------------------------+
|i1 : n = xmlNewRoot "foo"                               |
|                                                        |
|o1 = <foo/>                                             |
|                                                        |
|o1 : LibxmlNode (xmlTypeDescription)                    |
+--------------------------------------------------------+
|i2 : xmlAddElement(n,"bar")                             |
|                                                        |
|o2 = <bar/>                                             |
|                                                        |
|o2 : LibxmlNode (xmlTypeDescription)                    |
+--------------------------------------------------------+
|i3 : xmlAddText(oo,"hi there")                          |
|                                                        |
|o3 = "hi there"                                         |
|                                                        |
|o3 : LibxmlNode (xmlTypeDescription)                    |
+--------------------------------------------------------+
|i4 : xmlAddElement(n,"key")                             |
|                                                        |
|o4 = <key/>                                             |
|                                                        |
|o4 : LibxmlNode (xmlTypeDescription)                    |
+--------------------------------------------------------+
|i5 : xmlAddText(oo,"frobble 你好")                        |
|                                                        |
|o5 = "frobble 你好"                                       |
|                                                        |
|o5 : LibxmlNode (xmlTypeDescription)                    |
+--------------------------------------------------------+
|i6 : n                                                  |
|                                                        |
|o6 = <foo>                                              |
|           <bar>hi there</bar>                          |
|           <key>frobble 你好</key>                        |
|         </foo>                                         |
|                                                        |
|o6 : LibxmlNode (xmlTypeDescription)                    |
+--------------------------------------------------------+
|i7 : xmlDocDump n                                       |
|                                                        |
|o7 = <?xml version="1.0" encoding="UTF-8"?>             |
|     <foo><bar>hi there</bar><key>frobble 你好</key></foo>|
+--------------------------------------------------------+

See also
========

  * xmlNewRoot -- create the root node of an XML
    document

For the programmer
==================

The object xmlDocDump, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlFirstAttribute(LibxmlNode) -- get the first attribute of an XML node
***********************************************************************

  * Function: xmlFirstAttribute,
  * Usage:
        xmlFirstAttribute n
  * Inputs:
      * n, an instance of the type LibxmlNode,
  * Outputs:
      * an instance of the type LibxmlAttribute, The
        first attribute in the list of attributes of n.

Description
===========

+----------------------------------------------+
|i1 : xmlParse ///<bar id="foo" name="too"/>///|
|                                              |
|o1 = <bar id="foo" name="too"/>               |
|                                              |
|o1 : LibxmlNode (xmlTypeDescription)          |
+----------------------------------------------+
|i2 : xmlFirstAttribute oo                     |
|                                              |
|o2 = id = "foo"                               |
|                                              |
|o2 : LibxmlAttribute                          |
+----------------------------------------------+

See also
========

  * xmlGetNext -- get the next XML node or attribute

Ways to use this method:
========================

  * xmlFirstAttribute(LibxmlNode), --
    get the first attribute of an XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlFirstChild -- get the first child of an XML node or attribute
****************************************************************

  * Usage:
        xmlFirstChild n
  * Inputs:
      * n, an instance of the type LibxmlNode, or an instance
        of the type LibxmlAttribute,
  * Outputs:
      * an instance of the type LibxmlNode,

Description
===========

+-------------------------------------------------+
|i1 : n = xmlParse ///<bar a="123"><foo/></bar>///|
|                                                 |
|o1 = <bar a="123">                               |
|           <foo/>                                |
|         </bar>                                  |
|                                                 |
|o1 : LibxmlNode (xmlTypeDescription)             |
+-------------------------------------------------+
|i2 : xmlFirstChild n                             |
|                                                 |
|o2 = <foo/>                                      |
|                                                 |
|o2 : LibxmlNode (xmlTypeDescription)             |
+-------------------------------------------------+
|i3 : xmlFirstAttribute n                         |
|                                                 |
|o3 = a = "123"                                   |
|                                                 |
|o3 : LibxmlAttribute                             |
+-------------------------------------------------+
|i4 : xmlFirstChild oo                            |
|                                                 |
|o4 = "123"                                       |
|                                                 |
|o4 : LibxmlNode (xmlTypeDescription)             |
+-------------------------------------------------+

See also
========

  * xmlGetNext -- get the next XML node or attribute

Ways to use xmlFirstChild:
==========================

  * "xmlFirstChild(LibxmlAttribute)"
  * "xmlFirstChild(LibxmlNode)"

For the programmer
==================

The object xmlFirstChild, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlGetContent(LibxmlNode) -- get the string content of an XML text node
***********************************************************************

  * Function: xmlGetContent,
  * Usage:
        xmlGetContent n
  * Inputs:
      * n, an instance of the type LibxmlNode, a text node,
        as determined by xmlIsText,
  * Outputs:
      * a string (Macaulay2Doc), the content string contained in
        n

Description
===========

+---------------------------------------+
|i1 : xmlParse ///<bar>hi there</bar>///|
|                                       |
|o1 = <bar>hi there</bar>               |
|                                       |
|o1 : LibxmlNode (xmlTypeDescription)   |
+---------------------------------------+
|i2 : xmlFirstChild oo                  |
|                                       |
|o2 = "hi there"                        |
|                                       |
|o2 : LibxmlNode (xmlTypeDescription)   |
+---------------------------------------+
|i3 : xmlGetContent oo                  |
|                                       |
|o3 = hi there                          |
+---------------------------------------+
|i4 : class oo                          |
|                                       |
|o4 = String                            |
|                                       |
|o4 : Type                              |
+---------------------------------------+

Ways to use this method:
========================

  * xmlGetContent(LibxmlNode) -- get the
    string content of an XML text node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlGetName -- get the name of an XML node or attribute
******************************************************

  * Usage:
        xmlGetName n
  * Inputs:
      * n, an instance of the type LibxmlNode, or an instance
        of the type LibxmlAttribute,
  * Outputs:
      * a string (Macaulay2Doc), the name of the node

Description
===========

+-------------------------------------------------------+
|i1 : n = xmlParse ///<bar id="foo" name="too"></bar>///|
|                                                       |
|o1 = <bar id="foo" name="too"/>                        |
|                                                       |
|o1 : LibxmlNode (xmlTypeDescription)                   |
+-------------------------------------------------------+
|i2 : xmlGetName n                                      |
|                                                       |
|o2 = bar                                               |
+-------------------------------------------------------+
|i3 : xmlFirstAttribute n                               |
|                                                       |
|o3 = id = "foo"                                        |
|                                                       |
|o3 : LibxmlAttribute                                   |
+-------------------------------------------------------+
|i4 : xmlGetName oo                                     |
|                                                       |
|o4 = id                                                |
+-------------------------------------------------------+

Ways to use xmlGetName:
=======================

  * "xmlGetName(LibxmlAttribute)"
  * "xmlGetName(LibxmlNode)"

For the programmer
==================

The object xmlGetName, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlGetNext -- get the next XML node or attribute
************************************************

  * Usage:
        xmlGetNext n
  * Inputs:
      * n,
  * Outputs:
      * the next node in the linked list, or null (Macaulay2Doc),
        if there is none

Description
===========

+----------------------------------------------+
|i1 : xmlParse ///<bar><a/><b/></bar>///       |
|                                              |
|o1 = <bar>                                    |
|           <a/>                               |
|           <b/>                               |
|         </bar>                               |
|                                              |
|o1 : LibxmlNode (xmlTypeDescription)          |
+----------------------------------------------+
|i2 : xmlFirstChild oo                         |
|                                              |
|o2 = <a/>                                     |
|                                              |
|o2 : LibxmlNode (xmlTypeDescription)          |
+----------------------------------------------+
|i3 : xmlGetNext oo                            |
|                                              |
|o3 = <b/>                                     |
|                                              |
|o3 : LibxmlNode (xmlTypeDescription)          |
+----------------------------------------------+
|i4 : xmlGetNext oo                            |
+----------------------------------------------+
|i5 : xmlParse ///<bar id="foo" name="too"/>///|
|                                              |
|o5 = <bar id="foo" name="too"/>               |
|                                              |
|o5 : LibxmlNode (xmlTypeDescription)          |
+----------------------------------------------+
|i6 : xmlFirstAttribute oo                     |
|                                              |
|o6 = id = "foo"                               |
|                                              |
|o6 : LibxmlAttribute                          |
+----------------------------------------------+
|i7 : xmlGetNext oo                            |
|                                              |
|o7 = name = "too"                             |
|                                              |
|o7 : LibxmlAttribute                          |
+----------------------------------------------+
|i8 : xmlGetNext oo                            |
+----------------------------------------------+

Ways to use xmlGetNext:
=======================

  * "xmlGetNext(LibxmlAttribute)"
  * "xmlGetNext(LibxmlNode)"

For the programmer
==================

The object xmlGetNext, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlIsElement(LibxmlNode) -- whether an XML node is an element
*************************************************************

  * Function: xmlIsElement,
  * Usage:
        xmlIsElement n
  * Inputs:
      * n, an instance of the type LibxmlNode,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether n is an element

Description
===========

+------------------------------------+
|i1 : xmlParse ///<bar/>///          |
|                                    |
|o1 = <bar/>                         |
|                                    |
|o1 : LibxmlNode (xmlTypeDescription)|
+------------------------------------+
|i2 : xmlIsElement oo                |
|                                    |
|o2 = true                           |
+------------------------------------+

See also
========

  * xmlIsElement -- whether an XML node is
    an element
  * xmlGetContent -- get the string
    content of an XML text node

Ways to use this method:
========================

  * xmlIsElement(LibxmlNode) -- whether an
    XML node is an element
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlIsText(LibxmlNode) -- whether an XML node is text
****************************************************

  * Function: xmlIsText,
  * Usage:
        xmlIsText n
  * Inputs:
      * n, an instance of the type LibxmlNode,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether n is a text node

Description
===========

+-------------------------------------------+
|i1 : n = xmlParse ///<bar>hi there</bar>///|
|                                           |
|o1 = <bar>hi there</bar>                   |
|                                           |
|o1 : LibxmlNode (xmlTypeDescription)       |
+-------------------------------------------+
|i2 : c = xmlFirstChild n                   |
|                                           |
|o2 = "hi there"                            |
|                                           |
|o2 : LibxmlNode (xmlTypeDescription)       |
+-------------------------------------------+
|i3 : xmlIsText c                           |
|                                           |
|o3 = true                                  |
+-------------------------------------------+

See also
========

  * xmlIsElement -- whether an XML node is
    an element
  * xmlGetContent -- get the string
    content of an XML text node

Ways to use this method:
========================

  * xmlIsText(LibxmlNode) -- whether an XML
    node is text
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlNewRoot(String) -- create the root node of an XML document
*************************************************************

  * Function: xmlNewRoot,
  * Usage:
        xmlNewRoot v
  * Inputs:
      * v, a string (Macaulay2Doc),
  * Outputs:
      * an instance of the type LibxmlNode, the new root
        node of a new XML document, with name given by v

Description
===========

+-------------------------------------------+
|i1 : xmlNewRoot "foo"                      |
|                                           |
|o1 = <foo/>                                |
|                                           |
|o1 : LibxmlNode (xmlTypeDescription)       |
+-------------------------------------------+
|i2 : xmlDocDump oo                         |
|                                           |
|o2 = <?xml version="1.0" encoding="UTF-8"?>|
|     <foo/>                                |
+-------------------------------------------+

See also
========

  * xmlDocDump -- dump a document

Ways to use this method:
========================

  * xmlNewRoot(String) -- create the root node
    of an XML document
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

XMLnode -- the class of all XML trees created by the library libxml2
********************************************************************

Description
===========

An object of class XMLnode, is a hashtable used to contain a
representation of a node in an XML tree.

Each such hashtable represents a node of the tree, in which: the keys that are
strings provide the values of attributes; the symbol children provides the list
of children, each of which is a string (Macaulay2Doc), or an
instance of the type XMLnode,; and the symbol tag provides the
name of the element.

Currently, only element nodes and text nodes are implemented.

+-------------------------------------------------------+
|i1 : new XMLnode from {                                |
|          tag => "foo",                                |
|          children => {                                |
|               new XMLnode from {                      |
|                    tag => "bar",                      |
|                    children => { " chicken coop " } },|
|               " hi there ",                           |
|               new XMLnode from { tag => "bar" } } }   |
|                                                       |
|o1 = <foo                                              |
|       <bar " chicken coop "                           |
|       " hi there "                                    |
|       <bar                                            |
|                                                       |
|o1 : XMLnode                                           |
+-------------------------------------------------------+

Functions and methods returning an object of class XMLnode:
===========================================================

  * "parse" -- see parse(String), -- parse XML

Methods that use an object of class XMLnode:
============================================

  * toLibxmlNode(XMLnode) -- convert a
    hashtable of type XMLnode to an object of type LibxmlNode

For the programmer
==================

The object XMLnode, is a type (Macaulay2Doc), with
ancestor classes MutableHashTable (Macaulay2Doc), <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlParse(String) -- parse a string containing XML
*************************************************

  * Function: xmlParse,
  * Usage:
        xmlParse s
  * Inputs:
      * s, a string (Macaulay2Doc),
  * Outputs:
      * an instance of the type LibxmlNode,

Description
===========

+----------------------------------------------------------------------+
|i1 : xmlParse ///<foo>aabc<bar id="foo" name="too">asdf</bar></foo>///|
|                                                                      |
|o1 = <foo>aabc<bar id="foo" name="too">asdf</bar></foo>               |
|                                                                      |
|o1 : LibxmlNode (xmlTypeDescription)                                  |
+----------------------------------------------------------------------+

Ways to use this method:
========================

  * xmlParse(String) -- parse a string containing
    XML
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlType(LibxmlNode) -- the type code for an XML node
****************************************************

  * Function: xmlType,

Ways to use this method:
========================

  * xmlType(LibxmlNode) -- the type code for an
    XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlTypeDescription(LibxmlNode) -- the type description for an XML node
**********************************************************************

  * Function: xmlTypeDescription,
  * Usage:
        xmlTypeDescription n
  * Inputs:
      * n, an instance of the type LibxmlNode,
  * Outputs:
      * a string (Macaulay2Doc), the description of the type of n

Description
===========

+---------------------------------------------------------+
|i1 : xmlParse "<foo>the cat<bar/><!-- a comment--></foo>"|
|                                                         |
|o1 = <foo>the cat<bar/><!-- a comment--></foo>           |
|                                                         |
|o1 : LibxmlNode (xmlTypeDescription)                     |
+---------------------------------------------------------+
|i2 : getChildren oo                                      |
|                                                         |
|o2 = {"the cat"        }                                 |
|     {<bar/>           }                                 |
|     {<!-- a comment-->}                                 |
|                                                         |
|o2 : VerticalList                                        |
+---------------------------------------------------------+
|i3 : xmlTypeDescription \ oo                             |
|                                                         |
|o3 = {text node   }                                      |
|     {element node}                                      |
|     {comment node}                                      |
|                                                         |
|o3 : VerticalList                                        |
+---------------------------------------------------------+

Ways to use this method:
========================

  * xmlTypeDescription(LibxmlNode),
    -- the type description for an XML node
-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlTypeIndex -- get XML type code from its description
******************************************************

  * Usage:
        xmlTypeIndex

Description
===========

+------------------------------------------+
|i1 : xmlTypeIndex                         |
|                                          |
|o1 = HashTable{"attribute decl" => 16    }|
|               "attribute node" => 2      |
|               "cdata section node" => 4  |
|               "comment node" => 8        |
|               "document frag node" => 11 |
|               "document node" => 9       |
|               "document type node" => 10 |
|               "dtd node" => 14           |
|               "element decl" => 15       |
|               "element node" => 1        |
|               "entity decl" => 17        |
|               "entity node" => 6         |
|               "entity ref node" => 5     |
|               "html document node" => 13 |
|               "namespace decl" => 18     |
|               "notation node" => 12      |
|               "pi node" => 7             |
|               "text node" => 3           |
|               "xinclude end" => 20       |
|               "xinclude start" => 19     |
|                                          |
|o1 : HashTable                            |
+------------------------------------------+

See also
========

  * xmlTypeTable -- a hash table of descriptions for XML
    node type codes

For the programmer
==================

The object xmlTypeIndex, is a hash table (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlTypes -- a hash table of descriptions for XML node type codes
****************************************************************

Ways to use xmlTypes:
=====================

  * "xmlTypes(Sequence)"

For the programmer
==================

The object xmlTypes, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.

xmlTypeTable -- a hash table of descriptions for XML node type codes
********************************************************************

  * Usage:
        xmlTypeTable

Description
===========

+----------------------------------------+
|i1 : xmlTypeTable                       |
|                                        |
|o1 = HashTable{1 => element node       }|
|               2 => attribute node      |
|               3 => text node           |
|               4 => cdata section node  |
|               5 => entity ref node     |
|               6 => entity node         |
|               7 => pi node             |
|               8 => comment node        |
|               9 => document node       |
|               10 => document type node |
|               11 => document frag node |
|               12 => notation node      |
|               13 => html document node |
|               14 => dtd node           |
|               15 => element decl       |
|               16 => attribute decl     |
|               17 => entity decl        |
|               18 => namespace decl     |
|               19 => xinclude start     |
|               20 => xinclude end       |
|                                        |
|o1 : HashTable                          |
+----------------------------------------+

See also
========

  * xmlTypeIndex -- get XML type code from its description

For the programmer
==================

The object xmlTypeTable, is a hash table (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in XML.m2:662:0.