@@
[1] 
This is the work-in-progress
specification for the manakai's DOM binding for Perl.
This specification only scopes [[manakai]]'s DOM implementation;
it does not try to define what any other DOM implementation
should do.  However, other DOM implementation
that exposes interfaces to Perl scripts '''[[MAY]]''' use this binding.

@@
[2] TODO:
- Truck the draft for the ECMAScript binding authored by
W3C Web APIs WG
- Write comparison with SVGT 1.2's DOM Perl Language Binding
- The global object ([CODE(DOMi)@en[[[Window]]]])

* Objects and interfaces

[3]
A DOM object, i.e. an object implementing one
or more DOM interfaces, '''[[MUST]]''' be represented
by a Perl object, i.e. a thingly referenced
by some Perl references and [CODE@en[bless]]ed in
a Perl class, unless otherwise specified.
The Perl class '''[[MUST]]''' implement 
the DOM interfaces implemented by the DOM object.

@@ better wording, getFeature consideration

* Methods and attributes

[5]
A [[DOM]] method [['''MUST''']] be implemented as a [[Perl]] method.

[6]
A read-only [[DOM]] attribute [['''MUST''']] be implemented as
a [[Perl]] method that returns the value contained in the [[DOM]] attribute.
The [[Perl]] method [['''MAY''']] throw an implementation
dependent exception if any argument is specified for the [[Perl]] method.

[7]
A read-write [[DOM]] attribute [['''MUST''']] be implemented as
a [[Perl]] method.  The [[Perl]] method [['''MUST''']] return
the value contained in the [[DOM]] attribute if no argument is
specified for the [[Perl]] method (i.e. the only argument to
the subroutine implementing the [[Perl]] method is the object itself).
Otherwise, the [[Perl]] method [['''MUST''']] try to set
the first argument specified for the method (i.e. the
second argument to the subroutine implementing the
[[Perl]] method) to the [[DOM]] attribute.

;; Note that specifying [CODE(perl)@en[[[undef]]]]
as the argument to the [[Perl]] method, which
set the [CODE(DOM)@en[[[null]]]] value
to the [[DOM]] attribute, is different from
specifying no argument, which returns the [[DOM]]
attribute value.

[8]
A [[DOM]] parameter to a method is [DFN@en[optional]] if
either [CODE(DOM)@en[[[null]]]] or [CODE(IDL)@en[[[boolean]]]]
[CODE(DOM)@en[[[false]]]] value is allowed to be specified
to that parameter and any following [[DOM]] parameter
is optional.

The [[Perl]] method [['''MUST''']] act as if an [CODE(perl)@en[[[undef]]]]
or a [[Perl]] false value, depending on the data type of the parameter,
is specified to each optional parameter if no argument
corresponding to that parameter is specified.

* Constants

* Exceptions and errors

[9]
Throwing an exception [['''MUST''']] be implemented by [[Perl]]
[CODE(perl)@en[[[die]]]] function.  If the exception is one
defined in DOM specification, the argument to the
[CODE(perl)@en[[[die]]]] function [['''MUST''']]
be an object implementing the associated exception interface.

;; Implementations are encouraged to employ the
[CODE(perl)@en[[[Error]]]] module as a basis
to construct their own exception mechanism.

@@ Exception classes

@@ DOMErrors

* Events

* Naming Rule

[15]
Names of DOM methods and attributes [['''MUST''']]
be mapped to Perl method (subroutine) name
by following algorithm:
= Let [VAR@en[n]] as the name of a DOM method or attribute.
= If the first column of the table >>14 contains
[VAR@en[n]], then return the name contained
in the cell in the second column of the same row.
= Otherwise, repeating the following step while [VAR@en[n]]
contains any uppercase letter.
== Replace a sequence of one or more uppercase letters
in [VAR@en[n]] by a [CODE(charname)@en[[[LOW LINE]]]] followed
by the lowercase variant of that sequence.
= Then, return [VAR@en[n]].

