Skip to content

Commit

Permalink
Define a way to specify a default value for dictionaries (the literal
Browse files Browse the repository at this point in the history
"{}") and require it to be specified for the dictionary arguments that
are required to be optional.

Fixes #585
Fixes #602
  • Loading branch information
bzbarsky committed Jun 28, 2019
1 parent a029460 commit a740e17
Showing 1 changed file with 45 additions and 12 deletions.
57 changes: 45 additions & 12 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -2242,24 +2242,23 @@ corresponding argument omitted.
conversion of <emu-val>undefined</emu-val> to be used (i.e., <emu-val>false</emu-val>).
</p>

If the type of an argument is a [=dictionary type=] or a [=union type=] that has a dictionary as one
If the type of an argument is a [=dictionary type=] or a [=union type=] that has
a [=dictionary type=] as one
of its [=flattened member types=], and that dictionary type and its ancestors have no
[=required dictionary member|required members=], and the argument is either the final argument or is
followed only by [=optional arguments=], then the argument must be specified as optional. Such
arguments are always considered to have a [=optional argument/default value=] of an empty
dictionary, unless otherwise specified.
followed only by [=optional arguments=], then the argument must be specified as
optional and have a default value provided.

<div class="note">

This is to encourage API designs that do not require authors to pass an
empty dictionary value when they wish only to use the dictionary’s
default values.

Dictionary types cannot have a default value specified explicitly, so the
“unless otherwise specified” clause above can only be invoked for
a [=union type=] that has a
dictionary type as one of its [=flattened member types=].

Usually the default value provided will be <emu-t>{}</emu-t>, but in the
case of a [=union type=] that has a dictionary type as one of its
[=flattened member types=] a default value could be provided that
initializes some other member of the union.
</div>

When a boolean literal token (<emu-t>true</emu-t> or <emu-t>false</emu-t>),
Expand Down Expand Up @@ -2303,13 +2302,20 @@ is an [=enumeration=], then its
be one of the [=enumeration values|enumeration’s values=].

Optional argument default values can also be specified using the
two token value <code>[]</code>, which represents an empty sequence
two token value <emu-t>[]</emu-t>, which represents an empty sequence
value. The type of this value is the same as the type of the optional
argument it is being used as the default value of. That type
must be a [=sequence type=], a [=nullable type=] whose [=nullable types/inner type=] is a
[=sequence type=] or a [=union type=] or [=nullable type|nullable=] union type
that has a [=sequence type=] in its [=flattened member types=].

Optional argument default values can also be specified using the two token value
<emu-t>{}</emu-t>, which represents a default-initialized (as if from ES
<emu-t>null</emu-t> or an object with no properties) dictionary value. The type
of this value is the same as the type of the optional argument it is being used
as the default value of. That type must be a [=dictionary type=], or a [=union
type=] that has a [=dictionary type=] in its [=flattened member types=].

<div class="example">

The following [=IDL fragment=]
Expand Down Expand Up @@ -2337,6 +2343,31 @@ that has a [=sequence type=] in its [=flattened member types=].
</pre>
</div>

<div class="example">

The following [=IDL fragment=]
defines an [=interface=]
with an operation that takes a dictionary argument:

<!-- Should be `highlight="webidl"`, but that gives bikeshed conniptions
because it does not know about the syntax we are introducing -->
<pre>
dictionary LookupOptions {
boolean caseSensitive = true;
};

[Exposed=Window]
interface AddressBook {
boolean hasAddressForName(USVString name, optional LookupOptions options = {});
};
</pre>

If <code>hasAddressForName</code> is called with only one argument, the
second argument will be a default-initialized <code>LookupOptions</code>
dictionary, which will cause <code>caseSensitive</code> to be set to
<emu-t>true</emu-t>.
</div>

The following extended attributes are applicable to operations:
[{{Default}}],
[{{Exposed}}],
Expand All @@ -2349,6 +2380,7 @@ The following extended attributes are applicable to operations:
ConstValue
string
"[" "]"
"{" "}"
"null"
</pre>

Expand Down Expand Up @@ -4524,8 +4556,9 @@ an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token, a
<emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token,
one of the three special floating point literal values (<emu-t>Infinity</emu-t>,
<emu-t>-Infinity</emu-t> or <emu-t>NaN</emu-t>),
a <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token or
the two token sequence <emu-t>[]</emu-t> used as the
a <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token, the two
token sequence <emu-t>[]</emu-t>, or the two token sequence <emu-t>{}</emu-t> is
used as the
[=dictionary member/default value=],
it is interpreted in the same way as for an [=operation=]’s
[=optional argument/default value|optional argument default value=].
Expand Down

0 comments on commit a740e17

Please sign in to comment.