Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define a way to specify a default value for dictionaries (the literal "{}") and require it to be specified for the dictionary arguments that are required to be optional. #750

Merged
merged 1 commit into from
Jul 1, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 47 additions & 14 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -1616,8 +1616,8 @@ or one of the three special floating point constant values
(<emu-t>-Infinity</emu-t>, <emu-t>Infinity</emu-t> and <emu-t>NaN</emu-t>).

Note: These values – in addition to strings and the empty sequence – can also be used to specify the
[=dictionary member/default value|default value of a dictionary member=] or [=optional argument/default value|of an optional argument=]. Note that strings and the
empty sequence <code>[]</code> cannot be used as the value of a
[=dictionary member/default value|default value of a dictionary member=] or [=optional argument/default value|of an optional argument=]. Note that strings, the
empty sequence <emu-t>[]</emu-t>, and the default dictionary <emu-t>{}</emu-t> cannot be used as the value of a
[=constant=].

The value of the boolean literal tokens <emu-t>true</emu-t> and
Expand Down 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>).
bzbarsky marked this conversation as resolved.
Show resolved Hide resolved
</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 = false;
};

[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>false</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