Re: [whatwg/encoding] Add get an encoder and encode or fail for URLs (#238)

@andreubotella requested changes on this pull request.

Some of these changes depend on https://github.com/whatwg/encoding/pull/237#issuecomment-713899293.


> @@ -1045,11 +1045,16 @@ optional I/O queue of bytes <var>output</var> (default « »), return the result
 
 <h3 id=legacy-hooks>Legacy hooks for standards</h3>
 
-<p class=note>In addition to the <a>decode</a>, <a>BOM sniff</a>, and <a>encode</a> algorithms
-below, standards needing these legacy hooks will most likely also need to use <a>get an encoding</a>
-(to turn a <a>label</a> into an <a for=/>encoding</a>) and <a>get an output encoding</a> (to turn an
-<a for=/>encoding</a> into another <a for=/>encoding</a> that is suitable to pass into
-<a>encode</a>). Other algorithms are not to be used directly.
+<div class=note>
+ <p>In addition to the <a>decode</a>, <a>BOM sniff</a>, and <a>encode</a> algorithms below,
+ standards needing these legacy hooks will most likely also need to use <a>get an encoding</a> (to
+ turn a <a>label</a> into an <a for=/>encoding</a>) and <a>get an output encoding</a> (to turn an

```suggestion
 turn a <a>label</a> into an <a for=/>encoding</a> instance) and <a>get an output encoding</a> (to turn an
```

> @@ -1045,11 +1045,16 @@ optional I/O queue of bytes <var>output</var> (default « »), return the result
 
 <h3 id=legacy-hooks>Legacy hooks for standards</h3>
 
-<p class=note>In addition to the <a>decode</a>, <a>BOM sniff</a>, and <a>encode</a> algorithms
-below, standards needing these legacy hooks will most likely also need to use <a>get an encoding</a>
-(to turn a <a>label</a> into an <a for=/>encoding</a>) and <a>get an output encoding</a> (to turn an
-<a for=/>encoding</a> into another <a for=/>encoding</a> that is suitable to pass into
-<a>encode</a>). Other algorithms are not to be used directly.
+<div class=note>
+ <p>In addition to the <a>decode</a>, <a>BOM sniff</a>, and <a>encode</a> algorithms below,
+ standards needing these legacy hooks will most likely also need to use <a>get an encoding</a> (to
+ turn a <a>label</a> into an <a for=/>encoding</a>) and <a>get an output encoding</a> (to turn an
+ <a for=/>encoding</a> into another <a for=/>encoding</a> that is suitable to pass into
+ <a>encode</a>). Other algorithms are not to be used directly.
+
+ <p>For an extremely niche case custom encoder error handling is needed. The <a>get an encoder</a>

"For extremely niche cases", or to drive the point home, "for the extremely niche case of URL encoding".

Also, a comma here would be appreciated. "Niche case custom encoder error handling" sounds like word salad at first.

> -<a>UTF-8 encode</a> on top is safe as it never triggers
-<a>errors</a>.
-[[URL]]
-[[HTML]]
+<p class="note no-backref">This is a legacy hook for HTML forms. Layering <a>UTF-8 encode</a> on top
+is safe as it never triggers <a>errors</a>. [[HTML]]
+
+<hr>
+
+<p>To <dfn export lt="get an encoder|getting an encoder">get an encoder</dfn> from an
+<a for=/>encoding</a> <var>encoding</var>:
+
+<ol>
+ <li><p>Assert: <var>encoding</var> is not <a>replacement</a> or <a>UTF-16BE/LE</a>.
+
+ <li><p>Return <var>encoding</var>'s <a for=/>encoder</a>.

```suggestion
 <li><p>Return a new instance of <var>encoding</var>'s <a for=/>encoder</a>.
```

There's a difference between an encoder (an "encoder class", so to speak) and an encoder _instance_, which has state. This hook should also be renamed to "get an encoder instance".

See also https://github.com/whatwg/encoding/pull/237#issuecomment-713899293.


> +<p class="note no-backref">This is a legacy hook for HTML forms. Layering <a>UTF-8 encode</a> on top
+is safe as it never triggers <a>errors</a>. [[HTML]]
+
+<hr>
+
+<p>To <dfn export lt="get an encoder|getting an encoder">get an encoder</dfn> from an
+<a for=/>encoding</a> <var>encoding</var>:
+
+<ol>
+ <li><p>Assert: <var>encoding</var> is not <a>replacement</a> or <a>UTF-16BE/LE</a>.
+
+ <li><p>Return <var>encoding</var>'s <a for=/>encoder</a>.
+</ol>
+
+<p>To <dfn export>encode or fail</dfn> an I/O queue of scalar values <var>ioQueue</var> given an
+<a for=/>encoder</a> <var>encoder</var> and an I/O queue of bytes <var>output</var>, run these

```suggestion
<a for=/>encoder</a> instance <var>encoderInstance</var> and an I/O queue of bytes <var>output</var>, run these
```

> +<p>To <dfn export lt="get an encoder|getting an encoder">get an encoder</dfn> from an
+<a for=/>encoding</a> <var>encoding</var>:
+
+<ol>
+ <li><p>Assert: <var>encoding</var> is not <a>replacement</a> or <a>UTF-16BE/LE</a>.
+
+ <li><p>Return <var>encoding</var>'s <a for=/>encoder</a>.
+</ol>
+
+<p>To <dfn export>encode or fail</dfn> an I/O queue of scalar values <var>ioQueue</var> given an
+<a for=/>encoder</a> <var>encoder</var> and an I/O queue of bytes <var>output</var>, run these
+steps:
+
+<ol>
+ <li><p>Let <var>potentialError</var> be the result of <a>running</a> <var>encoder</var> with
+ <var>ioQueue</var>, <var>output</var>, and "<code>fatal</code>".

```suggestion
 <var>ioQueue</var>, <var>output</var>, and "<code>fatal</code>".

 <li><p><a for="I/O queue">Push</a> <a>end-of-queue</a> into <var>encoder</var>.
```

Needed so the conversion to a byte sequence in whatwg/url#558 doesn't hang.

> +<p>To <dfn export>encode or fail</dfn> an I/O queue of scalar values <var>ioQueue</var> given an
+<a for=/>encoder</a> <var>encoder</var> and an I/O queue of bytes <var>output</var>, run these
+steps:
+
+<ol>
+ <li><p>Let <var>potentialError</var> be the result of <a>running</a> <var>encoder</var> with
+ <var>ioQueue</var>, <var>output</var>, and "<code>fatal</code>".
+
+ <li><p>If <var>potentialError</var> is an <a>error</a>, then return <a>error</a>'s
+ <a>code point</a>'s <a for="code point">value</a>.
+
+ <li><p>Return null.
+</ol>
+
+<div class=note>
+ <p>This is a legacy hook for URLs. The caller will have to keep an <a for=/>encoder</a> alive as

```suggestion
 <p>This is a legacy hook for URLs. The caller will have to keep an <a for=/>encoder</a> instace alive as
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/encoding/pull/238#pullrequestreview-514245872