6.2.2182
SAVE-INPUT
 
CORE EXT
 
( -- xn ... x1 n )

x1 through xn describe the current state of the input source specification for later use by RESTORE-INPUT.

Rationale:
SAVE-INPUT and RESTORE-INPUT allow the same degree of input source repositioning within a text file as is available with BLOCK input. SAVE-INPUT and RESTORE-INPUT "hide the details" of the operations necessary to accomplish this repositioning, and are used the same way with all input sources. This makes it easier for programs to reposition the input source, because they do not have to inspect several variables and take different action depending on the values of those variables.

SAVE-INPUT and RESTORE-INPUT are intended for repositioning within a single input source; for example, the following scenario is NOT allowed for a Standard Program:

: XX
   SAVE-INPUT CREATE
   S" RESTORE-INPUT" EVALUATE
   ABORT" couldn't restore input"
;

This is incorrect because, at the time RESTORE-INPUT is executed, the input source is the string via EVALUATE, which is not the same input source that was in effect when SAVE-INPUT was executed.

The following code is allowed:

: XX
   SAVE-INPUT CREATE
   S" .( Hello)" EVALUATE
   RESTORE-INPUT ABORT" couldn't restore input"
;

After EVALUATE returns, the input source specification is restored to its previous state, thus SAVE- INPUT and RESTORE-INPUT are called with the same input source in effect.

In the above examples, the EVALUATE phrase could have been replaced by a phrase involving INCLUDE-FILE and the same rules would apply.

The standard does not specify what happens if a program violates the above rules. A Standard System might check for the violation and return an exception indication from RESTORE-INPUT, or it might fail in an unpredictable way.

The return value from RESTORE-INPUT is primarily intended to report the case where the program attempts to restore the position of an input source whose position cannot be restored. The keyboard might be such an input source.

Nesting of SAVE-INPUT and RESTORE-INPUT is allowed. For example, the following situation works as expected:

: XX
   SAVE-INPUT
   S" f1" INCLUDED
   \ The file "f1" includes:
   \ ... SAVE-INPUT ... RESTORE-INPUT ...
   \ End of file "f1"
   RESTORE-INPUT ABORT" couldn't restore input"
;

In principle, RESTORE-INPUT could be implemented to "always fail", e.g.:

: RESTORE-INPUT ( x1 ... xn n -- flag )
   0 ?DO DROP LOOP TRUE
;

Such an implementation would not be useful in most cases. It would be preferable for a system to leave SAVE-INPUT and RESTORE-INPUT undefined, rather than to create a useless implementation. In the absence of the words, the application programmer could choose whether or not to create "dummy" implementations or to work-around the problem in some other way.

Examples of how an implementation might use the return values from SAVE-INPUT to accomplish the save/restore function:


Input Source possible stack values

block >IN @ BLK @ 2
EVALUATE >IN @ 1
keyboard >IN @ 1
text file >IN @ lo-pos hi-pos 3

These are examples only; a Standard Program may not assume any particular meaning for the individual stack items returned by SAVE-INPUT.

Testing:
Testing with a file source
VARIABLE siv -1 siv !

: NeverExecuted
   ." This should never be executed" ABORT
;

11111 SAVE-INPUT

siv @

[IF]
   0 siv !
   RESTORE-INPUT
   NeverExecuted
[ELSE]
   \ Testing the ELSE part is executed
   22222
[THEN]

T{ -> 11111 0 22222 }T    \ 0 comes from RESTORE-INPUT

Testing with a string source
VARIABLE si_inc 0 si_inc !

: si1
   si_inc @ >IN +!
   15 si_inc !
;

: s$ S" SAVE-INPUT si1 RESTORE-INPUT 12345" ;

T{ s$ EVALUATE si_inc @ -> 0 2345 15 }T

Testing nesting
: read_a_line
   REFILL 0=
   ABORT" REFILL failed"
;

0 si_inc !
2VARIABLE 2res -1. 2res 2!

: si2
   read_a_line
   read_a_line
   SAVE-INPUT
   read_a_line
   read_a_line
   s$ EVALUATE 2res 2!
   RESTORE-INPUT
;

WARNING: do not delete or insert lines of text after si2 is called otherwise the next test will fail

si2
33333                  \ This line should be ignored
2res 2@ 44444        \ RESTORE-INPUT should return to this line

55555

T{ -> 0 0 2345 44444 55555 }T