2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010, 2011, 2012, 2013
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
11 When programs become large, naming conflicts can occur when a function
12 or global variable defined in one file has the same name as a function
13 or global variable in another file. Even just a @emph{similarity}
14 between function names can cause hard-to-find bugs, since a programmer
15 might type the wrong function name.
17 The approach used to tackle this problem is called @emph{information
18 encapsulation}, which consists of packaging functional units into a
19 given name space that is clearly separated from other name spaces.
21 @cindex information encapsulation
24 The language features that allow this are usually called @emph{the
25 module system} because programs are broken up into modules that are
26 compiled separately (or loaded separately in an interpreter).
28 Older languages, like C, have limited support for name space
29 manipulation and protection. In C a variable or function is public by
30 default, and can be made local to a module with the @code{static}
31 keyword. But you cannot reference public variables and functions from
32 another module with different names.
34 More advanced module systems have become a common feature in recently
35 designed languages: ML, Python, Perl, and Modula 3 all allow the
36 @emph{renaming} of objects from a foreign module, so they will not
37 clutter the global name space.
38 @cindex name space - private
40 In addition, Guile offers variables as first-class objects. They can
41 be used for interacting with the module system.
44 * General Information about Modules:: Guile module basics.
45 * Using Guile Modules:: How to use existing modules.
46 * Creating Guile Modules:: How to package your code into modules.
47 * Modules and the File System:: Installing modules in the file system.
48 * R6RS Version References:: Using version numbers with modules.
49 * R6RS Libraries:: The library and import forms.
50 * Variables:: First-class variables.
51 * Module System Reflection:: First-class modules.
52 * Accessing Modules from C:: How to work with modules with C code.
53 * provide and require:: The SLIB feature mechanism.
54 * Environments:: R5RS top-level environments.
57 @node General Information about Modules
58 @subsection General Information about Modules
60 A Guile module can be thought of as a collection of named procedures,
61 variables and macros. More precisely, it is a set of @dfn{bindings}
62 of symbols (names) to Scheme objects.
64 Within a module, all bindings are visible. Certain bindings
65 can be declared @dfn{public}, in which case they are added to the
66 module's so-called @dfn{export list}; this set of public bindings is
67 called the module's @dfn{public interface} (@pxref{Creating Guile
70 A client module @dfn{uses} a providing module's bindings by either
71 accessing the providing module's public interface, or by building a
72 custom interface (and then accessing that). In a custom interface, the
73 client module can @dfn{select} which bindings to access and can also
74 algorithmically @dfn{rename} bindings. In contrast, when using the
75 providing module's public interface, the entire export list is available
76 without renaming (@pxref{Using Guile Modules}).
78 All Guile modules have a unique @dfn{module name}, for example
79 @code{(ice-9 popen)} or @code{(srfi srfi-11)}. Module names are lists
80 of one or more symbols.
82 When Guile goes to use an interface from a module, for example
83 @code{(ice-9 popen)}, Guile first looks to see if it has loaded
84 @code{(ice-9 popen)} for any reason. If the module has not been loaded
85 yet, Guile searches a @dfn{load path} for a file that might define it,
88 The following subsections go into more detail on using, creating,
89 installing, and otherwise manipulating modules and the module system.
91 @node Using Guile Modules
92 @subsection Using Guile Modules
94 To use a Guile module is to access either its public interface or a
95 custom interface (@pxref{General Information about Modules}). Both
96 types of access are handled by the syntactic form @code{use-modules},
97 which accepts one or more interface specifications and, upon evaluation,
98 arranges for those interfaces to be available to the current module.
99 This process may include locating and loading code for a given module if
100 that code has not yet been loaded, following @code{%load-path}
101 (@pxref{Modules and the File System}).
103 An @dfn{interface specification} has one of two forms. The first
104 variation is simply to name the module, in which case its public
105 interface is the one accessed. For example:
108 (use-modules (ice-9 popen))
111 Here, the interface specification is @code{(ice-9 popen)}, and the
112 result is that the current module now has access to @code{open-pipe},
113 @code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Pipes}).
115 Note in the previous example that if the current module had already
116 defined @code{open-pipe}, that definition would be overwritten by the
117 definition in @code{(ice-9 popen)}. For this reason (and others), there
118 is a second variation of interface specification that not only names a
119 module to be accessed, but also selects bindings from it and renames
120 them to suit the current module's needs. For example:
122 @cindex binding renamer
124 (use-modules ((ice-9 popen)
125 #:select ((open-pipe . pipe-open) close-pipe)
126 #:renamer (symbol-prefix-proc 'unixy:)))
129 Here, the interface specification is more complex than before, and the
130 result is that a custom interface with only two bindings is created and
131 subsequently accessed by the current module. The mapping of old to new
134 @c Use `smallexample' since `table' is ugly. --ttn
136 (ice-9 popen) sees: current module sees:
137 open-pipe unixy:pipe-open
138 close-pipe unixy:close-pipe
141 This example also shows how to use the convenience procedure
142 @code{symbol-prefix-proc}.
144 You can also directly refer to bindings in a module by using the
145 @code{@@} syntax. For example, instead of using the
146 @code{use-modules} statement from above and writing
147 @code{unixy:pipe-open} to refer to the @code{pipe-open} from the
148 @code{(ice-9 popen)}, you could also write @code{(@@ (ice-9 popen)
149 open-pipe)}. Thus an alternative to the complete @code{use-modules}
153 (define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
154 (define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
157 There is also @code{@@@@}, which can be used like @code{@@}, but does
158 not check whether the variable that is being accessed is actually
159 exported. Thus, @code{@@@@} can be thought of as the impolite version
160 of @code{@@} and should only be used as a last resort or for
161 debugging, for example.
163 Note that just as with a @code{use-modules} statement, any module that
164 has not yet been loaded yet will be loaded when referenced by a
165 @code{@@} or @code{@@@@} form.
167 You can also use the @code{@@} and @code{@@@@} syntaxes as the target
168 of a @code{set!} when the binding refers to a variable.
170 @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
171 Return a procedure that prefixes its arg (a symbol) with
175 @deffn syntax use-modules spec @dots{}
176 Resolve each interface specification @var{spec} into an interface and
177 arrange for these to be accessible by the current module. The return
178 value is unspecified.
180 @var{spec} can be a list of symbols, in which case it names a module
181 whose public interface is found and used.
183 @var{spec} can also be of the form:
185 @cindex binding renamer
187 (MODULE-NAME [#:select SELECTION] [#:renamer RENAMER])
190 in which case a custom interface is newly created and used.
191 @var{module-name} is a list of symbols, as above; @var{selection} is a
192 list of selection-specs; and @var{renamer} is a procedure that takes a
193 symbol and returns its new name. A selection-spec is either a symbol or
194 a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
195 the used module and @var{seen} is the name in the using module. Note
196 that @var{seen} is also passed through @var{renamer}.
198 The @code{#:select} and @code{#:renamer} clauses are optional. If both are
199 omitted, the returned interface has no bindings. If the @code{#:select}
200 clause is omitted, @var{renamer} operates on the used module's public
203 In addition to the above, @var{spec} can also include a @code{#:version}
207 #:version VERSION-SPEC
210 where @var{version-spec} is an R6RS-compatible version reference. An
211 error will be signaled in the case in which a module with the same name
212 has already been loaded, if that module specifies a version and that
213 version is not compatible with @var{version-spec}. @xref{R6RS Version
214 References}, for more on version references.
216 If the module name is not resolvable, @code{use-modules} will signal an
220 @deffn syntax @@ module-name binding-name
221 Refer to the binding named @var{binding-name} in module
222 @var{module-name}. The binding must have been exported by the module.
225 @deffn syntax @@@@ module-name binding-name
226 Refer to the binding named @var{binding-name} in module
227 @var{module-name}. The binding must not have been exported by the
228 module. This syntax is only intended for debugging purposes or as a
232 @node Creating Guile Modules
233 @subsection Creating Guile Modules
235 When you want to create your own modules, you have to take the following
240 Create a Scheme source file and add all variables and procedures you wish
241 to export, or which are required by the exported procedures.
244 Add a @code{define-module} form at the beginning.
247 Export all bindings which should be in the public interface, either
248 by using @code{define-public} or @code{export} (both documented below).
251 @deffn syntax define-module module-name option @dots{}
252 @var{module-name} is a list of one or more symbols.
255 (define-module (ice-9 popen))
258 @code{define-module} makes this module available to Guile programs under
259 the given @var{module-name}.
261 @var{option} @dots{} are keyword/value pairs which specify more about the
262 defined module. The recognized options and their meaning are shown in
266 @item #:use-module @var{interface-specification}
267 Equivalent to a @code{(use-modules @var{interface-specification})}
268 (@pxref{Using Guile Modules}).
270 @item #:autoload @var{module} @var{symbol-list}
272 Load @var{module} when any of @var{symbol-list} are accessed. For
276 (define-module (my mod)
277 #:autoload (srfi srfi-1) (partition delete-duplicates))
280 (set! foo (delete-duplicates ...)))
283 When a module is autoloaded, all its bindings become available.
284 @var{symbol-list} is just those that will first trigger the load.
286 An autoload is a good way to put off loading a big module until it's
287 really needed, for instance for faster startup or if it will only be
288 needed in certain circumstances.
290 @code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in
291 that case an @code{@@} form must be written every time a binding from
294 @item #:export @var{list}
296 Export all identifiers in @var{list} which must be a list of symbols
297 or pairs of symbols. This is equivalent to @code{(export @var{list})}
300 @item #:re-export @var{list}
302 Re-export all identifiers in @var{list} which must be a list of
303 symbols or pairs of symbols. The symbols in @var{list} must be
304 imported by the current module from other modules. This is equivalent
305 to @code{re-export} below.
307 @item #:replace @var{list}
309 @cindex replacing binding
310 @cindex overriding binding
311 @cindex duplicate binding
312 Export all identifiers in @var{list} (a list of symbols or pairs of
313 symbols) and mark them as @dfn{replacing bindings}. In the module
314 user's name space, this will have the effect of replacing any binding
315 with the same name that is not also ``replacing''. Normally a
316 replacement results in an ``override'' warning message,
317 @code{#:replace} avoids that.
319 In general, a module that exports a binding for which the @code{(guile)}
320 module already has a definition should use @code{#:replace} instead of
321 @code{#:export}. @code{#:replace}, in a sense, lets Guile know that the
322 module @emph{purposefully} replaces a core binding. It is important to
323 note, however, that this binding replacement is confined to the name
324 space of the module user. In other words, the value of the core binding
325 in question remains unchanged for other modules.
327 Note that although it is often a good idea for the replaced binding to
328 remain compatible with a binding in @code{(guile)}, to avoid surprising
329 the user, sometimes the bindings will be incompatible. For example,
330 SRFI-19 exports its own version of @code{current-time} (@pxref{SRFI-19
331 Time}) which is not compatible with the core @code{current-time}
332 function (@pxref{Time}). Guile assumes that a user importing a module
333 knows what she is doing, and uses @code{#:replace} for this binding
334 rather than @code{#:export}.
336 A @code{#:replace} clause is equivalent to @code{(export! @var{list})}
339 The @code{#:duplicates} (see below) provides fine-grain control about
340 duplicate binding handling on the module-user side.
342 @item #:version @var{list}
343 @cindex module version
344 Specify a version for the module in the form of @var{list}, a list of
345 zero or more exact, nonnegative integers. The corresponding
346 @code{#:version} option in the @code{use-modules} form allows callers
347 to restrict the value of this option in various ways.
349 @item #:duplicates @var{list}
350 @cindex duplicate binding handlers
351 @cindex duplicate binding
352 @cindex overriding binding
353 Tell Guile to handle duplicate bindings for the bindings imported by
354 the current module according to the policy defined by @var{list}, a
355 list of symbols. @var{list} must contain symbols representing a
356 duplicate binding handling policy chosen among the following:
360 Raises an error when a binding is imported from more than one place.
362 Issue a warning when a binding is imported from more than one place
363 and leave the responsibility of actually handling the duplication to
364 the next duplicate binding handler.
366 When a new binding is imported that has the same name as a previously
367 imported binding, then do the following:
371 @cindex replacing binding
372 If the old binding was said to be @dfn{replacing} (via the
373 @code{#:replace} option above) and the new binding is not replacing,
374 the keep the old binding.
376 If the old binding was not said to be replacing and the new binding is
377 replacing, then replace the old binding with the new one.
379 If neither the old nor the new binding is replacing, then keep the old
383 @item warn-override-core
384 Issue a warning when a core binding is being overwritten and actually
385 override the core binding with the new one.
387 In case of duplicate bindings, the firstly imported binding is always
388 the one which is kept.
390 In case of duplicate bindings, the lastly imported binding is always
391 the one which is kept.
393 In case of duplicate bindings, leave the responsibility to the next
397 If @var{list} contains more than one symbol, then the duplicate
398 binding handlers which appear first will be used first when resolving
399 a duplicate binding situation. As mentioned above, some resolution
400 policies may explicitly leave the responsibility of handling the
401 duplication to the next handler in @var{list}.
403 If GOOPS has been loaded before the @code{#:duplicates} clause is
404 processed, there are additional strategies available for dealing with
405 generic functions. @xref{Merging Generics}, for more information.
407 @findex default-duplicate-binding-handler
408 The default duplicate binding resolution policy is given by the
409 @code{default-duplicate-binding-handler} procedure, and is
412 (replace warn-override-core warn last)
417 Create a @dfn{pure} module, that is a module which does not contain any
418 of the standard procedure bindings except for the syntax forms. This is
419 useful if you want to create @dfn{safe} modules, that is modules which
420 do not know anything about dangerous procedures.
425 @deffn syntax export variable @dots{}
426 Add all @var{variable}s (which must be symbols or pairs of symbols) to
427 the list of exported bindings of the current module. If @var{variable}
428 is a pair, its @code{car} gives the name of the variable as seen by the
429 current module and its @code{cdr} specifies a name for the binding in
430 the current module's public interface.
433 @deffn syntax define-public @dots{}
434 Equivalent to @code{(begin (define foo ...) (export foo))}.
437 @deffn syntax re-export variable @dots{}
438 Add all @var{variable}s (which must be symbols or pairs of symbols) to
439 the list of re-exported bindings of the current module. Pairs of
440 symbols are handled as in @code{export}. Re-exported bindings must be
441 imported by the current module from some other module.
444 @deffn syntax export! variable @dots{}
445 Like @code{export}, but marking the exported variables as replacing.
446 Using a module with replacing bindings will cause any existing bindings
447 to be replaced without issuing any warnings. See the discussion of
448 @code{#:replace} above.
451 @node Modules and the File System
452 @subsection Modules and the File System
454 Typical programs only use a small subset of modules installed on a Guile
455 system. In order to keep startup time down, Guile only loads modules
456 when a program uses them, on demand.
458 When a program evaluates @code{(use-modules (ice-9 popen))}, and the
459 module is not loaded, Guile searches for a conventionally-named file
460 from in the @dfn{load path}.
462 In this case, loading @code{(ice-9 popen)} will eventually cause Guile
463 to run @code{(primitive-load-path "ice-9/popen")}.
464 @code{primitive-load-path} will search for a file @file{ice-9/popen} in
465 the @code{%load-path} (@pxref{Load Paths}). For each directory in
466 @code{%load-path}, Guile will try to find the file name, concatenated
467 with the extensions from @code{%load-extensions}. By default, this will
468 cause Guile to @code{stat} @file{ice-9/popen.scm}, and then
469 @file{ice-9/popen}. @xref{Load Paths}, for more on
470 @code{primitive-load-path}.
472 If a corresponding compiled @file{.go} file is found in the
473 @code{%load-compiled-path} or in the fallback path, and is as fresh as
474 the source file, it will be loaded instead of the source file. If no
475 compiled file is found, Guile may try to compile the source file and
476 cache away the resulting @file{.go} file. @xref{Compilation}, for more
479 Once Guile finds a suitable source or compiled file is found, the file
480 will be loaded. If, after loading the file, the module under
481 consideration is still not defined, Guile will signal an error.
483 For more information on where and how to install Scheme modules,
484 @xref{Installing Site Packages}.
487 @node R6RS Version References
488 @subsection R6RS Version References
490 Guile's module system includes support for locating modules based on
491 a declared version specifier of the same form as the one described in
492 R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6
493 Report on the Algorithmic Language Scheme}). By using the
494 @code{#:version} keyword in a @code{define-module} form, a module may
495 specify a version as a list of zero or more exact, nonnegative integers.
497 This version can then be used to locate the module during the module
498 search process. Client modules and callers of the @code{use-modules}
499 function may specify constraints on the versions of target modules by
500 providing a @dfn{version reference}, which has one of the following
504 (@var{sub-version-reference} ...)
505 (and @var{version-reference} ...)
506 (or @var{version-reference} ...)
507 (not @var{version-reference})
510 in which @var{sub-version-reference} is in turn one of:
514 (>= @var{sub-version})
515 (<= @var{sub-version})
516 (and @var{sub-version-reference} ...)
517 (or @var{sub-version-reference} ...)
518 (not @var{sub-version-reference})
521 in which @var{sub-version} is an exact, nonnegative integer as above. A
522 version reference matches a declared module version if each element of
523 the version reference matches a corresponding element of the module
524 version, according to the following rules:
528 The @code{and} sub-form matches a version or version element if every
529 element in the tail of the sub-form matches the specified version or
533 The @code{or} sub-form matches a version or version element if any
534 element in the tail of the sub-form matches the specified version or
538 The @code{not} sub-form matches a version or version element if the tail
539 of the sub-form does not match the version or version element.
542 The @code{>=} sub-form matches a version element if the element is
543 greater than or equal to the @var{sub-version} in the tail of the
547 The @code{<=} sub-form matches a version element if the version is less
548 than or equal to the @var{sub-version} in the tail of the sub-form.
551 A @var{sub-version} matches a version element if one is @var{eqv?} to
555 For example, a module declared as:
558 (define-module (mylib mymodule) #:version (1 2 0))
561 would be successfully loaded by any of the following @code{use-modules}
565 (use-modules ((mylib mymodule) #:version (1 2 (>= 0))))
566 (use-modules ((mylib mymodule) #:version (or (1 2 0) (1 2 1))))
567 (use-modules ((mylib mymodule) #:version ((and (>= 1) (not 2)) 2 0)))
572 @subsection R6RS Libraries
574 In addition to the API described in the previous sections, you also
575 have the option to create modules using the portable @code{library} form
576 described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The
577 Revised^6 Report on the Algorithmic Language Scheme}), and to import
578 libraries created in this format by other programmers. Guile's R6RS
579 library implementation takes advantage of the flexibility built into the
580 module system by expanding the R6RS library form into a corresponding
581 Guile @code{define-module} form that specifies equivalent import and
582 export requirements and includes the same body expressions. The library
586 (library (mylib (1 2))
587 (import (otherlib (3)))
591 is equivalent to the module definition:
594 (define-module (mylib)
596 #:use-module ((otherlib) #:version (3))
597 #:export (mybinding))
600 Central to the mechanics of R6RS libraries is the concept of import
601 and export @dfn{levels}, which control the visibility of bindings at
602 various phases of a library's lifecycle --- macros necessary to
603 expand forms in the library's body need to be available at expand
604 time; variables used in the body of a procedure exported by the
605 library must be available at runtime. R6RS specifies the optional
606 @code{for} sub-form of an @emph{import set} specification (see below)
607 as a mechanism by which a library author can indicate that a
608 particular library import should take place at a particular phase
609 with respect to the lifecycle of the importing library.
611 Guile's library implementation uses a technique called
612 @dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R.
613 Kent Dybvig), which allows the expander and compiler to automatically
614 determine the necessary visibility of a binding imported from another
615 library. As such, the @code{for} sub-form described below is ignored by
616 Guile (but may be required by Schemes in which phasing is explicit).
618 @deffn {Scheme Syntax} library name (export export-spec ...) (import import-spec ...) body ...
619 Defines a new library with the specified name, exports, and imports,
620 and evaluates the specified body expressions in this library's
623 The library @var{name} is a non-empty list of identifiers, optionally
624 ending with a version specification of the form described above
625 (@pxref{Creating Guile Modules}).
627 Each @var{export-spec} is the name of a variable defined or imported
628 by the library, or must take the form
629 @code{(rename (internal-name external-name) ...)}, where the
630 identifier @var{internal-name} names a variable defined or imported
631 by the library and @var{external-name} is the name by which the
632 variable is seen by importing libraries.
634 Each @var{import-spec} must be either an @dfn{import set} (see below)
635 or must be of the form @code{(for import-set import-level ...)},
636 where each @var{import-level} is one of:
644 where @var{level} is an integer. Note that since Guile does not
645 require explicit phase specification, any @var{import-set}s found
646 inside of @code{for} sub-forms will be ``unwrapped'' during
647 expansion and processed as if they had been specified directly.
649 Import sets in turn take one of the following forms:
652 @var{library-reference}
653 (library @var{library-reference})
654 (only @var{import-set} @var{identifier} ...)
655 (except @var{import-set} @var{identifier} ...)
656 (prefix @var{import-set} @var{identifier})
657 (rename @var{import-set} (@var{internal-identifier} @var{external-identifier}) ...)
660 where @var{library-reference} is a non-empty list of identifiers
661 ending with an optional version reference (@pxref{R6RS Version
662 References}), and the other sub-forms have the following semantics,
663 defined recursively on nested @var{import-set}s:
668 The @code{library} sub-form is used to specify libraries for import
669 whose names begin with the identifier ``library.''
672 The @code{only} sub-form imports only the specified @var{identifier}s
673 from the given @var{import-set}.
676 The @code{except} sub-form imports all of the bindings exported by
677 @var{import-set} except for those that appear in the specified list
678 of @var{identifier}s.
681 The @code{prefix} sub-form imports all of the bindings exported
682 by @var{import-set}, first prefixing them with the specified
686 The @code{rename} sub-form imports all of the identifiers exported
687 by @var{import-set}. The binding for each @var{internal-identifier}
688 among these identifiers is made visible to the importing library as
689 the corresponding @var{external-identifier}; all other bindings are
690 imported using the names provided by @var{import-set}.
694 Note that because Guile translates R6RS libraries into module
695 definitions, an import specification may be used to declare a
696 dependency on a native Guile module --- although doing so may make
697 your libraries less portable to other Schemes.
701 @deffn {Scheme Syntax} import import-spec ...
702 Import into the current environment the libraries specified by the
703 given import specifications, where each @var{import-spec} takes the
704 same form as in the @code{library} form described above.
709 @subsection Variables
712 Each module has its own hash table, sometimes known as an @dfn{obarray},
713 that maps the names defined in that module to their corresponding
716 A variable is a box-like object that can hold any Scheme value. It is
717 said to be @dfn{undefined} if its box holds a special Scheme value that
718 denotes undefined-ness (which is different from all other Scheme values,
719 including for example @code{#f}); otherwise the variable is
722 On its own, a variable object is anonymous. A variable is said to be
723 @dfn{bound} when it is associated with a name in some way, usually a
724 symbol in a module obarray. When this happens, the name is said to be
725 bound to the variable, in that module.
727 (That's the theory, anyway. In practice, defined-ness and bound-ness
728 sometimes get confused, because Lisp and Scheme implementations have
729 often conflated --- or deliberately drawn no distinction between --- a
730 name that is unbound and a name that is bound to a variable whose value
731 is undefined. We will try to be clear about the difference and explain
732 any confusion where it is unavoidable.)
734 Variables do not have a read syntax. Most commonly they are created and
735 bound implicitly by @code{define} expressions: a top-level @code{define}
736 expression of the form
739 (define @var{name} @var{value})
743 creates a variable with initial value @var{value} and binds it to the
744 name @var{name} in the current module. But they can also be created
745 dynamically by calling one of the constructor procedures
746 @code{make-variable} and @code{make-undefined-variable}.
748 @deffn {Scheme Procedure} make-undefined-variable
749 @deffnx {C Function} scm_make_undefined_variable ()
750 Return a variable that is initially unbound.
753 @deffn {Scheme Procedure} make-variable init
754 @deffnx {C Function} scm_make_variable (init)
755 Return a variable initialized to value @var{init}.
758 @deffn {Scheme Procedure} variable-bound? var
759 @deffnx {C Function} scm_variable_bound_p (var)
760 Return @code{#t} if @var{var} is bound to a value, or @code{#f}
761 otherwise. Throws an error if @var{var} is not a variable object.
764 @deffn {Scheme Procedure} variable-ref var
765 @deffnx {C Function} scm_variable_ref (var)
766 Dereference @var{var} and return its value.
767 @var{var} must be a variable object; see @code{make-variable}
768 and @code{make-undefined-variable}.
771 @deffn {Scheme Procedure} variable-set! var val
772 @deffnx {C Function} scm_variable_set_x (var, val)
773 Set the value of the variable @var{var} to @var{val}.
774 @var{var} must be a variable object, @var{val} can be any
775 value. Return an unspecified value.
778 @deffn {Scheme Procedure} variable-unset! var
779 @deffnx {C Function} scm_variable_unset_x (var)
780 Unset the value of the variable @var{var}, leaving @var{var} unbound.
783 @deffn {Scheme Procedure} variable? obj
784 @deffnx {C Function} scm_variable_p (obj)
785 Return @code{#t} if @var{obj} is a variable object, else return
790 @node Module System Reflection
791 @subsection Module System Reflection
793 The previous sections have described a declarative view of the module
794 system. You can also work with it programmatically by accessing and
795 modifying various parts of the Scheme objects that Guile uses to
796 implement the module system.
798 At any time, there is a @dfn{current module}. This module is the one
799 where a top-level @code{define} and similar syntax will add new
800 bindings. You can find other module objects with @code{resolve-module},
803 These module objects can be used as the second argument to @code{eval}.
805 @deffn {Scheme Procedure} current-module
806 @deffnx {C Function} scm_current_module ()
807 Return the current module object.
810 @deffn {Scheme Procedure} set-current-module module
811 @deffnx {C Function} scm_set_current_module (module)
812 Set the current module to @var{module} and return
813 the previous current module.
816 @deffn {Scheme Procedure} save-module-excursion thunk
817 Call @var{thunk} within a @code{dynamic-wind} such that the module that
818 is current at invocation time is restored when @var{thunk}'s dynamic
819 extent is left (@pxref{Dynamic Wind}).
821 More precisely, if @var{thunk} escapes non-locally, the current module
822 (at the time of escape) is saved, and the original current module (at
823 the time @var{thunk}'s dynamic extent was last entered) is restored. If
824 @var{thunk}'s dynamic extent is re-entered, then the current module is
825 saved, and the previously saved inner module is set current again.
828 @deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] @
830 @deffnx {C Function} scm_resolve_module (name)
831 Find the module named @var{name} and return it. When it has not already
832 been defined and @var{autoload} is true, try to auto-load it. When it
833 can't be found that way either, create an empty module if @var{ensure}
834 is true, otherwise return @code{#f}. If @var{version} is true, ensure
835 that the resulting module is compatible with the given version reference
836 (@pxref{R6RS Version References}). The name is a list of symbols.
839 @deffn {Scheme Procedure} resolve-interface name [#:select=#f] @
840 [#:hide='()] [#:prefix=#f] @
841 [#:renamer=#f] [#:version=#f]
842 Find the module named @var{name} as with @code{resolve-module} and
843 return its interface. The interface of a module is also a module
844 object, but it contains only the exported bindings.
847 @deffn {Scheme Procedure} module-uses module
848 Return a list of the interfaces used by @var{module}.
851 @deffn {Scheme Procedure} module-use! module interface
852 Add @var{interface} to the front of the use-list of @var{module}. Both
853 arguments should be module objects, and @var{interface} should very
854 likely be a module returned by @code{resolve-interface}.
857 @deffn {Scheme Procedure} reload-module module
858 Revisit the source file that corresponds to @var{module}. Raises an
859 error if no source file is associated with the given module.
862 As mentioned in the previous section, modules contain a mapping between
863 identifiers (as symbols) and storage locations (as variables). Guile
864 defines a number of procedures to allow access to this mapping. If you
865 are programming in C, @ref{Accessing Modules from C}.
867 @deffn {Scheme Procedure} module-variable module name
868 Return the variable bound to @var{name} (a symbol) in @var{module}, or
869 @code{#f} if @var{name} is unbound.
872 @deffn {Scheme Procedure} module-add! module name var
873 Define a new binding between @var{name} (a symbol) and @var{var} (a
874 variable) in @var{module}.
877 @deffn {Scheme Procedure} module-ref module name
878 Look up the value bound to @var{name} in @var{module}. Like
879 @code{module-variable}, but also does a @code{variable-ref} on the
880 resulting variable, raising an error if @var{name} is unbound.
883 @deffn {Scheme Procedure} module-define! module name value
884 Locally bind @var{name} to @var{value} in @var{module}. If @var{name}
885 was already locally bound in @var{module}, i.e., defined locally and not
886 by an imported module, the value stored in the existing variable will be
887 updated. Otherwise, a new variable will be added to the module, via
891 @deffn {Scheme Procedure} module-set! module name value
892 Update the binding of @var{name} in @var{module} to @var{value}, raising
893 an error if @var{name} is not already bound in @var{module}.
896 There are many other reflective procedures available in the default
897 environment. If you find yourself using one of them, please contact the
898 Guile developers so that we can commit to stability for that interface.
901 @node Accessing Modules from C
902 @subsection Accessing Modules from C
904 The last sections have described how modules are used in Scheme code,
905 which is the recommended way of creating and accessing modules. You
906 can also work with modules from C, but it is more cumbersome.
908 The following procedures are available.
910 @deftypefn {C Function} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
911 Call @var{func} and make @var{module} the current module during the
912 call. The argument @var{data} is passed to @var{func}. The return
913 value of @code{scm_c_call_with_current_module} is the return value of
917 @deftypefn {C Function} SCM scm_public_variable (SCM @var{module_name}, SCM @var{name})
918 @deftypefnx {C Function} SCM scm_c_public_variable ({const char *}@var{module_name}, {const char *}@var{name})
919 Find a the variable bound to the symbol @var{name} in the public
920 interface of the module named @var{module_name}.
922 @var{module_name} should be a list of symbols, when represented as a
923 Scheme object, or a space-separated string, in the @code{const char *}
924 case. See @code{scm_c_define_module} below, for more examples.
926 Signals an error if no module was found with the given name. If
927 @var{name} is not bound in the module, just returns @code{#f}.
930 @deftypefn {C Function} SCM scm_private_variable (SCM @var{module_name}, SCM @var{name})
931 @deftypefnx {C Function} SCM scm_c_private_variable ({const char *}@var{module_name}, {const char *}@var{name})
932 Like @code{scm_public_variable}, but looks in the internals of the
933 module named @var{module_name} instead of the public interface.
934 Logically, these procedures should only be called on modules you write.
937 @deftypefn {C Function} SCM scm_public_lookup (SCM @var{module_name}, SCM @var{name})
938 @deftypefnx {C Function} SCM scm_c_public_lookup ({const char *}@var{module_name}, {const char *}@var{name})
939 @deftypefnx {C Function} SCM scm_private_lookup (SCM @var{module_name}, SCM @var{name})
940 @deftypefnx {C Function} SCM scm_c_private_lookup ({const char *}@var{module_name}, {const char *}@var{name})
941 Like @code{scm_public_variable} or @code{scm_private_variable}, but if
942 the @var{name} is not bound in the module, signals an error. Returns a
946 static SCM eval_string_var;
948 /* NOTE: It is important that the call to 'my_init'
949 happens-before all calls to 'my_eval_string'. */
952 eval_string_var = scm_c_public_lookup ("ice-9 eval-string",
956 SCM my_eval_string (SCM str)
958 return scm_call_1 (scm_variable_ref (eval_string_var), str);
963 @deftypefn {C Function} SCM scm_public_ref (SCM @var{module_name}, SCM @var{name})
964 @deftypefnx {C Function} SCM scm_c_public_ref ({const char *}@var{module_name}, {const char *}@var{name})
965 @deftypefnx {C Function} SCM scm_private_ref (SCM @var{module_name}, SCM @var{name})
966 @deftypefnx {C Function} SCM scm_c_private_ref ({const char *}@var{module_name}, {const char *}@var{name})
967 Like @code{scm_public_lookup} or @code{scm_private_lookup}, but
968 additionally dereferences the variable. If the variable object is
969 unbound, signals an error. Returns the value bound to @var{name} in
973 In addition, there are a number of other lookup-related procedures. We
974 suggest that you use the @code{scm_public_} and @code{scm_private_}
975 family of procedures instead, if possible.
977 @deftypefn {C Function} SCM scm_c_lookup ({const char *}@var{name})
978 Return the variable bound to the symbol indicated by @var{name} in the
979 current module. If there is no such binding or the symbol is not
980 bound to a variable, signal an error.
983 @deftypefn {C Function} SCM scm_lookup (SCM @var{name})
984 Like @code{scm_c_lookup}, but the symbol is specified directly.
987 @deftypefn {C Function} SCM scm_c_module_lookup (SCM @var{module}, {const char *}@var{name})
988 @deftypefnx {C Function} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
989 Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
990 module is used instead of the current one.
993 @deftypefn {C Function} SCM scm_module_variable (SCM @var{module}, SCM @var{name})
994 Like @code{scm_module_lookup}, but if the binding does not exist, just
995 returns @code{#f} instead of raising an error.
998 To define a value, use @code{scm_define}:
1000 @deftypefn {C Function} SCM scm_c_define ({const char *}@var{name}, SCM @var{val})
1001 Bind the symbol indicated by @var{name} to a variable in the current
1002 module and set that variable to @var{val}. When @var{name} is already
1003 bound to a variable, use that. Else create a new variable.
1006 @deftypefn {C Function} SCM scm_define (SCM @var{name}, SCM @var{val})
1007 Like @code{scm_c_define}, but the symbol is specified directly.
1010 @deftypefn {C Function} SCM scm_c_module_define (SCM @var{module}, {const char *}@var{name}, SCM @var{val})
1011 @deftypefnx {C Function} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
1012 Like @code{scm_c_define} and @code{scm_define}, but the specified
1013 module is used instead of the current one.
1016 In some rare cases, you may need to access the variable that
1017 @code{scm_module_define} would have accessed, without changing the
1018 binding of the existing variable, if one is present. In that case, use
1019 @code{scm_module_ensure_local_variable}:
1021 @deftypefn {C Function} SCM scm_module_ensure_local_variable (SCM @var{module}, SCM @var{sym})
1022 Like @code{scm_module_define}, but if the @var{sym} is already locally
1023 bound in that module, the variable's existing binding is not reset.
1027 @deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
1028 Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @code{#f}.
1031 @deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data})
1032 Define a new module named @var{name} and make it current while
1033 @var{init} is called, passing it @var{data}. Return the module.
1035 The parameter @var{name} is a string with the symbols that make up
1036 the module name, separated by spaces. For example, @samp{"foo bar"} names
1037 the module @samp{(foo bar)}.
1039 When there already exists a module named @var{name}, it is used
1040 unchanged, otherwise, an empty module is created.
1043 @deftypefn {C Function} SCM scm_c_resolve_module ({const char *}@var{name})
1044 Find the module name @var{name} and return it. When it has not
1045 already been defined, try to auto-load it. When it can't be found
1046 that way either, create an empty module. The name is interpreted as
1047 for @code{scm_c_define_module}.
1050 @deftypefn {C Function} SCM scm_c_use_module ({const char *}@var{name})
1051 Add the module named @var{name} to the uses list of the current
1052 module, as with @code{(use-modules @var{name})}. The name is
1053 interpreted as for @code{scm_c_define_module}.
1056 @deftypefn {C Function} SCM scm_c_export ({const char *}@var{name}, ...)
1057 Add the bindings designated by @var{name}, ... to the public interface
1058 of the current module. The list of names is terminated by
1063 @node provide and require
1064 @subsection provide and require
1066 Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
1067 implemented a provide/require mechanism for many Scheme implementations.
1068 Library files in SLIB @emph{provide} a feature, and when user programs
1069 @emph{require} that feature, the library file is loaded in.
1071 For example, the file @file{random.scm} in the SLIB package contains the
1078 so to use its procedures, a user would type
1084 and they would magically become available, @emph{but still have the same
1085 names!} So this method is nice, but not as good as a full-featured
1088 When SLIB is used with Guile, provide and require can be used to access
1092 @subsection Environments
1095 Scheme, as defined in R5RS, does @emph{not} have a full module system.
1096 However it does define the concept of a top-level @dfn{environment}.
1097 Such an environment maps identifiers (symbols) to Scheme objects such
1098 as procedures and lists: @ref{About Closure}. In other words, it
1099 implements a set of @dfn{bindings}.
1101 Environments in R5RS can be passed as the second argument to
1102 @code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to
1103 return environments: @code{scheme-report-environment},
1104 @code{null-environment} and @code{interaction-environment} (@pxref{Fly
1107 In addition, in Guile any module can be used as an R5RS environment,
1108 i.e., passed as the second argument to @code{eval}.
1110 Note: the following two procedures are available only when the
1111 @code{(ice-9 r5rs)} module is loaded:
1114 (use-modules (ice-9 r5rs))
1117 @deffn {Scheme Procedure} scheme-report-environment version
1118 @deffnx {Scheme Procedure} null-environment version
1119 @var{version} must be the exact integer `5', corresponding to revision
1120 5 of the Scheme report (the Revised^5 Report on Scheme).
1121 @code{scheme-report-environment} returns a specifier for an
1122 environment that is empty except for all bindings defined in the
1123 report that are either required or both optional and supported by the
1124 implementation. @code{null-environment} returns a specifier for an
1125 environment that is empty except for the (syntactic) bindings for all
1126 syntactic keywords defined in the report that are either required or
1127 both optional and supported by the implementation.
1129 Currently Guile does not support values of @var{version} for other
1130 revisions of the report.
1132 The effect of assigning (through the use of @code{eval}) a variable
1133 bound in a @code{scheme-report-environment} (for example @code{car})
1134 is unspecified. Currently the environments specified by
1135 @code{scheme-report-environment} are not immutable in Guile.
1141 @c TeX-master: "guile.texi"