One-time file loading (REQUIRED)

Reference

MAE/6

Author

M. Anton Ertl (anton@mips.complang.tuwien.ac.at)

Problem

A library is needed by several parts of the source code, but it should be loaded only once.

Proposal

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

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

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), the file will be INCLUDED the first time, but not necessarily several times.

Typical Use

s" filename" required

It is advisable to make the stack-effect of interpreting the file (i*x -- i*x), such that the stack-effect is the same, whether the file is INCLUDED or not.

Remarks

The syntax follows the good example of INCLUDED in being non-parsing. A parsing version like NEEDS can be easily defined from it with:

: NEEDS BL WORD COUNT REQUIRED ;

Some might say: Why not use the C solution --- put 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), requires cooperation from the author of the file (which is problematic, because not the author, but the users of the file have the trouble), and is cumbersome to express in standard Forth (there is no direct equivalent to #ifdef).

Experience

Gforth has REQUIRED. Many systems, including F-PC, Gforth, and Win32Forth, have NEEDS, a parsing version of REQUIRED. I use it extensively, and so do others.

Comments

Michael L. Gassanenko:

Yes. I do use NEEDS.

I often invent analogs to #ifdef, namely, if a name is defined, interpret the following line. AFAIK, both F-PC and WIN32FOR have such words, but the only name I can remember is #ifdef / #ifndef (it seems, I myself used this name, because the others were not much meaningful).

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.

---

---