6.22.1 Forth source files

The simplest way to interpret the contents of a file is to use one of these two equivalent syntaxes:

include mysource.fs
s" mysource.fs" included

You usually want to include a file only if it is not included already (by, say, another source file). In that case, you can replace include with require:

require mysource.fs
s" mysource.fs" required

It is good practice to write your source files such that interpreting them does not change the stack. Source files designed in this way can be used with required and friends without complications. For example, assume that including foo.fs has the stack effect ( u -- u ) (u might be a configuration parameter, such as a buffer size). Then you can use it with require:

1024 require foo.fs drop

If require actually includes foo.fs, the 1024 will be on the stack at the end, just like if require does nothing. With such parameters to required files, you have to ensure that the first require fits for all uses (i.e., require the file early in the master load file).

Another alternative is to pass configuration parameters by defining words (often constants) for them.

include-file ( i*x wfileid – j*x  ) file

Interpret (process using the text interpreter) the contents of the file wfileid.

included ( i*x c-addr u – j*x  ) file

include-file the file whose name is given by the string c-addr u.

included? ( c-addr u – f  ) gforth-0.2 “included-question”

True only if the file c-addr u is in the list of earlier included files. If the file has been loaded, it may have been specified as, say, foo.fs and found somewhere on the Forth search path. To return true from included?, you must specify the exact path to the file, even if that is ./foo.fs

include ( ... "file" – ...  ) file-ext

include-file the file file.

required ( i*x addr u – i*x  ) file-ext

include-file the file with the name given by addr u, if it is not included (or required) already. Currently this works by comparing the name of the file (with path) against the names of earlier included files.

require ( ... "file" – ...  ) file-ext

include-file file only if it is not included already.

needs ( ... "name" – ...  ) gforth-0.2

An alias for require; exists on other systems (e.g., Win32Forth).

\\\ ( –  ) gforth-1.0 “triple-backslash”

skip remaining source file

.included ( –  ) gforth-0.5 “dot-included”

List the names of the files that have been included.

sourcefilename ( – c-addr u  ) gforth-0.2

The name of the source file which is currently the input source. The result is valid only while the file is being loaded. If the current input source is no (stream) file, the result is an arbitrary string. In Gforth, the result is valid during the whole session (but not across savesystem etc.).

sourceline# ( – u  ) gforth-0.2 “sourceline-number”

The line number of the line that is currently being interpreted from a (stream) file. The first line has the number 1. If the current input source is not a (stream) file, the result is an unspecified number.

A definition in Standard Forth for required is provided in compat/required.fs.