Re: [w3c/FileAPI] Rewrite FileReader definitions. (#118)

mkruisselbrink commented on this pull request.



> @@ -251,6 +253,25 @@ Their [=deserialization step=], given |serialized| and |value|, are:
 
 2. Set |value|'s underlying byte sequence to |serialized|.\[[ByteSequence]].
 
+<div algorithm="get stream">
+A {{Blob}} |blob| has an associated <dfn for=Blob>get stream</dfn> algorithm,
+which runs these steps:
+
+1. Let |stream| be the result of [=construct a ReadableStream object|constructing=] a
+   {{ReadableStream}} object.
+1. 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.

Yeah, I'll leave figuring out how to better specify errors etc for a follow-up.

> @@ -251,6 +253,25 @@ Their [=deserialization step=], given |serialized| and |value|, are:
 
 2. Set |value|'s underlying byte sequence to |serialized|.\[[ByteSequence]].
 
+<div algorithm="get stream">
+A {{Blob}} |blob| has an associated <dfn for=Blob>get stream</dfn> algorithm,
+which runs these steps:
+
+1. Let |stream| be the result of [=construct a ReadableStream object|constructing=] a
+   {{ReadableStream}} object.
+1. 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|.

Ah, good point. Used similar language as fetch is doing to wrap things in a Uint8Array and error the stream if that fails. Would indeed be nice if you could just enqueue a byte sequence into a stream, and have that do the right thing.

>  };
 </pre>
 
+<div algorithm="read operation">
+A {{FileReader}} has an associated <dfn id=readOperation>read operation</dfn> algorithm,
+given |blob|, a |type| and an optional |encodingName|,
+runs the following steps:
+
+1. Set the [=context object=]'s {{FileReader/result}} to `null`.

Ah yes, that's much nicer. Done.

>  };
 </pre>
 
+<div algorithm="read operation">
+A {{FileReader}} has an associated <dfn id=readOperation>read operation</dfn> algorithm,
+given |blob|, a |type| and an optional |encodingName|,
+runs the following steps:
+
+1. Set the [=context object=]'s {{FileReader/result}} to `null`.
+1. Set the [=context object=]'s {{FileReader/error!!attribute}} to `null`.
+1. Let |stream| be the result of calling [=get stream=] on |blob|.
+1. Let |reader| be the result of [=get a reader|getting a reader=] from |stream|.
+1. Let |bytes| by an empty [=byte sequence=].
+1. Let |chunk| be the result of [=read a chunk|reading a chunk=] from |stream| with |reader|.

Done

> +<div algorithm="read operation">
+A {{FileReader}} has an associated <dfn id=readOperation>read operation</dfn> algorithm,
+given |blob|, a |type| and an optional |encodingName|,
+runs the following steps:
+
+1. Set the [=context object=]'s {{FileReader/result}} to `null`.
+1. Set the [=context object=]'s {{FileReader/error!!attribute}} to `null`.
+1. Let |stream| be the result of calling [=get stream=] on |blob|.
+1. Let |reader| be the result of [=get a reader|getting a reader=] from |stream|.
+1. Let |bytes| by an empty [=byte sequence=].
+1. Let |chunk| be the result of [=read a chunk|reading a chunk=] from |stream| with |reader|.
+1. Let |isFirstChunk| be true.
+1. [=In parallel=], while true:
+  1. Wait for |chunk| to be fulfilled or rejected.
+  1. If |chunk| is fulfilled, and |isFirstChunk| is true,
+     [=queue a task=] to [=fire a progress event=] called {{loadstart}} at the [=context object=].

Thanks, linked to that issue from here.

> -    until one of the <a>read methods</a> have been called on it.
-  <dt><dfn id="dfn-loading">LOADING</dfn> (numeric value 1)
-  <dd>A {{File}} or {{Blob}} is being read.
-    One of the <a>read methods</a> is being processed,
-    and no error has occurred during the read.
-  <dt><dfn id="dfn-done">DONE</dfn> (numeric value 2)
-  <dd>The entire {{File}} or {{Blob}} has been read into memory,
-    OR a <a>file read error</a> occurred,
-    OR the read was aborted using {{FileReader/abort()}}.
-    The {{FileReader}} is no longer reading a {{File}} or {{Blob}}.
-    If {{FileReader/readyState}} is set to {{FileReader/DONE}}
-    it means at least one of the <a>read methods</a> have been called on this {{FileReader}}.
-</dl>
+The {{FileReader/readyState}} attribute tells you in which state the object is:
+
+: {{EMPTY}} (numeric value 0)

So I changed this section from normative to non-normative domintro, since the algorithms themselves really are normative for what value readyState has at what particular point in time. But yeah, fixing the internal slots thing will bring back definitions for the attributes as well.

>  
-1. Initiate a <a>read operation</a> using the <code>blob</code> argument,
-  and with the <a>synchronous flag</a> *set*.
-  If the read operation returns failure,
-  throw the appropriate exception as defined in [[#dfn-error-codes]].
-  <a>Terminate this algorithm</a>.
-1. If no error has occurred,
-  return the |result| of the <a>read operation</a> represented as a string
-  in a format determined through the <a>encoding determination</a> algorithm.
+1. Let |stream| be the result of calling [=get stream=] on |blob|.
+1. Let |reader| be the result of [=get a reader|getting a reader=] from |stream|.
+1. Let |promise| be the result of [=read all bytes|reading all bytes=] from |stream| with |reader|.
+1. Wait for |promise| to be fulfilled or rejected.

Ah yes, this of course only sort of works because we control the stream, and we know no script has to execute for this particular stream to be drained and the promise to resolve... That's not very nice (but then neither are sync APIs in general :) )

>  };
 </pre>
 
+<div algorithm="read operation">
+A {{FileReader}} has an associated <dfn id=readOperation>read operation</dfn> algorithm,
+given |blob|, a |type| and an optional |encodingName|,
+runs the following steps:
+
+1. Set the [=context object=]'s {{FileReader/result}} to `null`.
+1. Set the [=context object=]'s {{FileReader/error!!attribute}} to `null`.

Done (and in doing so, realized that I somehow had lost the step that sets readyState to loading. Fixed that as well).

-- 
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/118#discussion_r265769818