info bigloo

3.2 Module declaration

The module declaration form is

bigloo syntax: module name clause …

This form defines a module and must be the first in the file. The argument name is a symbol naming the module. If the same module name is used more than once, Bigloo signals an error. The runtime library is composed of modules that are read when a user module is compiled and hence, if a user module has the same name as one of the library modules, an error is signaled.

A simple module can be:

(module foo)

(display "this is a module")

The first line here is the complete module definition, the last line is the complete module body and together they form a complete Bigloo program. If these lines were stored in file zz.scm, invoking ‘bigloo zz.scm’ would create the executable a.out which, when obeyed, would display ‘this is a module’ on the terminal.

Note: Some special identifiers are reserved and can’t be used to name modules. If such an identifier is used, the compiler will produce the message:

#(module t
#^
# *** ERROR:bigloo:TOP-LEVEL:Parse error
# Illegal module name -- (MODULE eval ...

The list of reserved identifiers may be enlarged for next release. For the current release that list is made of: eval, foreign and t.

Module clauses can be:

bigloo module clause: main name

This clause defines the entry point for a stand alone application to be procedure name of arity one. Bigloo invokes this procedure at the beginning of execution providing the list, composed of the shell command line arguments, as its single argument.

(module foo
   (main start))

(define (start argv)
   (display argv)
   (newline))

Then if this program is compiled into foo and invoked using the command ‘foo -t bar’, the list which is the argument for the main procedure start would be ("foo" "-t" "bar").

The special form args-parse helps main function argument parsing (see section Command Line Parsing).

bigloo module clause: include file-name …

This is a list of file-names to be included in the source file. Include files are not modules and may have a special syntax. Thus, besides containing Bigloo expressions, they can contain import and include clauses, which must be written in a single list whose first element is the keyword directives. Includes files can be used to include implementation-neutral Scheme expressions and definitions in a Bigloo module. Here is an example of an include file.

;; ‘foo.sch’
(define-struct point x y)

and the module that includes the ‘foo.sch’ file:

;; ‘foo.scm’
(module foo
   (include "foo.sch"))

(print (point 1 2))

Include files, may contain module information. This is the role of the include directives clause here illustrated with the ‘bar.sch’ example:

;; ‘bar.sch’
;; the directives
(directives (include "foobar.sch")
            (import  hux))

;; expressions
(define (gee x) (print x))

bigloo module clause: import import …

An import is a list of the form:

<import>      → <iclause> …
<iclause>     → (<bind-name> … <bind-name> <module-name> <file-name> …)
                | (<bind-name> … <bind-name> <module-name>)
                | <module-name>
                | (<module-name> <file-name> …)
<bind-name>   → <r5rs-ident>
                | <alias-name>
<alias-name>  → (<r5rs-ident> <r5rs-ident>)
<module-name> → <r5rs-ident>
<file-name>   → <string>

The first alternative in iclause imports the variable named bind-name which is defined in the module module-name, located in the files file-name …. The second does the same but without specifying the name of the file where the module is located. The third and the fourth form import all the exported variables of the module module-name.

Note: The need for specifying in which files modules are located comes from the fact that there is no automatic mapping between module names and files names. Such a mapping can be defined in a “module access file” (see section Module access file) or in the import clause itself, as in the first and fourth alternatives in iclause above.

Here is an example of an import clause:

(module foo
   (import 
      ;; import all bar exported bindings:
      bar
      ;; import the hux binding exported by
      ;; the module hux:
      (hux hux)       
      ;; import the fun1, fun2 and fun3 bindings exported by
      ;; the module mod:
      (fun1 fun2 fun3 mod)       
      ;; import the fun4 bindings that will be known in this module
      ;; under the alias name f
      ((f fun4) mod)
      ;; import all gee bindings. the gee module
      ;; is located in a file called ‘gee.scm’:
      (gee "gee.scm")))

bigloo module clause: use use …: use has the same meaning as import except that modules which are used are not initialized (see section Module initialization). Used modules are read before imported modules.

bigloo module clause: with with …: This clause specifies a list of modules which have to be initialized at runtime and is used to force the initialization of modules which are never imported but which are required by an application (see section Embedded Bigloo applications).

bigloo module clause: export export …

In order to make a module’s global bindings available to other modules, they have to be exported. Export clauses are in charge of this task and an export is a list of the form:

<export>  → <eclause> …
<eclause> → <ident>
            | (inline <ident> <ident> …)
            | (generic <ident> <ident> <ident> …)
            | (<ident> <ident> …)
            | <class>
            | (macro <ident> <ident> …)
            | (expander <ident>)
            | (syntax <ident>)

The first form of eclause allows the variable ident be exported, the second allows the function ident, always regarded as immutable when exported this way, to be exported and the third exports an inline-procedure (see section Inline procedures) whose name is extracted from the first ident after the word inline. The last two are both connected with Bigloo’s object system. The generic clause exports generic functions (see section Generic functions) and class clause exports classes (see section Class declaration).

Note: Only bindings defined in module m can be exported by m (i.e. bindings imported by m cannot be exported by m).

Type information, specified in any ident in an export clause, is used by Bigloo. Where no type information is given, a default generic type named obj is used.

