[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:

Conformance

[48] Statements about conformance in this specification are only applied to implementations that support related feature. For example, MUST-level requirements for treatement of the EventHandler objects do not apply to implementations that do not support DOM Events module.

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 blessed in a Perl class, unless otherwise specified. The Perl class MUST implement the DOM interfaces implemented by the DOM object.

better wording, getFeature consideration

[114] The class implementing a DOM interface MAY inherit non-DOM classes.

[115] For example, the class implementing the DOMException interface might inherit a class that defines the exception mechanism the implementation is build on top of it. Another example is that any class implementing DOM interfaces might inherit from the "object" base class provided by the object-orient programming framework used by the implementation.

[117] The implementation MAY provide ways to determine whether an object implements a specific DOM interface or not. However, this is not required.

[66] Specifications often requires that two objects be same. They don't have to be same object in Perl sense, but they have to exhibit following characteristics:

[69] >>68 ensures that following code works as intended:
@different_parents = grep { not $found{$node->parent_node}++ } @node;

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 undef as the argument to the Perl method, which set the 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 optional if either null or boolean 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 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.

[98] If the return value of the operator is defined as void, the method implementing the operation MUST return an empty list.

[123] Since Perl objects can be overloaded such that stringification and similar operations can be defined by the application, it is important to ensure the conversion from the Perl value to the WebIDL value is performed in the right way.

[124] Following pairs of code fragments can make different side effects:

## Evaluation order is significant.
$v1 = ''.$_[1];
$v2 = ''.$_[2];

$v2 = ''.$_[2];
$v1 = ''.$_[1];


## Three serializations can be different.
$v1 = ''.$_[1];

$v1 = 0+$_[1];

$v1 = !!$_[1];


## Whether the overloaded operation has been invoked or not is observable.
$v1 = ''.$_[1];
$v2 = ''.$_[2];
return;

$v1 = ''.$_[1];
return if $v1; # or throw an exception
$v2 = ''.$_[2];
return;


## How many times overloaded operation has been invoked is observable.
$v1 = ''.$_[1];
$v1 = ''.$_[1];

$v1 = ''.$_[1];

Constants

[62] When a constant is defined by some interface, any platform object implementing the interface MUST have a method whose name is equal to the constant name. The method MUST return the constant value.

[65] Any class implementing the interface SHOULD have a method whose name is equal to the constant name. If there is such a method, it MUST return the constant value.

[63] If there is a module corresponding to the interface, it MAY have a constant subroutine whose name is equal to the constant name. If there is such a constant subroutine, it MUST return the constant value. It MAY be exported from the module.

[64] If an implementation supports all of these constant representations, the ELEMENT_NODE constant of the Node interface can be used like this:
# >>62
is $node->ELEMENT_NODE, 1;

# >>65
is +MyDOM::Node->ELEMENT_NODE, 1;

# >>63
use MyDOM::Node;
is ELEMENT_NODE, 1;
Since module or class name appears in invocations of >>65 and >>63, they are not portable among implementations by definition, which is why they are not a MUST-level requirement. Note that when a constant is exported as mentioned in >>63, whether it is exported by default or not is implementation dependent. Moreover, it can be exported as part of some tag (e.g. :node_type) if desired.

Legacy callers

[40] The legacycaller keyword MUST have no effect.

Exceptions and errors

[54] The following IDL fragment MUST be implemented when simple exception classes and/or SyntaxError is implemented:

[Constructor(optional DOMString message = "")]
interface Error {
  readonly attribute DOMString name;
  readonly attribute DOMString message;
  readonly attribute DOMString fileName;
  readonly attribute long lineNumber;
  stringifier;
};

[Constructor(optional DOMString message = "")]
interface EvalError : Error {};

[Constructor(optional DOMString message = "")]
interface RangeError : Error {};

[Constructor(optional DOMString message = "")]
interface ReferenceError : Error {};

[Constructor(optional DOMString message = "")]
interface SyntaxError : Error {};

[Constructor(optional DOMString message = "")]
interface TypeError : Error {};

[Constructor(optional DOMString message = "")]
interface URIError : Error {};

[183] The constructors of these interfaces MUST return a new object implementing the respective interface. The object's name MUST be set to the name of the interface. The object's message MUST be set to the message argument.

[182] An object which is a simple exception or DOMException MUST be an object implementing the Perl Error Object Interface Level 1 https://github.com/manakai/perl-web-dom/blob/master/lib/Web/DOM/Error.pod#error-object-api. Semantics of attributes name, message, fileName, and lineNumber and the stringifier are defined by that specification. The constructor is expected to set the fileName and lineNumber of the created object.

[9] To throw an exception exception, die MUST be invoked with exception.

[53] Implementations are encouraged to employ the Error module as a basis to construct their own exception mechanism.

[57] The fileName attribute MUST return the string identifying the file where the method or attribute that throws the exception is invoked. The lineNumber attribute MUST return the line number in the file, where the method or attribute that throws the exception is invoked. How to determine the these values are implementation dependent.

[58] The stringifier WebIDL method MUST return the message WebIDL followed by string at followed by the fileName followed by string line followed by stringified XXXref representation of lineNumber followed by . followed by the value equal to Perl expression "\n".

[116] The DOMError object's "" operation MUST return the implementation-specific value that describes the error.

Events

...

Method names

[15] The name of the method corresponding to an IDL attribute or method MUST be the value returned by the following steps:

  1. Let n be the name of the IDL attribute or method.
  2. If it is an IDL attribute and the IDL attribute reflects the content attribute with name attr:
    1. If n is equal to attr ASCII case-insensitively, return attr and abort these steps.
  3. Otherwise, if it is a camel-cased attribute http://dev.w3.org/csswg/cssom/#dom-cssstyledeclaration-camel-cased-attribute of the CSSStyleDeclaration interface:
    1. Let prop be the result of the IDL attribute to CSS property algorithm for the attribute.
    2. Replace any - character in prop by the _ character.
    3. Return prop and abort these steps.
  4. If the method_name_map JSON object in https://github.com/manakai/data-web-defs/blob/master/data/dom-perl.json contains a name name, return the corresponding value and abort these steps.
    1. If there is a row in the table >>14 whose first column is equal to n, return the value of the second column of the row and abort these steps.
  5. Otherwise, replace a sequence of one or more uppercase letters at the end of n, if any, by the lowercase variant of the sequence.
  6. Replace any sequence of two or more uppercase letters in n by a sequence of a LOW LINE character, the lowercase variant of the sequence except the last letter, a LOW LINE character, and the lowercase variant of the last letter of the sequence.
  7. Replace any uppercase letter by a LOW LINE character followed by the lowercase variant of the letter.
  8. Then, return n.

[139] For example, localName is mapped to local_name, setAttributeNS to set_attribute_ns, createLSInput to create_ls_input, and MozBoxSizing to _moz_box_sizing.

[140] If a random interface defines the itemId attribute, its Perl name is item_id. However, since the itemId attribute of the HTMLElement interface reflects the itemid content attribute, its Perl name is itemid.

[14] Exceptions.
DOMDOM Perl BindingNote
accessKeyaccesskeyHTMLInputElement, HTMLTextAreaElement, HTMLButtonElement, HTMLLabelElement, HTMLLegendElement, HTMLAnchorElement, HTMLAreaElement (DOM HTML)
aLinkalinkHTMLBodyElement (DOM HTML)
bgColorbgcolorHTMLDocument, HTMLBodyElement, HTMLTableElement, HTMLTableRowElement, HTMLTableCellElement (DOM HTML)
cellPaddingcellpaddingHTMLTableElement (DOM HTML)
cellSpacingcellspacingHTMLTableElement (DOM HTML)
codeBasecodebaseHTMLObjectElement, HTMLAppletElement (DOM HTML)
codeTypecodetypeHTMLObjectElement (DOM HTML)
colSpancolspanHTMLTableCellElement (DOM HTML)
createTFootcreate_tfootHTMLTableElement (DOM HTML)
createTHeadcreate_theadHTMLTableElement (DOM HTML)
dateTimedatetimeHTMLModElement (DOM HTML)
dateTimedatetimeHTMLTimeElement (DOM HTML)
deleteTFootdelete_tfootHTMLTableElement (DOM HTML)
deleteTHeaddelete_theadHTMLTableElement (DOM HTML)
findOffset16find_offset_16StringExtended (DOM Core informative)
findOffset32find_offset_32StringExtended (DOM Core informative)
frameBorderframeborderHTMLFrameElement, HTMLIFrameElement (DOM HTML)
getAbsoluteReference3986get_absolute_reference_3986URIReference (manakai's extension)
getAbsoluteReference3987get_absolute_reference_3987URIReference (manakai's extension)
getIRIReference3987get_iri_reference_3987URIReference (manakai's extension)
getURIReference3986get_uri_reference_3986URIReference (manakai's extension)
isAbsoluteIRI3987is_absolute_iri_3987URIReference (manakai's extension)
isAbsoluteURI3986is_absolute_uri_3986URIReference (manakai's extension)
isIRI3987is_iri_3987URIReference (manakai's extension)
isIRIReference3987is_iri_reference_3987URIReference (manakai's extension)
isMapismapHTMLImageElement (DOM HTML)
isRelativeIRIReference3987is_iri_reference_3987URIReference (manakai's extension)
isRelativeReference3986is_relative_reference_3986URIReference (manakai's extension)
isSameDocumentReference3986is_same_document_reference_3986URIReference (manakai's extension)
isURI3986is_uri_3986URIReference (manakai's extension)
isURIReference3986is_uri_reference_3986URIReference (manakai's extension)
itemValueitemvalueHTMLElement
longDesclongdescHTMLImageElement, HTMLFrameElement, HTMLIFrameElement (DOM HTML)
marginHeightmarginheightHTMLFrameElement, HTMLIFrameElement (DOM HTML)
marginWidthmarginwidthHTMLFrameElement, HTMLIFrameElement (DOM HTML)
maxLengthmaxlengthHTMLInputElement (DOM HTML)
noHrefnohrefHTMLAreaElement (DOM HTML)
noResizenoresizeHTMLFrameElement (DOM HTML)
noShadenoshadeHTMLHRElement (DOM HTML)
noWrapnowrapHTMLTableCellElement (DOM HTML)
readOnlyreadonlyHTMLInputElement, HTMLTextAreaElement(DOM HTML)
rowSpanrowspanHTMLTableCellElement (DOM HTML)
scrollbar3dLightShadowColorscrollbar_3dlight_colorCSSStyleDeclarationProperties (CSSOM)
scrollbarDarkShadowColorscrollbar_darkshadow_colorCSSStyleDeclarationProperties (CSSOM)
tabIndextabindexHTMLSelectElement, HTMLInputElement, HTMLTextAreaElement, HTMLButtonElement, HTMLAnchorElement, HTMLObjectElement, HTMLAreaElement (DOM HTML)
tBodiestbodiesHTMLTableElement (DOM HTML)
tFoottfootHTMLTableElement (DOM HTML)
tHeadtheadHTMLTableElement (DOM HTML)
timeStamptimestampEvent
URLurlHTMLDocument (DOM HTML)
useMapusemapHTMLInputElement , HTMLImageElement, HTMLObjectElement (DOM HTML)
utf16Offsetutf16_offsetDOMLocator (DOM Core)
utf32Offsetutf32_offsetDOMLocator (DOM Core)
vAlignvalignHTMLTableColElement , HTMLTableSectionElement, HTMLTableRowElement, HTMLTableCellElement (DOM HTML)
valueTypevaluetypeHTMLParamElement (DOM HTML)
vLinkvlinkHTMLBodyElement (DOM HTML)

Editor's note (informative): manakai//Issue//1//9

Data types

[10] In this section, number types includes: long, unsigned long, unsigned long long, short, and 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., 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., 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.

Execution of algorithms defined for JavaScript

[84] When an algorithm for JavaScript is executed for a Perl value, the word "ECMAScript value" in the algorithm is read as "Perl value" instead.

[85] Whenever the JavaScript ToNumber() operation is applied to $n, the following steps MUST be run instead:

  1. [179] Return the result of evaluate Perl expression 0 + $x in scalar context.

[180] This can invoke an author-defined code if $x overloads the 0+ operation.

boolean

[120] If a WebIDL boolean value true or false is converted into a Perl value, it MUST be converted to a Perl true or false value, respectively. If the value is returned in context where both boolean and null can be returned, the false value MUST be represented as non-undef value in Perl.

unsigned long

[83] A Perl value is converted to an IDL unsigned long value by running the algorithm for JavaScript http://dev.w3.org/2006/webapi/WebIDL/#es-unsigned-long.

unsigned short

[118] A Perl value is converted to an IDL unsigned short value by running the algorithm for JavaScript http://dev.w3.org/2006/webapi/WebIDL/#es-unsigned-short.

null

[23] The null value in DOM is bound to undef in Perl.

[24] If something is defined to return or set null, it MUST return or set undef unless otherwise specified.

[25] Where null is allowed to be specified, an implementation MUST behave as if a null is specified when a undef is specified.

[26] Where null is not allowed to be specified, how an implementation behaves when a undef depends on the expected data type. An implementation MAY cause zero or more uninitialized warnings reported by Perl or MAY report its own uninitialized warnings, when warnings are enabled by e.g. use warnings pragma.

TODO: Make relationship to JavaScript undefined and null clearer.

DOMString and USVString

[181] For the purpose of DOM Perl Binding, USVString MUST be treated as a synonym for DOMString.

[70] In WebIDL and DOM, strings are defined in terms of UTF-16 code units, while in Perl they are represented in UTF-8 based encoding in most environments.[75] This specification does not support any environment where Perl character strings are not represented in utf8 (e.g. EBCDIC environment).

[96] Since some methods are defined in terms of UTF-16 code units, if the index used by the method identifies a location between surrogate code points, a character is broken into two surrogate code points. If the string "a\x{10003}b" is split into two substrings with index two (2), the first substring is "a\x{D800}" and the second substring is "\x{DC03}b".

[71] When a string in WebIDL context is exposed to Perl, it MUST be represented as the value that can be interpreted as a sequence of characters. If no character in the sequence is greater than U+00FF, it MAY be represented as the value that can be interpreted as a sequence of bytes encoded in Latin-1.

[72] The Latin-1 encoding in this context is different from the Web iso-8859-1 encoding, which is equivalent to the windows-1252 encoding Encoding.

[73] When a value in Perl in interpreted in WebIDL context, it MUST be first stringified by concatenated with the empty string and then interpreted as the sequence of characters. If the result of the stringification is the sequence of the bytes, then it is interpreted as encoded in the Latin-1 encoding.

[74] A Perl string can contain non-Unicode characters (i.e. code points greater than U+10FFFF). Unless otherwise specified, such a character MUST be treated as if that were an unassigned Unicode character.

[91] Therefore, the code-point length of the string consist of a character greater than U+10FFFF is one (1).

[92] A Perl string can contain both surrogate code points and code points greater than U+FFFF. Since a Perl string is not encoded in UTF-16, combination of surrogate code points does not represent a character, but are barely interpreted as sequence of those code points as is.

[93] For example, a string "\x{10003}" is different from "\x{D800}\x{DC03}".

[94] When a string ending with a high surrogate code point is concatenated with a string starting by a low surrogate code point by a DOM operation, these two code points MUST be replaced by corresponding code point.

[95] For example, if "a\x{D800}" is followed by "\x{DC03}b", then the result is string "a\x{10003}b".

[97] Even when strings beginning with or ending by surrogate pair code points are concatenated, they are not automatically converted into a Unicode character. Therefore, even if same sequence of operations are performed, semantics of result strings could be different in the DOM Perl Binding and in the JavaScript-based Web browser environment. However, this does not mean requirements in Web platform specifications apply differently among these environments.

[121] The number of Unicode code points in the string "a\x{D800}\x{DC03}b" is three in both environments.

[33] Some methods are defined to accept a scalar reference specified as a value of a parameter. Such a method, when a scalar reference is specified as a parameter value, MUST dereference the parameter value as a scalar reference (i.e. by operator ${}) before it is in use, if the ref of the parameter value is SCALAR.

[89] If the [TreatNullAs=EmptyString] extended attribute is specified, when the value is undef it MUST be converted to the empty string before it is processed.

[90] The [TreatUndefinedAs] extended attribute is ignored by the DOM Perl Binding.

[155] Whether a string $P is an array index property name MUST be determined by the following steps:

  1. [174] Let $n be the result of 0+$P0+.
  2. [175] Let $s be the result of "".$n"".
  3. [176] If not $n eq $s, then return false.
  4. [177] Return true.

[178] These steps are referenced by the itemitem (DOM) method of the HTMLAllCollection interface.

StringExtended

[99] The operations of the StringExtended interface DOM3CORE MUST be implemented as functions, where the zeroth argument to the function is treated as the context object (i.e. the string) and the first argument to the function is treated as the argument to the operation. The int data type MUST be handled as WebIDL unsigned long data type. The StringIndexOutOfBoundsException exception MUST be treated as the "IndexSizeError" exception.

Enumeration types

[135] Enumeration types are represented as character strings in Perl.

[136] If an invalid value is specified to the method argument where the enumeration type is expected, a TypeError MUST be thrown.

[137] Much more stricter definition is necessary...

DOMTimeStamp

[4] DOMTimeStamp for a Calendar Date-Time

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

For example, 1970-01-01T00:00:00Z is mapped to a numeric value of 0.Leap seconds, days before 1970-01-01T00:00:00Z

Objects

XXX this wording is a bit unclear

[80] If WebIDL definition for the method parameter is typed with an interface but the value that is not an instance of the interface is specified as the argument, then a TypeError MUST be thrown and the processing of the method MUST be aborted. This type checking MUST be performed in the order of parameters.

[81] Likewise, if WebIDL definition for the attribute is typed with an interface but the value that is not an instance of the interface is specified as the new value of the attribute, then a TypeError MUST be thrown and the processing of the method MUST be aborted.

[82] An implementation MAY treat an object from another DOM implementation as implementing no DOM interface at all.

XXX but it might be treated as user object (rather than platform object).

DOMUserData

[100] The DOMUserData data type DOM3CORE corresponding to any scalar value in Perl.

Security

Features

DOMImplementationRegistry

[16] The variable $Message::DOM::DOMImplementationRegistry MUST contain a value via which methods provided by DOMImplementationRegistry object can be invoked.

For example,
$Message::DOM::DOMImplementationRegistry->get_dom_implementation

returns a DOM implementation.

The DOMImplementationRegistry object don't have to be an object in the Perl context; it might be a string representing the package name of the class implementing the DOMImplementationRegistry interface.

Operator overloading

[127] The implementation MUST NOT overload the following operators (using the overload pragma) in a way that contradicts with this specification and any applicable specifications:

"", 0+, bool, @{}, %{}, &{}, cmp, eq, ne, lt, le, gt, and ge.

[18] Unless otherwise specified, an object implementing some DOM interface SHOULD NOT overload these operators. If these operators are overloaded in implementation-specific ways, it MUST behave as if it were not overloaded to the extent applications don't have to distinguish whether it is overloaded or not.

[128] For example, an implementation can choose to let the "" operator of the Element object to return the internal address of the object followed by the class name of the implementation. An application can use this string to distinguish element objects each other, or element objects and non-DOM objects, as it does for non-DOM objects. However, the implementation cannot choose to let the operator to return the XML representation of the element.

[28] In any way, when an operator is overloaded, it MUST be consistent with other operators.

For example, if the eq operator is overloaded,
my $eq = $a eq $b;
my $ne = $a ne $b;
die unless ($eq and not $ne) or (not $eq and $ne);

... must not die.

More details -

Array-like and / or hash-like objects

[86] If an interface supports indexed properties http://dev.w3.org/2006/webapi/WebIDL/#dfn-support-indexed-properties, the object implementing the interface MUST behave as if that were a blessed array reference, at least to the extent allowed by defining the Perl overload pragma's @{} operator.

[87] If only the indexed property getter is defined for the interface, the object MUST behave as if that were a read-only array reference.

[88] Following code fragment illustrates how the NodeList object behave:

my $node_list = $node->child_nodes;
warn scalar @$node_list;      # Number of child nodes
warn $node_list->[1];         # Child node with index 1 (= second node in the children list)
warn $node_list->[-1];        # Last child node
$node_list->[2] = $new_node;  # Error because setter is not defined for NodeList

Please note that index -1 is converted by Perl to the index of the last element in the array before WebIDL processing (i.e. unsigned long conversion), it would return different item in the list from the corresponding normal method;

warn $node_list->[-1];        # last item in the list
warn $node_list->item (-1);   # (-1 % 2^32 == 4294967295)th item (undef in most cases)

better wording

[17] For following interfaces, dereferencing an object as array acts as if it is an array:

That is, $obj->[$n] MUST return the same value as $obj->item ($n) if $obj is an object implementing any of interfaces listed above and $n is a non-negative integer less than $obj->length.

If $n is negative, then length - $n. If length is zero, greater than $n, smaller than -length, non-number, then?[138] Need to define DOMTokenList bindingNameList[ArrayClass]

[50] The to_a method and the as_list of an array-like object MUST return a reference to a new array that contains the items in the array-like object, in order.

[51] The as_list method is provided for compatibility with Template::Iterator module. It should not be used for other purposes.

[52] The to_list method of an array-like object MUST return a Perl list that contains the items in the array-like object, in order.

[154] The CSSStyleDeclaration interface does not have these methods.

[113] If an interface supports named properties, they MUST be accessible by dereferencing the object by the %{} operator.

Need to define it much more strictly...[126] T[] (e.g. DOMString[]) - tied array; obj.domstringlist = ["str1", "str2"]

[133] keys and each do not have to preserve the order of items in the hash-like object. However, the order has to be stable such that each can be used for iteration.

Read-only array-like or hash-like objects

[29] If an array-like or hash-like object is read-only, STORE, STORESIZE, DELETE, and any other operations that implies these operations MUST throw an NO_MODIFICATION_ALLOWED_ERR DOMException.

[112] When an array or hash is read-only, any attempt to modify it or its values MAY throw an exception. Whether an exception is thrown or not, any attempt to modify them MUST be ignored.

[129] Whether that exception is a string or an object, what the stringified representation of the exception is, or whether the exception is actually thrown or not, is implementation dependent. This is a quality of implementation issue, as what is the behavior of the "native" Perl read-only array or hash is somewhat unclear or unstable.[134] NodeList, HTMLCollection, and NamedNodeMap can be used as read-pnly array-like object.

The DOMConfiguration interface

[105] The Perl parameter name of a parameter is the value returned by the following steps:

  1. Let name be the parameter name.
  2. If name starts with http://, return null and abort these steps.
  3. Replace any - character in name by a _ character.
  4. Return name.

[106] The supported property names of a DOMConfiguration object is the values returned by the following steps:

  1. Let values be the array of the string containing the values in the parameterNames attribute of the object.
  2. For each item value in the array, in order:
    1. Let perl value be the Perl parameter name of the parameter whose name is name.
    2. If perl value is null, delete value from values.
    3. Otherwise, replace value in values by perl value.
  3. Return values.

[107] To determine the value of a named property of a DOMConfiguration object, the following steps MUST be run:

  1. Let name be the property name.
  2. If name is one of the supported property names, return the value that would be returned if the getParameter method is invoked with the parameter name whose Perl parameter name is name.
  3. Otherwise, return undef.

[108] To set the value of an existing named property or set the value of a new named property of a DOMConfiguration object, the following steps MUST be run:

  1. Let name be the property name.
  2. If name is one of the supported property names, return the value that would be returned if the setParameter method is invoked with the parameter name whose Perl parameter name is name and the assigned value. For the purpose of this invocation only, the setParameter method MUST NOT treat the undef value as WebIDL null.

[110] The following code set "false" to the parameter:

$config = $document->dom_config;
$config->{manakai_strict_document_children} = undef;
ok not $config->{manakai_strict_document_children};

However, the following code unset the parameter:

$config->set_parameter ('manakai-strict-document-children', undef);
ok $config->{manakai_strict_document_children};

Since the default value of the parameter is "true", unsetting the parameter results in the "true" value set to the parameter.

[109] To delete an existing named property of a DOMConfiguration object, the following steps MUST be run:

  1. Let name be the property name.
  2. If name is one of the supported property names, return the value that would be returned if the setParameter method is invoked with the parameter name whose Perl parameter name is name and null.

[111] The IDL data type of the second argument to the setParameter method is DOMUserData, which can be any Perl scalar value, while parameters have their expected value type defined. Therefore "casting" of the value is performed within the setParameter method. It MUST be performed by applying the steps to convert the Perl value into WebIDL value of appropriate data type. If this fails, as defined in the DOM3 Core specification, a "TypeMismatchError" exception is thrown.

Constructor

[19] The new method is reserved.

Cloning method

[20] The clone method is reserved.

It is planned to make Node's clone method an alias of cloneNode method.

Stringify method

[21] Method names stringify, as_string, and to_string are reserved.

XXX What "reserved" means?

[60] If the WebIDL interface has the stringifier WebIDL defined, the "" operator of the class MUST be overloaded such that stringifying the object invoke the stringifier.

[61] Unless otherwise defined, the bool operator of the class MUST return a true value, whatever value is returned by the stringifier.

Function-like interfaces

Maybe support for non-coderef objects (arbitrary object with "handle_event" method, or &{} overloaded) will be dropped...

[22] Several interfaces are defined as function-like. Only Perl native CODE references, i.e. values whose ref is CODE, and objects for which the &{} operation is defined MUST be treated as if they implement the function-like interfaces and are referred to as objects implementing the function-like interfaces. Each function-like interface has a method, typically named as handleEvent. Invoking that method on the object implementing a function-like interface from another language binding invokes the object itself, by &{} operation. In the Perl binding itself, however, the method of the interface is not directly accessible on the object implementing the interface.

Unlike in ECMAScript language binding, arbitrary object with handle_event method (and no &{} operation defined) does not implement the function-like interfaces.

[43] Function-like interfaces are:

[44] When the method would be invoked, the &{} operation MUST be performed over the object with appropriate arguments. The return value of the &{} operation MUST be treated as if the return value of the method. If the &{} operation results in an exception is raised, it MUST be treated as if it is an exception raised by the method.

For example, 
$node->add_event_listener ('click', sub {
  my $ev = shift;
  print $ev->details, "\n";
  return 0;
});

would make the subroutine invoked when the node is clicked. The subroutine, implementing the EventHandler interface and treated as if it is the handleEvent method, would prints the number of clicks and then cancel the default action for the event.

[45] Though in some of function-like interfaces constants are defined, they are not accessible via the object implemeting that interface in the Perl binding. Other interface might provide such constants alternatively. For example, objects implementing the Node interface provides contants in UserDataHandler interface (see >>42).

Legacy caller

[144] If an interface defines the legacy caller, the &{} operation of the corresponding class MUST invoke the legacy caller and return its result.

Dictionaries

[153] dictionary is represented by a hash reference.

details...

Specifics

The Node interface

[27] Multiple calles of the getter of attributes or childNodes on a Node MUST return the same object respectively in terms of Perl eq operator.

For example, 
my $c1 = $node->child_nodes;
my $c2 = $node->child_nodes;
die unless $c1 eq $c2;

... must not die.

[34] The manakaiAppendText method of the Node interface accepts a scalar reference (>>33) as the first parameter.

[42] A package that implements the Node interface MUST implement the OperationType constant group of the UserDataHandler interface.

For example, $node->NODE_CLONED where $node is a Node object must return the value of 1.

The Document interface

Qualified name methods

[119] Methods createElementNS, createAttributeNS, setAttributeNS, createDocument:

[13]

  1. If the second parameter, qualifiedName, is an array reference, i.e. the ref operator with that parameter returns a string of 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 undef, then there is no namespace prefix (i.e. the qualified name has no COLON character).
    • The local name part of the qualified name is the first item in the array. It MUST NOT be undef; if it is, then it MUST be treated as if an empty string is specified.

Second (third) or more items, if any, are ignored.

[122] In addition to qualified name's syntax tests performed by these methods, following steps MUST be run:

  1. If the namespace prefix is not null and is not an XML NCName, throw a "NamespaceError" exception.
  2. If the local name is not an XML NCName, throw a "NamespaceError" exception.

The strictErrorChecking attribute also affects these checks.Unlike these methods, the qualifiedName parameter of the createDocumentType method of the DOMImplementation interface has no special interpretation for an array reference, since the method does not parse the parameter as a pair of namespace prefix and local name.

The createDocumentType method

[125] If the second or third argument to the createDocumentType method of the DOMImplementation interface is undef, it MUST be converted to the empty string.

Methods createTextNode, createComment, createCDATASection

[32] Methods createTextNode, createComment, and createCDATASection of the Document interface accept a scalar reference (>>33) as the first parameter.

The DOMStringList interface

==Should we allow any Perl array reference as arg?

The DOMStirngMap interface

[147] For the purpose of DOM Perl Binding, following definitions MUST be applied:

[148] The algorithm for getting the list of name-value pairs
  1. Let list be an empty list of name-value pairs.
  2. For each content attribute on the element whose first five characters are the string "data-" and whose remaining characters (if any) do not include U+005F LOW LINE character (_), add a name-value pair to list whose name is the attribute's name with the first five characters removed and whose value is the attribute's value.
  3. For each name list, replace each U+005F LOW LINE character (_) by a U+002D HYPHEN-MINUS character (-).
  4. Return list.
[149] The algorithm for setting names to certain values
  1. Let name be the name passed to the algorithm.
  2. Let value be the value passed to the algorithm.
  3. If name contains a U+002D HYPHEN-MINUS character (-), throw a SyntaxError exception and abort these steps.
  4. Replace each U+005F LOW LINE character (_) in name by a U+002D HYPHEN-MINUS character (-).
  5. Insert the string data- at the front of name.
  6. Set the value of the attribute with the name name, to the value value, replacing any previous value if the attribute already existed. If setAttribute() would have thrown an exception when setting an attribute with the name name, then this must throw the same exception.
[150] The algorithm for deleting names
  1. Let name be the name passed to the algorithm.
  2. Replace each U+005F LOW LINE character (_) in name by a U+002D HYPHEN-MINUS character (-).
  3. Insert the string data- at the front of name.
  4. Remove the attribute with the name name, if such an attribute exists. Do nothing otherwise.
[151] The subset of the data-* attributes accessible via the DOMStringMap object of the DOM Perl Binding is different from those in JavaScript binding or the set of valid data-* attribute names.

[152] The CLEAR operation of the hash reference returned by the %{} operation on the DOMStringMap object MUST remove all attributes in the null namespace whose name begins with data-.

The NodeList interface

[30] For any NodeList object, the == operator MUST be so overloaded that it returns whether two arguments are equal in the equality defined for the isEqualNode method of the Node interface.

However, if the other operand is not a NodeList object, then it MUST return a false value.

The NamedNodeMap interface

[31] For any NamedNodeMap object, the == operator MUST be so overloaded that it returns whether two arguments are equal in the equality defined for the isEqualNode method of the Node interface.

[130] The NamedNodeMap object MUST be treated as a read-only hash-like object, where keys are those accessible via the getNamedItem method.

[131] If there are multiple items with same name in the NamedNodeMap, the getNamedItem method returns the first one.[132] This definition is not so strict...

The XPathNSResolver Interface

[162] The XPathNSResolver interface is part of DOM XPath. The NSResolver interface is a variant of the XPathNSResolver interface defined in the earlier versions of Selectors API.

[46] The XPathNSResolver interface is unusual in that it can be existed both as a platform object and as a user object.

[47] The createNSResolver method MUST return a platform object implementing the XPathNSResolver interface.

[163] For the purpose of the XPathNSResolver interface used as a user object, its IDL definition MUST be interpreted as if it were a callback interface.

[164] In other word, a Perl code reference can be used as a XPathNSResolver object.

[165] For example, the return value of the createNSResolver method can be specified as an argument to the evaluate method:

$resolver = $document->create_ns_resolver ($node);
$result = $document->evaluate ($expr, $ctx, $resolver);

[166] A code reference returning the namespace URL can also be used as an argument:

$result = $document->evaluate ($expr, $ctx, sub {
  my ($self, $prefix) = @_;
  return $PrefixToURL->{$prefix};
});

document.all

[141] The item method and the &{} operation of the document.all object MUST run these steps:

  1. Convert the argument from Perl to IDL as a DOMString value and let index be the result.
  2. If index is a valid non-negative integer, invoke the operation item(unsigned long index) of the HTMLCollection interface with index, return its result, and abort these steps.
  3. Otherwise, invoke the operation item(DOMString name) of the HTMLAllCollection interface with index and return its result.

[142] Based on Chrome behavior.

[143] The HTMLAllCollection's bool operation MUST return the false value.

[145] The namedItem method MUST always return the same object if the same argument is specified.

[146] The tags method MUST always return the same object if the same argument (after converted to ASCII lowercase if it is an HTML document) is specified.

The DOMImplementation interface

[37] If the class for the DOMImplementation interface has the constructor method, i.e. the new method, it MUST follow these steps:

  1. Let document be the document returned by invoking the Document constructor DOM.
  2. Return the DOMImplementation object that is associated with document.

The HTMLPropertiesCollection interface and the PropertyNodeList interface

[167] An HTMLPropertiesCollection object MUST be represented as a read-only hash reference in Perl.

[170] Note that "read-only" hash is different from restricted hash of Perl in DOM Perl Binding.

[168] The keys of the hash MUST be the values that would be returned by the names attribute of the HTMLPropertiesCollection.

[169] In Perl, order of hash keys are undefined.

[171] The values of the hash MUST be the PropertyNodeList objects corresponding to the keys, respectively.

[172] A PropertyNodeList object MUST be represented as a read-only array reference in Perl.

[173] The items of the array MUST be the nodes in the PropertyNodeList, in same order.

The AbortSignal interface

[55] The following IDL fragment MUST be implemented:

partial interface AbortSignal {
  attributeIDL attribute ManakaiAbortCallback manakaiOnabort;
  attributeIDL attribute DOMException manakaiError;
};
callback ManakaiAbortCallback = void ();

[56] An AbortSignal object has an associated abort callback and error object, which are initially null. When an AbortSignal object is created, the following steps MUST be run:

  1. [59] Add the following steps to the context object:
    1. [196] Set the context object's error object to a new DOMException object whose name is AbortError.
    2. [76] Let cb be the context object's abort callback.
    3. [77] If cb is not null:
      1. [78] Run cb. If this throws an exception, report the exception.
      2. [79] Set the context object's abort callback to null.

[184] On getting, the manakaiOnabort attributeIDL attribute of the AbortSignal interface MUST run these steps:

  1. [185] Return the context object's abort callback.

[186] On setting, the attributeIDL attribute MUST run these steps:

  1. [187] If the context object's aborted flag is not set:
    1. [188] Set context object's abort callback to the new value.

[190] This attributeIDL attribute can be used by non-DOM applications to register the abort action.

[193] On getting, the manakaiError attributeIDL attribute MUST run these steps:

  1. [194] Return the context object's error object.

[195] On setting, the attributeIDL attribute MUST run these steps:

  1. [197] Set context object's error object to the new value.

Exposing unsupported features

[156] In general, when a feature is not supported at all, it SHOULD NOT be exposed to the application.

[157] If an implementation does not support the adoptNode method of the Document interface, the Document object ought not have the adopt_node method.

[158] When a feature might or might not be supported depending on the configuration of the implementation, the feature MAY be exposed even when it is not enabled.

[159] If a CSS implementation does support the 'float' property but the associated renderer does not support floating of the box, the cssFloat attribute of the CSSStyleDeclaration interface might be exposed as the css_float method. As the method is defined in terms of the getPropertyValue and setProperty methods, these methods' behavior on unsupported CSS properties apples. (That is, the method return the empty on getting, or do nothing on setting.)

[160] An event handler IDL attribute might be exposed even when the implementation is currently not connected to the device that would fire the event in question.

[161] There might be the geolocation attribute of the Navigator object even when no positioning device is known to available.

Garbage collection

[101] Since Perl's garbage collection is reference count, simply implementing various DOM attributes as references could cause objects that could not be freed at all. To work around this situation, implementations can adopt different strategies, including:

For the purpose of DOM conformance, limitations caused by those strategies are considered "platform-specific limitations" http://dom.spec.whatwg.org/#conformance.

References

[191] The terms interface, attributeIDL attribute, and IDL fragment is defined by the Web IDL specification.

[192] The term AbortSignal is defined by the DOM Standard.

[189] The term report an exception is defined by the HTML Standard.

Normative References

[DOMCore]
[DOMEvents]
[DOMLS]
[DOMTraversal]
[SelectorsAPI]
Selectors API, W3C Editor's Draft, 29 August 2007, http://dev.w3.org/cvsweb/~checkout~/2006/webapi/selectors-api/Overview.html?rev=1.28&content-type=text/html;%20charset=utf-8. The latest published version of Selectors API is available at http://www.w3.org/TR/selectors-api/. (Latest version of the specifcation whose maturity level is higher than Candidate Recommendation, if any, or latest Editor's Draft is referenced.)

Informative References

[SVGPB]
SVG's Perl binding

memo

[35]

Maybe we should define "==" for DOMImplementationList (and any other array like objects) (名無しさん)

[36]

DOMImplementationList.push (non-dom-impl)

[38]

%Message::DOM::DOMImplementationRegistry::SourceClass (名無しさん)

[39] >>38 $SourceClass

[41]

Node.isEqualNode == Node.==

[49]

In binding languages that support setting to a readonly attribute setting media to a string must set the value of mediaText on the MediaList object.

[CSSOM]