In This Forth, as in Standard Forth, a file is referenced
by a file-id.  In This Forth, a file-id is a file pointer
returned from the Standard C Library `fopen'. The following
are all equivalent. (Words in all upper case can also be
written in all lower case.)

	S" foo" S" r" FOPEN DUP 0= ABORT" Can't open "
	S" foo" S" r" OPENED
	S" foo" INPUT
	
They all leave a file-id on the stack.

To reference the file the file-id should be used to define
a constant or value-name (or stored in a variable).  A
constant can be used when you're never going to close the
file or change the file name. In general you start out:

	S" foo" INPUT VALUE in

and use the value-name `in' to reference file "foo".

In file "rth" there is this definition

	: COPY filter get-char EMIT unfilter ;

To show file "foo" say:

	in copy

Another easy filter:

	: UPCASE filter get-char >upper EMIT unfilter ;

To show a file in upper case:

	in upcase

To change the file associated with `in' first close `in'.

	in CLOSED
	S" bar" INPUT TO in

Getting a file-id for output works similarly.

	S" baz" S" w" FOPEN DUP 0= ABORT" Can't open " VALUE out
		or
	S" baz" S" w" OPENED VALUE out
		or
	S" baz" OUTPUT VALUE out
	...
	out CLOSED
	S" qux" OUTPUT VALUE TO out

The following sugar coating may appeal to you:

	S" foo" ==> in
	in closed
	S" bar" ==> in
	
	S" baz" <== out
	out closed
	S" qux" <== out

: initialize			( n "name" -- )
	bl word dup find nip 0= if
		count please "value ~ "
	else
		count please "to ~ "
	then
; immediate

: ==> ~please "input initialize ~ " ; immediate

: <== ~please "output initialize ~ " ; immediate

: <-- display ;


The kernel word DISPLAY is used to assign the user output device.
It stays assigned until re-assigned. `0 DISPLAY' can be used to assign
the user output device back to standard output.

I'm not happy with the term DISPLAY but all the good names have been
taken.  The Standard defines `display' as

	to send one or more characters to the user output device.

so it _is_ appropriate.

Example.

To convert files "foo" and "bar" to upper case and write out to "foobar":

	s" foo" ==> in
	s" foobar" <== out
	out <-- ." File 'foo' " cr 0 <--
	out <-- in upcase 0 <--
	in closed
	s" bar" ==> in
	out <-- ." File 'bar' " cr in upcase 0 <--
	in closed   out closed

Now take a look at it.

	s" foobar" ==> in
	in copy
or
	s" foobar" ==> out
	out copy

`filter' and `unfilter' are macros.  As far as the compiler knows, the
definition of `copy' above is identical to:

	: copy				( file-id -- )
		stream				( )
			BEGIN
				next-char eol <>
			WHILE
				get-char EMIT
			REPEAT
			SOURCE-ID		( file-id)
		unstream
		REWIND				( )
	;

Another spoonful of sugar:

: <<	~please "display ~ 0 display " ; immediate

: >>	~please "case stream ~ unstream esac " ; immediate
