[whatwg] DOMStringMap named properties

[Cameron McCormack]

Continuing a conversation from IRC
(http://krijnhoetmer.nl/irc-logs/whatwg/20081217#l-187):

Cameron McCormack:
> <heycam> Hixie, i think it would be better if DOMStringMap still
>   had operations annotated with [NameGetter] etc., and then for me to
>   introduce something in Web IDL to indicate that the operations don't
>   correspond to functions, and then for you to use that functionality
> <heycam> Hixie, so something like http://paste.lisp.org/display/72289
> <heycam> it'd have the advantage of both making the description of the
>   named property accessors simpler (since you'd just do your usual
>   description of operations) and also makes the interfaces suitable
>   for languages that don't support object indexing
> <heycam> s/makes/making/
> …
> <heycam> Hixie,
>   http://dev.w3.org/2006/webapi/WebIDL/#NoIndexingOperations

Ian Hickson:
> <Hixie> heycam: i'm scared that that's like giving implementors a
>   loaded gun and telling them to point it at their foot and set the
>   safety and then pull the trigger -- implementors who aren't paying
>   attention will shoot themselves
> <Hixie> heycam: i.e. they'll think "what's NoIndexingOperations? oh
>   well let's ignore it for now" and we'll get the functions exposed

Is that a valid concern?  There are many requirements that Web IDL makes
that aren’t immediately obvious just by looking at an IDL fragment.
Such a concern could easily be mitigated with a small note.

> [19:38] <Hixie> heycam: i'd much rather have the idl look like the js
>   object and have [IndexSetter] etc take arguments to provide names
>   for the other languages

But would you add those names? :)  You’d need to specify the type of
the values, too, so that the implicit name getter operation can have a
return type (and to give the type of the name setter/creator operation’s
second argument).


This is how I would recommend the section read:

  The DOMStringMap interface represents a set of name-value pairs. When
  a DOMStringMap object is instantiated, it is associated with three
  algorithms: one for getting the list of name-value pairs, one for
  setting names to certain values, and one for deleting names.

    [NoIndexingOperations]
    interface DOMStringMap {
      [NameGetter] DOMString get(in DOMString name);
      [NameSetter, NameCreator] void put(in DOMString name,
                                         in DOMString value);
      [NameDeleter] void delete(in DOMString name);
    };

    <!-- green note -->
    Note that due to the use of the [NoIndexingOperations] extended
    attribute, the interface prototype object for DOMStringMap will not
    have properties named get, set and remove; the only way to access
    the strings stored in a DOMStringMap is by accessing them via
    properties directly on the object.

  The names of the supported named properties on a DOMStringMap object
  are the names of each pair returned by the algorithm for getting the
  list of name-value pairs.

  The get(name) method must run the following algorithm:

    1. Let /pairs/ be the list returned from the algorithm for getting
       the list of name-value pairs.
    2. Let /pair/ be the entry in /pairs/ whose name component is equal
       to /name/.
    3. Return the value component of /pair/.

  The set(name, value) method must run the algorithm for setting names
  to certain values, passing /name/ as the name and /value/ as the
  value.

  The delete(name) method must run the algorithm for deleting names,
  passing /name/ as the name.


If you definitely don’t want to use [NoIndexingOperations], then the
section should look like the following:

  The DOMStringMap interface represents a set of name-value pairs. When
  a DOMStringMap object is instantiated, it is associated with three
  algorithms: one for getting the list of name-value pairs, one for
  setting names to certain values, and one for deleting names.

    [NameGetter, NameSetter, NameCreator, NameDeleter]
    interface DOMStringMap {
    };

  The names of the supported named properties on a DOMStringMap object
  are the names of each pair returned by the algorithm for getting the
  list of name-value pairs.

  When a DOMStringMap object is indexed to retrieve a named property
  /name/, the following algorithm must be run:

    1. Let /pairs/ be the list returned from the algorithm for getting
       the list of name-value pairs.
    2. Let /pair/ be the entry in /pairs/ whose name component is equal
       to /name/.
    3. Return the value component of /pair/.

  When a DOMStringMap object is indexed to create or modify a named
  property /name/ with value /value/, the algorithm for setting names to
  certain values must be run, passing /name/ as the name and the
  result of converting /value/ to a DOMString as the value.

  When a DOMStringMap object is indexed to delete a named property named
  /name/, the algorithm for deleting names must be run, passing /name/
  as the name.


If you go without [NoIndexingOperations], then I suggest specifying
somehow that HTMLElement::dataset only exist in language bindings that
support object indexing, or only in ECMAScript.

-- 
Cameron McCormack ≝ http://mcc.id.au/