The HTML version of this RfD is
<http://www.complang.tuwien.ac.at/forth/ansforth/required.html>

CHANGE HISTORY

2001-08-14: Changed stack effect from ( i*x c-addr u -- j*x ) to ( i*x
c-addr u -- i*x ), following a suggestion from Guido Draheim, and
related changes in the text.

PROBLEM

A library is needed by several parts of the source code (e.g., in
other libraries), but it should be loaded only once.

PROPOSAL

REQUIRED ( i*x c-addr u -- i*x )

If the file specified by c-addr u has been INCLUDED or REQUIRED
already, discard c-addr u; otherwise, perform INCLUDED.

An ambiguous condition exists if a file is REQUIRED while it is being
REQUIRED or INCLUDED.

An ambiguous condition exists if the same file is REQUIRED twice using
different names (e.g., through symbolic links), or different files
with the same name are REQUIRED (by doing some renaming between the
invocations of REQUIRED).

An ambiguous condition exists if the stack effect of including the
file is not ( i*x -- i*x ).

REQUIRE ( i*x "name" -- i*x )

Skip leading white space and parse name delimited by a white space
character. Push the address and length of the name on the stack and
perform REQUIRED.

INCLUDE ( i*x "name" -- j*x )

Skip leading white space and parse name delimited by a white space
character. Push the address and length of the name on the stack and
perform INCLUDED.

TYPICAL USE

... s" filename" required ...
require filename
include filename

REMARKS

REQUIRED syntax

The syntax follows the good example of INCLUDED in being non-parsing.
That syntax allows more flexible uses and it allows REQUIREing
filenames containing spaces.

INCLUDE

INCLUDE is implemented and used widely, so we might just as well
standardize it (and why not in this RfD). OTOH, once REQUIRE is widely
implemented, it might see much less use. if enough people argue
against its inclusion, I will remove it from this RfD.

REQUIRE

Given what happened with INCLUDED and INCLUDE, we might just as well
provide a parsing variant of REQUIRED right from the start. However,
the essential word is REQUIRED, the parsing variant is just syntactic
sugar.

REQUIRE name

The name is modeled on the relation between INCLUDED and INCLUDE, and
also on Emacs Lisp's require. However, this word has been implemented
under other names: NEEDS in various systems, REQUIRES in PFE and MPE's
systems.

What's worse, some systems have used these names for other purposes:
PFE has a NEEDS with a different meaning, and ciforth has a REQUIRE
with a different meaning (but ciforth's author thinks that ciforth is
not significant and has promised to rename/drop his word if consensus
on using REQUIRE for another purpose is reached
[3]<ielhfd.416@...>).

So, which of the names would you prefer? Please post or mail me your
preferences, and I will collect them and then decide on the final
name, if any. Also, if you know of other conflicts for these names,
please let me know.

Why not use load screens?

Some people prefer to have a single file that contains INCLUDEs for
all the other files in a program. These people do not need REQUIRED.

However, other people want to build programs out of reusable (and
possibly independently developed) libraries, and the load-screen
approach causes increased maintenance work in this context: E.g., if a
new version of a library needs to load an additional sublibrary, the
load screens of all programs using the library would have to be
changed. In contrast, with REQUIRED, the library REQUIREs the
sublibrary itself, and REQUIRED makes sure that it is not loaded
twice.

What about the C approach

Some might say: Why not use the C solution: The C solution to this
problem is putting a wrapper like

#ifndef FILE_H
#define FILE_H
...
#endif

around every source file. This is inefficient (the whole file has to
be read again, unless the compiler does some pretty sophisticated
stuff), and requires cooperation from the author of the file (which is
problematic, because not the author, but the users of the file have
the trouble).

EXPERIENCE

Many systems have REQUIRED, REQUIRE, REQUIRES, and/or NEEDS. Many
systems contain INCLUDE. The occurences of these words in the Gforth
sources are:

occurences regexp
88 "^require "
45 "^include "
4 " included$"
2 " required$"

IMPLEMENTATION AND TESTS

* [4]Reference implementation
* [5]Tests

COMMENTS

from an earlier (Pre-RfD) version of the proposal:

Michael L. Gassanenko:

Yes. I do use NEEDS.

Peter Knaggs:

Perl introduced a version of REQUIRED some time ago that works exactly
in this manner. I agree very much with its usefulness, indeed it
would allow a standard "library" model. Having said that, it can be
defined using standard ANS.

Guido Draheim:

* Both Forth.com's Swiftforth and MPE's ProforthVFX have defined
`requires` as the selfparsing version of `required`, and they use
it. PFE will adopt this in the next version (> 0.30.30)

* The specification is non-deterministic in its stack effect - the
user of `required` has no way to check in advance if a file will get
`included`. Many systems use a word like `loaded?` but it can not as
easily specified for many systems just as it is done for `required`
itself, where the form of `requires` has found wide acceptance. It may
be useful to *allow* the use CSP-like techniques to ensure a
deterministic stack-effect, and it may be useful to *recommend* that
atleast a warning message is shown for the case of stack-depth
differences.

References

1. http://www.complang.tuwien.ac.at/forth/ansforth/rfds.html
2. http://www.complang.tuwien.ac.at/forth/ansforth/proposals.html
3.
http://groups.google.com/group/comp.lang.forth/msg/fbead31cda1c3c4a?dmode=source
4.
http://www.complang.tuwien.ac.at/forth/ansforth/reference-implementations/requir\
ed.fs
5. http://www.complang.tuwien.ac.at/forth/ansforth/tests/required.fs
6. http://www.complang.tuwien.ac.at/anton/

- anton
--
M. Anton Ertl http://www.complang.tuwien.ac.at/anton/home.html
comp.lang.forth FAQs: http://www.complang.tuwien.ac.at/forth/faq/toc.html
New standard: http://www.complang.tuwien.ac.at/forth/ansforth/forth200x.html