# Module Words

Modules in zeptoforth are built on top of wordlists, and form a user-friendly means of controlling word namespaces instead of manually manipulating wordlists. Modules and wordlists are one and the same, but by convention they are named with `*`.

At any given time once `src/forth/common/module.fs` is loaded there is a module stack which controls how module words manipulate the wordlist order. Initially there is one entry on the module stack, corresponding to the `forth` wordlist. When new entries are pushed onto the module stack, they save the state of `base` prior to their creation, and restore it once they are popped. Also, module stack entries specify the current wordlist for them, and when module stack entries immediately above them on the stack are popped, their wordlist is restored as the current wordlist.

A new module is defined by `begin-module`; the module named must not exist yet.  An existing module can be extended by `continue-module`; the named module must exist.  Definitions after that point are added to the module, until `end-module` or `end-module>` is seen.

Within a given module, the user may import and unimport modules/wordlists, which pushes them on the wordlist order and removes them from that module's portion of the wordlist's order respectively. Note that all the wordlists imported with a module definition are automatically unimported when that module definition is ended.

Words inside modules or inside nested modules may be used without importing the modules in question with *paths* specified with *module*`::`*word* or, mor generally, *module0*`::`...`::`*modulen*`::`*word*. These paths can be used not simply by the outer interpreter but also by any word which looks up another word by name, such as `'`, `[']`, `postpone`, `averts`, and `triggers`.

Note that it is recommended that once `src/common/forth/module.fs` is loaded, the user should not manually use `set-order` or `set-current`, as the module system will not know about this and thus unexpected results may occur.

### `forth`

The following words are defined in `forth`:

##### `x-already-defined`
( -- )

Module already defined exception.

##### `x-not-found`
( -- )

Module not found exception.

##### `begin-module`
( "name" -- )

Begin the definition of module *name*; module *name* must not already exist or `x-already-defined` will be raised.

##### `continue-module`
( "name" -- )

Continue the definition of a preexisting module *name*; if module *name* does not exist `x-not-found` will be raised.

##### `private-module`
( -- )

Begin the definition of a private module, i.e a module not bound to a word.

##### `end-module`
( -- )

End the definition of the module at the top of the module stack, removing each wordlist for each module imported within it from the wordlist order.

##### `end-module>`
( --  module )

End the definition of the module at the top of the module stack, removing each wordlist for each module imported within it from th e wordlist order, and then push the module whose definition had ended onto the data stack.

##### `import`
( module -- )

Import a specified module into the current module's wordlist order; if the module does not exist `x-not-found` is raised.

##### `import-from`
( module "name" -- )

Import a specified named word from within the specified module into the current namespace; note that this word will not shadow identically named words defined in the current namespace, and will persist until the end of the current module's definition.

##### `begin-imports-from`
( module "name0" ... "namen" "end-imports-from" -- )

Import multiple specified named words from within the specified module into the current namespace; note that these words will not shadow identically named words defined in the current namespace, and will persist untilt he end of the current module's definition. Note that these imports can cross multiple lines of input, as in:

```
begin-module foobar
  : foo ." FOO " ;
  : bar ." BAR " ;
  : baz ." BAZ " ;
end-module

foobar begin-imports-from
  foo bar
end-imports-from
```

##### `unimport`
( module -- )

Remove a specified module from the current module's wordlist order; note that it does not remove it from parent modules' wordlist orders, so if it  had been imported within them they are still searchable.

##### `export`
( xt "word-name" -- )

Export *xt* from the module currently being defined as *word-name*.