2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000-2004, 2007-2014
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:)))
134 (use-modules ((ice-9 popen)
135 #:select ((open-pipe . pipe-open) close-pipe)
139 Here, the interface specification is more complex than before, and the
140 result is that a custom interface with only two bindings is created and
141 subsequently accessed by the current module. The mapping of old to new
144 @c Use `smallexample' since `table' is ugly. --ttn
146 (ice-9 popen) sees: current module sees:
147 open-pipe unixy:pipe-open
148 close-pipe unixy:close-pipe
151 This example also shows how to use the convenience procedure
152 @code{symbol-prefix-proc}.
154 You can also directly refer to bindings in a module by using the
155 @code{@@} syntax. For example, instead of using the
156 @code{use-modules} statement from above and writing
157 @code{unixy:pipe-open} to refer to the @code{pipe-open} from the
158 @code{(ice-9 popen)}, you could also write @code{(@@ (ice-9 popen)
159 open-pipe)}. Thus an alternative to the complete @code{use-modules}
163 (define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
164 (define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
167 There is also @code{@@@@}, which can be used like @code{@@}, but does
168 not check whether the variable that is being accessed is actually
169 exported. Thus, @code{@@@@} can be thought of as the impolite version
170 of @code{@@} and should only be used as a last resort or for
171 debugging, for example.
173 Note that just as with a @code{use-modules} statement, any module that
174 has not yet been loaded yet will be loaded when referenced by a
175 @code{@@} or @code{@@@@} form.
177 You can also use the @code{@@} and @code{@@@@} syntaxes as the target
178 of a @code{set!} when the binding refers to a variable.
180 @deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
181 Return a procedure that prefixes its arg (a symbol) with
185 @deffn syntax use-modules spec @dots{}
186 Resolve each interface specification @var{spec} into an interface and
187 arrange for these to be accessible by the current module. The return
188 value is unspecified.
190 @var{spec} can be a list of symbols, in which case it names a module
191 whose public interface is found and used.
193 @var{spec} can also be of the form:
195 @cindex binding renamer
197 (MODULE-NAME [#:select SELECTION]
202 in which case a custom interface is newly created and used.
203 @var{module-name} is a list of symbols, as above; @var{selection} is a
204 list of selection-specs; @var{prefix} is a symbol that is prepended to
205 imported names; and @var{renamer} is a procedure that takes a symbol and
206 returns its new name. A selection-spec is either a symbol or a pair of
207 symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in the used
208 module and @var{seen} is the name in the using module. Note that
209 @var{seen} is also modified by @var{prefix} and @var{renamer}.
211 The @code{#:select}, @code{#:prefix}, and @code{#:renamer} clauses are
212 optional. If all are omitted, the returned interface has no bindings.
213 If the @code{#:select} clause is omitted, @var{prefix} and @var{renamer}
214 operate on the used module's public interface.
216 In addition to the above, @var{spec} can also include a @code{#:version}
220 #:version VERSION-SPEC
223 where @var{version-spec} is an R6RS-compatible version reference. An
224 error will be signaled in the case in which a module with the same name
225 has already been loaded, if that module specifies a version and that
226 version is not compatible with @var{version-spec}. @xref{R6RS Version
227 References}, for more on version references.
229 If the module name is not resolvable, @code{use-modules} will signal an
233 @deffn syntax @@ module-name binding-name
234 Refer to the binding named @var{binding-name} in module
235 @var{module-name}. The binding must have been exported by the module.
238 @deffn syntax @@@@ module-name binding-name
239 Refer to the binding named @var{binding-name} in module
240 @var{module-name}. The binding must not have been exported by the
241 module. This syntax is only intended for debugging purposes or as a
245 @node Creating Guile Modules
246 @subsection Creating Guile Modules
248 When you want to create your own modules, you have to take the following
253 Create a Scheme source file and add all variables and procedures you wish
254 to export, or which are required by the exported procedures.
257 Add a @code{define-module} form at the beginning.
260 Export all bindings which should be in the public interface, either
261 by using @code{define-public} or @code{export} (both documented below).
264 @deffn syntax define-module module-name option @dots{}
265 @var{module-name} is a list of one or more symbols.
268 (define-module (ice-9 popen))
271 @code{define-module} makes this module available to Guile programs under
272 the given @var{module-name}.
274 @var{option} @dots{} are keyword/value pairs which specify more about the
275 defined module. The recognized options and their meaning are shown in
279 @item #:use-module @var{interface-specification}
280 Equivalent to a @code{(use-modules @var{interface-specification})}
281 (@pxref{Using Guile Modules}).
283 @item #:autoload @var{module} @var{symbol-list}
285 Load @var{module} when any of @var{symbol-list} are accessed. For
289 (define-module (my mod)
290 #:autoload (srfi srfi-1) (partition delete-duplicates))
293 (set! foo (delete-duplicates ...)))
296 When a module is autoloaded, all its bindings become available.
297 @var{symbol-list} is just those that will first trigger the load.
299 An autoload is a good way to put off loading a big module until it's
300 really needed, for instance for faster startup or if it will only be
301 needed in certain circumstances.
303 @code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in
304 that case an @code{@@} form must be written every time a binding from
307 @item #:export @var{list}
309 Export all identifiers in @var{list} which must be a list of symbols
310 or pairs of symbols. This is equivalent to @code{(export @var{list})}
313 @item #:re-export @var{list}
315 Re-export all identifiers in @var{list} which must be a list of
316 symbols or pairs of symbols. The symbols in @var{list} must be
317 imported by the current module from other modules. This is equivalent
318 to @code{re-export} below.
320 @item #:replace @var{list}
322 @cindex replacing binding
323 @cindex overriding binding
324 @cindex duplicate binding
325 Export all identifiers in @var{list} (a list of symbols or pairs of
326 symbols) and mark them as @dfn{replacing bindings}. In the module
327 user's name space, this will have the effect of replacing any binding
328 with the same name that is not also ``replacing''. Normally a
329 replacement results in an ``override'' warning message,
330 @code{#:replace} avoids that.
332 In general, a module that exports a binding for which the @code{(guile)}
333 module already has a definition should use @code{#:replace} instead of
334 @code{#:export}. @code{#:replace}, in a sense, lets Guile know that the
335 module @emph{purposefully} replaces a core binding. It is important to
336 note, however, that this binding replacement is confined to the name
337 space of the module user. In other words, the value of the core binding
338 in question remains unchanged for other modules.
340 Note that although it is often a good idea for the replaced binding to
341 remain compatible with a binding in @code{(guile)}, to avoid surprising
342 the user, sometimes the bindings will be incompatible. For example,
343 SRFI-19 exports its own version of @code{current-time} (@pxref{SRFI-19
344 Time}) which is not compatible with the core @code{current-time}
345 function (@pxref{Time}). Guile assumes that a user importing a module
346 knows what she is doing, and uses @code{#:replace} for this binding
347 rather than @code{#:export}.
349 A @code{#:replace} clause is equivalent to @code{(export! @var{list})}
352 The @code{#:duplicates} (see below) provides fine-grain control about
353 duplicate binding handling on the module-user side.
355 @item #:version @var{list}
356 @cindex module version
357 Specify a version for the module in the form of @var{list}, a list of
358 zero or more exact, nonnegative integers. The corresponding
359 @code{#:version} option in the @code{use-modules} form allows callers
360 to restrict the value of this option in various ways.
362 @item #:duplicates @var{list}
363 @cindex duplicate binding handlers
364 @cindex duplicate binding
365 @cindex overriding binding
366 Tell Guile to handle duplicate bindings for the bindings imported by
367 the current module according to the policy defined by @var{list}, a
368 list of symbols. @var{list} must contain symbols representing a
369 duplicate binding handling policy chosen among the following:
373 Raises an error when a binding is imported from more than one place.
375 Issue a warning when a binding is imported from more than one place
376 and leave the responsibility of actually handling the duplication to
377 the next duplicate binding handler.
379 When a new binding is imported that has the same name as a previously
380 imported binding, then do the following:
384 @cindex replacing binding
385 If the old binding was said to be @dfn{replacing} (via the
386 @code{#:replace} option above) and the new binding is not replacing,
387 the keep the old binding.
389 If the old binding was not said to be replacing and the new binding is
390 replacing, then replace the old binding with the new one.
392 If neither the old nor the new binding is replacing, then keep the old
396 @item warn-override-core
397 Issue a warning when a core binding is being overwritten and actually
398 override the core binding with the new one.
400 In case of duplicate bindings, the firstly imported binding is always
401 the one which is kept.
403 In case of duplicate bindings, the lastly imported binding is always
404 the one which is kept.
406 In case of duplicate bindings, leave the responsibility to the next
410 If @var{list} contains more than one symbol, then the duplicate
411 binding handlers which appear first will be used first when resolving
412 a duplicate binding situation. As mentioned above, some resolution
413 policies may explicitly leave the responsibility of handling the
414 duplication to the next handler in @var{list}.
416 If GOOPS has been loaded before the @code{#:duplicates} clause is
417 processed, there are additional strategies available for dealing with
418 generic functions. @xref{Merging Generics}, for more information.
420 @findex default-duplicate-binding-handler
421 The default duplicate binding resolution policy is given by the
422 @code{default-duplicate-binding-handler} procedure, and is
425 (replace warn-override-core warn last)
430 Create a @dfn{pure} module, that is a module which does not contain any
431 of the standard procedure bindings except for the syntax forms. This is
432 useful if you want to create @dfn{safe} modules, that is modules which
433 do not know anything about dangerous procedures.
438 @deffn syntax export variable @dots{}
439 Add all @var{variable}s (which must be symbols or pairs of symbols) to
440 the list of exported bindings of the current module. If @var{variable}
441 is a pair, its @code{car} gives the name of the variable as seen by the
442 current module and its @code{cdr} specifies a name for the binding in
443 the current module's public interface.
446 @deffn syntax define-public @dots{}
447 Equivalent to @code{(begin (define foo ...) (export foo))}.
450 @deffn syntax re-export variable @dots{}
451 Add all @var{variable}s (which must be symbols or pairs of symbols) to
452 the list of re-exported bindings of the current module. Pairs of
453 symbols are handled as in @code{export}. Re-exported bindings must be
454 imported by the current module from some other module.
457 @deffn syntax export! variable @dots{}
458 Like @code{export}, but marking the exported variables as replacing.
459 Using a module with replacing bindings will cause any existing bindings
460 to be replaced without issuing any warnings. See the discussion of
461 @code{#:replace} above.
464 @node Modules and the File System
465 @subsection Modules and the File System
467 Typical programs only use a small subset of modules installed on a Guile
468 system. In order to keep startup time down, Guile only loads modules
469 when a program uses them, on demand.
471 When a program evaluates @code{(use-modules (ice-9 popen))}, and the
472 module is not loaded, Guile searches for a conventionally-named file
473 from in the @dfn{load path}.
475 In this case, loading @code{(ice-9 popen)} will eventually cause Guile
476 to run @code{(primitive-load-path "ice-9/popen")}.
477 @code{primitive-load-path} will search for a file @file{ice-9/popen} in
478 the @code{%load-path} (@pxref{Load Paths}). For each directory in
479 @code{%load-path}, Guile will try to find the file name, concatenated
480 with the extensions from @code{%load-extensions}. By default, this will
481 cause Guile to @code{stat} @file{ice-9/popen.scm}, and then
482 @file{ice-9/popen}. @xref{Load Paths}, for more on
483 @code{primitive-load-path}.
485 If a corresponding compiled @file{.go} file is found in the
486 @code{%load-compiled-path} or in the fallback path, and is as fresh as
487 the source file, it will be loaded instead of the source file. If no
488 compiled file is found, Guile may try to compile the source file and
489 cache away the resulting @file{.go} file. @xref{Compilation}, for more
492 Once Guile finds a suitable source or compiled file is found, the file
493 will be loaded. If, after loading the file, the module under
494 consideration is still not defined, Guile will signal an error.
496 For more information on where and how to install Scheme modules,
497 @xref{Installing Site Packages}.
500 @node R6RS Version References
501 @subsection R6RS Version References
503 Guile's module system includes support for locating modules based on
504 a declared version specifier of the same form as the one described in
505 R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6
506 Report on the Algorithmic Language Scheme}). By using the
507 @code{#:version} keyword in a @code{define-module} form, a module may
508 specify a version as a list of zero or more exact, nonnegative integers.
510 This version can then be used to locate the module during the module
511 search process. Client modules and callers of the @code{use-modules}
512 function may specify constraints on the versions of target modules by
513 providing a @dfn{version reference}, which has one of the following
517 (@var{sub-version-reference} ...)
518 (and @var{version-reference} ...)
519 (or @var{version-reference} ...)
520 (not @var{version-reference})
523 in which @var{sub-version-reference} is in turn one of:
527 (>= @var{sub-version})
528 (<= @var{sub-version})
529 (and @var{sub-version-reference} ...)
530 (or @var{sub-version-reference} ...)
531 (not @var{sub-version-reference})
534 in which @var{sub-version} is an exact, nonnegative integer as above. A
535 version reference matches a declared module version if each element of
536 the version reference matches a corresponding element of the module
537 version, according to the following rules:
541 The @code{and} sub-form matches a version or version element if every
542 element in the tail of the sub-form matches the specified version or
546 The @code{or} sub-form matches a version or version element if any
547 element in the tail of the sub-form matches the specified version or
551 The @code{not} sub-form matches a version or version element if the tail
552 of the sub-form does not match the version or version element.
555 The @code{>=} sub-form matches a version element if the element is
556 greater than or equal to the @var{sub-version} in the tail of the
560 The @code{<=} sub-form matches a version element if the version is less
561 than or equal to the @var{sub-version} in the tail of the sub-form.
564 A @var{sub-version} matches a version element if one is @var{eqv?} to
568 For example, a module declared as:
571 (define-module (mylib mymodule) #:version (1 2 0))
574 would be successfully loaded by any of the following @code{use-modules}
578 (use-modules ((mylib mymodule) #:version (1 2 (>= 0))))
579 (use-modules ((mylib mymodule) #:version (or (1 2 0) (1 2 1))))
580 (use-modules ((mylib mymodule) #:version ((and (>= 1) (not 2)) 2 0)))
585 @subsection R6RS Libraries
587 In addition to the API described in the previous sections, you also
588 have the option to create modules using the portable @code{library} form
589 described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The
590 Revised^6 Report on the Algorithmic Language Scheme}), and to import
591 libraries created in this format by other programmers. Guile's R6RS
592 library implementation takes advantage of the flexibility built into the
593 module system by expanding the R6RS library form into a corresponding
594 Guile @code{define-module} form that specifies equivalent import and
595 export requirements and includes the same body expressions. The library
599 (library (mylib (1 2))
601 (import (otherlib (3))))
604 is equivalent to the module definition:
607 (define-module (mylib)
609 #:use-module ((otherlib) #:version (3))
610 #:export (mybinding))
613 Central to the mechanics of R6RS libraries is the concept of import
614 and export @dfn{levels}, which control the visibility of bindings at
615 various phases of a library's lifecycle --- macros necessary to
616 expand forms in the library's body need to be available at expand
617 time; variables used in the body of a procedure exported by the
618 library must be available at runtime. R6RS specifies the optional
619 @code{for} sub-form of an @emph{import set} specification (see below)
620 as a mechanism by which a library author can indicate that a
621 particular library import should take place at a particular phase
622 with respect to the lifecycle of the importing library.
624 Guile's library implementation uses a technique called
625 @dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R.
626 Kent Dybvig), which allows the expander and compiler to automatically
627 determine the necessary visibility of a binding imported from another
628 library. As such, the @code{for} sub-form described below is ignored by
629 Guile (but may be required by Schemes in which phasing is explicit).
631 @deffn {Scheme Syntax} library name (export export-spec ...) (import import-spec ...) body ...
632 Defines a new library with the specified name, exports, and imports,
633 and evaluates the specified body expressions in this library's
636 The library @var{name} is a non-empty list of identifiers, optionally
637 ending with a version specification of the form described above
638 (@pxref{Creating Guile Modules}).
640 Each @var{export-spec} is the name of a variable defined or imported
641 by the library, or must take the form
642 @code{(rename (internal-name external-name) ...)}, where the
643 identifier @var{internal-name} names a variable defined or imported
644 by the library and @var{external-name} is the name by which the
645 variable is seen by importing libraries.
647 Each @var{import-spec} must be either an @dfn{import set} (see below)
648 or must be of the form @code{(for import-set import-level ...)},
649 where each @var{import-level} is one of:
657 where @var{level} is an integer. Note that since Guile does not
658 require explicit phase specification, any @var{import-set}s found
659 inside of @code{for} sub-forms will be ``unwrapped'' during
660 expansion and processed as if they had been specified directly.
662 Import sets in turn take one of the following forms:
665 @var{library-reference}
666 (library @var{library-reference})
667 (only @var{import-set} @var{identifier} ...)
668 (except @var{import-set} @var{identifier} ...)
669 (prefix @var{import-set} @var{identifier})
670 (rename @var{import-set} (@var{internal-identifier} @var{external-identifier}) ...)
673 where @var{library-reference} is a non-empty list of identifiers
674 ending with an optional version reference (@pxref{R6RS Version
675 References}), and the other sub-forms have the following semantics,
676 defined recursively on nested @var{import-set}s:
681 The @code{library} sub-form is used to specify libraries for import
682 whose names begin with the identifier ``library.''
685 The @code{only} sub-form imports only the specified @var{identifier}s
686 from the given @var{import-set}.
689 The @code{except} sub-form imports all of the bindings exported by
690 @var{import-set} except for those that appear in the specified list
691 of @var{identifier}s.
694 The @code{prefix} sub-form imports all of the bindings exported
695 by @var{import-set}, first prefixing them with the specified
699 The @code{rename} sub-form imports all of the identifiers exported
700 by @var{import-set}. The binding for each @var{internal-identifier}
701 among these identifiers is made visible to the importing library as
702 the corresponding @var{external-identifier}; all other bindings are
703 imported using the names provided by @var{import-set}.
707 Note that because Guile translates R6RS libraries into module
708 definitions, an import specification may be used to declare a
709 dependency on a native Guile module --- although doing so may make
710 your libraries less portable to other Schemes.
714 @deffn {Scheme Syntax} import import-spec ...
715 Import into the current environment the libraries specified by the
716 given import specifications, where each @var{import-spec} takes the
717 same form as in the @code{library} form described above.
722 @subsection Variables
725 Each module has its own hash table, sometimes known as an @dfn{obarray},
726 that maps the names defined in that module to their corresponding
729 A variable is a box-like object that can hold any Scheme value. It is
730 said to be @dfn{undefined} if its box holds a special Scheme value that
731 denotes undefined-ness (which is different from all other Scheme values,
732 including for example @code{#f}); otherwise the variable is
735 On its own, a variable object is anonymous. A variable is said to be
736 @dfn{bound} when it is associated with a name in some way, usually a
737 symbol in a module obarray. When this happens, the name is said to be
738 bound to the variable, in that module.
740 (That's the theory, anyway. In practice, defined-ness and bound-ness
741 sometimes get confused, because Lisp and Scheme implementations have
742 often conflated --- or deliberately drawn no distinction between --- a
743 name that is unbound and a name that is bound to a variable whose value
744 is undefined. We will try to be clear about the difference and explain
745 any confusion where it is unavoidable.)
747 Variables do not have a read syntax. Most commonly they are created and
748 bound implicitly by @code{define} expressions: a top-level @code{define}
749 expression of the form
752 (define @var{name} @var{value})
756 creates a variable with initial value @var{value} and binds it to the
757 name @var{name} in the current module. But they can also be created
758 dynamically by calling one of the constructor procedures
759 @code{make-variable} and @code{make-undefined-variable}.
761 @deffn {Scheme Procedure} make-undefined-variable
762 @deffnx {C Function} scm_make_undefined_variable ()
763 Return a variable that is initially unbound.
766 @deffn {Scheme Procedure} make-variable init
767 @deffnx {C Function} scm_make_variable (init)
768 Return a variable initialized to value @var{init}.
771 @deffn {Scheme Procedure} variable-bound? var
772 @deffnx {C Function} scm_variable_bound_p (var)
773 Return @code{#t} if @var{var} is bound to a value, or @code{#f}
774 otherwise. Throws an error if @var{var} is not a variable object.
777 @deffn {Scheme Procedure} variable-ref var
778 @deffnx {C Function} scm_variable_ref (var)
779 Dereference @var{var} and return its value.
780 @var{var} must be a variable object; see @code{make-variable}
781 and @code{make-undefined-variable}.
784 @deffn {Scheme Procedure} variable-set! var val
785 @deffnx {C Function} scm_variable_set_x (var, val)
786 Set the value of the variable @var{var} to @var{val}.
787 @var{var} must be a variable object, @var{val} can be any
788 value. Return an unspecified value.
791 @deffn {Scheme Procedure} variable-unset! var
792 @deffnx {C Function} scm_variable_unset_x (var)
793 Unset the value of the variable @var{var}, leaving @var{var} unbound.
796 @deffn {Scheme Procedure} variable? obj
797 @deffnx {C Function} scm_variable_p (obj)
798 Return @code{#t} if @var{obj} is a variable object, else return
803 @node Module System Reflection
804 @subsection Module System Reflection
806 The previous sections have described a declarative view of the module
807 system. You can also work with it programmatically by accessing and
808 modifying various parts of the Scheme objects that Guile uses to
809 implement the module system.
811 At any time, there is a @dfn{current module}. This module is the one
812 where a top-level @code{define} and similar syntax will add new
813 bindings. You can find other module objects with @code{resolve-module},
816 These module objects can be used as the second argument to @code{eval}.
818 @deffn {Scheme Procedure} current-module
819 @deffnx {C Function} scm_current_module ()
820 Return the current module object.
823 @deffn {Scheme Procedure} set-current-module module
824 @deffnx {C Function} scm_set_current_module (module)
825 Set the current module to @var{module} and return
826 the previous current module.
829 @deffn {Scheme Procedure} save-module-excursion thunk
830 Call @var{thunk} within a @code{dynamic-wind} such that the module that
831 is current at invocation time is restored when @var{thunk}'s dynamic
832 extent is left (@pxref{Dynamic Wind}).
834 More precisely, if @var{thunk} escapes non-locally, the current module
835 (at the time of escape) is saved, and the original current module (at
836 the time @var{thunk}'s dynamic extent was last entered) is restored. If
837 @var{thunk}'s dynamic extent is re-entered, then the current module is
838 saved, and the previously saved inner module is set current again.
841 @deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] @
843 @deffnx {C Function} scm_resolve_module (name)
844 Find the module named @var{name} and return it. When it has not already
845 been defined and @var{autoload} is true, try to auto-load it. When it
846 can't be found that way either, create an empty module if @var{ensure}
847 is true, otherwise return @code{#f}. If @var{version} is true, ensure
848 that the resulting module is compatible with the given version reference
849 (@pxref{R6RS Version References}). The name is a list of symbols.
852 @deffn {Scheme Procedure} resolve-interface name [#:select=#f] @
853 [#:hide='()] [#:prefix=#f] @
854 [#:renamer=#f] [#:version=#f]
855 Find the module named @var{name} as with @code{resolve-module} and
856 return its interface. The interface of a module is also a module
857 object, but it contains only the exported bindings.
860 @deffn {Scheme Procedure} module-uses module
861 Return a list of the interfaces used by @var{module}.
864 @deffn {Scheme Procedure} module-use! module interface
865 Add @var{interface} to the front of the use-list of @var{module}. Both
866 arguments should be module objects, and @var{interface} should very
867 likely be a module returned by @code{resolve-interface}.
870 @deffn {Scheme Procedure} reload-module module
871 Revisit the source file that corresponds to @var{module}. Raises an
872 error if no source file is associated with the given module.
875 As mentioned in the previous section, modules contain a mapping between
876 identifiers (as symbols) and storage locations (as variables). Guile
877 defines a number of procedures to allow access to this mapping. If you
878 are programming in C, @ref{Accessing Modules from C}.
880 @deffn {Scheme Procedure} module-variable module name
881 Return the variable bound to @var{name} (a symbol) in @var{module}, or
882 @code{#f} if @var{name} is unbound.
885 @deffn {Scheme Procedure} module-add! module name var
886 Define a new binding between @var{name} (a symbol) and @var{var} (a
887 variable) in @var{module}.
890 @deffn {Scheme Procedure} module-ref module name
891 Look up the value bound to @var{name} in @var{module}. Like
892 @code{module-variable}, but also does a @code{variable-ref} on the
893 resulting variable, raising an error if @var{name} is unbound.
896 @deffn {Scheme Procedure} module-define! module name value
897 Locally bind @var{name} to @var{value} in @var{module}. If @var{name}
898 was already locally bound in @var{module}, i.e., defined locally and not
899 by an imported module, the value stored in the existing variable will be
900 updated. Otherwise, a new variable will be added to the module, via
904 @deffn {Scheme Procedure} module-set! module name value
905 Update the binding of @var{name} in @var{module} to @var{value}, raising
906 an error if @var{name} is not already bound in @var{module}.
909 There are many other reflective procedures available in the default
910 environment. If you find yourself using one of them, please contact the
911 Guile developers so that we can commit to stability for that interface.
914 @node Accessing Modules from C
915 @subsection Accessing Modules from C
917 The last sections have described how modules are used in Scheme code,
918 which is the recommended way of creating and accessing modules. You
919 can also work with modules from C, but it is more cumbersome.
921 The following procedures are available.
923 @deftypefn {C Function} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
924 Call @var{func} and make @var{module} the current module during the
925 call. The argument @var{data} is passed to @var{func}. The return
926 value of @code{scm_c_call_with_current_module} is the return value of
930 @deftypefn {C Function} SCM scm_public_variable (SCM @var{module_name}, SCM @var{name})
931 @deftypefnx {C Function} SCM scm_c_public_variable ({const char *}@var{module_name}, {const char *}@var{name})
932 Find a the variable bound to the symbol @var{name} in the public
933 interface of the module named @var{module_name}.
935 @var{module_name} should be a list of symbols, when represented as a
936 Scheme object, or a space-separated string, in the @code{const char *}
937 case. See @code{scm_c_define_module} below, for more examples.
939 Signals an error if no module was found with the given name. If
940 @var{name} is not bound in the module, just returns @code{#f}.
943 @deftypefn {C Function} SCM scm_private_variable (SCM @var{module_name}, SCM @var{name})
944 @deftypefnx {C Function} SCM scm_c_private_variable ({const char *}@var{module_name}, {const char *}@var{name})
945 Like @code{scm_public_variable}, but looks in the internals of the
946 module named @var{module_name} instead of the public interface.
947 Logically, these procedures should only be called on modules you write.
950 @deftypefn {C Function} SCM scm_public_lookup (SCM @var{module_name}, SCM @var{name})
951 @deftypefnx {C Function} SCM scm_c_public_lookup ({const char *}@var{module_name}, {const char *}@var{name})
952 @deftypefnx {C Function} SCM scm_private_lookup (SCM @var{module_name}, SCM @var{name})
953 @deftypefnx {C Function} SCM scm_c_private_lookup ({const char *}@var{module_name}, {const char *}@var{name})
954 Like @code{scm_public_variable} or @code{scm_private_variable}, but if
955 the @var{name} is not bound in the module, signals an error. Returns a
959 static SCM eval_string_var;
961 /* NOTE: It is important that the call to 'my_init'
962 happens-before all calls to 'my_eval_string'. */
965 eval_string_var = scm_c_public_lookup ("ice-9 eval-string",
969 SCM my_eval_string (SCM str)
971 return scm_call_1 (scm_variable_ref (eval_string_var), str);
976 @deftypefn {C Function} SCM scm_public_ref (SCM @var{module_name}, SCM @var{name})
977 @deftypefnx {C Function} SCM scm_c_public_ref ({const char *}@var{module_name}, {const char *}@var{name})
978 @deftypefnx {C Function} SCM scm_private_ref (SCM @var{module_name}, SCM @var{name})
979 @deftypefnx {C Function} SCM scm_c_private_ref ({const char *}@var{module_name}, {const char *}@var{name})
980 Like @code{scm_public_lookup} or @code{scm_private_lookup}, but
981 additionally dereferences the variable. If the variable object is
982 unbound, signals an error. Returns the value bound to @var{name} in
986 In addition, there are a number of other lookup-related procedures. We
987 suggest that you use the @code{scm_public_} and @code{scm_private_}
988 family of procedures instead, if possible.
990 @deftypefn {C Function} SCM scm_c_lookup ({const char *}@var{name})
991 Return the variable bound to the symbol indicated by @var{name} in the
992 current module. If there is no such binding or the symbol is not
993 bound to a variable, signal an error.
996 @deftypefn {C Function} SCM scm_lookup (SCM @var{name})
997 Like @code{scm_c_lookup}, but the symbol is specified directly.
1000 @deftypefn {C Function} SCM scm_c_module_lookup (SCM @var{module}, {const char *}@var{name})
1001 @deftypefnx {C Function} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
1002 Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
1003 module is used instead of the current one.
1006 @deftypefn {C Function} SCM scm_module_variable (SCM @var{module}, SCM @var{name})
1007 Like @code{scm_module_lookup}, but if the binding does not exist, just
1008 returns @code{#f} instead of raising an error.
1011 To define a value, use @code{scm_define}:
1013 @deftypefn {C Function} SCM scm_c_define ({const char *}@var{name}, SCM @var{val})
1014 Bind the symbol indicated by @var{name} to a variable in the current
1015 module and set that variable to @var{val}. When @var{name} is already
1016 bound to a variable, use that. Else create a new variable.
1019 @deftypefn {C Function} SCM scm_define (SCM @var{name}, SCM @var{val})
1020 Like @code{scm_c_define}, but the symbol is specified directly.
1023 @deftypefn {C Function} SCM scm_c_module_define (SCM @var{module}, {const char *}@var{name}, SCM @var{val})
1024 @deftypefnx {C Function} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
1025 Like @code{scm_c_define} and @code{scm_define}, but the specified
1026 module is used instead of the current one.
1029 In some rare cases, you may need to access the variable that
1030 @code{scm_module_define} would have accessed, without changing the
1031 binding of the existing variable, if one is present. In that case, use
1032 @code{scm_module_ensure_local_variable}:
1034 @deftypefn {C Function} SCM scm_module_ensure_local_variable (SCM @var{module}, SCM @var{sym})
1035 Like @code{scm_module_define}, but if the @var{sym} is already locally
1036 bound in that module, the variable's existing binding is not reset.
1040 @deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
1041 Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @code{#f}.
1044 @deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data})
1045 Define a new module named @var{name} and make it current while
1046 @var{init} is called, passing it @var{data}. Return the module.
1048 The parameter @var{name} is a string with the symbols that make up
1049 the module name, separated by spaces. For example, @samp{"foo bar"} names
1050 the module @samp{(foo bar)}.
1052 When there already exists a module named @var{name}, it is used
1053 unchanged, otherwise, an empty module is created.
1056 @deftypefn {C Function} SCM scm_c_resolve_module ({const char *}@var{name})
1057 Find the module name @var{name} and return it. When it has not
1058 already been defined, try to auto-load it. When it can't be found
1059 that way either, create an empty module. The name is interpreted as
1060 for @code{scm_c_define_module}.
1063 @deftypefn {C Function} SCM scm_c_use_module ({const char *}@var{name})
1064 Add the module named @var{name} to the uses list of the current
1065 module, as with @code{(use-modules @var{name})}. The name is
1066 interpreted as for @code{scm_c_define_module}.
1069 @deftypefn {C Function} void scm_c_export ({const char *}@var{name}, ...)
1070 Add the bindings designated by @var{name}, ... to the public interface
1071 of the current module. The list of names is terminated by
1076 @node provide and require
1077 @subsection provide and require
1079 Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
1080 implemented a provide/require mechanism for many Scheme implementations.
1081 Library files in SLIB @emph{provide} a feature, and when user programs
1082 @emph{require} that feature, the library file is loaded in.
1084 For example, the file @file{random.scm} in the SLIB package contains the
1091 so to use its procedures, a user would type
1097 and they would magically become available, @emph{but still have the same
1098 names!} So this method is nice, but not as good as a full-featured
1101 When SLIB is used with Guile, provide and require can be used to access
1105 @subsection Environments
1108 Scheme, as defined in R5RS, does @emph{not} have a full module system.
1109 However it does define the concept of a top-level @dfn{environment}.
1110 Such an environment maps identifiers (symbols) to Scheme objects such
1111 as procedures and lists: @ref{About Closure}. In other words, it
1112 implements a set of @dfn{bindings}.
1114 Environments in R5RS can be passed as the second argument to
1115 @code{eval} (@pxref{Fly Evaluation}). Three procedures are defined to
1116 return environments: @code{scheme-report-environment},
1117 @code{null-environment} and @code{interaction-environment} (@pxref{Fly
1120 In addition, in Guile any module can be used as an R5RS environment,
1121 i.e., passed as the second argument to @code{eval}.
1123 Note: the following two procedures are available only when the
1124 @code{(ice-9 r5rs)} module is loaded:
1127 (use-modules (ice-9 r5rs))
1130 @deffn {Scheme Procedure} scheme-report-environment version
1131 @deffnx {Scheme Procedure} null-environment version
1132 @var{version} must be the exact integer `5', corresponding to revision
1133 5 of the Scheme report (the Revised^5 Report on Scheme).
1134 @code{scheme-report-environment} returns a specifier for an
1135 environment that is empty except for all bindings defined in the
1136 report that are either required or both optional and supported by the
1137 implementation. @code{null-environment} returns a specifier for an
1138 environment that is empty except for the (syntactic) bindings for all
1139 syntactic keywords defined in the report that are either required or
1140 both optional and supported by the implementation.
1142 Currently Guile does not support values of @var{version} for other
1143 revisions of the report.
1145 The effect of assigning (through the use of @code{eval}) a variable
1146 bound in a @code{scheme-report-environment} (for example @code{car})
1147 is unspecified. Currently the environments specified by
1148 @code{scheme-report-environment} are not immutable in Guile.
1154 @c TeX-master: "guile.texi"