Skip to content

Commit

Permalink
Add the ability to construct a callback function
Browse files Browse the repository at this point in the history 
This helps move some of the heavy lifting into IDL, to avoid issues like whatwg/html#2381.
  • Loading branch information
@domenic
domenic authored Mar 27, 2017
1 parent ca44d67 commit 36b3646
Showing 1 changed file with 83 additions and 40 deletions.
123 changes: 83 additions & 40 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12171,14 +12171,36 @@ a [=callback interface=] that:
* has one or more [=regular operations=] that all have the same [=identifier=],
and no others.

A <dfn>Web IDL arguments list</dfn> is a [=list=] of values each of which is either an IDL value or
the special value “missing”, which represents a missing optional argument.

<div algorithm>
To <dfn lt="converting" for="Web IDL arguments list">convert a Web IDL arguments list to an
ECMAScript arguments list</dfn>, given a [=Web IDL arguments list=] |args|, perform the
following steps:

1. Let |esArgs| be an empty [=list=].
1. Let |i| be 0.
1. Let |count| be 0.
1. While |i| &lt; |args|'s [=list/size=]:
1. If |args|[|i|] is the special value “missing”, then [=list/append=]
<emu-val>undefined</emu-val> to |esArgs|.
1. Otherwise, |args|[|i|] is an IDL value:
1. Let |convertResult| be the result of [=converted to an ECMAScript value|converting=]
|args|[|i|] to an ECMAScript value. Rethrow any exceptions.
1. [=list/Append=] |convertResult| to |esArgs|.
1. Set |count| to |i| + 1.
1. Set |i| to |i| + 1.
1. Truncate |esArgs| to contain |count| items.
1. Return |esArgs|.
</div>

<div algorithm="to call a user object's operation">

To <dfn id="call-a-user-objects-operation" export>call a user object's operation</dfn>,
given a [=Interface types|callback interface type=] value |value|,
sometimes-optional operation name |opName|,
list of argument values |arg|<sub>0..|n|−1</sub> each of which is either
an IDL value or the special value “missing” (representing a missing optional argument),
and optional <dfn id="dfn-callback-this-value" export>callback this value</dfn> |thisArg|,
sometimes-optional operation name |opName|, [=Web IDL arguments list=] |args|, and optional
<dfn id="dfn-callback-this-value" export>callback this value</dfn> |thisArg|,
perform the following steps.
These steps will either return an IDL value or throw an exception.

Expand Down Expand Up @@ -12206,21 +12228,10 @@ a [=callback interface=] that:
1. If |value|'s interface is not a [=single operation callback interface=],
or if [=!=] [=IsCallable=](|O|) is <emu-val>false</emu-val>,
set |thisArg| to |O| (overriding the provided value).
1. Let |esArgs| be an empty List of ECMAScript values.
1. Let |i| be 0.
1. Let |count| be 0.
1. While |i| &lt; |n|:
1. If |arg|<sub>|i|</sub> is the special value “missing”, then
append <emu-val>undefined</emu-val> to |esArgs|.
1. Otherwise, |arg|<sub>|i|</sub> is an IDL value:
1. Let |convertResult| be the result of [=converted to an ECMAScript value|converting=]
|arg|<sub>|i|</sub> to an ECMAScript value.
1. If |convertResult| is an abrupt completion, set |completion|
to |convertResult| and jump to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
1. Append |convertResult|.\[[Value]] to |esArgs|.
1. Set |count| to |i| + 1.
1. Set |i| to |i| + 1.
1. Truncate |esArgs| to have length |count|.
1. Let |esArgs| be the result of [=Web IDL arguments list/converting=] |args| to an ECMAScript
arguments list. If this throws an exception, set |completion| to the completion value
representing the thrown exception and jump to the step labeled
<a href="#call-user-object-operation-return"><i>return</i></a>.
1. Let |callResult| be [=Call=](|X|, |thisArg|, |esArgs|).
1. If |callResult| is an abrupt completion, set |completion| to
|callResult| and jump to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
Expand Down Expand Up @@ -12320,10 +12331,8 @@ described in the previous section).
<div algorithm>

