Re: [whatwg/encoding] Rename Encoding's "streams" to "I/O queues" (#215)

@annevk commented on this pull request.

The concepts look pretty good to me. I have mostly nits, some I'm happy to address myself once you're satisfied.

> @@ -13,6 +13,8 @@ Translate IDs: dictdef-textdecoderoptions textdecoderoptions,dictdef-textdecodeo
 
 <pre class=link-defaults>
 spec:streams; type:interface; text:ReadableStream
+spec:infra; type:dfn; text:list;

I think you can avoid this by using `<a for=/>list</a>`. I think we can now also remove the above line and ideally this entire block.

> @@ -94,37 +96,118 @@ bitwise AND by "&amp;", and bitwise OR by "|".
 
 <hr>
 
-<p>A <dfn id=concept-token>token</dfn> is a piece of data, such as a <a>byte</a> or
-<a>scalar value</a>.
+<p>An <dfn id=concept-stream export>I/O queue</dfn> is a type of <a>list</a>

Can we wrap new and changed text at 100 columns please? As it's editorial I'm also willing to do this as a final pass.

> @@ -94,37 +96,118 @@ bitwise AND by "&amp;", and bitwise OR by "|".
 
 <hr>
 
-<p>A <dfn id=concept-token>token</dfn> is a piece of data, such as a <a>byte</a> or
-<a>scalar value</a>.
+<p>An <dfn id=concept-stream export>I/O queue</dfn> is a type of <a>list</a>
+with <a>items</a> of a particular type (i.e. <a>bytes</a> or <a>scalar

No newlines inside "inline" elements.

And "i.e.,".

>  
-<p>A <dfn id=concept-stream>stream</dfn> represents an ordered sequence of
-<a>tokens</a>. <dfn>End-of-stream</dfn> is a special
-<a>token</a> that signifies no more
-<a>tokens</a> are in the
-<a for=/>stream</a>.
+<p>To <dfn>create an I/O queue</dfn>, return a new <a for=/>I/O queue</a>

Shouldn't this also take some data as an argument to put in the queue?

> +
+<p>To <dfn id=concept-stream-read for="I/O queue" export>read</dfn> an
+<a>item</a> from an <a for=/>I/O queue</a> <var>ioQueue</var>, run these steps:
+
+<ol>
+ <li><p>If <var>ioQueue</var> is <a for=list>empty</a>, then wait until its
+ <a for=list>size</a> is at least 1.
+
+ <li><p>If the first item in <var>ioQueue</var> is <a>end-of-file</a>, then
+ return <a>end-of-file</a>.
+
+ <li><p>Otherwise, <a for=list>remove</a> the first item in <var>ioQueue</var>
+ and return it.
+</ol>
+
+<p>To read a number <var>number</var> of <a>items</a> from <var>ioQueue</var>,

If we need this primitive it should have a dfn, no?

> +results in an I/O queue "<code>&amp;#128169; hello world</code>". The next item
+to be read would be <code>&amp;</code>. <!-- 💩 -->
+
+<p class=note><a for=/>I/O queues</a> are defined as <a>lists</a>, not
+<a spec=infra>queues</a>, because they feature a <a for="I/O queue">prepend</a>
+operation. However, this prepend operation is an internal detail of the
+algorithms in this specification, and is not to be used by other standards.
+Implementations are free to find alternative ways to implement such algorithms,
+as detailed in [[#implementation-considerations]].
+
+<hr>
+
+<p><a for=/>I/O queues</a> can be implicitly converted into and from
+<a>strings</a> and <a>byte sequences</a> using the following operations.
+
+<p>To <dfn for="byte sequence to I/O queue" export>convert</dfn> a <a>byte

If we're going to define this as part of this PR we should also reference it where it's needed below I think.

> @@ -94,37 +96,177 @@ bitwise AND by "&amp;", and bitwise OR by "|".
 
 <hr>
 
-<p>A <dfn id=concept-token>token</dfn> is a piece of data, such as a <a>byte</a> or
-<a>scalar value</a>.
+<p>An <dfn id=concept-stream export>I/O queue</dfn> is a type of <a>list</a>
+with <a>items</a> of a particular type (i.e. <a>bytes</a> or <a>scalar
+values</a>). <dfn id="end-of-stream" export>End-of-file</dfn> is a special

end-of-queue?

-- 
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/215#pullrequestreview-449616865