# Class: xml

## DESCRIPTION:

Constructor for an xml-object

#

## Properties

No properties

# Public: addns

## DESCRIPTION:

addns - add a namespace definition to the xml-object

## CALL:

obj = addns(obj,S)

## INPUT:

obj | xml-object |
    S:   <struct> fieldnames --> namespace variable
                  values     --> namespace value
         <cell array> nx2, first column  --> namespace variable
                           second column --> namespace value

## OUTPUT:

obj | xml-object |
    EXAMPLE
     %create an xml-object
     obj = xml(fullfile(pwd,'examples','namespaces.xml'))

     %try to get attribute
     obj.width.('@nsdim:dim')

     %add namespace
     addns(obj,{'nsdim','http://www.modelit.nl/dimension'})

     %get attribute
     obj.width.('@nsdim:dim')

# Public: attributeNames

## DESCRIPTION:

xml/attributeNames is a function. names = attributeNames(obj)

# Public: clearns

## DESCRIPTION:

clearns - remove all the namespace definitions from the xml-object

## CALL:

obj = addns(obj,S)

## INPUT:

obj | xml-object |
    S:   <struct> fieldnames --> namespace variable
                  values     --> namespace value
         <cell array> size: nx2, first column  --> namespace variable
                           second column --> namespace value

## OUTPUT:

       obj: <xml-object> with no namespace definitions

      EXAMPLE
       %create an xml-object
       obj = xml(fullfile(pwd,'examples','namespaces.xml'))

       %add namespaces
       addns(obj,{'ns','http://www.w3schools.com/furniture'})
       addns(obj,{'nsdim','http://www.modelit.nl/dimension'})

       %list namespaces
       listns(obj)

       %clear all defined namespaces
       clearns(obj)

       %list namespaces
       listns(obj)

# Public: display

## DESCRIPTION:

display - display information about an xml-object on the console

## CALL:

