Re: [w3c/FileAPI] Add simpler reading methods to Blob interface. (#117)

annevk commented on this pull request.

Thanks for working on this!

> @@ -551,6 +559,59 @@ It must act as follows:
   </pre>
 </div>
 
+<h4 id="stream-method-algo">
+The stream method</h4>

I guess this is technically up to you, but I'd prefer not wrapping after an opening tag or before a closing tag as it introduces whitespace where there should be none.

> @@ -551,6 +559,59 @@ It must act as follows:
   </pre>
 </div>
 
+<h4 id="stream-method-algo">
+The stream method</h4>

Also, if these are to have headings we should use `<code>stream()</code>` or some such as that's the typical way of writing down a method name.

> @@ -551,6 +559,59 @@ It must act as follows:
   </pre>
 </div>
 
+<h4 id="stream-method-algo">
+The stream method</h4>
+
+The <dfn method for=Blob>stream()</dfn> method returns the contents
+of the blob as a {{ReadableStream}}.

Do we need this summary? It seems clearer if the `<dfn>` is immediately about the normative aspect.

> @@ -551,6 +559,59 @@ It must act as follows:
   </pre>
 </div>
 
+<h4 id="stream-method-algo">
+The stream method</h4>
+
+The <dfn method for=Blob>stream()</dfn> method returns the contents
+of the blob as a {{ReadableStream}}.
+
+It must return the result of [=getting a stream for a Blob=] for the [=context object=].
+
+To <dfn lt="get a stream for a Blob|getting a stream for a Blob">get a stream for a {{Blob}}</dfn>
+|blob|, run the following steps:
+
+1. Let |stream| be the result of [=construct a ReadableStream object|constructing=] a
+   {{ReadableStream}} object.
+1. Return |stream| and run the following steps [=in parallel=]:

Please do the return as the last step. So "2. Run these steps in parallel: 2.1 ... 3. Return _stream_."

> +It must return the result of [=getting a stream for a Blob=] for the [=context object=].
+
+To <dfn lt="get a stream for a Blob|getting a stream for a Blob">get a stream for a {{Blob}}</dfn>
+|blob|, run the following steps:
+
+1. Let |stream| be the result of [=construct a ReadableStream object|constructing=] a
+   {{ReadableStream}} object.
+1. Return |stream| and run the following steps [=in parallel=]:
+  1. While not all bytes of |blob| have been read:
+    1. Let |bytes| be the byte sequence that results from reading a [=chunk=] from |blob|.
+    1. If a [=file read error=] occured while reading |bytes|, [$ReadableStream/error$]
+       |stream| with a [=failure reason=] and abort these steps.
+    1. [=ReadableStream/Enqueue=] |bytes| into |stream|.
+
+    Issue: We need to specify more concretely what reading from a Blob actually does, and what
+    possible errors can happen.

Yeah, and how large is a chunk? Is there some POSIX operation we can hint at?

> +    1. If a [=file read error=] occured while reading |bytes|, [$ReadableStream/error$]
+       |stream| with a [=failure reason=] and abort these steps.
+    1. [=ReadableStream/Enqueue=] |bytes| into |stream|.
+
+    Issue: We need to specify more concretely what reading from a Blob actually does, and what
+    possible errors can happen.
+
+<h4 id="text-method-algo">
+The text method</h4>
+
+The <dfn method for=Blob>text()</dfn> method returns the contents
+of the blob as a {{USVString}}.
+
+It must act as follows:
+
+1. Let |stream| be the the result of [=getting a stream for a Blob=] for the [=context object=].

So if we're going to define these in terms of streaming. Should we perhaps test this approach on `FileReader` first? So that the underlying streaming primitive is powerful enough to explain all these various features. For this particular method we could then likely use a shared abstraction as `FileReader` also has a string-returning feature.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/FileAPI/pull/117#pullrequestreview-211664382