Note: The last formal argument of a multiple arity function can not be typed because this argument is bound to be a pair or null. This union cannot be denoted by any type.

Here is an example of the module foo that exports bindings:

(module foo
   (export 
      ;; export the bar mutable variable
      bar
      ;; export the hux function. this
      ;; function takes exactly two arguments
      (hux x y)       
      ;; export the inline function gee
      ;; that takes at least one argument.
      (inline gee x . z)))

bigloo module clause: static static …: A static clause has exactly the same syntax as an export clause. However, bindings declared static are local to the module. Since the default scope of all bindings is static, static module clauses are useful only for program documentation.

bigloo module clause: from from …

from clauses have the syntax of import clauses. The allow the re-exportation of imported bindings. That is, any module can export any bindings imported via a from clause.

As an example, suppose we have module bar:

(module bar
   (export (fun)))

(define (fun) "bar")

Now, suppose we have a module foo that imports bar, by the means of a from clause. Module foo is able to re-export the bar binding of module bar:

(module foo
   (from (fun bar "bar.scm")))

A third module, let’s name it gee, importing module foo, can see the binding for function bar:

(module gee
   (import (foo "foo.scm")))

(print (fun))

This feature is very useful when compiling modules exporting functions with type annotations. In particular, one may write:

(module foo
  (export (class c1 x)))

Then,

(module bar
  (import foo)
  (from foo)
  (export (fun::c1)))

(define (fun)
   (instantiate::c1 (x 10)))

And,

(module gee
   (import bar)
   (main main))

(define (main x)
   (let ((o (fun)))
      (print o)
      (print (c1? o))))

bigloo module clause: load load …

A load is a list of the form:

<load>    → <lclause> …
<lclause> → (<module-name> <file-name>)
            | <module-name>

This clause forces Bigloo to load the module specified in the lclause in the environment used by the macro expansion mechanism. This means that the user’s macros can use all the bindings of all the loaded modules but the loaded bindings remains unknown to the compiler.

If the module foo is defined by:

(module foo
   (export (foo x)))

(define (foo x)
   `(cons ,x ,x))

then,

(module gee
   (load (foo "foo.scm")))

(define-macro (gee x)
   `(cons ,(-fx x 1) ,(foo x)))

(gee 5)   → (cons 4 (cons 5 5))
          ⇒ (4 5 . 5)

bigloo module clause: eval eval…

This form allows interactions between compiled code and interpreted code. (See the Section Eval command line options for a presentation of compilation flags that enable compilation tuning for eval.) Each eval has the following syntax:

<eval> → (export-all)
         | (export-module)
         | (export-exports)
         | (export <bind-name>)
         | (export (@ <bind-name> <module-name>))
         | (import <bind-name>)
         | (class <bind-name>)
         | (library lib1 ...)

The first clause, (export-all), exports all the variables bound in the module (i.e., the variables defined in the module and the imported variables). The second clause, (export-module), exports all the module’s variables (those declared static and exported) to the interpreter; the third exports all the exports (i.e. the ones present inside an export clause) variables to the interpreter; the fourth and fifth clause each export one variable to the interpreter. The last clause imports a variable from the interpreter and all such imported variables are immutable (i.e. they cannot be the first argument of a set! expression with the compiled code). Variables that are exported to the evaluators must be exported. If a variable is exported to the evaluators but not exported within an export clause, the compiler will produce an error message. The library clause makes the variables and functions of a library accessible from the interpreter.

(module foo
   (export (fib x))
   (eval (export fib)
         (import bar)))

(define (fib x) ...)
(print bar)

The clause (class <bind-name>) exports a class definition to the interpreter. This makes the class constructor, the class predicate and the slots access functions available from the interpreter. The form (instantiate::class ...) and (with-access::class ...) are also available from the interpreter.

bigloo module clause: extern extern …: Extern (aka foreign) clauses will be explained in the foreign interface (see section The C interface).

bigloo module clause: java java …: Java clauses will be explained in the Java interface (see section The Java interface).

bigloo module clause: option option …

This clause enables variables which affect compilation to be set from inside a module and since the expressions, option …, are evaluated when compiling, no code is compiled for them. They are allowed to make side effects and to change the values of the global variables which describe how the compiler must compile. Usually they allow the control variables, which are described when Bigloo is invoked with the -help2 option, to be set as in the following example:

(module examplar
   (option (set! *debug* 3)
           (set! *verbose* 2)))

(print 'dummy)

Whatever arguments are passed on the command line, Bigloo will compile this module in both verbose mode and debug mode.

bigloo module clause: library library …

This clause enables libraries (see section Bigloo Libraries) when compiling and linking Bigloo modules. The expressions library … are symbols naming the libraries to be used.

Here is an example of a module declaration which makes use of a library named format:

(module test
   (library format)
   (main    test-format)
   (import  (test2 "test2.scm")))

Using a library does not automatically binds its variables and functions to the interpreter. In order to make these available to the interpreter an explicit use of an eval library clause must be used.

bigloo module clause: type type …: This forms is used to define builtin Bigloo types. It is not recommended to use it in user programs. So, it is left undocumented.

This document was generated on March 31, 2014 using texi2html 5.0.