ModulesA modules is a compiler and interpreter entity. Modules have been first designed for the compiler that compiles modules and then, links them against libraries in order to produce executables. A module may be split into several files but a file cannot contain more than one module. A module is made of a module clause that is a list for which the
caris the symbol
moduleand followed by any Bigloo expression (that is definitions or expressions). The module clause names the module and defines the scope of the definitions. At last, the module clause is also the place where foreign bindings are defined and where classes are defined. Recent versions of Bigloo (since 2.7b) fully supports modules from the interpreter.
Program StructureA Bigloo program is composed of one or more Bigloo modules where a module is defined by the following grammar:
<module> ⇒ <module-declaration> <module-body> <module-declaration> ⇒ the module declaration <module-body> ⇒ the module bodyA module is not related to a specific file and can be spread over several files if that is convenient. In particular, there is no relationship between module names and file names. The module declaration (see Module Declaration) must be the first expression in the first of the files containing the module; other expressions form the body of the module. The module body (see Core Language) contains global variables, function definitions and top level expressions (see Expressions).
Module declarationThe module declaration form is
module name clause ...bigloo syntaxThis 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.outwhich, 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:
.keepModule clauses can be:
main namebigloo module clauseThis 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
fooand invoked using the command foo -t bar, the list which is the argument for the main procedure
("foo" "-t" "bar"). The special form
args-parsehelps main function argument parsing (see Command Line Parsing).
include file-name ...bigloo module clauseThis 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
directivesclause here illustrated with the `bar.sch' example:
;; `bar.sch' ;; the directives (directives (include "foobar.sch") (import hux)) ;; expressions (define (gee x) (print x))
import import ...bigloo module clauseAn 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 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")))
use use ...bigloo module clause
usehas the same meaning as
importexcept that modules which are used are not initialized (see Module Initialization). Used modules are read before imported modules.
with with ...bigloo module clauseThis 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 Embedded Bigloo applications).
export export ...bigloo module clauseIn 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> ⇒ <varexport> | <funexport> | <macroexport> | <classexport> <varexport> ⇒ <ident> <funexport> ⇒ | (<ident> <ident> ...) | (inline <ident> <ident> ...) | (generic <ident> <ident> <ident> ...) <classexport> ⇒ <class> <macroexport> ⇒ (macro <ident> <ident> ...) | (expander <ident>) | (syntax <ident>)Note: Only bindings defined in module
mcan be exported by
m(i.e. bindings imported by
mcannot be exported by
m). The first form of varexport allows the variable ident be exported. Exported variables are mutable. That is, modules importing a variable can change its value. The form funexport exports functions. An exported function is read-only. No module can modify its value. The prototype of exported functions must be explicitly specified. 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
objis used. Note: The last formal argument of a multiple arity function can not be typed because this argument is bound to be a
null. This union cannot be denoted by any type. Inline functions (see Inline Procedures) prototypes are prefixed by the
inlinekeyword. Pay attention that in order to export an inline function, all the variables used in that function body must be exported too. It is an error to export a non-inline function using the
(module mod-exp (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)))Generic functions (see Generic functions) are exported by using the
generickeyword. Note that methods are not exported. Only the generic function they are attached to are. It is an error to export a non-generic function using the
(module mod-exp-object (export ;; define tow classes an export them (class point2d x y) (class point3d::point2d z) ;; export a generic function (generic show ::point2d ::output-port)))It is an error to export an inline or a generic function without using the proper keyword. The last form macroexport enables macro and expanders to be exported. The prototype of the macro should be specified on the export clause. Example:
(module mod-exp-macros (export ;; exports the ``add'' macro (macro add x y) ;; exports the ``+'' expander (expander +))) (define-macro (add x y) (if (and (number? x) (number? y)) (+ x y) `(+ ,x ,y))) (define-expander + (lambda (x e) (match-case x ((+ ?n ?m) (+ n m)) (else (map (lambda (z e) (e z e)) x)))))
static static ...bigloo module clauseA
staticclause 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,
staticmodule clauses are useful only for program documentation.
from from ...bigloo module clause
fromclauses have the syntax of
importclauses. 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
(module bar (export (fun))) (define (fun) "bar")Now, suppose we have a module
bar, by the means of a
foois able to re-export the
barbinding of module
(module foo (from (fun bar "bar.scm")))A third module, let's name it
gee, importing module
foo, can see the binding for function
(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))))
load load ...bigloo module clauseA 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
foois 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)
eval eval...bigloo module clauseThis form allows interactions between compiled code and interpreted code. (See the Section Eval, , 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 the module to eval to so that it can be imported by other evaluated modules; the third exports all the exports (i.e. the ones present inside an
exportclause) 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
exportclause, the compiler will produce an error message. The
libraryclause 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
(with-access::class ...)are also available from the interpreter.
extern extern ...bigloo module clauseExtern (aka foreign) clauses will be explained in the foreign interface (see C Interface).
java java ...bigloo module clauseJava clauses will be explained in the Java interface (see Java Interface).
option option ...bigloo module clauseThis 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
-help2option, 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.
library library ...bigloo module clauseThis clause enables libraries (see 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
(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
libraryclause must be used.
type type ...bigloo module clauseThis forms is used to define builtin Bigloo types. It is not recommended to use it in user programs. So, it is left undocumented.
Module initializationInitializing a module means evaluating, at runtime, its top level forms (global bindings are top level forms). When a module, module1, imports a module, module2, module2 is initialized before module1. Modules are initialized only once, nothing being done if a module already met during initialization is met again. Library modules are initialized before user modules and imported modules are initialized in the same order as they appear in import clauses. Here is a first example with two modules. First the module
;; module foo (module foo (main main) (import (bar "bar.scm"))) (define (main argv) (print "argv: " argv)) (print "foo")Then the module
;; module bar (module bar) (print "bar")These can be compiled into the executable a.out with:
$ bigloo -c foo.scm $ bigloo -c bar.scm $ bigloo foo.o bar.oExecution of a.out produces:
$ a.out ⇥ bar foo argv: (a.out)The explanation is:
foocontains the program entry point so this is where initialization begins.
barmust be initialized before
- module initialization for
foois completed before
main is called. This explains why word
foo. This explains why the word
baris printed before anything else.
foois printed before
;; module1 (module module1 (main main) (import (module2 "module2.scm"))) (define (main argv) (print "argv: " argv)) (print "module1")The second module:
;; module2 (module module2 (import (module3 "module3.scm"))) (print "module2")The third module:
;; module3 (module module3 (import (module1 "module1.scm"))) (print "module3")Compile with:
$ bigloo module1.scm -c $ bigloo module2.scm -c $ bigloo module3.scm -c $ bigloo module1.o module2.o module3.oExecution produces:
$ a.out ⇥ module3 module2 module1 argv: (a.out)The order of module initialization can be explicitly specified using
Qualified notationGlobal variables can be referenced using implicit notation or using qualified notation. Implicit notation is used when variables are referenced just by their name whereas qualified notation is used when variables are referenced by their name and the name of the module which defines them. Qualified notation has the following syntax:
(@ <bind-name> <module-name>)and is useful when several imported modules export a variable with the same name. Using qualified notations instead of short notation only affects compilation. When several variables are defined under the same identifier, the compiler uses the two following rules in order to decide which variable is selected by an implicit reference: 1) the variable defined in a module has a higher precedence than all imported variables, 2) imported variables have a higher precedence than library variables.
Inline proceduresBigloo allows procedures called inline and which differ from normal ones only in the type of code planted. An inline procedure is a first class object which can be manipulated in the same way as any other procedure but when Bigloo sees a reference to one, rather than generating a C function call to the function, the body of the inline procedure is open-coded. The definition of an inline is given in the following way:
define-inline (name args ...) bodybigloo syntax
define-inline (name args ... . arg) bodybigloo syntaxApart from the initial word, this form has the same syntax as that used by
definefor procedures. Inline procedures are exportable which means that the compiler scans imported files to find the bodies of all inline procedures. Here is a small example of a module which exports an inline and a module which imports it.
;; the exporter module (module exporter (export (inline make-list . objs))) (define-inline (make-list . objs) objs)
;; the importer module (module importer (import exporter)) (print (make-list 1 2 3 4 5))Because of the open-coding of the exporter procedure, the above print statement is equivalent to:
(print (let ((objs (list 1 2 3 4 5))) objs))Any procedure can be an inline. Also any exported procedure can be an inline provided all global variables and functions it uses are also exported. Note: Bigloo can decide to inline procedures declared with
definebut this can be achieved only with local procedures whereas procedures declared with the
define-inlineform are open-coded even through module importation. Note: Procedures declared inline are macro expanded with the macro defined in the module where they are invoked. That is, if module
module1declares an inline procedure
pmay have two different macro-expansions: one for
module1and one for
Module access fileBigloo is different from languages such as C where a module is defined by a file. For Bigloo, the module name is not necessarily the name of the file where the text of the module is written and modules can even be split across several files. Since modules are defined independently of files, it is necessary to make a link between a module and its files and there are two ways of doing this. Choosing an import clause where the file-names are specified or creating a ``module access file''. Such a file must contain only one list, each element of the list being of the form:
(module-name "file-name" ... "file-name")Use the -afile <file> option to specify the ``module accessfile'' when compiling. By default Bigloo checks if a file named
.afileexists. If it exists it is loaded as a module access file. The Bigloo command line. Note: The Bigloo distribution contains a tool,
bglafile, that can automatically build a ``module access file''. See the manpage for
Reading pathImported, included or loaded files are sought first in the current directory and then in the directories, sequentially from start to end, of the list in the
*load-path*variable. This variable, initially set to the empty list, can be reset by the -I option of the compiler.