Section 3: Source Management
Traditionally, Forth source and data were maintained in 1024-byte blocks on disk. This format was appropriate for early systems, many of which used Forth as the only operating system, with native disk drivers. In such an environment, a block number mapped directly to the physical head/track/sector location on disk, and was an extremely fast and reliable means of handling the disk. As more Forths were implemented on other host operating systems, blocks became a kind of lingua franca, or standardized source interface, presented to the programmer regardless of the host OS. On such systems, blocks were normally implemented in host OS files.
Today, native Forth systems are extremely rare, and text files are the most portable medium between systems. ANS Forth includes an optional wordset for managing text files, as well as a block-handling wordset. SwiftForth provides full support for both, although SwiftForth source resides in text files.
The primary vehicle for SwiftForth program source is text files, which may be edited using a linked editor of your choice as described in Section 2.4.1. This section describes tools for managing text files.
3.1 Interpreting Source Files
You may load source files using the File > Include menu option, the Include button on the Toolbar, or by typing:
INCLUDE
…in the command window. The functional difference between these is that the button or menu options display a browse window in which you can select the file, and leaves SwiftForth’s path set to that of the selected file, whereas the typed command handles a specified file (including relative path information) and doesn’t affect your current path.
The INCLUDE command causes all of a file to be loaded, as in:
INCLUDE HEXCALC
The default filename extension .f (Forth source) is assumed if no extension is given.
The standard DOS/Windows rules for describing paths apply:
1. Absolute path: The name starts with a \ or :\ or \. Any of these indicates an absolute path to the file. This type of path is typically discouraged, because it must be changed manually if the directory structure changes.
2. Relative path to subdirectories: The name does not contain a leading \ or ..\ designation, and the file is located in the current directory or a subdirectory below it.
3. Relative path to parent directories: The name begins with a series of ..\ (two periods and a backslash). Each series raises the location one level from the current subdirectory. After you have raised the level sufficiently, you can use the technique in #2 to go down subdirectory levels.
In addition, SwiftForth can manage paths relative to the location of the actual executable (normally in the SwiftForth\bin directory). Such paths are indicated by the starting symbol %, and the actual root is two levels above wherever the executable is. For example, the basic error handling functions are loaded by:
INCLUDE %SwiftForth\src\ide\win32\errmessages.f
If you have launched SwiftForth from a project file or shortcut in your project directory (described in Section 3.1), your default path is that directory, so you don’t need to preface local files with any path information. So, your local configuration file could be loaded like this:
INCLUDE CONFIG
The word INCLUDING returns the string address and length of the filename currently being interpreted by INCLUDE. This may be convenient for diagnostic or logging tools.
The CD (Change Directory) command works in the SwiftForth command window just as it does in a Windows command line, except there must be a space between CD and any following string. The CD command followed by no string will display your current path. No spaces are permitted in the pathname, and no other command may appear on the line. CD is not appropriate for use in definitions.
If you wish to change your directory path temporarily, you may take advantage of SwiftForth’s directory stack. The word PUSHPATH pushes your current path information onto the directory stack, and POPPATH pops the top path from the directory stack to become the current path.
Files can load other files that load still others. It is the programmer’s responsibility to develop manageable load sequences. We recommend that you cluster the INCLUDE commands for a logical section of a program into a single file, rather than scattering INCLUDEs throughout the source. Your program will be more manageable if you can look in a small number of files to find the INCLUDE sequences.
REQUIRES includes the first matching file it finds from among all the files in the following list of directories, in this order:
1. The current directory
2. The directory specified by the environment variable SFLOCAL_USER
3. %SwiftForth\lib
4. %SwiftForth\lib\options
5. %SwiftForth\lib\options\win32
6. %SwiftForth\lib\samples
7. %SwiftForth\lib\samples\win32 The syntax is simply:
REQUIRES
Another function helps you to avoid loading the same file more than once, and also makes it possible to add files to the lists displayed by the Tools >Optional Packages > Load Options dialogs.
The usage is:
OPTIONAL
Name can be any text that doesn’t contain a space character. Description must be on the same line and not exceed 200 characters in length.
OPTIONAL is valid only while including a file.
If name already exists in the LOADED-OPTIONS wordlist, the rest of the file will be ignored. If name does not exist in the LOADED-OPTIONS wordlist, a dictionary entry for name will be contructed and the rest of the line will be ignored.
If, and only if, OPTIONAL is the first word of one the first 10 lines of a file that exists in one of the directories…
%SwiftForth\lib\samples\
%SwiftForth\lib\samples\win32\
%SwiftForth\lib\options\
%SwiftForth\lib\options\win32\
…name will appear in one of the LOAD-OPTIONS dialogs (selected via the Tools > Optional Packages menu), and the associated description will be displayed in that dialog box.
Glossary
INCLUDE <.ext>
Direct the text interpreter to process filename; the extension is required if it is not .f. Path information is optional; it will search only in the current path, unless you precede filename with path information. INCLUDE differs from the File > Include menu option and Toolbar button in that it does not offer a browse dialog box and does not change your current path.
INCLUDING ( — c-addr u )
Returns the string address and count of the filename currently being interpreted by INCLUDE.
OPTIONAL ( — )
If name already exists in the LOADED-OPTIONS wordlist, the rest of the file will be ignored; otherwise, name will be added to the LOADED-OPTIONS wordlist and loading will continue. Valid only while including a file.
If this appears as the first word in the first line of a file that exists in one of the directories specified above (Section 3.1), name and description will appear in one of the Load Options dialogs.
PUSHPATH ( — )
Push the current directory path onto the directory stack.
POPPATH ( — )
Pop the top path from the directory stack to become the new current path.
REQUIRES <.ext>
INCLUDE the file filename from a pre-defined list of directories. The extension is required if it is not .f.
References
File-based disk access, Forth Programmer’s Handbook
3.2 Extended Comments
It is common in source files to wish to have commentary extending over several lines. Forth provides for comments beginning with ( (left parenthesis) and ending with ) (right parenthesis) to extend over several lines. However, the most common use of multi-line comments is to describe a group of words about to follow, and such descriptions frequently need to include parentheses for stack comments or for actual parenthetical remarks.
To provide for this, SwiftForth defines braces as functionally equivalent to parentheses except for taking a terminating brace. So a multi-line comment can begin with { and end with }, and can contain parenthetical remarks and stack comments. Note that the starting brace, like a left parenthesis, is a Forth word and therefore must be followed by a space. The closing brace is a delimiter, and does not need a space.
For extra visual highlighting of extended comments, SwiftForth uses a full line of dashes at the beginning and end of an extended comment:
{ —————————————————–
Numeric conversion bases
Forth allows the user to deal with arbitrary numeric conversion bases for input and output. These are the most common.
—————————————————– }
Glossary
{ ( — )
Begin a comment that may extend over multiple lines, until a terminating right brace } is encountered.
\ ( — )
During an INCLUDE operation, treat anything following this word as a comment; i.e., anything that follows \ in a source file will not be compiled.
3.3 File-related Debugging Aids
You can monitor the progress of an INCLUDE operation by using a flexible utility enabled by the command VERBOSE and disabled by SILENT. The level of monitoring is controlled by the dialog box, shown in Figure 11, that can be invoked by using the Options > Include monitoring menu item. The default behavior is “Display the text of each line.”
Figure 11. Included file monitoring configuration
For example, you might place these commands in a file where there is a problem:
VERBOSE
< troublesome code >
SILENT
VERBOSE turns on the monitor, and SILENT turns off the monitor. While monitoring is active, any INCLUDE will also display the name of the file being processed.
These words are not immediate, which means they should be used outside definitions unless you specifically intend to define a word that incorporates this behavior.
The default mode for the system is SILENT.
Glossary
VERBOSE ( — )
Enables the INCLUDE monitor, with a default behavior of “display the text of each line.”
SILENT ( — )
Disables the INCLUDE monitor.