pfe-environ-ext
Prev? | pfe Forth Wordset List | ?Next

## Name

pfe-environ-ext ? Environment related definitions

## Synopsis

`ENVIRONMENT? ( name-ptr name-len -- 0 | ?? name-flag! ) ?=>? (` | `)`; | ?

`[FORTH]`;
?

`REQUIRED ( ... str-ptr str-len -- ??? ) ?=>? (` | `)`; | ?

`[FORTH]`;
?

`REQUIRE ( ... "file-name" -- ... ) ?=>? (` | `)`; | ?

`[FORTH]`;
?

`NEEDS ( name -- ) ?=>? (` | `)`; | ?

`[FORTH]`;
?

## Description

ENVIRONMENT? ( name-ptr name-len -- 0 | ?? name-flag! ) [ANS] => [FORTH]

check the environment for a property, usually a condition like questioning the existance of specified wordset, but it can also return some implementation properties like "WORDLISTS" (the length of the search-order) or "#LOCALS" (the maximum number of locals)

Here it implements the environment queries as a `SEARCH-WORDLIST` in a user-visible vocabulary called `ENVIRONMENT`

      : ENVIRONMENT?
        ['] ENVIRONMENT &gt;WORDLIST SEARCH-WORDLIST
        IF  EXECUTE TRUE ELSE  FALSE THEN ;

REQUIRED ( ... str-ptr str-len -- ??? ) => [FORTH]

the filename argument is loaded via `INCLUDED` as an extension package to the current system. The filename is registered in the current `ENVIRONMENT` so that it is only `INCLUDED` once (!!) if called multiple times via `REQUIRED` or `REQUIRES`

REQUIRE ( ... "file-name" -- ... ) => [FORTH]

parses the next `WORD` and passes it to `REQUIRED` this is the self-parsing version of `REQUIRED` and it does parrallel `INCLUDE` w.r.t. `INCLUDED`

NEEDS ( name -- ) => [FORTH]

A self-parsing variant of an environment-query check. It is similar to a simulation like

      : NEEDS PARSE-WORD 2DUP ENVIRONMENT?
        IF DROP ( extra value ) 2DROP ( success - be silent )
        ELSE TYPE ." not available " CR THEN ;

however that would only match those worset-envqueries which return a single extra item under the uppermost TRUE flag in the success case. Instead it works more like

      : NEEDS PARSE-WORD 2DUP ENVIRONMENT-WORDLIST SEARCH-WORDLIST
        IF 2DROP ( success - be silent and just drop the parsed word )
        ELSE TYPE ." not available " CR THEN ;

however we add the same extension as in `ENVIRONMENT`? as that it can automatically load a wordset module to fullfil a query that looks like "[wordsetname]-ext". Therefore, the following two lines are pretty much identical:

      LOADM floating
      NEEDS floating-ext

the difference between the two: if somebody did provide a forth level implementation of floating-ext then that implementation might have registered a hint "floating-ext" in the environment-wordlist. This extra-hint will inhibit loading of the binary module even if it exists and not been loaded so far. The `LOADM` however will not check the `ENVIRONMENT-WORDLIST` and only check its loadlist of binary wordset modules in the system.

It is therefore recommended to use `NEEDS` instead of `LOADM` unless you know you want the binary module, quickly and uncondtionally.

Prev? | Up | ?Next
pfe-forth-ext? | Home | ?pfe-exception-ext