[14]
'''Exceptions'''.
,[[DOM]],[[DOM Perl Binding]],Note
,[CODE(DOMa)@en[[[accessKey]]]],[CODE(perl)@en[[[accesskey]]]],"[CODE(DOMi)@en[[[HTMLInputElement]]]], [CODE(DOMi)@en[[[HTMLTextAreaElement]]]], [CODE(DOMi)@en[[[HTMLButtonElement]]]], [CODE(DOMi)@en[[[HTMLLabelElement]]]], [CODE(DOMi)@en[[[HTMLLegendElement]]]], [CODE(DOMi)@en[[[HTMLAnchorElement]]]], [CODE(DOMi)@en[[[HTMLAreaElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[aLink]]]],[CODE(perl)@en[[[alink]]]],[CODE(DOMi)@en[[[HTMLBodyElement]]]] ([[DOM HTML]])
,[CODE(DOMa)@en[[[bgColor]]]],[CODE(perl)@en[[[bgcolor]]]],"[CODE(DOMi)@en[[[HTMLDocument]]]], [CODE(DOMi)@en[[[HTMLBodyElement]]]], [CODE(DOMi)@en[[[HTMLTableElement]]]], [CODE(DOMi)@en[[[HTMLTableRowElement]]]], [CODE(DOMi)@en[[[HTMLTableCellElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[cellPadding]]]],[CODE(perl)@en[[[cellpadding]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[cellSpacing]]]],[CODE(perl)@en[[[cellspacing]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[codeBase]]]],[CODE(perl)@en[[[codebase]]]],"[CODE(DOMi)@en[[[HTMLObjectElement]]]], [CODE(DOMi)@en[[[HTMLAppletElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[codeType]]]],[CODE(perl)@en[[[codetype]]]],"[CODE(DOMi)@en[[[HTMLObjectElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[colSpan]]]],[CODE(perl)@en[[[colspan]]]],"[CODE(DOMi)@en[[[HTMLTableCellElement]]]] ([[DOM HTML]])"
,[CODE(DOMm)@en[[[createTFoot]]]],[CODE(perl)@en[[[create_tfoot]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMm)@en[[[createTHead]]]],[CODE(perl)@en[[[create_thead]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[dateTime]]]],[CODE(perl)@en[[[datetime]]]],"[CODE(DOMi)@en[[[HTMLModElement]]]] ([[DOM HTML]])"
,[CODE(DOMm)@en[[[deleteTFoot]]]],[CODE(perl)@en[[[delete_tfoof]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMm)@en[[[deleteTHead]]]],[CODE(perl)@en[[[delete_thead]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMm)@en[[[findOffset16]]]],[CODE(perl)@en[[[find_offset_16]]]],[CODE(DOMi)@en[[[StringExtended]]]] ([[DOM Core]] informative)
,[CODE(DOMm)@en[[[findOffset32]]]],[CODE(perl)@en[[[find_offset_32]]]],[CODE(DOMi)@en[[[StringExtended]]]] ([[DOM Core]] informative)
,[CODE(DOMa)@en[[[frameBorder]]]],[CODE(perl)@en[[[frameborder]]]],"[CODE(DOMi)@en[[[HTMLFrameElement]]]], [CODE(DOMi)@en[[[HTMLIFrameElement]]]] ([[DOM HTML]])"
,[CODE(DOMm)@en[[[getAbsoluteReference3986]]]],[CODE(perl)@en[[[get_absolute_reference_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMm)@en[[[getAbsoluteReference3987]]]],[CODE(perl)@en[[[get_absolute_reference_3987]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMm)@en[[[getIRIReference3987]]]],[CODE(perl)@en[[[get_iri_reference_3987]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMm)@en[[[getURIReference3986]]]],[CODE(perl)@en[[[get_uri_reference_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isAbsoluteIRI3987]]]],[CODE(perl)@en[[[is_absolute_iri_3987]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isAbsoluteURI3986]]]],[CODE(perl)@en[[[is_absolute_uri_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isIRI3987]]]],[CODE(perl)@en[[[is_iri_3987]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isIRIReference3987]]]],[CODE(perl)@en[[[is_iri_reference_3987]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isMap]]]],[CODE(perl)@en[[[ismap]]]],"[CODE(DOMi)@en[[[HTMLImageElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[isRelativeIRIReference3987]]]],[CODE(perl)@en[[[is_iri_reference_3987]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isRelativeReference3986]]]],[CODE(perl)@en[[[is_relative_reference_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMm)@en[[[isSameDocumentReference3986]]]],[CODE(perl)@en[[[is_same_document_reference_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isURI3986]]]],[CODE(perl)@en[[[is_uri_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[isURIReference3986]]]],[CODE(perl)@en[[[is_uri_reference_3986]]]],[CODE(DOMi)@en[[[URIReference]]]] ([[manakai]]'s extension)
,[CODE(DOMa)@en[[[longDesc]]]],[CODE(perl)@en[[[longdesc]]]],"[CODE(DOMi)@en[[[HTMLImageElement]]]], [CODE(DOMi)@en[[[HTMLFrameElement]]]], [CODE(DOMi)@en[[[HTMLIFrameElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[marginHeight]]]],[CODE(perl)@en[[[marginheight]]]],"[CODE(DOMi)@en[[[HTMLFrameElement]]]], [CODE(DOMi)@en[[[HTMLIFrameElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[marginWidth]]]],[CODE(perl)@en[[[marginwidth]]]],"[CODE(DOMi)@en[[[HTMLFrameElement]]]], [CODE(DOMi)@en[[[HTMLIFrameElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[maxLength]]]],[CODE(perl)@en[[[maxlength]]]],"[CODE(DOMi)@en[[[HTMLInputElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[noHref]]]],[CODE(perl)@en[[[nohref]]]],[CODE(DOMi)@en[[[HTMLAreaElement]]]] ([[DOM HTML]])
,[CODE(DOMa)@en[[[noResize]]]],[CODE(perl)@en[[[noresize]]]],"[CODE(DOMi)@en[[[HTMLFrameElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[noShade]]]],[CODE(perl)@en[[[noshade]]]],[CODE(DOMi)@en[[[HTMLHRElement]]]] ([[DOM HTML]])
,[CODE(DOMa)@en[[[noWrap]]]],[CODE(perl)@en[[[nowrap]]]],"[CODE(DOMi)@en[[[HTMLTableCellElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[readOnly]]]],[CODE(perl)@en[[[readonly]]]],"[CODE(DOMi)@en[[[HTMLInputElement]]]], [CODE(DOMi)@en[[[HTMLTextAreaElement]]]]([[DOM HTML]])"
,[CODE(DOMa)@en[[[rowSpan]]]],[CODE(perl)@en[[[rowspan]]]],"[CODE(DOMi)@en[[[HTMLTableCellElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[tabIndex]]]],[CODE(perl)@en[[[tabindex]]]],"[CODE(DOMi)@en[[[HTMLSelectElement]]]], [CODE(DOMi)@en[[[HTMLInputElement]]]], [CODE(DOMi)@en[[[HTMLTextAreaElement]]]], [CODE(DOMi)@en[[[HTMLButtonElement]]]], [CODE(DOMi)@en[[[HTMLAnchorElement]]]], [CODE(DOMi)@en[[[HTMLObjectElement]]]], [CODE(DOMi)@en[[[HTMLAreaElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[tBodies]]]],[CODE(perl)@en[[[tbodies]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[tFoot]]]],[CODE(perl)@en[[[tfoot]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[tHead]]]],[CODE(perl)@en[[[thead]]]],"[CODE(DOMi)@en[[[HTMLTableElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[URL]]]],[CODE(perl)@en[[[url]]]],[CODE(DOMi)@en[[[HTMLDocument]]]] ([[DOM HTML]])
,[CODE(DOMa)@en[[[useMap]]]],[CODE(perl)@en[[[usemap]]]],"[CODE(DOMi)@en[[[HTMLInputElement]]]] , [CODE(DOMi)@en[[[HTMLImageElement]]]], [CODE(DOMi)@en[[[HTMLObjectElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[vAlign]]]],[CODE(perl)@en[[[valign]]]],"[CODE(DOMi)@en[[[HTMLTableColElement]]]] , [CODE(DOMi)@en[[[HTMLTableSectionElement]]]], [CODE(DOMi)@en[[[HTMLTableRowElement]]]], [CODE(DOMi)@en[[[HTMLTableCellElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[valueType]]]],[CODE(perl)@en[[[valuetype]]]],"[CODE(DOMi)@en[[[HTMLParamElement]]]] ([[DOM HTML]])"
,[CODE(DOMa)@en[[[vLink]]]],[CODE(perl)@en[[[vlink]]]],[CODE(DOMi)@en[[[HTMLBodyElement]]]] ([[DOM HTML]])

* Data types

[10] In this section, [DFN@en[number type]]s includes:
[CODE(IDL)@en[[[long]]]], [CODE(IDL)@en[[[unsigned long]]]],
[CODE(IDL)@en[[[unsigned long long]]]],
[CODE(IDL)@en[[[short]]]], 
and [CODE(IDL)@en[[[unsigned short]]]].

[11]
If the return value of the [[DOM]] method or the [[DOM]] attribute
is of number type and a [[Perl]] method return a value
in that type, jt [['''MUST''']] return a value
that can be evaluated as a number (by, e.g., [CODE(perl)@en[0+]]
operation).

[12]
If a [[DOM]] method parameter or the [[DOM]] attribute is 
of number type and it is necessary for a [[Perl]] method to
get the specified value, it [['''MAY''']] evaluate
the specified value as a value (by, e.g., [CODE(perl)@en[0+]]
operation).


@@
Similary, IDL type <TYPE^^DISCore|QName::idl|boolean>
    is expected to be evaluated in the Boolean context.

    IDL type <TYPE^^DISCore|QName::idl|any> is corresponding to any scalar valu\
e
    in Perl.  IDL type <TYPE^^DISCore|QName::idl|Object> is bound to object.

    The <DOM::null> value is bound to <Perl::undef>.

** [CODE(DOM)@en[DOMString]]

@@
  The <TYPE::MIString> type is bound to Perl string value and
    expected to be evaluated in the string context.  A <TYPE::MIString>
    value <kwd:MUST> be interpreted as a sequence of characters rather than
    a sequence of bytes or octets.  If it is represented
    internally as a byte string, i.e. the utf8 flag turned off,
    it <kwd:MUST> be interpreted as a ISO/IEC 8859-1 <bibref::ISO8859-1> string\
.


** [CODE(DOM)@en[DOMTimeStamp]]

[4] '''[CODE(DOM)@en[DOMTimeStamp]] for a Calendar Date-Time'''

A [CODE(DOM)@en[DOMTimeStamp]] value that is
an absolute date-time [['''MUST''']] be represented
by a scalar value of the number of the seconds
from [CODE[[[1970-01-01T00:00:00Z]]]].
The scalar value [['''MAY''']] contain fraction part,
which represents a fraction of a second.

;; For example, [CODE[[[1970-01-01T00:00:00Z]]]]
is mapped to a numeric value of [CODE(perl)[[[0]]]].

@@ Leap seconds, days before [CODE[[[1970-01-01T00:00:00Z]]]]

* Security

* Features and DOMImplementationRegistry

* Specifics

** The [CODE(DOMi)@en[Document]] interface

*** The [CODE(DOMm)@en[createElementNS]] method and the [CODE(DOMm)@en[createAttributeNS]] method

[13] If the second parameter, [CODE(DOMp)@en[[[qualifiedName]]]],
is an array reference, i.e. the [CODE(perl)@en[[[ref]]]]
operator with that parameter returns a string
of [CODE(perl)@en[[[ARRAY]]]], then the parameter 
[['''MUST''']] be interpreted as following:
- The namespace prefix part of the qualified name
is the zeroth item in the array.  If it is 
[CODE(perl)@en[[[undef]]]], then there is
no namespace prefix (i.e. the qualified name has no
[CODE(char)@en[[[COLON]]]] character).
- The local name part of the qualified name
is the first item in the array.  It [['''MUST NOT''']]
be [CODE(perl)@en[[[undef]]]]; if it is, then
it [['''MUST''']] be treated as if an empty string
is specified.

Using an array reference, an illegal qualified name
can be specified.  If the qualified name is illegal,
then an appropriate exception might be thrown
as defined by DOM specifications.

* memo