5.17.1 Forth source files

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

     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 use one of these three formats:

     require mysource.fs
     needs 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:

     1024 require foo.fs drop

Here you want to pass the argument 1024 (e.g., a buffer size) to foo.fs. Interpreting foo.fs has the stack effect ( n – n ), which allows its use with require. Of course with such parameters to required files, you have to ensure that the first require fits for all uses (i.e., require it early in the master load file).

include-file       i*x wfileid – j*x         file       “include-file”

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

included       i*x c-addr u – j*x         file       “included”

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

included?       c-addr u – f         gforth       “included?”

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" – ...         gforth       “include”

include-file the file file.

required       i*x addr u – i*x         gforth       “required”

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" – ...         gforth       “require”

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

needs       ... "name" – ...         gforth       “needs”

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

sourcefilename       – c-addr u         gforth       “sourcefilename”

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 undefined. In Gforth, the result is valid during the whole seesion (but not across savesystem etc.).

sourceline#       – u         gforth       “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 undefined.

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