To <dfn id="invoke-a-callback-function" export>invoke</dfn> a
[=callback function type=] value |callable| with
a list of arguments |arg|<sub>0..|n|−1</sub>, each of which is either
an IDL value or the special value “missing” (representing a missing optional argument),
and with optional [=callback this value|callback this value=] |thisArg|,
[=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|
and an optional [=callback this value|callback this value=] |thisArg|,
perform the following steps.
These steps will either return an IDL value or throw an exception.

Expand All @@ -12343,21 +12352,10 @@ described in the previous section).
1. Let |stored settings| be |callable|'s [=callback context=].
1. [=Prepare to run script=] with |relevant settings|.
1. [=Prepare to run a callback=] with |stored settings|.
1. Let |esArgs| be an empty List of ECMAScript values.
1. Let |i| be 0.
1. Let |count| be 0.
1. While |i| &lt; |n|:
1. If |arg|<sub>|i|</sub> is the special value “missing”, then
append <emu-val>undefined</emu-val> to |esArgs|.
1. Otherwise, |arg|<sub>|i|</sub> is an IDL value:
1. Let |convertResult| be the result of [=converted to an ECMAScript value|converting=]
|arg|<sub>|i|</sub> to an ECMAScript value.
1. If |convertResult| is an abrupt completion, set |completion|
to |convertResult| and jump to the step labeled <a href="#invoke-return"><i>return</i></a>.
1. Append |convertResult|.\[[Value]] to |esArgs|.
1. Set |count| to |i| + 1.
1. Set |i| to |i| + 1.
1. Truncate |esArgs| to have length |count|.
1. Let |esArgs| be the result of [=Web IDL arguments list/converting=] |args| to an ECMAScript
arguments list. If this throws an exception, set |completion| to the completion value
representing the thrown exception and jump to the step labeled
<a href="#invoke-return"><i>return</i></a>.
1. Let |callResult| be [=Call=](|F|, |thisArg|, |esArgs|).
1. If |callResult| is an abrupt completion, set |completion| to
|callResult| and jump to the step labeled <a href="#invoke-return"><i>return</i></a>.
Expand All @@ -12379,6 +12377,42 @@ described in the previous section).
|rejectedPromise| to the callback function's return type.
</div>

Some callback functions are instead used as constructors. Such callback functions must not have
a return type that is a [=promise type=].

<div algorithm>

To <dfn id="construct-a-callback-function" export>construct</dfn> a
[=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|,
perform the following steps.
These steps will either return an IDL value or throw an exception.

1. Let |completion| be an uninitialized variable.
1. Let |F| be the ECMAScript object corresponding to |callable|.
1. If [=!=] [=IsConstructor=](|F|) is <emu-val>false</emu-val>, throw a
<emu-val>TypeError</emu-val> exception.
1. Let |realm| be |F|'s [=associated Realm=].
1. Let |relevant settings| be |realm|'s [=Realm/settings object=].
1. Let |stored settings| be |callable|'s [=callback context=].
1. [=Prepare to run script=] with |relevant settings|.
1. [=Prepare to run a callback=] with |stored settings|.
1. Let |esArgs| be the result of [=Web IDL arguments list/converting=] |args| to an ECMAScript
arguments list. If this throws an exception, set |completion| to the completion value
representing the thrown exception and jump to the step labeled
<a href="#construct-return"><i>return</i></a>.
1. Let |callResult| be [=Construct=](|F|, |esArgs|).
1. If |callResult| is an abrupt completion, set |completion| to
|callResult| and jump to the step labeled <a href="#construct-return"><i>return</i></a>.
1. Set |completion| to the result of [=converted to an IDL value|converting=]
|callResult|.\[[Value]] to an IDL value of the same type as the operation’s
return type.
1. <i id="construct-return">Return:</i> at this
point |completion| will be set to an ECMAScript completion value.
1. [=Clean up after running a callback=] with |stored settings|.
1. [=Clean up after running script=] with |relevant settings|.
1. Return |completion|.
</div>


<h3 id="es-namespaces">Namespaces</h3>

Expand Down Expand Up @@ -12972,8 +13006,6 @@ The following typographic conventions are used in this document:
* Unicode characters: <span class="char">U+0030 DIGIT ZERO ("0")</span>
* Extended attributes: [<code class="idl">ExampleExtendedAttribute</code>]
* Variable names in prose and algorithms: <var ignore>exampleVariableName</var>.
* Algorithms use the [=conventions of the ECMAScript specification=],
including the ! and ? notation for unwrapping completion records.
* IDL informal syntax examples:
<pre highlight="webidl" class="syntax">
interface identifier {
Expand Down Expand Up @@ -13013,6 +13045,17 @@ The following typographic conventions are used in this document:
window.onload = function() { window.alert("loaded"); };
</pre>

The following conventions are used in the algorithms in this document:

* Algorithms use the [=conventions of the ECMAScript specification=],
including the ! and ? notation for unwrapping completion records.
* Algorithms sometimes treat returning/throwing values and returning completion records
interchangeably. That is, an algorithm that uses return/throw terminology may be treated as
returning a completion record, while one that returns a completion record may be treated as
returning a value or throwing an exception.
* Completion records are extended by allowing them to contain values that are not ECMAScript
values, such as Web IDL values.


<h2 id="conformance" class="no-num" oldids="conformant-algorithms">Conformance</h2>

Expand Down

0 comments on commit 36b3646

Please sign in to comment.