WebIDL
Yehuda Katz:
- There are a number of ECMAScript-specific extensions here that have obscure names and non-obvious behavior. For instance, understanding "[Replaceable] readonly" is non-trivial. In fact, "[Replaceable] readonly" has somewhat confusing semantics, in that the attribute is not really readonly at all. The readonly definition is "An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute", while [Replaceable] means "If the [Replaceable] extended attribute appears on a read only attribute, it indicates that setting the corresponding property on the host object will result in that property being removed and a new one created that is unrelated to the attribute, and which has the value being assigned".
In fact, aren't these properties not readonly at all. Instead, doesn't this idiom mean that the property is linked to some invisible attribute that is also used by other methods? Isn't that a more useful thing to express?
In the ES binding, the properties for these [Replaceable] attributes are effectively writable, but assigning to them breaks their link to the original attribute. The assignment doesn’t perform any conversion from the ES value to the IDL type, either. In other language bindings you would want these properties to behave like normal readonly attributes, e.g. in Java by having only a setter method.
Note that, while it may not be clear from the text, section 3 of Web IDL only makes requirements of IDL fragments, not on language bindings for any interfaces. The talk about not allowing assignment to the attribute is a true description of both the ES and the Java bindings: the IDL attribute itself isn’t writable, but [Replaceable] indicates that the ES property that reflects that attribute is writable (and does something non-obvious).
I wonder if for [Replaceable] and other similar hacks for legacy DOM behaviour we should state that they SHOULD NOT be used.
- Can't we have more useful defaults here? For instance, why can't
readonly attribute WindowProxy parent; readonly attribute Element frameElement; WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace);
be identical to
readonly WindowProxy parent; readonly Element frameElement; WindowProxy open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace);
We could make the syntax for attributes less similar to OMG IDL’s by dropping the “attribute” keyword, but given that people are familiar with this syntax (pre-Web IDL) and that implementations use IDL files with this syntax as part of their builds, I’m not sure it’s worth it.
Although, we did drop the requirement for the “in” keyword:
The "in" keyword used in the declaration of each argument is optional. No other types of arguments (such as out or in-out arguments) can be specified with Web IDL. — dev.w3.org/2006/webapi/WebIDL/#idl-operations
Additionally, isn't this stream of characters somewhat confusing? What about:
readonly parent: returns WindowProxy; readonly frameElement: returns Element; open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace): returns WindowProxy;
Similarly, I don’t think moving the return type to the end buys us anything.
The specifics here aren't so important. My question is around whether some well-selected defaults (like "in" for arguments) might significantly reduce the amount of necessary verbiage.
I agree with the principle, but some of the basics of the IDL syntax are well established and recognised. (It probably argues against the use of “returns” in your example above, too.)
- In the case of events, there's a bit of fudging going on, isn't there? There is no default type,
I’m not sure what you mean by default type here.
and nothing forces the user to provide a Function.
Right, the author could assign anything. But the rules for how to handle arbitrary ES values are defined:
If a host object implements an interface, then for each attribute defined on the interface, there MUST be a corresponding property on the host object: ... * If the attribute is not declared readonly, then when setting the property to a particular ECMAScript value, the IDL value assigned to the attribute is the result of converting the ECMAScript value to an IDL value. — dev.w3.org/2006/webapi/WebIDL/#host-objects
When looking at WebIDL, attribute types are defined thusly:
The type of the attribute is given by the DeclarationType non-terminal. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the attribute is defined, to an interface, typedef or boxed valuetype that has been declared previously.
There's no clear description of what that actually means.
It’s a requirement on IDL fragments. It means that
interface A { attribute B x; };
interface B { };
is not conforming while
interface B { };
interface A { attribute B x; };
is. There have been discussions on removing this requirement, though.
Should implementors reject an attempt to assign a different type to the attribute? By what mechanism?
In the ES binding, you need to follow the rules for converting the ES value to an IDL value according to section 4.1 (that’s where the “converting” word is linked to, in the text I quoted above). Function is an interface type, so the rules in 4.1.15 should apply:
dev.w3.org/2006/webapi/WebIDL/#es-interface
That section should say something about handling [Callback]-annotated interfaces, but it doesn’t seem to. The intention is for the rules in 4.2.2 to apply:
dev.w3.org/2006/webapi/WebIDL/#Callback
What does the type even mean in dynamic languages?
Not sure what you mean here. “Function” is an interface defined in HTML5.
- There are some cases where WebIDL requires the use of a type that is effectively mapped to ECMAScript types. For instance, instead of requiring the use of "unsigned long", why not simply define "Number" and use that? This would make it easier for casual readers of the spec.
unsigned long doesn’t map exactly to Number. Assigning a Number to an unsigned long attribute does truncation, for example:
dev.w3.org/2006/webapi/WebIDL/#es-unsigned-long
The case could be made for “float”, which maps to Number (apart from floats being exactly IEEE 754 singles whereas Number treats all NaNs the same). The type name “float” comes from OMG IDL and is thus already familiar to people. I think it’s a better name for that IDL type (i.e., language binding neutral type) than Number.
- There are some things I can't make heads or tails of, like:
getter WindowProxy (in unsigned long index); getter WindowProxy (in DOMString name);
I think Boris explained those correctly.
- In a previous thread, the WebIDL spec was called "short". I printed out the spec to PDF to test that, and it ran 78 pages. That may well be considered "short" in the realm of standards bodies, but it's a rather heavy requirement for reading a spec like HTML5.
Hey, it’s well within the range of a short (≤ 32767 pages). :-)
Additionally, it's not a very simple spec to understand. Putting together things like "[Replaceable] readonly" requires some conceptual work, which makes understanding the HTML5 spec quite difficult.
I agree that’s unintuitive. Would a different name for the extended attribute here help?
Not quite an alternative proposal, but these are my thoughts.
And thanks for them!
Cameron
Boris Zbarsky:
This I'd like to second. I spent a day or so last week tracing through the overload resolution stuff and the general "what happens when someone tries to call a method" flow, and it's very difficult to follow: lots of jumping back and forth required, for example.
I agree that the overload resolution stuff is too convoluted and could do with some rewriting to be clearer.
I wonder how much is inherent to the complexity of the issue and how much is just the presentation...
Perhaps a bit of both.
On Sep 25, 2009, at 10:29 PM, Cameron McCormack wrote:
unsigned long doesn’t map exactly to Number. Assigning a Number to an unsigned long attribute does truncation, for example:
dev.w3.org/2006/webapi/WebIDL/#es-unsigned-long
The case could be made for “float”, which maps to Number (apart from floats being exactly IEEE 754 singles whereas Number treats all NaNs
the same). The type name “float” comes from OMG IDL and is thus already familiar to people. I think it’s a better name for that IDL type
(i.e., language binding neutral type) than Number.
JS numbers are IEEE doubles, not singles (modulo the
indistinguishability of different NaNs and other such details).
Additionally, it's not a very simple spec to understand. Putting together things like "[Replaceable] readonly" requires some
conceptual work, which makes understanding the HTML5 spec quite difficult.I agree that’s unintuitive. Would a different name for the extended attribute here help?
For what it's worth, this concept has been called "replaceable" for
some time in the oral tradition of browser implementors.
, Maciej
Maciej Stachowiak:
JS numbers are IEEE doubles, not singles (modulo the indistinguishability of different NaNs and other such details).
Right, my mistake.
Thanks for your responses. They are very useful. First of all, the length of this response (and the explanations themselves) speak to the difficulty casual spec readers have in understanding this syntax. More specific responses inline.
On Fri, Sep 25, 2009 at 10:29 PM, Cameron McCormack <cam at mcc.id.au> wrote:
Hi Yehuda.
Yehuda Katz:
- There are a number of ECMAScript-specific extensions here that have obscure names and non-obvious behavior. For instance, understanding "[Replaceable] readonly" is non-trivial. In fact, "[Replaceable] readonly" has somewhat confusing semantics, in that the attribute is not really readonly at all. The readonly definition is "An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute", while [Replaceable] means "If the [Replaceable] extended attribute appears on a read only attribute, it indicates that setting the corresponding property on the host object will result in that property being removed and a new one created that is unrelated to the attribute, and which has the value being assigned".
In fact, aren't these properties not readonly at all. Instead, doesn't this idiom mean that the property is linked to some invisible attribute that is also used by other methods? Isn't that a more useful thing to express?
In the ES binding, the properties for these [Replaceable] attributes are effectively writable, but assigning to them breaks their link to the original attribute. The assignment doesn’t perform any conversion from the ES value to the IDL type, either. In other language bindings you would want these properties to behave like normal readonly attributes, e.g. in Java by having only a setter method.
So this extension effectively converts a readonly attribute to a writable one? Talk about confusing. And this isn't true about the same attribute in non-ES contexts?!
Note that, while it may not be clear from the text, section 3 of Web IDL only makes requirements of IDL fragments, not on language bindings for any interfaces. The talk about not allowing assignment to the attribute is a true description of both the ES and the Java bindings: the IDL attribute itself isn’t writable, but [Replaceable] indicates that the ES property that reflects that attribute is writable (and does something non-obvious).
It wasn't clear from the text, but now that I understand it, it doesn't help much. "An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute. It is language binding specific whether assignment is simply disallowed by the language, ignored or an exception is thrown." It's unclear to me how this is not specifying a requirement on the language binding. This whole thing is extremely confusing.
I wonder if for [Replaceable] and other similar hacks for legacy DOM behaviour we should state that they SHOULD NOT be used.
If something is in WebIDL purely as a description for known legacy behavior, it would be helpful if the case(s) in question were called out in the spec, and use of the syntax was disallowed for other cases.
- Can't we have more useful defaults here? For instance, why can't
readonly attribute WindowProxy parent; readonly attribute Element frameElement; WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace);
be identical to
readonly WindowProxy parent; readonly Element frameElement; WindowProxy open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace);
We could make the syntax for attributes less similar to OMG IDL’s by dropping the “attribute” keyword, but given that people are familiar with this syntax (pre-Web IDL) and that implementations use IDL files with this syntax as part of their builds, I’m not sure it’s worth it.
I'll put it another way: what's the utility of this additional word. In my opinion, if a word appears in the HTML5 specification, it should be there for a reason. If it is not, it just adds additional confusion for readers of the spec.
Although, we did drop the requirement for the “in” keyword:
The "in" keyword used in the declaration of each argument is optional. No other types of arguments (such as out or in-out arguments) can be specified with Web IDL. — dev.w3.org/2006/webapi/WebIDL/#idl-operations
So there's precedent then!
Additionally, isn't this stream of characters somewhat confusing? What about:
readonly parent: returns WindowProxy; readonly frameElement: returns Element; open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace): returns WindowProxy;
Similarly, I don’t think moving the return type to the end buys us anything.
I think it buys clarity, but I'm not too concerned about it.
The specifics here aren't so important. My question is around whether some well-selected defaults (like "in" for arguments) might significantly reduce the amount of necessary verbiage.
I agree with the principle, but some of the basics of the IDL syntax are well established and recognised. (It probably argues against the use of “returns” in your example above, too.)
Well established and recognized by whom? I'd be more concerned with newcomers than implementors (who will have no trouble adjusting to small changes here).
- In the case of events, there's a bit of fudging going on, isn't there? There is no default type,
I’m not sure what you mean by default type here.
I mean that nothing is actually present in onabort by default.
and nothing forces the user to provide a Function.
Right, the author could assign anything. But the rules for how to handle arbitrary ES values are defined:
If a host object implements an interface, then for each attribute defined on the interface, there MUST be a corresponding property on the host object: ... * If the attribute is not declared readonly, then when setting the property to a particular ECMAScript value, the IDL value assigned to the attribute is the result of converting the ECMAScript value to an IDL value. — dev.w3.org/2006/webapi/WebIDL/#host-objects
Which imposes a requirement on ECMAScript that such conversions be defined and possible. This is not always (or even often) possible.
When looking at WebIDL, attribute types are defined thusly:
The type of the attribute is given by the DeclarationType non-terminal. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the attribute is defined, to an interface, typedef or boxed valuetype that has been declared previously.
There's no clear description of what that actually means.
It’s a requirement on IDL fragments. It means that
interface A { attribute B x; };
interface B { };
is not conforming while
interface B { };
interface A { attribute B x; };
is. There have been discussions on removing this requirement, though.
Understood. My confusion was answered by your response above, which is where the spec specified coercions. Where does the spec specify how Function should be coerced:
[Callback=FunctionOnly, NoInterfaceObject] interface Function { any call(in any... arguments); };
(at this point, a reasonable observer should be wondering how a reader of the spec should be expected to figure any of this out)
Should implementors reject an attempt to assign a different type to the attribute? By what mechanism?
In the ES binding, you need to follow the rules for converting the ES value to an IDL value according to section 4.1 (that’s where the “converting” word is linked to, in the text I quoted above). Function is an interface type, so the rules in 4.1.15 should apply:
dev.w3.org/2006/webapi/WebIDL/#es-interface
That section should say something about handling [Callback]-annotated interfaces, but it doesn’t seem to. The intention is for the rules in 4.2.2 to apply:
Aha! And I was supposed to figure this out? Even if that information was there, I would not have found it and put two and two together.
What does the type even mean in dynamic languages?
Not sure what you mean here. “Function” is an interface defined in HTML5.
[Callback=FunctionOnly, NoInterfaceObject] interface Function { any call(in any... arguments); };
Is this really something that you would expect a non-expert reader to understand? Or is that just not a goal at all?
- There are some cases where WebIDL requires the use of a type that is effectively mapped to ECMAScript types. For instance, instead of requiring the use of "unsigned long", why not simply define "Number" and use that? This would make it easier for casual readers of the spec.
unsigned long doesn’t map exactly to Number. Assigning a Number to an unsigned long attribute does truncation, for example:
Ugh. From the spec: "However, the bindings in these specifications for the language most commonly used on the web, ECMAScript, are consistently specified with low enough precision as to result in interoperability issues. In addition, each specification must describe the same basic information, such as DOM interfaces described in IDL corresponding to properties on the ECMAScript global object, or the unsigned long IDL type mapping to the Number type in ECMAScript."
So it doesn't "map" but does "describe the same basic information". I'm so confused :(
The case could be made for “float”, which maps to Number (apart from floats being exactly IEEE 754 singles whereas Number treats all NaNs the same). The type name “float” comes from OMG IDL and is thus already familiar to people. I think it’s a better name for that IDL type (i.e., language binding neutral type) than Number.
Again, I would ask which people it's familiar to. I think the people for whom that statement is true are also the people with the least need for special help understanding this stuff.
- There are some things I can't make heads or tails of, like:
getter WindowProxy (in unsigned long index); getter WindowProxy (in DOMString name);
I think Boris explained those correctly.
I'd be interested to know where in the spec these constructs are described. I can't piece together how it's even valid WebIDL :/
- In a previous thread, the WebIDL spec was called "short". I printed out the spec to PDF to test that, and it ran 78 pages. That may well be considered "short" in the realm of standards bodies, but it's a rather heavy requirement for reading a spec like HTML5.
Hey, it’s well within the range of a short (≤ 32767 pages). :-)
Touché!
Additionally, it's not a very simple spec to understand. Putting together things like "[Replaceable] readonly" requires some conceptual work, which makes understanding the HTML5 spec quite difficult.
I agree that’s unintuitive. Would a different name for the extended attribute here help?
The problem is that [Replaceable] readonly actually means "writeable but only in ECMAScript", which is not something I even understood before reading your reply. The right solution for that case would be, as you expressed, to be explicit in WebIDL about the fact that this extended property is a hack for known, specific legacy behavior.
Not quite an alternative proposal, but these are my thoughts.
And thanks for them!
Cameron
-- Cameron McCormack ≝ mcc.id.au
Thanks for your time. Don't let my tone make you feel like you're wasting your effort. I appreciate your attempts to explain things to (noob) me.
On Sep 25, 2009, at 11:05 PM, Yehuda Katz wrote:
In the ES binding, the properties for these [Replaceable]
attributes are effectively writable, but assigning to them breaks their link to the original attribute. The assignment doesn’t perform any conversion
from the ES value to the IDL type, either. In other language bindings you would want these properties to behave like normal readonly
attributes, e.g. in Java by having only a setter method.So this extension effectively converts a readonly attribute to a writable one? Talk about confusing. And this isn't true about the same attribute in non-ES contexts?!
Please hold your fire. [Replaceable] was added in the 90s when
Netscape 4 and IE4 tried to evolve the DOM by adding properties to the
global (window) object, and found the common names intended were
already in use. It's a mistake to try to add common names, but try we
did (both Netscape and Microsoft), with the hack of allowing the name
to be preempted by content. Only if not "replaced" would the Netscape
code actually reify the new property on demand. I'm not sure how IE
did it.
This is an ongoing issue. Adding JSON (from json2.js) to ES5 involved
some pain, due to other implementations of a JSON codec using the same
name but different method names in the top-level JSON object. But it
didn't require anything like [Replaceable] to sort out.
We're stuck with [Replaceable], although like any sunk cost it is not
cost-free and we could reengineer it. But what's the gain? Pointing
out the silly way it makes readonly properties low-integrity is not
helpful. Yes, you can "replace" (or preempt, I prefer) such properties
with your own vars or functions in content. That was the way it worked
in the 4th generation browsers. Why reengineer this minor piece of
WebIDL now?
On Fri, Sep 25, 2009 at 11:28 PM, Brendan Eich <brendan at mozilla.com> wrote:
On Sep 25, 2009, at 11:05 PM, Yehuda Katz wrote:
In the ES binding, the properties for these [Replaceable] attributes are effectively writable, but assigning to them breaks their link to the original attribute. The assignment doesn’t perform any conversion from the ES value to the IDL type, either. In other language bindings you would want these properties to behave like normal readonly attributes, e.g. in Java by having only a setter method.
So this extension effectively converts a readonly attribute to a writable one? Talk about confusing. And this isn't true about the same attribute in non-ES contexts?!
Please hold your fire. [Replaceable] was added in the 90s when Netscape 4 and IE4 tried to evolve the DOM by adding properties to the global (window) object, and found the common names intended were already in use. It's a mistake to try to add common names, but try we did (both Netscape and Microsoft), with the hack of allowing the name to be preempted by content. Only if not "replaced" would the Netscape code actually reify the new property on demand. I'm not sure how IE did it.
Understood. I don't have the benefit of the history here (unfortunately), just the specs as they stand today.
This is an ongoing issue. Adding JSON (from json2.js) to ES5 involved some pain, due to other implementations of a JSON codec using the same name but different method names in the top-level JSON object. But it didn't require anything like [Replaceable] to sort out.
We're stuck with [Replaceable], although like any sunk cost it is not cost-free and we could reengineer it. But what's the gain? Pointing out the silly way it makes readonly properties low-integrity is not helpful. Yes, you can "replace" (or preempt, I prefer) such properties with your own vars or functions in content. That was the way it worked in the 4th generation browsers. Why reengineer this minor piece of WebIDL now?
WebIDL, taken as a whole, make it very difficult for someone new to the spec(s) to understand what's going on. I started, like a reasonable person, by looking at the Window object. When looking at it, I encountered a number of somewhat confusing constructs, like this one. It is possible to have a long conversation where all of the details are hashed out, but the reality is that the specs cannot be easily understood without such a hashing.
I did not single out Replaceable in my efforts to understand.
I did not single out Replaceable in my efforts to understand.
Sure, but it is certainly odd and I wanted to recount some of the
history, just so you'd know not to over-attend to it. ;-)
WebIDL comes from OMG IDL, much of the precedent is documented in
various online sites, CORBA books, etc. It's not all that strange or
bad, just a bit "'90s big OOP system" in flavor.
To understand it all takes a while, and Maciej allowed as how some of
it could be cut without harm. Maybe we should start there.
On Fri, Sep 25, 2009 at 11:38 PM, Brendan Eich <brendan at mozilla.com> wrote:
I did not single out Replaceable in my efforts to understand.
Sure, but it is certainly odd and I wanted to recount some of the history, just so you'd know not to over-attend to it. ;-)
Ha. Maybe it would be worth putting a note in HTML5. "[Replaceable] is a quirk of history. Do not over-attend to it".
WebIDL comes from OMG IDL, much of the precedent is documented in various online sites, CORBA books, etc. It's not all that strange or bad, just a bit "'90s big OOP system" in flavor.
To understand it all takes a while, and Maciej allowed as how some of it could be cut without harm. Maybe we should start there.
Do we disagree that it is a worthy goal to have a specification that can be understood without having to take a while? I certainly understand the utility in using something with precedent like IDL (for implementors). Perhaps the IDL version could be part of an addendum, and something with less historical and conceptual baggage be used inline? Or is that too much work?
On Sep 25, 2009, at 11:43 PM, Yehuda Katz wrote:
Do we disagree that it is a worthy goal to have a specification that can be understood without having to take a while? I certainly understand the utility in using something with precedent like IDL (for implementors). Perhaps the IDL version could be part of an addendum, and something
What "something"?
with less historical and conceptual baggage be used inline? Or is that too much work?
Do the work, it's the only way to get to "something" and make it stick.
I don't think we should continue cross-posting like this to three
standards groups' lists. Yes, old and layered specs are often complex,
even over-complicated. No, we can't fix that complexity in the case of
WebIDL by rewriting the extant interface descriptions in ES. As Maciej
noted, doing so would cost ~10x the source lines, and beyond verbosity
would be incredibly unclear and error-prone.
Those who seek to replace WebIDL must first grok what it means, how it
is used. To do that, I suggest trimming cross-posts, and even before
replying, reading up on the relevant WebIDL docs and list. Once you've
braced yourself for this process, and gotten further into it, I am
sure that a Q&A process will work better.
You are absolutely correct that the specs are complex and have gaps.
Every engineer who has worked on a web-compatible browser has had to
learn this the hard way. I don't expect the Web to be "done" but I do
think better specs will close gaps and reduce some of the complexity
over time. That's the hope behind this overlong, cross-posted thread,
anyway. I'll shut up now.
On Sep 25, 2009, at 11:33 PM, Yehuda Katz wrote:
WebIDL, taken as a whole, make it very difficult for someone new to the spec(s) to understand what's going on. I started, like a reasonable person, by looking at the Window object. When looking at it, I encountered a number of somewhat confusing constructs, like this one. It is possible to have a long conversation where all of the details are hashed out, but the reality is that the specs cannot be easily understood without such a hashing.
Window probably has more bizarre legacy behavior than any other
interface. It's probably not the best starting point for understanding.
, Maciej
On Fri, 25 Sep 2009, Yehuda Katz wrote:
At the urging of some folks, I've poked around WebIDL and have a few observations. I'll use the Window object from HTML as a prop here (it is reproduced, in full, below)
If there are issues you would like fixed in HTML5 (as opposed to WebIDL), please file them as bugs. The easiest way to do that is to use the little text box at the bottom of the browser window when looking at:
www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#the
On Fri, 25 Sep 2009, Yehuda Katz wrote:
On Fri, Sep 25, 2009 at 11:38 PM, Brendan Eich <brendan at mozilla.com> wrote:
I did not single out Replaceable in my efforts to understand.
Sure, but it is certainly odd and I wanted to recount some of the history, just so you'd know not to over-attend to it. ;-)
Ha. Maybe it would be worth putting a note in HTML5. "[Replaceable] is a quirk of history. Do not over-attend to it".
If we start calling out all the quirks of history in HTML5, we'd probably end up doubling the size of the spec.
Yehuda Katz:
Ha. Maybe it would be worth putting a note in HTML5. "[Replaceable] is a quirk of history. Do not over-attend to it".
Ian Hickson:
If we start calling out all the quirks of history in HTML5, we'd probably end up doubling the size of the spec.
OTOH calling out features in Web IDL that exist solely for quirky compatibility reasons, that would help to discourage their use in other specs.
On Sep 26, 2009, at 3:30 PM, Cameron McCormack wrote:
Yehuda Katz:
Ha. Maybe it would be worth putting a note in HTML5.
"[Replaceable] is a quirk of history. Do not over-attend to it".Ian Hickson:
If we start calling out all the quirks of history in HTML5, we'd
probably end up doubling the size of the spec.OTOH calling out features in Web IDL that exist solely for quirky compatibility reasons, that would help to discourage their use in
other specs.
Calling these cases out in Web IDL (as opposed to HTML5) seems like a
good idea.
, Maciej
At the urging of some folks, I've poked around WebIDL and have a few observations. I'll use the Window object from HTML as a prop here (it is reproduced, in full, below):
In fact, aren't these properties not readonly at all. Instead, doesn't this idiom mean that the property is linked to some invisible attribute that is also used by other methods? Isn't that a more useful thing to express?
be identical to
Additionally, isn't this stream of characters somewhat confusing? What about:
The specifics here aren't so important. My question is around whether some well-selected defaults (like "in" for arguments) might significantly reduce the amount of necessary verbiage.
There's no clear description of what that actually means. Should implementors reject an attempt to assign a different type to the attribute? By what mechanism? What does the type even mean in dynamic languages?
There are some cases where WebIDL requires the use of a type that is effectively mapped to ECMAScript types. For instance, instead of requiring the use of "unsigned long", why not simply define "Number" and use that? This would make it easier for casual readers of the spec.
There are some things I can't make heads or tails of, like:
Not quite an alternative proposal, but these are my thoughts.
[OverrideBuiltins] interface Window { // the current browsing context readonly attribute WindowProxy window; readonly attribute WindowProxy self; attribute DOMString name; [PutForwards=href] readonly attribute Location location; readonly attribute History history; readonly attribute UndoManager undoManager; Selection getSelection(); [Replaceable] readonly attribute BarProp locationbar; [Replaceable] readonly attribute BarProp menubar; [Replaceable] readonly attribute BarProp personalbar; [Replaceable] readonly attribute BarProp scrollbars; [Replaceable] readonly attribute BarProp statusbar; [Replaceable] readonly attribute BarProp toolbar; void close(); void focus(); void blur();
// other browsing contexts [Replaceable] readonly attribute WindowProxy frames; [Replaceable] readonly attribute unsigned long length; readonly attribute WindowProxy top; [Replaceable] readonly attribute WindowProxy opener; readonly attribute WindowProxy parent; readonly attribute Element frameElement; WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace); getter WindowProxy (in unsigned long index); getter WindowProxy (in DOMString name);
// the user agent readonly attribute Navigator navigator; readonly attribute ApplicationCache applicationCache;
// user prompts void alert(in DOMString message); boolean confirm(in DOMString message); DOMString prompt(in DOMString message, in optional DOMString default); void print(); any showModalDialog(in DOMString url, in optional any argument);
// cross-document messaging void postMessage(in any message, in DOMString targetOrigin); void postMessage(in any message, in MessagePortArray ports, in DOMString targetOrigin);
// event handler IDL attributes attribute Function onabort; attribute Function onafterprint; attribute Function onbeforeprint; attribute Function onbeforeunload; attribute Function onblur; attribute Function oncanplay; attribute Function oncanplaythrough; attribute Function onchange; attribute Function onclick; attribute Function oncontextmenu; attribute Function ondblclick; attribute Function ondrag; attribute Function ondragend; attribute Function ondragenter; attribute Function ondragleave; attribute Function ondragover; attribute Function ondragstart; attribute Function ondrop; attribute Function ondurationchange; attribute Function onemptied; attribute Function onended; attribute Function onerror; attribute Function onfocus; attribute Function onformchange; attribute Function onforminput; attribute Function onhashchange; attribute Function oninput; attribute Function oninvalid; attribute Function onkeydown; attribute Function onkeypress; attribute Function onkeyup; attribute Function onload; attribute Function onloadeddata; attribute Function onloadedmetadata; attribute Function onloadstart; attribute Function onmessage; attribute Function onmousedown; attribute Function onmousemove; attribute Function onmouseout; attribute Function onmouseover; attribute Function onmouseup; attribute Function onmousewheel; attribute Function onoffline; attribute Function ononline; attribute Function onpause; attribute Function onplay; attribute Function onplaying; attribute Function onpopstate; attribute Function onprogress; attribute Function onratechange; attribute Function onreadystatechange; attribute Function onredo; attribute Function onresize; attribute Function onscroll; attribute Function onseeked; attribute Function onseeking; attribute Function onselect; attribute Function onshow; attribute Function onstalled; attribute Function onstorage; attribute Function onsubmit; attribute Function onsuspend; attribute Function ontimeupdate; attribute Function onundo; attribute Function onunload; attribute Function onvolumechange; attribute Function onwaiting; }; Window implements EventTarget;
-- Yehuda Katz Developer | Engine Yard (ph) 718.877.1325
At the urging of some folks, I've poked around WebIDL and have a few observations. I'll use the Window object from HTML as a prop here (it is reproduced, in full, below): 1. There are a number of ECMAScript-specific extensions here that have obscure names and non-obvious behavior. For instance, understanding "[Replaceable] readonly" is non-trivial. In fact, "[Replaceable] readonly" has somewhat confusing semantics, in that the attribute is not really readonly at all. The readonly definition is "An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute", while [Replaceable] means "If the [Replaceable] extended attribute appears on a read only attribute, it indicates that setting the corresponding property on the host object will result in that property being removed and a new one created that is unrelated to the attribute, and which has the value being assigned". In fact, aren't these properties not readonly at all. Instead, doesn't this idiom mean that the property is linked to some invisible attribute that is also used by other methods? Isn't that a more useful thing to express? 2. Can't we have more useful defaults here? For instance, why can't > readonly attribute WindowProxy parent; > readonly attribute Element frameElement; > WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace); be identical to > readonly WindowProxy parent; > readonly Element frameElement; > WindowProxy open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace); Additionally, isn't this stream of characters somewhat confusing? What about: > readonly parent: returns WindowProxy; > readonly frameElement: returns Element; > open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace): returns WindowProxy; The specifics here aren't so important. My question is around whether some well-selected defaults (like "in" for arguments) might significantly reduce the amount of necessary verbiage. 3. In the case of events, there's a bit of fudging going on, isn't there? There is no default type, and nothing forces the user to provide a Function. When looking at WebIDL, attribute types are defined thusly: > The type of the attribute is given by the DeclarationType non-terminal. If the DeclarationType is > a scoped name, then it must resolve, with respect to the enclosing module of the interface on > which the attribute is defined, to an interface, typedef or boxed valuetype that has been > declared previously. There's no clear description of what that actually *means*. Should implementors reject an attempt to assign a different type to the attribute? By what mechanism? What does the type even mean in dynamic languages? 4. There are some cases where WebIDL requires the use of a type that is effectively mapped to ECMAScript types. For instance, instead of requiring the use of "unsigned long", why not simply define "Number" and use that? This would make it easier for casual readers of the spec. 5. There are some things I can't make heads or tails of, like: > getter WindowProxy (in unsigned long index); > getter WindowProxy (in DOMString name); 6. In a previous thread, the WebIDL spec was called "short". I printed out the spec to PDF to test that, and it ran 78 pages. That may well be considered "short" in the realm of standards bodies, but it's a rather heavy requirement for reading a spec like HTML5. Additionally, it's not a very simple spec to understand. Putting together things like "[Replaceable] readonly" requires some conceptual work, which makes understanding the HTML5 spec quite difficult. --- Not quite an alternative proposal, but these are my thoughts. --- [OverrideBuiltins] interface Window { // the current browsing context readonly attribute WindowProxy window; readonly attribute WindowProxy self; attribute DOMString name; [PutForwards=href] readonly attribute Location location; readonly attribute History history; readonly attribute UndoManager undoManager; Selection getSelection(); [Replaceable] readonly attribute BarProp locationbar; [Replaceable] readonly attribute BarProp menubar; [Replaceable] readonly attribute BarProp personalbar; [Replaceable] readonly attribute BarProp scrollbars; [Replaceable] readonly attribute BarProp statusbar; [Replaceable] readonly attribute BarProp toolbar; void close(); void focus(); void blur(); // other browsing contexts [Replaceable] readonly attribute WindowProxy frames; [Replaceable] readonly attribute unsigned long length; readonly attribute WindowProxy top; [Replaceable] readonly attribute WindowProxy opener; readonly attribute WindowProxy parent; readonly attribute Element frameElement; WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace); getter WindowProxy (in unsigned long index); getter WindowProxy (in DOMString name); // the user agent readonly attribute Navigator navigator; readonly attribute ApplicationCache applicationCache; // user prompts void alert(in DOMString message); boolean confirm(in DOMString message); DOMString prompt(in DOMString message, in optional DOMString default); void print(); any showModalDialog(in DOMString url, in optional any argument); // cross-document messaging void postMessage(in any message, in DOMString targetOrigin); void postMessage(in any message, in MessagePortArray ports, in DOMString targetOrigin); // event handler IDL attributes attribute Function onabort; attribute Function onafterprint; attribute Function onbeforeprint; attribute Function onbeforeunload; attribute Function onblur; attribute Function oncanplay; attribute Function oncanplaythrough; attribute Function onchange; attribute Function onclick; attribute Function oncontextmenu; attribute Function ondblclick; attribute Function ondrag; attribute Function ondragend; attribute Function ondragenter; attribute Function ondragleave; attribute Function ondragover; attribute Function ondragstart; attribute Function ondrop; attribute Function ondurationchange; attribute Function onemptied; attribute Function onended; attribute Function onerror; attribute Function onfocus; attribute Function onformchange; attribute Function onforminput; attribute Function onhashchange; attribute Function oninput; attribute Function oninvalid; attribute Function onkeydown; attribute Function onkeypress; attribute Function onkeyup; attribute Function onload; attribute Function onloadeddata; attribute Function onloadedmetadata; attribute Function onloadstart; attribute Function onmessage; attribute Function onmousedown; attribute Function onmousemove; attribute Function onmouseout; attribute Function onmouseover; attribute Function onmouseup; attribute Function onmousewheel; attribute Function onoffline; attribute Function ononline; attribute Function onpause; attribute Function onplay; attribute Function onplaying; attribute Function onpopstate; attribute Function onprogress; attribute Function onratechange; attribute Function onreadystatechange; attribute Function onredo; attribute Function onresize; attribute Function onscroll; attribute Function onseeked; attribute Function onseeking; attribute Function onselect; attribute Function onshow; attribute Function onstalled; attribute Function onstorage; attribute Function onsubmit; attribute Function onsuspend; attribute Function ontimeupdate; attribute Function onundo; attribute Function onunload; attribute Function onvolumechange; attribute Function onwaiting; }; Window implements EventTarget; -- Yehuda Katz Developer | Engine Yard (ph) 718.877.1325