#### XMLNS

#### Synopsis

    HELP:   Namespace definitions (activate namespace handling)
    TYPE:   OBJECT
    SYNTAX: XMLNS[(PREFIX/PFX='str',URI='str')...]

#### Description

Defining XML namespaces activates namespace handling in XML-based tables. It is an array of pairs consisting of a prefix and a URI. The prefix is an abbreviation which can be used in path specifications (i.e. in `root` and `path` attributes when defining columns). If the prefix is not specified or an empty string, it is considered the default namespace which applies to all path elements which are not explicitly prefixed with one of the defined namespace prefixes. By defining a namespace without specifying prefix and URI (see below), the NULL namespace is used.

       ns() == namespace(prefix='' uri='')

This corresponds to an XML document without namespace definitions (using the NULL namespace for elements and attributes), but the namespace `xml` will be internally known and handled.

Attribute names are always in the NULL namespace according to the XML specification unless it has a namespace prefix.

If namespace handling is used when reading an XML document, the XML parser resolves all namespace prefixes in the document to the respective URIs and returns the namespace URI for each tag and attribute name. This URI is compared with the URI that is defined for path elements in the row specification of your table. The prefixes used in the XML document and the prefixes defined with the `prefix` attribute are consequently totally independent. The given namespace prefix is, however, used when writing tables as XML documents.

The prefixes for all namespaces must be unique and are case sensitive.

With namespace handling enabled, it no longer matters which prefixes are used inside the XML document since namespace are matched by URI. Therefore, the same `root` and `path` specifications can be used no matter if a tag is named `<ns1:svg>` or `<svg:svg>` in the XML document as long as both prefixes are mapped to the same URI. The namespace prefixes used in `root` and `path` strings must only match those defined via `xmlns(prefix=...)`.

When writing XML documents, the namespace declarations are put in the root XML tag. Per-subtree namespace declarations can currently not be written. Please contact support if this is required.

The defined prefix for a URI can be used in root and path strings:

    ...
    table(format=xml defaults(...
     xmlns(             uri='http://www.example.com/myspec')
     xmlns(prefix='ns0' uri='http://www.example.com/myspec')
     xmlns(prefix='ns1' uri='http://www.example.com/otherspec')
     ...)
     row(name='row1'
      col(name='col1' root='xml/ns0:row' path='dat1/&color')
      col(name='col2' root='xml/ns0:row' path='ns0:dat1')
      col(name='col3' root='xml/ns1:dmy' path='ns1:dmy1/&ns1:color')
      col(name='col4' root='xml/ns1:dmy' path='ns1:dmy1')
      ...
     )
     ...
    )
    ...

The prefix `ns0` can (but does not have to) be used in the root and path strings because the empty prefix (global namespace) has the same URI. The prefix 'ns1' must be used in the root and path strings where appropriate. If a path element in the `root` or `path` string contains a colon and the string before the colon is not a defined namespace prefix, the whole tag must match and the NULL namespace is used. When reading XML, this will yield an informational message or a warning (if enabled) to make you aware of possibly missing namespace declarations or typos. When writing XML, prefixes that are defined but not used in path or root strings are not written to the XML document. This could be used to read prefixed and unprefixed (i.e. with global namespace) XML documents and always write XML documents either with or without the prefix `ns0` in the example above, depending on whether or not you use the prefix in the `root` and `path` strings.

With only the global namespace definiton it looks like:

    ...
    table(format=xml defaults(...
     xmlns(             uri='http://www.example.com/myspec')
     xmlns(prefix='ns1' uri='http://www.example.com/otherspec')
     ...)
     row(name='row1'
      col(name='col1' root='xml/row' path'dat1/&color')
      col(name='col2' root='xml/row' path'dat1')
      col(name='col3' root='xml/ns1:dmy' path='ns1:dmy1/&ns1:color')
      col(name='col4' root='xml/ns1:dmy' path='ns1:dmy1')
      ...
     )
     ...
    )
    ...

With only a prefixed namespace definiton it must look like this:

    ...
    table(format=xml defaults(...
     xmlns(prefix='ns0' uri='http://www.example.com/myspec')
     xmlns(prefix='ns1' uri='http://www.example.com/otherspec')
     ...)
     row(name='row1'
      col(name='col1' root='ns0:xml/ns0:row' path='ns0:dat1/&color')
      col(name='col2' root='ns0:xml/ns0:row' path='ns0:dat1')
      col(name='col3' root='ns0:xml/ns1:dmy' path='ns1:dmy1/&ns1:color')
      col(name='col4' root='ns0:xml/ns1:dmy' path='ns1:dmy1')
      ...
     )
     ...
    )
    ...

