From 113220b10d4dfb6728fe8a7ed7102c62d5e28627 Mon Sep 17 00:00:00 2001 From: Andrew Alderwick Date: Wed, 1 Dec 2021 22:01:26 +0000 Subject: [PATCH] Deprecate file-read-chunks by incorporating it inside asma. --- projects/library/asma.tal | 54 ++++++- projects/library/file-read-chunks.tal | 209 -------------------------- 2 files changed, 53 insertions(+), 210 deletions(-) delete mode 100644 projects/library/file-read-chunks.tal diff --git a/projects/library/asma.tal b/projects/library/asma.tal index 1837de9..5c62583 100644 --- a/projects/library/asma.tal +++ b/projects/library/asma.tal @@ -230,7 +230,59 @@ POP2 POP2 POP2 POP2 POP2 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 diff --git a/projects/library/file-read-chunks.tal b/projects/library/file-read-chunks.tal deleted file mode 100644 index f553c87..0000000 --- a/projects/library/file-read-chunks.tal +++ /dev/null @@ -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 - -)