# STklos Reference Manual

3. Program structure

Contents
| *Top*
1 | Introduction
2 | Expressions
3 | Program structure
4 | Standard Procedures
5 | Regular Expressions
6 | Pattern Matching
7 | Exceptions and Conditions
8 | STklos Object System
9 | Threads, Mutexes and Condition Variables
10 | Customizations
11 | Using the SLIB package
12 | SRFIs
13 | Index
| Bibliography

R5RS discusses how to structure programs. Everything which is defined in Section 5 of R5RS applies also to STklos. To make things shorter, this aspects will not be described here (see R5RS for complete information).

STklos modules can be used to organize a program into separate environments (or name spaces). Modules provide a clean way to organize and enforce the barriers between the components of a program.

STklos provides a simple module system which is largely inspired from the one of Tung and Dybvig exposed in [14]. As their modules system, STklos modules are defined to be easily used in an interactive environment.

`(define-module <name> <expr1> <expr2> ...)` | STklos syntax

`Define-module` evaluates the expressions `<expr1>`, `<expr2>` ... which constitute the body of the module `<name>` in the environment of that module. `Name` must be a valid symbol. If this symbol has not already been used to define a module, a new module, named `name`, is created. Otherwise, the expressions `<expr1>`, `<expr2>` ... are evaluated in the environment of the (old) module `<name>` 1. Definitions done in a module are local to the module and do not interact with the definitions in other modules. Consider the following definitions,

>     (define-module M1
>        (define a 1))

>     (define-module M2
>       (define a 2)
>       (define b (* 2 x)))

Here, two modules are defined and they both bind the symbol `a` to a value. However, since `a` has been defined in two distinct modules they denote two different locations.
The `STklos` module, which is predefined, is a special module which contains all the global variables of a R5RS program. A symbol defined in the `STklos` module, if not hidden by a local definition, is always visible from inside a module. So, in the previous exemple, the `x` symbol refers the `x` symbol defined in the `STklos` module.
The result of `define-module` is void.

`(current-module)` | STklos procedure

Returns the current module.

>     (define-module M
>       (display
>           (cons (eq? (current-module) (find-module 'M))
>                 (eq? (current-module) (find-module 'STklos)))))
>        -| (#t . #f)

`(find-module name)` | STklos procedure

`(find-module name default)`
STklos modules are first class objects and `find-module` returns the module associated to `name` if it exists. If there is no module associated to `name`, an error is signaled if no `default` is provided, otherwise `find-module` returns `default`.

`(module? object)` | STklos procedure

Returns `#t` if `object` is a module and `#f` otherwise.

>     (module? (find-module 'STklos))  ⇒ #t
>     (module? 'STklos)                ⇒ #f
>     (module? 123 'no)                ⇒ no

`(export <symbol1> <symbol2> ...)` | STklos syntax

Specifies the symbols which are exported (i.e. visible) outside the current module. By default, symbols defined in a module are not visible outside this module, excepted if they appear in an `export` clause.
If several `export` clauses appear in a module, the set of exported symbols is determined by ``unionizing'' symbols exported in all the `export` clauses.
The result of `export` is void.

`(import <module1> <module2> ...)` | STklos syntax

Specifies the modules which are imported by the current module. Importing a module makes the symbols it exports visible to the importer, if not hidden by local definitions. When a symbol is exported by several of the imported modules, the location denoted by this symbol in the importer module correspond to the one of the first module in the list

>     (<module1> <module2> ...)

which exports it.
If several `import` clauses appear in a module, the set of imported modules is determined by appending the various list of modules in their apparition order.

>     (define-module M1
>       (export a b)
>       (define a 'M1-a)
>       (define b 'M1-b))

>     (define-module M2
>       (export b c)
>       (define b 'M2-b)
>       (define c 'M2-c))

>     (define-module M3
>       (import M1 M2)
>       (display (list a b c)))  -| (m1-a m1-b m2-c)

Note: Importations are not transitive: when the module C imports the module B which is an importer of module A the symbols of A are not visible from C, except by explicitly importing the A module from C.
Note: The module `STklos`, which contains the global variables is always implicitly imported from a module. Furthermore, this module is always placed at the end of the list of imported modules.

`(select-module <name>)` | STklos syntax

Changes the value of the current module to the module with the given `name`. The expressions evaluated after `select-module` will take place in module `name` environment. Module `name` must have been created previously by a `define-module`. The result of `select-module` is void. `Select-module` is particularly useful when debugging since it allows to place toplevel evaluation in a particular module. The following transcript shows an usage of `select-module`. 2:

>     stklos> (define foo 1)
>     stklos> (define-module bar
>               (define foo 2))
>     stklos> foo
>     1
>     stklos> (select-module bar)
>     bar> foo
>     2
>     bar> (select-module stklos)
>     stklos>

`(symbol-value symbol module)` | STklos procedure

`(symbol-value symbol module default)`
Returns the value bound to `symbol` in `module`. If `symbol` is not bound, an error is signaled if no `default` is provided, otherwise `symbol-value` returns `default`.

`(symbol-value* symbol module)` | STklos procedure

`(symbol-value* symbol module default)`
Returns the value bound to `symbol` in `module`. If `symbol` is not bound, an error is signaled if no `default` is provided, otherwise `symbol-value` returns `default`.
Note that this function searches the value of `symbol` in `module` and all the modules it imports whereas `symbol-value` searches only in `module`.

`(module-name module)` | STklos procedure

Returns the name (a symbol) associated to a `module`.

`(module-imports module)` | STklos procedure

Returns the list of modules that `module` imports.

`(module-exports module)` | STklos procedure

Returns the list of symbols exported by `module`. Note that this function returns the list of symbols given in the module `export` clause and that some of these symbols can be not yet defined.

`(module-symbols module)` | STklos procedure

Returns the list of symbols already defined in `module`.

`(all-modules)` | STklos procedure

Returns the list of all the living modules.

`(in-module mod s)` | STklos syntax

`(in-module mod s default)`
This form returns the value of symbol with name `s` in the module with name `mod`. If this symbol is not bound, an error is signaled if no `default` is provided, otherwise `in-module` returns `default`. Note that the value of `s` is searched in `mod` and all the modules it imports.
This form is in fact a shortcut. In effect,

>     (in-module my-module foo)

is equivalent to

>     (symbol-value* 'foo (find-module 'my-module))

1: In fact `define-module` on a given name defines a new module only the first time it is invoked on this name. By this way, interactively reloading a module does not define a new entity, and the other modules which use it are not altered.
2: This transcript uses the default toplevel loop which displays the name of the current module in the evaluator prompt.

This Html page has been produced by Skribe.
Last update Tue Dec 19 15:25:36 2006