This is NO page from the dpans'94 document.
It is an experimental draft for public review, here at FORTH.SF.NET

RFC
2002

TOC

19. The optional Environment word set

See: A.19 The optional Environment word set

19.1 Introduction

19.2 Additional terms and notation

environment hints:: The value returned by environment queries without the flag for its existance.
environment word list:: The word list into which new environment hints are placed.
environment library sources:: Forth source files installed by the system to provide implementations not present in the initial system.
environment library path:: A character string that serves as prefix for filenames and filepaths used to adress a library of forth source files. The format of the library path prefix is implementation defined, as is the filename from 11.3.1.4

See: A.19.2 Additional terms

19.3 Additional usage requirements

19.3.1 Basis

The environment wordlist is an implementation form for environment querys as given in table 3.5 using standard data types for the environment hints. It inherits the restrictions on definition name and creation and lookup of them.

See: 3.1 Data types, 3.4.2 Finding definition names, 3.4 The Forth text interpreter.

19.3.2 Environmental queries

Append table 19.2 to table 3.5.

See: 3.2.6 Environmental queries

Table 19.2 - Environmental query strings

String            Value data type  Constant?  Meaning
------            ---------------  ---------  -------
ENVIRONMENT-EXT   flag             no         environment extensions word set present

19.3.3 Finding environment sources

When searching an environment source file the system shall be able to modify the source file name by prefixing it with the environment library path. The system may also look into multiple such library path prefixes. The number of prefixes and their length is implementation dependent. Atleast one environment library path must be defined. If it can be modified then it must be atleast 80 chars long.

Changing the environment shall only affect the subsequent finding of environment hints and answers to environment queries.

A program that requires a modifiable library path has an environmental dependency.

See: 3.4.2 Finding definition names, A.19.3.3 Finding definition names.

19.4 Additional documentation requirements

19.4.1 System documentation

19.4.1.1 Implementation-defined options

the initial environment library path prefix.
whether environment queries can trigger loading of an environment library source file.
whether the stack effect of environment source includes triggers additional behaviour.

19.4.1.2 Ambiguous conditions

whether filenames without the environment library path prefix can be accounted as library path sources for environment loading.
whether the check for multiple includes by REQUIRED can react to executions of INCLUDED.

19.4.1.3 Other system documentation

no additional requirements.

19.4.2 Program documentation

19.4.2.1 Environmental dependencies

no additional dependencies.

19.4.2.2 Other program documentation

no additional requirements.

19.5 Compliance and labeling

19.5.1 STD Forth systems

The phrase Providing the Environment word set shall be appended to the label of any Standard System that provides all of the Environment word set.

The phrase Providing name(s) from the Environment Extensions word set shall be appended to the label of any Standard System that provides portions of the Environment Extensions word set.

The phrase Providing the Environment Extensions word set shall be appended to the label of any Standard System that provides all of the Environment and Environment Extensions word sets.

19.5.2 STD Forth programs

The phrase Requiring the Environment word set shall be appended to the label of Standard Programs that require the system to provide the Environment word set.

The phrase Requiring name(s) from the Environment Extensions word set shall be appended to the label of Standard Programs that require the system to provide portions of the Environment Extensions word set.

The phrase Requiring the Environment Extensions word set shall be appended to the label of Standard Programs that require the system to provide all of the Environment and Environment Extensions word sets.

19.6 Glossary

19.6.1 Environment words


19.6.1.1345 ENVIRONMENT?

ENVIRON

        ( c-addr u -- false | i*x true )

Extend the semantics of ENVIRONMENT? to search the ENVIRONMENT-WORDLIST for hints. When the call to SEARCH-WORDLIST finds an environment hint then the EXECUTE of the returned execution token will push parameters on the stack, and a TRUE flag is added, otherwise return just a FALSE flag.

See: 3.4.2 Finding definition names, A.19.3 ENVIRONMENT? implementation .6.1.1345 CORE ENVIRONMENT?


19.6.1.1595 ENVIRONMENT-WORDLIST

ENVIRON

        ( -- wid )

Return wid, the identifier of the word list that includes all environment hints provided by the implementation. This word list is never part of the initial search-order.

