Re: Dictionaries in WebIDL

Hi Ross,

sorry for the delay in replying.

On 7/10/11 11:45 PM, Ross Burton wrote:
> I'm trying to express in WebIDL an interface with a string attribute
> "uri", and a string-string dictionary "options" that has no
> restrictions on the keys.
>
> In JS this would be something like this as a literal:
>
> {
>   uri: "",
>   options: {}
> }
>
> Now I came up with the following WebIDL:
>
>   /* arbitrary key-value hints */
>   dictionary Options {};
>
>   [Constructor]
>   interface Item {
>     attribute DOMString uri;
>     attribute Options options;
>   };
>
> Which seems reasonable to me but the specification says "Dictionaries
> must not be used as the type of an attribute, constant or exception
> field".  Maybe I'm misreading the spec but doesn't this make my IDL
> invalid?  Is there a better way of expressing what I want?

Yes, dictionaries are passed by making a copy of them, so we disallow 
them (along with sequences) from being the type of attributes.  This is 
to avoid a pattern like

   for (var k in item.options) {
   }

where each iteration would return a new JS object representing the 
dictionary.

Also, dictionaries are not used for open ended sets of keys.  What you 
want instead is to define an interface that has a named property getter 
on it:

   interface Options {
     getter DOMString (DOMString);
   };

and if you want to allow users of this object to create new and set & 
delete existing values too:

   interface Options {
     getter DOMString (DOMString name);
     creator setter void (DOMString name, DOMString value);
     deleter void (DOMString name);
   };

If you want to give these names so that you can explicitly call them as 
functions, you can do that:

   interface Options {
     getter DOMString get(DOMString name);
     creator setter void set(DOMString name);
     deleter void remove(DOMString name);
   };

> Related: is there a good tutorial/annotated reference/set of examples
> for WebIDL?  The spec is quite... concise and isn't that great for
> learning from. :)

Not yet, I'm afraid.  Robin Berjon is putting together a "best 
practices" document for API design:

   http://scriptlib-cg.github.com/api-design-cookbook/

Received on Friday, 9 December 2011 02:36:40 UTC