File Names and Directories
2010-09-23: make environmental restriction and dependency of not
supporting '/' and using some other directory separator explicit
(suggested by Stephen Pelc).
1st RfD: Split out this (hopefully less contentious) proposal from the
What are portable file names? How do I refer to directories? What
about relative file names? Forth-94 does not specify these things; as
a result, systems implement diverging approaches (in particular wrt
relative file names in loading words). This proposal tries to outline
the common ground at the moment.
We specify portable file names and a directory separator (and follow
POSIX here). We also specify working-directory-relative file names
and source-directory-relative file names, and which words are
guaranteed to use one of these approaches, and which words use either.
Keep all source files in one directory. Forget about separately
Portable file name components: consist of ASCII letters, digits, ".",
"_", and "-" [from POSIX 2004 3.276]. Case matching may be case
sensitive or insensitive, so file names shall be referred to in the
case in which they were created, and no two file names differring
only by case shall be created in one directory.
Directory separator: The directory separator is "/".
File names: A file name has an optional beginning "/", followed by
zero or more portable file name components separated by "/"
Absolute file names: start with "/".
Relative file names: start with a portable file name component. What
a relative file name is relative to is defined further on.
Using file names containing other characters is an ambiguous condition
[They are treated differently on different Forth systems, different
operating systems, or different file systems].
Parent directory: ".." refers to the parent directory, "../.." to the
grandparent, "../sibling" to a different directory at the same level.
Source-directory-relative file name: Given a relative file name F that
occurs in the text of a Forth source file /SD/S, then using F as
source-directory-relative file name results in /SD/F. Using F as
source-directory-relative file name while not including a file is
an ambiguous condition [A typical fallback then might be to use F
as working-directory relative].
Working-directory-relative file name: If the absolute file name of the
working directory is /WD, then using F as
working-directory-relative file name results in the absolute file
name /WD/F. If the operating system does not support a working
directory, only absolute file names can be used in words that would
use relative file names as working-directory relative.
Passing a relative filename to any word consuming a filename except
INCLUDED, INCLUDE, REQUIRED or REQUIRE uses the file name as
working-directory-relative file name.
Passing a relative filename to INCLUDED, REQUIRED, INCLUDE or REQUIRE
uses the file name as either working-directory-relative file name
or as source-directory-relative file name [you can still use that
by making sure they are the same]. An ambiguous condition exists
if the file does not exist or is not accessible. [A fallback then
might be to search a path, or to throw an exception]. [Note that
all the known implementations of REQUIRE treat the file name as
source-directory-relative, so maybe you should refrain from
implementing it in a working-directory-relative way.]
A system that does not support '/' as directory separator has an
environmental restriction. A program that uses a directory separator
other than '/' has an environmental dependency.
Reference implementation and tests
Will be done after the solution has solidified after more discussion.
Existing practice and experience
To the best of my knowledge, all standard Forth systems that implement
the FILE wordset implement this proposal (as far as they implement the
words mentioned in the proposal).
Some systems implement source-directory-relative file names for
INCLUDED, REQUIRED and INCLUDE, some implement
working-directory-relative file names for these words. For REQUIRE,
all systems that implement it, implement source-directory relative
file names; but in order to avoid touching a contentious topic, even
REQUIRE is specified weakly in this proposal.
Isn't specifying "/" as directory separator too OS-specific?
It works in practice, and other approaches don't. E.g., Peter Knaggs
|Java has a special DirectorySeparator constant you are supposed to use,
|but nobody ever does.
If there is ever a Forth 200x system for an OS that has a different
directory syntax (e.g., VMS), the Forth system can translate the
filename with the slashes into the native directory syntax (I guess
that the POSIX layer for such OSs does the same).
Note that DOS and Windows understand "/" just fine (except in their
command-line interpreter, but Forth systems work through system
calls, not through the command-line interpreter).