Deprecate file-read-chunks by incorporating it inside asma.
This commit is contained in:
Andrew Alderwick
parent
60f04ca053
commit
113220b10d
|
|
@ -230,7 +230,59 @@
|
||||||
POP2 POP2 POP2 POP2 POP2
|
POP2 POP2 POP2 POP2 POP2
|
||||||
JMP2r
|
JMP2r
|
||||||
|
|
||||||
~projects/library/file-read-chunks.tal
|
@file-read-chunks ( func* udata* buf* size* filename* -- func* udata'* buf* size* filename* )
|
||||||
|
|
||||||
|
#0000 DUP2 ( F* U* B* SZ* FN* OL* OH* / )
|
||||||
|
&resume
|
||||||
|
ROT2 STH2 ( F* U* B* SZ* OL* OH* / FN* )
|
||||||
|
ROT2 ( F* U* B* OL* OH* SZ* / FN* )
|
||||||
|
|
||||||
|
&loop
|
||||||
|
STH2kr .File/name DEO2 ( F* U* B* OL* OH* SZ* / FN* )
|
||||||
|
STH2k ,ffwd/length STR2 ( F* U* B* OL* OH* / FN* SZ* )
|
||||||
|
STH2 ( F* U* B* OL* / FN* SZ* OH* )
|
||||||
|
STH2k ,ffwd/offset STR2 ( F* U* B* / FN* SZ* OH* OL* )
|
||||||
|
DUP2 ,ffwd/addr STR2
|
||||||
|
,ffwd JSR
|
||||||
|
SWP2 ( F* B* U* / FN* SZ* OH* OL* )
|
||||||
|
ROT2k NIP2 ( F* B* U* B* F* / FN* SZ* OH* OL* )
|
||||||
|
OVR2 .File/read DEO2 ( F* B* U* B* F* / FN* SZ* OH* OL* )
|
||||||
|
.File/success DEI2 SWP2 ( F* B* U* B* length* F* / FN* SZ* OH* OL* )
|
||||||
|
JSR2 ( F* B* U'* done-up-to* / FN* SZ* OH* OL* )
|
||||||
|
ROT2 SWP2 ( F* U'* B* done-up-to* / FN* SZ* OH* OL* )
|
||||||
|
SUB2k NIP2 ( F* U'* B* -done-length* / FN* SZ* OH* OL* )
|
||||||
|
ORAk ,¬-end JCN ( F* U'* B* -done-length* / FN* SZ* OH* OL* )
|
||||||
|
|
||||||
|
POP2 POP2r POP2r ( F* U'* B* / FN* SZ* )
|
||||||
|
STH2r STH2r ( F* U'* B* SZ* FN* / )
|
||||||
|
JMP2r
|
||||||
|
|
||||||
|
¬-end
|
||||||
|
STH2r SWP2 ( F* U'* B* OL* -done-length* / FN* SZ* OH* )
|
||||||
|
LTH2k JMP INC2r ( F* U'* B* OL* -done-length* / FN* SZ* OH'* )
|
||||||
|
SUB2 ( F* U'* B* OL'* / FN* SZ* OH'* )
|
||||||
|
STH2r STH2r ( F* U'* B* OL'* OH'* SZ* / FN* )
|
||||||
|
,&loop JMP
|
||||||
|
|
||||||
|
@ffwd
|
||||||
|
LIT2 &length $2
|
||||||
|
LIT2 &offset $2
|
||||||
|
|
||||||
|
&coarse ( length* offset* )
|
||||||
|
GTH2k ,&fine JCN
|
||||||
|
OVR2 .File/length DEO2
|
||||||
|
,&addr LDR2 .File/read DEO2
|
||||||
|
OVR2 SUB2
|
||||||
|
,&coarse JMP
|
||||||
|
|
||||||
|
&fine ( length* offset* )
|
||||||
|
.File/length DEO2 ( length* )
|
||||||
|
,&addr LDR2 .File/read DEO2
|
||||||
|
.File/length DEO2 ( )
|
||||||
|
JMP2r
|
||||||
|
|
||||||
|
&addr $2
|
||||||
|
|
||||||
|
|
||||||
(
|
(
|
||||||
Assemble a chunk of source code, which begins with whitespace or the start
|
Assemble a chunk of source code, which begins with whitespace or the start
|
||||||
|
|
|
||||||
|
|
@ -1,209 +0,0 @@
|
||||||
(
|
|
||||||
|
|
||||||
# Summary
|
|
||||||
|
|
||||||
*** CAUTION: this library is deprecated! ***
|
|
||||||
|
|
||||||
Chunked file reads are now possible in the File device directly: just use
|
|
||||||
File/read or File/write multiple times. This library exists for compatibility to
|
|
||||||
keep asma going until it gets a more substantial rewrite.
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
Reads a file in chunks - perfect for when you have a small buffer or when you
|
|
||||||
don't know the file size. Copes with files up to 4,294,967,295 bytes long.
|
|
||||||
|
|
||||||
# Code
|
|
||||||
|
|
||||||
)
|
|
||||||
@file-read-chunks ( func* udata* buf* size* filename* -- func* udata'* buf* size* filename* )
|
|
||||||
|
|
||||||
#0000 DUP2 ( F* U* B* SZ* FN* OL* OH* / )
|
|
||||||
&resume
|
|
||||||
ROT2 STH2 ( F* U* B* SZ* OL* OH* / FN* )
|
|
||||||
ROT2 ( F* U* B* OL* OH* SZ* / FN* )
|
|
||||||
|
|
||||||
&loop
|
|
||||||
STH2kr .File/name DEO2 ( F* U* B* OL* OH* SZ* / FN* )
|
|
||||||
STH2k ,ffwd/length STR2 ( F* U* B* OL* OH* / FN* SZ* )
|
|
||||||
STH2 ( F* U* B* OL* / FN* SZ* OH* )
|
|
||||||
STH2k ,ffwd/offset STR2 ( F* U* B* / FN* SZ* OH* OL* )
|
|
||||||
DUP2 ,ffwd/addr STR2
|
|
||||||
,ffwd JSR
|
|
||||||
SWP2 ( F* B* U* / FN* SZ* OH* OL* )
|
|
||||||
ROT2k NIP2 ( F* B* U* B* F* / FN* SZ* OH* OL* )
|
|
||||||
OVR2 .File/read DEO2 ( F* B* U* B* F* / FN* SZ* OH* OL* )
|
|
||||||
.File/success DEI2 SWP2 ( F* B* U* B* length* F* / FN* SZ* OH* OL* )
|
|
||||||
JSR2 ( F* B* U'* done-up-to* / FN* SZ* OH* OL* )
|
|
||||||
ROT2 SWP2 ( F* U'* B* done-up-to* / FN* SZ* OH* OL* )
|
|
||||||
SUB2k NIP2 ( F* U'* B* -done-length* / FN* SZ* OH* OL* )
|
|
||||||
ORAk ,¬-end JCN ( F* U'* B* -done-length* / FN* SZ* OH* OL* )
|
|
||||||
|
|
||||||
POP2 POP2r POP2r ( F* U'* B* / FN* SZ* )
|
|
||||||
STH2r STH2r ( F* U'* B* SZ* FN* / )
|
|
||||||
JMP2r
|
|
||||||
|
|
||||||
¬-end
|
|
||||||
STH2r SWP2 ( F* U'* B* OL* -done-length* / FN* SZ* OH* )
|
|
||||||
LTH2k JMP INC2r ( F* U'* B* OL* -done-length* / FN* SZ* OH'* )
|
|
||||||
SUB2 ( F* U'* B* OL'* / FN* SZ* OH'* )
|
|
||||||
STH2r STH2r ( F* U'* B* OL'* OH'* SZ* / FN* )
|
|
||||||
,&loop JMP
|
|
||||||
|
|
||||||
@ffwd
|
|
||||||
LIT2 &length $2
|
|
||||||
LIT2 &offset $2
|
|
||||||
|
|
||||||
&coarse ( length* offset* )
|
|
||||||
GTH2k ,&fine JCN
|
|
||||||
OVR2 .File/length DEO2
|
|
||||||
,&addr LDR2 .File/read DEO2
|
|
||||||
OVR2 SUB2
|
|
||||||
,&coarse JMP
|
|
||||||
|
|
||||||
&fine ( length* offset* )
|
|
||||||
.File/length DEO2 ( length* )
|
|
||||||
,&addr LDR2 .File/read DEO2
|
|
||||||
.File/length DEO2 ( )
|
|
||||||
JMP2r
|
|
||||||
|
|
||||||
&addr $2
|
|
||||||
|
|
||||||
(
|
|
||||||
|
|
||||||
# Arguments
|
|
||||||
|
|
||||||
* func* - address of callback routine
|
|
||||||
* udata* - userdata to pass to callback routine
|
|
||||||
* buf* - address of first byte of buffer of file's contents
|
|
||||||
* size* - size in bytes of buffer
|
|
||||||
* filename* - address of filename string (zero-terminated)
|
|
||||||
|
|
||||||
All of the arguments are shorts (suffixed by asterisks *).
|
|
||||||
|
|
||||||
# Callback routine
|
|
||||||
|
|
||||||
If you make use of userdata, the signature of the callback routine is:
|
|
||||||
)
|
|
||||||
( udata* buf* length* -- udata'* done-up-to* )
|
|
||||||
(
|
|
||||||
|
|
||||||
* udata* and buf* are as above.
|
|
||||||
* length* is the length of the chunk being worked on, which could be less than
|
|
||||||
size* when near the end of the file, and func* is called with zero length* to
|
|
||||||
signify end of file.
|
|
||||||
* udata'* is the (potentially) modified userdata, to be passed on to the next
|
|
||||||
callback routine call and returned by file-read-chunks after the last chunk.
|
|
||||||
* done-up-to* is the pointer to the first unprocessed byte in the buffer, or
|
|
||||||
buf* + length* if the whole chunk was processed.
|
|
||||||
|
|
||||||
If you don't make use of any userdata, feel free to pretend the signature is:
|
|
||||||
)
|
|
||||||
( buf* length* -- done-up-to* )
|
|
||||||
(
|
|
||||||
|
|
||||||
# Userdata
|
|
||||||
|
|
||||||
The udata* parameter is not processed by file-read-chunks, except to keep the
|
|
||||||
one returned from one callback to the next. The meaning of its contents is up
|
|
||||||
to you - it could simply be a short integer or a pointer to a region of memory.
|
|
||||||
|
|
||||||
# Operation
|
|
||||||
|
|
||||||
file-read-chunks reads a file into the buffer you provide and calls func* with
|
|
||||||
JSR2 with each chunk of data, finishing with an empty chunk at end of file.
|
|
||||||
|
|
||||||
file-read-chunks loops until done-up-to* equals buf*, equivalent to when no
|
|
||||||
data is processed by func*. This could be because processing cannot continue
|
|
||||||
without a larger buffer, an error is detected in the data and further
|
|
||||||
processing is pointless, or because the end-of-file empty chunk leaves the
|
|
||||||
callback routine with no other choice.
|
|
||||||
|
|
||||||
# Return values
|
|
||||||
|
|
||||||
Since file-read-chunks's input parameters remain available throughout its
|
|
||||||
operation, they are not automatically discarded in case they are useful to the
|
|
||||||
caller.
|
|
||||||
|
|
||||||
# Discussion about done-up-to*
|
|
||||||
|
|
||||||
file-read-chunks is extra flexible because it doesn't just give you one chance
|
|
||||||
to process each part of the file. Consider a func* routine that splits the
|
|
||||||
chunk's contents into words separated by whitespace. If the buffer ends with a
|
|
||||||
letter, you can't assume that letter is the end of that word - it's more likely
|
|
||||||
to be the in the middle of a word that continues on. If func* returns the
|
|
||||||
address of the first letter of the word so far, it will be called again with
|
|
||||||
that first letter as the first character of the next chunk's buffer. There's no
|
|
||||||
need to remember the earlier part of the word because you get presented with
|
|
||||||
the whole lot again to give parsing another try.
|
|
||||||
|
|
||||||
That said, func* must make at least _some_ progress through the chunk: if it
|
|
||||||
returns the address at the beginning of the buffer, buf*, file-read-chunks will
|
|
||||||
terminate and return to its caller. With our word example, a buffer of ten
|
|
||||||
bytes will be unable to make progress with words that are ten or more letters
|
|
||||||
long. Depending on your application, either make the buffer big enough so that
|
|
||||||
progress should always be possible, or find a way to discern this error
|
|
||||||
condition from everything working fine.
|
|
||||||
|
|
||||||
# Discussion about recursion
|
|
||||||
|
|
||||||
Since all of file-read-chunks's data is on the working and return stacks, it
|
|
||||||
can be called recursively by code running in the callback routine. For example,
|
|
||||||
a code assembler can process the phrase "include library.tal" by calling
|
|
||||||
file-read-chunks again with library.tal as the filename. There are a couple of
|
|
||||||
caveats:
|
|
||||||
|
|
||||||
* the filename string must not reside inside file-read-chunk's working buffer,
|
|
||||||
otherwise it gets overwritten by the file's contents and subsequent chunks
|
|
||||||
will fail to be read properly; and
|
|
||||||
|
|
||||||
* if the buffer is shared with the parent file-read-chunk, the callback routine
|
|
||||||
should stop further processing and return with done-up-to* straight away,
|
|
||||||
since the buffer contents have already been replaced by the child
|
|
||||||
file-read-chunk.
|
|
||||||
|
|
||||||
# Resuming / starting operation from an arbitrary offset
|
|
||||||
|
|
||||||
You can call file-read-chunks/resume instead of the main routine if you'd like
|
|
||||||
to provide your own offset shorts rather than beginning at the start of the
|
|
||||||
file. The effective signature for file-read-chunks/resume is:
|
|
||||||
)
|
|
||||||
( func* udata* buf* size* filename* offset-ls* offset-hs* -- func* udata'* buf* size* filename* )
|
|
||||||
(
|
|
||||||
|
|
||||||
# Example callback routines
|
|
||||||
|
|
||||||
This minimal routine is a no-op that "processes" the entire buffer each time
|
|
||||||
and returns a valid done-up-to*:
|
|
||||||
|
|
||||||
@quick-but-useless
|
|
||||||
ADD2 JMP2r
|
|
||||||
|
|
||||||
This extremely inefficient callback routine simply prints a single character
|
|
||||||
from the buffer and asks for the next one. It operates with a buffer that is
|
|
||||||
just one byte long, but for extra inefficiency you can assign a much larger
|
|
||||||
buffer and it will ignore everything after the first byte each time. If the
|
|
||||||
buffer is zero length it returns done-up-to* == buf* so that file-read-chunks
|
|
||||||
returns properly.
|
|
||||||
|
|
||||||
@one-at-a-time
|
|
||||||
#0000 NEQ2 JMP JMP2r
|
|
||||||
LDAk .Console/write DEO
|
|
||||||
INC2 JMP2r
|
|
||||||
|
|
||||||
This more efficient example writes the entire chunk to the console before
|
|
||||||
requesting the next one by returning. How short can you make a routine that
|
|
||||||
does the same?
|
|
||||||
|
|
||||||
@chunk-at-a-time
|
|
||||||
&loop
|
|
||||||
ORAk ,¬-eof JCN
|
|
||||||
POP2 JMP2r
|
|
||||||
|
|
||||||
¬-eof
|
|
||||||
STH2
|
|
||||||
LDAk .Console/write DEO
|
|
||||||
INC2 STH2r #0001 SUB2
|
|
||||||
,&loop JMP
|
|
||||||
|
|
||||||
)
|
|
||||||
Loading…
Reference in New Issue