Skip to content

Commit 76cbc96

Browse files
saschanazsaschanaz
authored
Drop stringifier operation longhand
Per webref, nothing is using it. Closes #816.
1 parent 769f896 commit 76cbc96

File tree

1 file changed

+132
-171
lines changed

1 file changed

+132
-171
lines changed

‎index.bs

Lines changed: 132 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -1226,7 +1226,7 @@ These [=constants=], [=regular operations=], [=regular attributes=], and [=strin
12261226
describe the behaviors that can be implemented by an object,
12271227
as if they were specified on the [=interface=] that [=includes=] them.
12281228

1229-
[=Static attributes=], [=static operations=], [=special operations=] except for [=stringifiers=], and
1229+
[=Static attributes=], [=static operations=], [=special operations=], and
12301230
[=iterable declaration|iterable=], [=asynchronously iterable declaration|asynchronously iterable=],
12311231
[=maplike declaration|maplike=], and [=setlike declarations=] cannot appear in [=interface mixin=]
12321232
declarations.
@@ -1568,11 +1568,18 @@ and summarized in the following informative table:
15681568
<td>●</td>
15691569
<td>●</td>
15701570
</tr>
1571+
<tr>
1572+
<th>[=Stringifiers=]</th>
1573+
<td>●</td>
1574+
<td></td>
1575+
<td>●</td>
1576+
<td></td>
1577+
</tr>
15711578
<tr>
15721579
<th>[=Special Operations=]</th>
15731580
<td>●</td>
15741581
<td></td>
1575-
<td>Only [=stringifiers=]</td>
1582+
<td></td>
15761583
<td></td>
15771584
</tr>
15781585
<tr>
@@ -2054,7 +2061,7 @@ are applicable only to regular attributes:
20542061
An <dfn id="dfn-operation" export>operation</dfn> is an [=interface member=], [=callback interface
20552062
member=] or [=namespace member=]
20562063
(matching <emu-t>static</emu-t> <emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt>,
2057-
<emu-t>stringifier</emu-t> <emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt>,
2064+
<emu-t>stringifier</emu-t>,
20582065
<emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt> or
20592066
<emu-nt><a href="#prod-SpecialOperation">SpecialOperation</a></emu-nt>)
20602067
that defines a behavior that can be invoked on objects implementing the interface.
@@ -2708,6 +2715,122 @@ See [[#interface-object]] for details on how a [=constructor operation=] is to b
27082715
<div data-fill-with="grammar-ArgumentNameKeyword"></div>
27092716

27102717

2718+
<h4 id="idl-stringifiers">Stringifiers</h4>
2719+
2720+
When an [=interface=] has a <dfn id="dfn-stringifier">stringifier</dfn>, it indicates that objects
2721+
that implement the interface have a non-default conversion to a string. Stringifiers can be
2722+
specified using a <emu-t>stringifier</emu-t> keyword, which creates a stringifier operation when
2723+
used alone.
2724+
2725+
<pre highlight="webidl" class="syntax">
2726+
interface interface_identifier {
2727+
stringifier;
2728+
};
2729+
</pre>
2730+
2731+
Prose accompanying the interface must define
2732+
the <dfn id="dfn-stringification-behavior" export>stringification behavior</dfn>
2733+
of the interface.
2734+
2735+
The <emu-t>stringifier</emu-t> keyword
2736+
can also be placed on an [=attribute=].
2737+
In this case, the string to convert the object to is the
2738+
value of the attribute. The <emu-t>stringifier</emu-t> keyword
2739+
must not be placed on an attribute unless
2740+
it is declared to be of type {{DOMString}} or {{USVString}}.
2741+
It also must not be placed on
2742+
a [=static attribute=].
2743+
2744+
<pre highlight="webidl" class="syntax">
2745+
interface interface_identifier {
2746+
stringifier attribute DOMString identifier;
2747+
};
2748+
</pre>
2749+
2750+
On a given [=interface=], there must exist at most one stringifier.
2751+
2752+
<pre class="grammar" id="prod-Stringifier">
2753+
Stringifier :
2754+
"stringifier" StringifierRest
2755+
</pre>
2756+
2757+
<pre class="grammar" id="prod-StringifierRest">
2758+
StringifierRest :
2759+
OptionalReadOnly AttributeRest
2760+
";"
2761+
</pre>
2762+
2763+
<div class="example">
2764+
2765+
The following [=IDL fragment=]
2766+
defines an interface that will stringify to the value of its
2767+
<code class="idl">name</code> attribute:
2768+
2769+
<pre highlight="webidl">
2770+
[Exposed=Window]
2771+
interface Student {
2772+
constructor();
2773+
attribute unsigned long id;
2774+
stringifier attribute DOMString name;
2775+
};
2776+
</pre>
2777+
2778+
In the ECMAScript binding, using a <code class="idl">Student</code>
2779+
object in a context where a string is expected will result in the
2780+
value of the object’s <code class="idl">name</code> property being
2781+
used:
2782+
2783+
<pre highlight="js">
2784+
var s = new Student();
2785+
s.id = 12345678;
2786+
s.name = '周杰倫';
2787+
2788+
var greeting = 'Hello, ' + s + '!'; // Now greeting == 'Hello, 周杰倫!'.
2789+
</pre>
2790+
2791+
The following [=IDL fragment=]
2792+
defines an interface that has custom stringification behavior that is
2793+
not specified in the IDL itself.
2794+
2795+
<pre highlight="webidl">
2796+
[Exposed=Window]
2797+
interface Student {
2798+
constructor();
2799+
attribute unsigned long id;
2800+
attribute DOMString? familyName;
2801+
attribute DOMString givenName;
2802+
2803+
stringifier;
2804+
};
2805+
</pre>
2806+
2807+
Thus, prose is required to explain the stringification behavior.
2808+
We assume that the <code class="idl">familyName</code> and
2809+
<code class="idl">givenName</code> attributes are backed by
2810+
family name and given name concepts, respectively.
2811+
2812+
<blockquote>
2813+
2814+
The [=stringification behavior=] steps are:
2815+
2816+
1. If [=this=]'s family name is null, then return [=this=]'s given name.
2817+
2. Return the concatenation of [=this=]'s given name, followed by U+0020 SPACE, followed by [=this=]'s family name.
2818+
2819+
</blockquote>
2820+
2821+
An ECMAScript implementation of the IDL would behave as follows:
2822+
2823+
<pre highlight="js">
2824+
var s = new Student();
2825+
s.id = 12345679;
2826+
s.familyName = 'Smithee';
2827+
s.givenName = 'Alan';
2828+
2829+
var greeting = 'Hi ' + s; // Now greeting == 'Hi Alan Smithee'.
2830+
</pre>
2831+
</div>
2832+
2833+
27112834
<h4 id="idl-special-operations">Special operations</h4>
27122835

27132836
A <dfn id="dfn-special-operation" export>special operation</dfn> is a
@@ -2717,7 +2840,7 @@ Special operations are declared by using a
27172840
<dfn id="dfn-special-keyword" export>special keyword</dfn>
27182841
in an operation declaration.
27192842

2720-
There are four kinds of special operations. The table below indicates
2843+
There are three kinds of special operations. The table below indicates
27212844
for a given kind of special operation what special keyword
27222845
is used to declare it and what the purpose of the special operation is:
27232846

@@ -2743,11 +2866,6 @@ is used to declare it and what the purpose of the special operation is:
27432866
<td><emu-t>deleter</emu-t></td>
27442867
<td>Defines behavior for when an object is indexed for property deletion.</td>
27452868
</tr>
2746-
<tr>
2747-
<td><dfn id="dfn-stringifier" export lt="stringifier">Stringifiers</dfn></td>
2748-
<td><emu-t>stringifier</emu-t></td>
2749-
<td>Defines how an object is converted into a {{DOMString}}.</td>
2750-
</tr>
27512869
</table>
27522870

27532871
Not all language bindings support all of the four kinds of special
@@ -2828,7 +2946,6 @@ for details.
28282946

28292947
On a given [=interface=],
28302948
there must exist at most one
2831-
stringifier, at most one
28322949
[=named property deleter=],
28332950
and at most one of each variety of getter and setter.
28342951

@@ -2847,159 +2964,6 @@ that defines a given special operation, then it is undefined which (if any)
28472964
special operation is invoked for that operation.
28482965

28492966

2850-
<h5 id="idl-stringifiers">Stringifiers</h5>
2851-
2852-
When an [=interface=] has a
2853-
[=stringifier=], it indicates that objects that implement
2854-
the interface have a non-default conversion to a string. As mentioned above,
2855-
stringifiers can be specified using an [=operation=]
2856-
declared with the <emu-t>stringifier</emu-t> keyword.
2857-
2858-
<pre highlight="webidl" class="syntax">
2859-
interface interface_identifier {
2860-
stringifier DOMString identifier();
2861-
stringifier DOMString ();
2862-
};
2863-
</pre>
2864-
2865-
If an operation used to declare a stringifier does not have an
2866-
[=identifier=], then prose
2867-
accompanying the interface must define
2868-
the <dfn id="dfn-stringification-behavior" export>stringification behavior</dfn>
2869-
of the interface. If the operation does have an identifier,
2870-
then the object is converted to a string by invoking the
2871-
operation to obtain the string.
2872-
2873-
Stringifiers declared with operations must
2874-
be declared to take zero arguments and return a {{DOMString}}.
2875-
2876-
As a shorthand, if the <emu-t>stringifier</emu-t> keyword
2877-
is declared using an operation with no identifier, then the
2878-
operation’s [=return type=] and
2879-
argument list can be omitted.
2880-
2881-
<pre highlight="webidl" class="syntax">
2882-
interface interface_identifier {
2883-
stringifier;
2884-
};
2885-
</pre>
2886-
2887-
<div class="example">
2888-
2889-
The following two interfaces are equivalent:
2890-
2891-
<pre highlight="webidl">
2892-
[Exposed=Window]
2893-
interface A {
2894-
stringifier DOMString ();
2895-
};
2896-
</pre>
2897-
<pre highlight="webidl">
2898-
[Exposed=Window]
2899-
interface A {
2900-
stringifier;
2901-
};
2902-
</pre>
2903-
</div>
2904-
2905-
The <emu-t>stringifier</emu-t> keyword
2906-
can also be placed on an [=attribute=].
2907-
In this case, the string to convert the object to is the
2908-
value of the attribute. The <emu-t>stringifier</emu-t> keyword
2909-
must not be placed on an attribute unless
2910-
it is declared to be of type {{DOMString}} or {{USVString}}.
2911-
It also must not be placed on
2912-
a [=static attribute=].
2913-
2914-
<pre highlight="webidl" class="syntax">
2915-
interface interface_identifier {
2916-
stringifier attribute DOMString identifier;
2917-
};
2918-
</pre>
2919-
2920-
<pre class="grammar" id="prod-Stringifier">
2921-
Stringifier :
2922-
"stringifier" StringifierRest
2923-
</pre>
2924-
2925-
<pre class="grammar" id="prod-StringifierRest">
2926-
StringifierRest :
2927-
OptionalReadOnly AttributeRest
2928-
RegularOperation
2929-
";"
2930-
</pre>
2931-
2932-
<div class="example">
2933-
2934-
The following [=IDL fragment=]
2935-
defines an interface that will stringify to the value of its
2936-
<code class="idl">name</code> attribute:
2937-
2938-
<pre highlight="webidl">
2939-
[Exposed=Window]
2940-
interface Student {
2941-
constructor();
2942-
attribute unsigned long id;
2943-
stringifier attribute DOMString name;
2944-
};
2945-
</pre>
2946-
2947-
In the ECMAScript binding, using a <code class="idl">Student</code>
2948-
object in a context where a string is expected will result in the
2949-
value of the object’s <code class="idl">name</code> property being
2950-
used:
2951-
2952-
<pre highlight="js">
2953-
var s = new Student();
2954-
s.id = 12345678;
2955-
s.name = '周杰倫';
2956-
2957-
var greeting = 'Hello, ' + s + '!'; // Now greeting == 'Hello, 周杰倫!'.
2958-
</pre>
2959-
2960-
The following [=IDL fragment=]
2961-
defines an interface that has custom stringification behavior that is
2962-
not specified in the IDL itself.
2963-
2964-
<pre highlight="webidl">
2965-
[Exposed=Window]
2966-
interface Student {
2967-
constructor();
2968-
attribute unsigned long id;
2969-
attribute DOMString? familyName;
2970-
attribute DOMString givenName;
2971-
2972-
stringifier DOMString ();
2973-
};
2974-
</pre>
2975-
2976-
Thus, prose is required to explain the stringification behavior.
2977-
We assume that the <code class="idl">familyName</code> and
2978-
<code class="idl">givenName</code> attributes are backed by
2979-
family name and given name concepts, respectively.
2980-
2981-
<blockquote>
2982-
2983-
The [=stringification behavior=] steps are:
2984-
2985-
1. If [=this=]'s family name is null, then return [=this=]'s given name.
2986-
2. Return the concatenation of [=this=]'s given name, followed by U+0020 SPACE, followed by [=this=]'s family name.
2987-
2988-
</blockquote>
2989-
2990-
An ECMAScript implementation of the IDL would behave as follows:
2991-
2992-
<pre highlight="js">
2993-
var s = new Student();
2994-
s.id = 12345679;
2995-
s.familyName = 'Smithee';
2996-
s.givenName = 'Alan';
2997-
2998-
var greeting = 'Hi ' + s; // Now greeting == 'Hi Alan Smithee'.
2999-
</pre>
3000-
</div>
3001-
3002-
30032967
<h5 id="idl-indexed-properties" dfn export>Indexed properties</h5>
30042968

30052969
An [=interface=] that defines an [=indexed property getter=]
@@ -12274,7 +12238,7 @@ A [=regular operation=] that does not [=have default method steps=] must not be
1227412238
</pre>
1227512239
</div>
1227612240

12277-
<h5 id="es-stringifier">Stringifiers</h5>
12241+
<h4 id="es-stringifier">Stringifiers</h4>
1227812242

1227912243
If the [=interface=] has an [=exposed=] [=stringifier=],
1228012244
then there must exist a property with the following characteristics:
@@ -12301,19 +12265,16 @@ then there must exist a property with the following characteristics:
1230112265
1. If |O| does not [=implement=] the [=interface=]
1230212266
on which the stringifier was declared, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
1230312267
1. Let |V| be an uninitialized variable.
12304-
1. Depending on where <code>stringifier</code> was specified:
12268+
1. Depending on how <code>stringifier</code> was specified:
1230512269
<dl class="switch">
12270+
: as a declaration
12271+
:: Set |V| to the result of performing the [=stringification behavior=]
12272+
of the interface.
1230612273
: on an [=attribute=]
1230712274
:: Set |V| to the result of running the [=getter steps=] of the attribute
1230812275
(or those listed in the [=getter steps=] of the inherited attribute, if this attribute is declared to
1230912276
[=inherit its getter=]),
1231012277
with |O| as [=this=].
12311-
: on an [=operation=] with an identifier
12312-
:: Set |V| to the result of running the [=method steps=]
12313-
of the operation, with |O| as [=this=] and an empty list as the argument values.
12314-
: on an [=operation=] with no identifier
12315-
:: Set |V| to the result of performing the [=stringification behavior=]
12316-
of the interface.
1231712278
</dl>
1231812279
1. Return the result of [=converted to an ECMAScript value|converting=] |V| to a String value.
1231912280
</div>

0 commit comments

Comments
 (0)