I can't figure out from the DPANS documentation what these two words are
supposed to do.
Can someone please give me an example of how these words would be used
in an ever-day program?

Thanks,
Shaun Jackman

You might not need them in everyday programs.  Here's a rationale for
what it might be good for.

No matter what you have for an input buffer, you can do SOURCE to get
the buffer and length and then change >IN to change what gets
interpreted next.

If you have a BLOCK system you can do very sophisticated things if you
want to (which might be hard to debug etc, but still they're possible).  
And you can do similar sophisticated things with file input.  But it
takes very different methods.  If you use SAVE-INPUT and RESTORE-INPUT
to remember where you've been and get back, you might be able to use
the same method for either sort of file.  Each time you do SAVE-INPUT
it will tell you everything it will later need to know to get back.
You don't have to know what those numbers mean to it, you just have to
store them someplace safe and then get them back and do RESTORE-INPUT .
Since different systems might need a different number of items, and
you do need to know how many to save them (unless you just leave them
on the data stack which might be inconvenient), they include the number
of items.

I think this was something that looked like a good idea at the time,
it may not have been something that had a lot of use before they made
it.  I haven't actually used it much at all.

I use them very often!

The idea is to somehow take a snapshot of the state of the input stream,
do your bits, and then restore the input stream to what it was.

Here's an example:

: ANEW ( "name" -- )  SAVE-INPUT
       BL WORD FIND IF EXECUTE ELSE DROP THEN
       RESTORE-INPUT ABORT" ANEW error"
       MARKER ;

Here, ANEW checks to see if the following word exists, and if it is the
case, EXECUTEs it.
Whether or not the word was found, the input stream is restored so that
MARKER can operate with this very same word that ANEW just checked the
existence of.

An other area where I use it all the time is in defining words which do
parsing using CREATE. Since CREATE was ill-factored out in the standard,
and because I want to construct some symbol table of the entries defined
by my defining word, I use something of the form:

: MY-DEFINING-WORD
   SAVE-INPUT
   BL WORD COUNT save-to-symbol-table
   RESTORE-INPUT ABORT" parsing error"

   CREATE
   ....
   DOES>
   ....
;

--

----------

On Thu, 14 Jan 1999 22:02:18 +0000, "Jean-Francois Brouillet"

        An excellent example of my question. How would one do these as
THROWs, if you didn't already know what THROWs were in use on the
systems that might load the source code?

(
----------
Virtually,

Bruce McFarling, Newcastle,

)

An excellent question!  This is why the standard restricts system throw
codes to -4095...-1 (of which -255...-1 are reserved for the
Standard itself), leaving the entire domain of positive numbers
for your application to use.

Cheers,
Elizabeth

--
===============================================
Elizabeth D. Rather  (US & Canada) 800-55-FORTH
FORTH Inc.                      +1 310-372-8493
111 N. Sepulveda Blvd.     Fax: +1 310-318-7130
Manhattan Beach, CA 90266
http://www.forth.com

"Forth-based products and Services for real-time
applications since 1973."
===============================================

In a definition, saving and restoring  >IN  is more
attractive to me.  Here is the definition of  ANEW  that
I like.

    : POSSIBLY  BL WORD FIND  ?DUP AND IF  EXECUTE  THEN ;

POSSIBLY <name>  executes <name> if <name> is defined.  
It's good for initialization of words that might or might
not have been defined earlier.

Outside a definition  SAVE-INPUT  and  RESTORE-INPUT  could
be used to iterate compilation/interpretation of a script.

Here is a stript-down outline of an exercise I once did.

I wanted to check different approaches to doing something.

    : DROPPED  ( x1 x2 ... xn n -- )
        0 ?DO  DROP  LOOP
    ;

    : DUPPED  ( x1 x2 ... xn n -- x1 x2 ... xn x1 x2 ... xn )
        DUP 0 ?DO  DUP >R  1- PICK  R>  LOOP DROP
    ;

    : STOP-INPUT  ( x1 x2 ... xn n flag -- )
        IF    DROPPED
        ELSE  DUP 1+ DUPPED  RESTORE-INPUT DROP
        THEN
    ;

    VARIABLE #ROUND

    0 #ROUND !

    SAVE-INPUT  1 #ROUND +!

    .( \  This is Together. ) CR

    \  This is One.
    \  This is Together.
    \  This is Two.
    \  This is Together.
    \  This is Three.
    \  This is Together.

I love this one! The "FIND ?DUP AND IF" is particularly smart.

I hate this one.
Probably more on `religious' grounds than anything else, but the way I
see it, >IN is a leftover of the implementation specification that Forth 83
was, that Forth 94 couldn't deprecate because too much user code would
have been broken.

Put bluntly: global variables are BAD, and public global variables are
even worse.
They won't show up in my code, unless I absolutely have to. In that
precise case, there was no reason to make my code dependent on an
implementation feature (even if described in the ANS Standard) when
a clean alternative was available.

What this code is trying to achieve is not, well, crystal-clear (at
least to me) and an explanation of that "exercise about `something'"
would have been welcome in the first place...

--

It passes over the source file three times, doing something different each time,
and finally doing one piece of source whose behavior may be different because
of the different paths there.

--