display(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       none, information about the xml-object is displayed on the console

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       %display function was automatically called by Matlab

# Public: fieldnames

## DESCRIPTION:

fieldNames - get the names of the direct children of the root node c.f. the function fieldnames for structures

## CALL:

fields = fieldnames(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       fields: <cellstring> with the nodenames of the children of the root node

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       fieldnames(obj)

       book1 = obj.book(1)
       fieldnames(book1{1})

# Public: get

## DESCRIPTION:

get - get the value of the specified property for an xml-object (from the object itself not from the xml)

## CALL:

prop_val = get(obj,prop_name)

## INPUT:

obj | xml-object |
    prop_name:   <string> propertyname, possible values:
                         - DOM  <org.apache.xerces.dom.DeferredDocumentImpl>
                                with the DOM representation of the xml
                         - file <string> with filename
                         - NS   <java.util.HashMap> with namespaces

## OUTPUT:

       prop_val:     the value of the specified property for the xml-object
                     <struct> with all properties plus values if nargin == 1

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       %get all property-value pairs
       get(obj)
       %get the (D)ocument (O)bject (M)odel
       get(obj,'DOM')

# Public: getRoot

## DESCRIPTION:

getRoot - get the root node of an xml-object and its name

## CALL:

[rootname root] = getRoot(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       rootname: <string> the name of the root node
       root:     <java object> org.apache.xerces.dom.DeferredElementNSImpl or
                               org.apache.xerces.dom.DeferredElementImpl

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       [rootname root] = getRoot(obj)

# Public: getns

## DESCRIPTION:

getns - retrieve a namespace definition from the xml-object

## CALL:

S = listns(obj,key)

## INPUT:

obj | xml-object |
    key: <string> with a namespace variable for which the definition has to
                  be retrieved

## OUTPUT:

       S: <string> with the namespace definition

      EXAMPLE
       %create an xml-object
       obj = xml(fullfile(pwd,'examples','namespaces.xml'))

       %add namespace
       addns(obj,{'nsdim','http://www.modelit.nl/dimension'})

       %get namespace
       getns(obj,'nsdim')

# Public: inspect

## DESCRIPTION:

inspect - visualize the xml document as a tree in a separate window

## CALL:

inspect(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       none, the DOM representation of the xml document appears as a tree
             in a separate window

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       inspect(obj)

# Public: isempty

## DESCRIPTION:

isempty - true if the xml-object has no fields

## CALL:

tf = isempty(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       tf: <boolean> true if the DOM representation of the xml document does
                     not contain any nodes, or equivalently the xml-document
                     has no fields

## EXAMPLE:

       %create an empty xml-object
       obj = xml
       isempty(obj)

       %add a field to the xml-object
       obj.field = 'field'
       isempty(obj)

       %remove field from the xml-object
       rmfield(obj,'field');
       isempty(obj)

# Public: isfield

## DESCRIPTION:

isfield - true if at least one node satisfies the indexing 'sub'

## CALL:

tf = isfield(obj,field)

## INPUT:

obj | xml-object |
    sub: <string> index into xml document (same format as indexing into
                  Matlab structures) e.g. 'book(1)' or 'book(1).title'
                  result in the same substructs as would be obtained if
                  S.book(1)or S.book(1).title were used (S a Matlab
                  structure)
         <string> with xpath expression

## OUTPUT:

       tf: <boolean>  true if at least one node satisfies the indexing 'sub'

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       isfield(obj,'book(1:2)')
       isfield(obj,'book(2).@category')
       %N.B. in the following statement true is return although the number of
       %books is 4, this is because book(2:4) exist
       isfield(obj,'book(2:10)')

       %examples with xpath expression
       %are there any books in english?
       isfield(obj,'bookstore/book/title[@lang=''en'']')
       %are there any books in spanish?
       isfield(obj,'bookstore/book/title[@lang=''es'']')
       %are there books cheaper than 30 euro
       isfield(obj,'bookstore/book[price < 30]')

# Public: listns

## DESCRIPTION:

listns - list the namespace definitions of the xml-object

## CALL:

listns(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       no direct output, the defined namespaces are displayed on the console

      EXAMPLE
       %create an xml-object
       obj = xml(fullfile(pwd,'examples','namespaces.xml'))

       %no namespaces defined yet
       listns(obj)

       %add namespaces
       addns(obj,{'ns','http://www.w3schools.com/furniture'})
       addns(obj,{'nsdim','http://www.modelit.nl/dimension'})

       %list namespaces
       listns(obj)

# Public: noNodes

## DESCRIPTION:

noNodes - get the total number of nodes present in the DOM-representation of the xml document

## CALL:

N = noNodes(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       N: <integer> with the total number of nodes in the DOM object

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       noNodes(obj)

# Public: removens

## DESCRIPTION:

removens - remove a namespace definition from the xml-object

## CALL:

obj = removens(obj,S)

## INPUT:

obj | xml-object |
    S:   <char array> with names of the namespace definitions to be removed
         <cell array> with names of the namespace definitions to be removed

## OUTPUT:

obj | xml-object |
    EXAMPLE
     %create an xml-object
     obj = xml(fullfile(pwd,'examples','namespaces.xml'))

     %add namespace
     addns(obj,{'nsdim','http://www.modelit.nl/dimension'})

     %get attribute
     obj.width.('@nsdim:dim')

     %remove namespace
     removens(obj,{'nsdim'})

     %try to get attribute
     obj.width.('@nsdim:dim')

# Public: rmfield

## DESCRIPTION:

rmfield - remove elements and attributes from an xml-object which satisfy the indexing 'sub'

## CALL:

rmfield(obj,sub)

## INPUT:

obj | xml-object |
    sub: <string> index into xml document (same format as indexing into
                  Matlab structures) e.g. 'book(1)' or 'book(1).title'
                  result in the same substructs as would be obtained if
                  S.book(1)or S.book(1).title were used (S a Matlab
                  structure)
         <string> with xpath expression

## OUTPUT:

       none, the xml-object is updated

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       rmfield(obj,'book(1:2)')
       rmfield(obj,'book(2).@category')
       inspect(obj)

       %examples with xpath expression
       obj = xml(fullfile(pwd,'examples','books.xml'))
       %remove books cheaper than 30 euro
       rmfield(obj,'bookstore/book[price < 30]')
       inspect(obj)

       obj = xml(fullfile(pwd,'examples','books.xml'))
       %remove books in the category 'WEB'
       rmfield(obj,'bookstore/book[@category = ''WEB'']')
       inspect(obj)

# Public: save

## DESCRIPTION:

save - save the xml-object as an xml file

## CALL:

obj = save(obj,fname)

## INPUT:

obj | xml-object |
    fname: <string> (optional) the name of the xml file, if fname is not
                               specified a save dialog will pop up

## OUTPUT:

       obj: <xml-object> the file field of the xml-object is updated and an xml
                         file is created

## EXAMPLE:

       obj = xml                  %create an empty xml object
       obj.date = datestr(now)    %add fields with values
       obj.description = 'test'
       obj = save(obj,'test.xml') %save object by specifying filename
       obj = xml('test.xml')
       inspect(obj);

# Public: selectNodes

## DESCRIPTION:

selectNodes - select nodes from the XML DOM tree

## CALL:

nodesList = selectNodes(obj,ind)

## INPUT:

obj | xml-object |
    ind: <struct array> with fields
                        - type: one of '.' or '()'
                        - subs: subscript values (field name or cell array
                                of index vectors)
         <string> with an xpath expression

## OUTPUT:

       nodesList: <java object> java.util.ArrayList with tree nodes

# Public: set

## DESCRIPTION:

set - set the value of the specified property for an xml-object

## CALL:

set(obj,prop_name,prop_value)

## INPUT:

obj | xml-object |
    prop_name:   <string> propertyname, possible values:
                         - DOM  <org.apache.xerces.dom.DeferredDocumentImpl>
                                with the DOM representation of the xml
                         - file <string> with filename
                         - NS   <java.util.HashMap> with namespaces
    prop_value:   the value of the property to be set for the xml-object

## OUTPUT:

       obj: <xml-object> with the property prop_name set to prop_value

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       %get all property-value pairs
       get(obj,'file')
       %get the (D)ocument (O)bject (M)odel
       obj = set(obj,'file',fullfile(pwd,'examples','books_changed.xml'))
       get(obj,'file')

# Public: storeStructure

## DESCRIPTION:

storeStructure - store contents of structure in xml object

## CALL:

obj = storeStructure(obj,S)

## INPUT:

       S: <struct> or <struct array>

## OUTPUT:

obj | xml-object |

## EXAMPLE:

       obj=xml
       obj = storeStructure(obj,S)
       inspect(obj)

      NOTES
          - This function is called by xml object constructor, in case where
          constructure is called with a structure as its input argument.
          - Although alternative uses of this method may be possible, they have
          not yet been tested

# Public: subsasgn

## DESCRIPTION:

subsasgn - assign new values to the xml document in an xml-object

## CALL:

obj = subsassgn(obj,ind,data)

## INPUT:

obj | xml-object |
    ind:  <struct array> with fields
                         - type: one of '.' or '()'
                         - subs: subscript values (field name or cell array
                                 of index vectors)
          <string> with an xpath expression
    data: (optional) with the values to be put in the by ind defined
                     fields in the xml-object, allowed types:
                      - <struct> matlab structure
                      - <xml-object>
                      - <org.apache.xerces.dom.ElementImpl>

## OUTPUT:

obj | xml-object |

# Public: subsref

## DESCRIPTION:

subsref - subscripted reference for an xml object

## CALL:

S = subsref(obj,ind)

## INPUT:

obj | xml-object |
    ind:  <struct array> with fields
                         - type: one of '.' or '()'
                         - subs: subscript values (field name or cell array
                                 of index vectors)
          <string> with an xpath expression

## OUTPUT:

       S: <cell array> with contents of the referenced nodes, can contain
                       xml objects, strings or numbers

# Public: view

## DESCRIPTION:

view - convert the xml-object into a string Note: This method has been superseeded by the method "xml2str" the method view is kept for backward compability but will become obsolete in the future.

## CALL:

view(obj) S=view(obj)

## INPUT:

obj | xml-object |

## OUTPUT:

       S:       <string> with the xml-document

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       view(obj)

# Public: xml

## DESCRIPTION:

xml - Constructor for an xml-object

## CALL:

obj = xml(FileName, isNameSpaceAware)

## INPUT:

FileName | any |
    string, the name of the sourcefile
    string, the xml string
    java-object, a D(ocument) (O)bject (M)odel
    struct, a Matlab structure
isNameSpaceAware | any |
    boolean, (optional) (default == 1) use namespaces

## OUTPUT:

obj | any |
    xml-object with fields:
     - DOM:  <java object> the DOM object
     - file: <string> the name of the xml source
     - NS:   <java object> a hashmap with namespace definitions
             N.B. obj is empty when an error occurred

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       inspect(obj)

       %create an xml from a sourcefile
       obj = xml(java.io.File(fullfile(pwd,'examples','books.xml')))
       inspect(obj)

       %create an xml from a Matlab structure
       obj = xml(dir)
       inspect(obj)

       %create an xml directly from a string
       str = '<book category="MATHS"><title lang="en">Nonlinear Programming</title><author>Dimitri P. Bertsekas</author></book>'
       obj = xml(str)
       inspect(obj)

       %create an xml directly from an inputstream
       obj = xml(java.io.FileInputStream((fullfile(pwd,'examples','books.xml'))))
       inspect(obj)

# Public: xml2str

## DESCRIPTION:

xml2str - convert the xml-object into a string Note: This method replaces the method "view" the method view is kept for backward compability

## CALL:

xml2str(obj) S=xml2str(obj)

## INPUT:

obj | xml-object |
    removeEOL: optional boolean, default value: false
               if true remove ascii codes 10 13 and return string in 1 line

## OUTPUT:

       S:       <string> with the xml-document

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       xml2str(obj)

# Public: xml2struct

## DESCRIPTION:

xml2struct - transform xml object to Matlab structure if contents of XML permit this CALL s=xml2struct(obj) s=xml2struct(obj,NOCELL) INPUT obj: XML object NOCELL: if true, do NOT store data in cells. Defaults to false OUTPUT corresponding Matlab structure NOTE not all XML documents can be represented as a Matlab strucure if XML contents do not fit the following error results: "XML contents do not fit in Matlab structure"

# Public: xmlBK

## DESCRIPTION:

xml - constructor for an xml-object

## CALL:

obj = xml(FileName,isNameSpaceAware,isValidating)

## INPUT:

       FileName:         <string> name of the sourcefile
                         <string> the xml string
                         <java-object> with a D(ocument) (O)bject (M)odel
                         <struct> a Matlab structure
       isNameSpaceAware: <boolean> (optional) (default == 1) ignore namespaces
       isValidating:     <boolean> (optional) (default == 0) validate document

## OUTPUT:

       obj: <xml-object> with fields:
                         - DOM:  <java object> the DOM object
                         - file: <string> the name of the xml source
                         - NS:   <java object> a hashmap with namespace
                                               definitions
                         N.B. obj is empty when an error occurred

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       inspect(obj)

       %create an xml from a sourcefile
       obj = xml(java.io.File(fullfile(pwd,'examples','books.xml')))
       inspect(obj)

       %create an xml from a Matlab structure
       obj = xml(dir)
       inspect(obj)

       %create an xml directly from a string
       str = '<book category="MATHS"><title lang="en">Nonlinear Programming</title><author>Dimitri P. Bertsekas</author></book>'
       obj = xml(str)
       inspect(obj)

       %create an xml directly from an inputstream
       obj = xml(java.io.FileInputStream((fullfile(pwd,'examples','books.xml'))))
       inspect(obj)

       %create an xml from a sourcefile and validate against a dtd (specified
       %in the xml itself
       obj = xml(fullfile(pwd,'examples','note_dtd.xml'),0,1)

       %create an xml from a sourcefile and validate against a xsd (specified
       %in the xml itself
       obj = xml(fullfile(pwd,'examples','note_xsd.xml'),1,1)

# Public: xpath

## DESCRIPTION:

xpath - carry out a set or get for an xml-object using xpath syntax

## CALL:

S = xpath(obj,ind) S = xpath(obj,ind,data)

## INPUT:

obj | xml-object |
    ind:  <struct array> with fields
                         - type: one of '.' or '()'
                         - subs: subscript values (field name or cell array
                                 of index vectors)
          <string> with an xpath expression
    data: (optional) with the values to be put in the by ind defined
                     fields in the xml-object, allowed types:
                      - <struct> matlab structure
                      - <xml-object>
                      - <org.apache.xerces.dom.ElementImpl>

## OUTPUT:

       S:       <cell array> in nargin == 2 (get is used)
                <xml-object> if nargin == 3 (set is used)

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','books.xml'))
       %select the book with title 'Harry Potter'
       book = xpath(obj,'parent::/bookstore/book[title="Harry Potter"')
       inspect(book{1})

# Public: xslt

## DESCRIPTION:

xslt - transform the xml-object to html by using a stylesheet

## CALL:

HTMLstring = xslt(obj,xsl,fileName)

## INPUT:

obj | xml-object |
    xsl:      <string> filename of the stylesheet
    fileName: <string> (optional) the name of the file to which the HTML has
                                  to be saved

## OUTPUT:

       HTMLstring:  <string> to HTML transformed XML string

## EXAMPLE:

       %create an xml from a sourcefile
       obj = xml(fullfile(pwd,'examples','cd_catalog.xml'))
       HTMLstring = xslt(obj,fullfile(pwd,'examples','cd_catalog.xsl'))
       %display in browser
       web(['text://' HTMLstring]);