Below is an XML example for namespaces and the corresponding row definition with an additional `xml:id` and `xml:lang` usage in the paragraphs to test the implicit `xml` prefix definition:

    #
    <html xmlns="http://www.w3.org/1999/xhtml"
          xmlns:svg="http://www.w3.org/2000/svg">
      <head>
        <title>Example with multiple namespaces</title>
      </head>
      <body>
        <h1>A math formula:</h1>
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <mi>x</mi><mo>=</mo><mn>2</mn>
        </math>
        <p xml:id="Chapter_1" xml:lang="en">The same as a picture:</p>
        <svg:svg>
          <svg:rect x="0" y="0" width="10" height="10" />
          <svg:text>
            <svg:tspan>A formula in the image:</svg:tspan>
            <svg:tspan>
              <math xmlns="http://www.w3.org/1998/Math/MathML">
                <mi>y</mi><mo>=</mo><mn>1</mn>
              </math>
            </svg:tspan>
          </svg:text>
        </svg:svg>
        <p xml:id="Chapter_2">An SVG image can also be used without prefix:</p>
        <svg xmlns="http://www.w3.org/2000/svg">
          <circle svg:cx="10" svg:cy="10" svg:r="5" svg:fill="red" />
        </svg>
      </body>
    </html>
    #
    format=xml defaults(type=string frasep=period
     xmlns(             uri='http://www.w3.org/1999/xhtml')
     xmlns(prefix='ns1' uri='http://www.w3.org/2000/svg')
     xmlns(prefix='ns2' uri='http://www.w3.org/1998/Math/MathML')
    )
    row(name='test'     root='html'
     col(name='title'   path='head/title'                                                    )
     col(name='h1m'     path='body/h1'                                                       )
     col(name='mi1'     path='body/ns2:math/ns2:mi'                                          )
     col(name='mo1'     path='body/ns2:math/ns2:mo'                                          )
     col(name='mn1'     path='body/ns2:math/ns2:mn'                            TYPE.INTEGER())
     col(name='p1id'    path='body/p/&xml:id'                                                )
     col(name='p1lang'  path='body/p/&xml:lang'                                              )
     col(name='p1'      path='body/p'                                                        )
     col(name='rect1x'  path='body/ns1:svg/ns1:rect/&x'                        TYPE.INTEGER())
     col(name='rect1y'  path='body/ns1:svg/ns1:rect/&y'                        TYPE.INTEGER())
     col(name='rect1w'  path='body/ns1:svg/ns1:rect/&width'                    TYPE.INTEGER())
     col(name='rect1h'  path='body/ns1:svg/ns1:rect/&height'                   TYPE.INTEGER())
     col(name='tspan1'  path='body/ns1:svg/ns1:text/ns1:tspan'                               )
     col(name='mi2'     path='body/ns1:svg/ns1:text/ns1:tspan/ns2:math/ns2:mi'               )
     col(name='mo2'     path='body/ns1:svg/ns1:text/ns1:tspan/ns2:math/ns2:mo'               )
     col(name='mn2'     path='body/ns1:svg/ns1:text/ns1:tspan/ns2:math/ns2:mn' TYPE.INTEGER())
     col(name='p2id'    path='body/p/&xml:id'                                                )
     col(name='p2'      path='body/p'                                                        )
     col(name='circ1x'  path='body/ns1:svg/ns1:circle/&ns1:cx'                 TYPE.INTEGER())
     col(name='circ1y'  path='body/ns1:svg/ns1:circle/&ns1:cy'                 TYPE.INTEGER())
     col(name='circ1r'  path='body/ns1:svg/ns1:circle/&ns1:r'                  TYPE.INTEGER())
     col(name='circ1f'  path='body/ns1:svg/ns1:circle/&ns1:fill'                             )
    )

The contents of the XML document are read into one row. The prefix `xml` is supported by default using the URI `http://www.w3.org/XML/1998/namespace` does not need to be defined.

The URIs are stored in a literal cache to save memory, but the corresponding hash calculation can increase the CPU utilization at read if namespace handling active.

#### Arguments

- `STRING: PREFIX/PFX='str' - Prefix for XML namespace handling ['']`
- `STRING: URI='str' - URI for XML namespace handling ['']`