@node sxml namespaced
@section Namespaced SXML

Namespaces is a variant to ``regular'' SXML. Difference being that
instead of representing XML-tags as symbols, they are instead actual
objects.

For example
@example
`(a (b "Content"))
@end example

Would be represented as
@example
`(,(xml 'a)
  (,(xml 'b)
   "Content"))
@end example

In this document a list with an XML tag object in its car is sometimes
refered to as an XML node.

@defun namespaced-sxml->sxml tree [namespace-prefixes='()]
Takes a tree of namespaced-sxml, and optionally an assoc list from
namespace symbols, to prefered prefix.

Returns a sxml tree, with xmlns:<prefix>=namespace attributes
@end defun

@defun namespaced-sxml->xml tree [namespaces='()] [port='(current-output-port)]
Serializes the namespaced sxml tree to port. @var{namespaces} should
be an association list from namespace symbols, to prefered prefixes.
@end defun

@defun namespaced-sxml->sxml/namespaces tree [namespace-prefixes='()]
Returns two values:
@itemize
@item An SXML tree (which doesn't have namespace attributes)
@item an association list from namespace symbols, to used prefixes.
@end itemize
@end defun

@c xml->namespcaed-sxml and sxml->namespaced-sxml don't share
@c implementation, despite doing almost the same thing. This is since
@c xml->namespaced-sxml directly uses the ssax parser, giving us great
@c controll, while sxml->namespaced-sxml attempt to look at symbols.

@defun xml->namespaced-sxml port-or-string
Reads xml from port, and return a namespaced SXML tree.
@end defun

@defun sxml->namespaced-sxml tree namespaces
Converts a ``regular'' SXML tree into a namespaced sxml tree.
@var{namespaces} must be an association list which maps each prefix
used in @var{tree} onto a full XML namespace.

The key @code{#f} can be used to map non-namespaced elements into a
namespace.
@end defun

@defun xml tag
@defunx xml ns tag [attrs]
@anchor{xml-tag}
       A single XML element, suitable to go as the car of a list to
       create a full object.

       @var{xml} is a shorthand to @code{make-xml-element}, which
       either takes just a tag (for non-namespaced elements), or a
       namespace, a tag, and a list of attributes.

       @itemize
       @item @var{tag} should be a symbol.
       @item @var{ns} should be a symbol.
       @item @var{attrs} should be a hash table.
       @end itemize

       @defun make-xml-element tagname namespace attributes
       @end defun

       @defun xml-element? x
       @end defun

       @defun xml-element-tagname el
       @end defun

       @defun xml-element-namespace el
       @end defun

       @defun xml-element-attributes el
       @end defun
@end defun


@defun make-pi-element tag body
       @defun pi-element? x
       @end defun

       @defun pi-tag pi
       @end defun

       @defun pi-body pi
       @end defun
@end defun

@section Namespaced SXML utilities

Provided by the module @code{(sxml namespaced util)}.

@defun xml-element-hash-key xml-tag
Given an xml tag object @ref{xml-tag}, return a suitable key for
@code{hash-ref} and family.

These key objects should preferably not be carried around for
long. Prefer to keep the @emph{real} xml-tag object, and only call
this while directly referencing the hash table.
@end defun

@defun find-element target list
@var{list} should be an element of XML nodes, and @var{target} an XML
element object.

Returns the first element of @var{list} which matches the tagname and
namespace of @var{target}.
@end defun

@defun element-matches? element node
Checks that the bare element @var{element} has the same tagname and
namespaces as the begining tag of @var{node}.
@end defun

@defun on-root-element proc tree
Apply proc to the root element of the tree. The root elemnet here is
assumed to be the topmost ``regular'' xml component.

For example, the tree
@example
<?doctype example?>
<a/>
@end example

Would serialize as
@example
'(*TOP* (*PI* doctype "example")
        (a))
@end example

This procedure would apply @var{proc} to @code{(a)}, and return the
form generated by replacing @code{(a)} with the return value of
@var{proc}.
@end defun

@defun root-element
Extract the root element of a namespaced sxml tree.
@end defun