See: 19.6.2.1590 ENVIRONMENT 19.6.1.1345 ENVIRONMENT? A.19.3 ENVIRONMENT? implementation 16.6.1.1595 FORTH-WORDLIST


19.6.1.1718 REQUIRED

ENVIRON

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

The execution of INCLUDED is prepended with semantics to load environment library sources from the filepath that is formed by the argument prepended with the environment library path. Furthermore it must be assured that for multiple invokations of REQUIRED with the same filepath only the first is forwarded to INCLUDED while other calls do nothing.

It is an implementation defined option whether multiple environment path prefixes are tested for source files, including the option to check for a source file without the environment path prefix.

It is an implementation defined option whether the check for multiple includes by REQUIRED can react to indepent executions of INCLUDED.

Apart from the ambigous conditions set by INCLUDED there is an additional implementation defined behaviour when the call to INCLUDED would modify the parameter stack - which may even include changes in stack depth. An implementation shall check the stack depth and throw a exception which the self-parsing variant REQUIRES can catch - an implementation calling REQUIRED within a CATCH domain will see the stack depth difference at the exit of the CATCH - so it must be prepared to handle a stack effect of ( i*x c-addr u -- j*x ) .

An implementation without exceptions shall print a warning message that otherwise REQUIRES would emit or any other word that will CATCH the exception thrown.

See: 19.6.2.1718 REQUIRES 11.6.1.1718 INCLUDED 9.6.1.0875 CATCH 9.6.1.2275 THROW


19.6.1.1550 [DEFINED]

ENVIRON

        Compilation: Perform the execution semantics given below.

        Execution: ( "name" -- flag )

Skip leading space delimiters. Parse name delimited by a space. Try to find name returning true if it can be found as for ['], otherwise return a false flag. The flag is intended to be consumed by [IF].

See: the inverse of [UNDEFINED].


19.6.1.1549 [UNDEFINED]

ENVIRON

        Compilation: Perform the execution semantics given below.

        Execution: ( "name" -- flag )

Skip leading space delimiters. Parse name delimited by a space. Try to find name returning false if it can be found as for ['], otherwise return a true flag. The flag is intended to be consumed by [IF].

See: the inverse of [DEFINED].

19.6.2 Environment extension words


19.6.2.1590 ENVIRONMENT

ENVIRON EXT

        ( -- )

Transform the environment consisting of widn, ... wid2, wid1 (where wid1 is searched first) into widn, ... wid2, wid ENVIRONMENT-WORDLIST.

See: 19.6.2.1595 ENVIRONMENT-WORDLIST 19.6.1.1345 ENVIRONMENT? A.19.3 ENVIRONMENT? implementation 16.6.2.1590 FORTH


19.6.2.1718 REQUIRES

ENVIRON EXT

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

Skip leading space delimiters. Parse name delimited by a space. Submit the string to REQUIRED

If the underlying REQUIRED call did detect a stack depth change from including a source file, this word must catch the corresponding exception and it may print a warning on doing so.

within a system that does not support exceptions, the warning message on a stack change should have been printed by REQUIRED itself. Consequently in this case, this word is simply the self-parsing variant of the underlying REQUIRED.

In both cases, this word REQUIRES is responsible to ensure that a stack depth change does not cause an exception to be handled by the caller of this word. It may consequently leave the stack depth change visible to the caller of this word, so the caller of REQUIRES can not assume to access parameters pushed on the parameter stack before this call, and consequently this word is not supposed to be run in compilation mode (though it may get compiled).

See: 19.6.1.1718 REQUIRED 11.6.1.1718 INCLUDED 9.6.1.0875 CATCH R.11.6.1.1718 INCLUDE ,


19.6.2.1485 [VOID]

ENVIRON EXT

        Compilation: Perform the execution semantics given below.

        Execution: ( -- false )

Place a false flag to be consumed by [IF].

An ambiguous condition exists if [VOID] is POSTPONEd

See: 6.2.1485 FALSE 15.6.2.2532 [IF] 19.6.1.1550 [DEFINED]

Table of Contents

Next Section