6 Glossary

6.2.2182 SAVE-INPUT CORE EXT

( -- x_n ... x₁ n )

x₁ through x_n describe the current state of the input source specification for later use by RESTORE-INPUT.

See:

15.6.2.1908 N>R, 15.6.2.1940 NR>, A.6.2.2182 SAVE-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

ContributeContributions

FrancoisLaagel [265] Bogus Test Case for SAVE-INPUTSuggested Testcase2022-09-06 14:36:57

In the "Testing" NeverExecuted obviously is executed and that's the end of it!

ruv [r865] 2022-09-07 09:45:56

Again, where have you tested the code?

RESTORE-INPUT changes the input source state, so after the next REFILL the parse area contains not " NeverExecuted" but " siv @" (that returns 0 in this time).

FrancoisLaagel [r927] 2022-10-06 18:01:09

Hello ruv,

I do apologize for the noise. Back when I published this, I was focusing on implementing EVALUATE without having a clearly defined SAVE-INPUT and RESTORE-INPUT process. The smoke has cleared up from my side since then and I have learned my lesson. I should always compare behaviour to what GNU Forth does, even though I will never support all the features of that beats.

Sorry about that.

    Francois

Closed

Reply New Version

JohanKotlinski [282] Is data stack required?Request for clarification2023-02-14 20:17:30

Is it a requirement that SAVE-INPUT and RESTORE-INPUT saves the state on the data stack?

I would prefer if it was allowed to keep the state on some other stack. (my Forth has a very limited data stack space)

JohanKotlinski [r953] 2023-02-14 20:37:42

Umm... given that N>R R>N are listed as related. Is the intended workflow like this?

SAVE-INPUT N>R ... R>N RESTORE-INPUT ?

ruv [r954] 2023-02-14 21:58:26

I would prefer if it was allowed to keep the state on some other stack.

Probably, you need other (system-specific) words for that. The words save-input and restore-input are not what they appear on the first glance — see my other comment.

Is the intended workflow like this? SAVE-INPUT N>R ... R>N RESTORE-INPUT ?

It's a possible workflow, but in a single found program that uses these words ("Lambda Expressions in ANS Forth" by Gerry Jackson), they are used in a totally different manner. See a discussion on ForthHub.

AntonErtl [r956] 2023-02-15 11:53:32

Yes, it's a requirement. However, given that the other requirements (guarantees to programs) are very weak, you do not need to put a lot of data on the data stack (at least for a minimal implementation of SAVE-INPUT).

Those who support N>R NR> told me that SAVE-INPUT N>R ... NR> RESTORE-INPUT is a usage that motivates N>R NR>. WHERE N>R on SwiftForth shows two uses, both after SAVE-INPUT and likewise both usese of NR> are before RESTORE-INPUT.

ruv [r959] 2023-02-15 22:07:23

N>R on SwiftForth shows two uses, both after SAVE-INPUT and likewise both usese of NR> are before RESTORE-INPUT.

BTW, in SwiftForth RESTORE-INPUT is used on a different input source. A standard program cannot use them in such a manner due to an ambiguous condition, which "exists if the input source represented by the arguments is not the same as the current input source".

Also, a SwiftForth version 3.11.6 peculiar (probably not only its) is that RESTORE-INPUT returns 0 (success) when it actually does not restore the state of the input source — e.g., in the case of keyboard. In this case it restores the position, but not the content of the input buffer. According to the specification, it shall restore nothing and return fail (-1), if it cannot restore the state of the input source.

UlrichHoffmann [r967] 2023-02-17 14:16:28

In my opinion, the ctual SAVE-INPUT values could be in a different memory area at some addrese ADDR and the stack effect of SAVE-INPUT might just be ( -- ADDR 1 ). This would be acceptable as a standard behaviour and would relieve the data stack on stack space limited systems.

AntonErtl [r981] 2023-02-23 18:35:56

We discussed this question at the meeting on 2023-02-17, and our conclusion was that we do not recommend implementing SAVE-INPUT and RESTORE-INPUT on systems that are so memory constrained that the amount of data-stack memory is a problem.

Closed

Reply New Version