222 lines
12 KiB
HTML
222 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<!-- This manual documents Guile version 3.0.10.
|
|
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
|
Inc.
|
|
|
|
Copyright (C) 2021 Maxime Devos
|
|
|
|
Copyright (C) 2024 Tomas Volf
|
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
copy of the license is included in the section entitled "GNU Free
|
|
Documentation License." -->
|
|
<title>Using Guile Modules (Guile Reference Manual)</title>
|
|
|
|
<meta name="description" content="Using Guile Modules (Guile Reference Manual)">
|
|
<meta name="keywords" content="Using Guile Modules (Guile Reference Manual)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content=".texi2any-real">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<link href="index.html" rel="start" title="Top">
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="Modules.html" rel="up" title="Modules">
|
|
<link href="Creating-Guile-Modules.html" rel="next" title="Creating Guile Modules">
|
|
<link href="General-Information-about-Modules.html" rel="prev" title="General Information about Modules">
|
|
<style type="text/css">
|
|
<!--
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
|
div.example {margin-left: 3.2em}
|
|
span:hover a.copiable-link {visibility: visible}
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
|
-->
|
|
</style>
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<div class="subsection-level-extent" id="Using-Guile-Modules">
|
|
<div class="nav-panel">
|
|
<p>
|
|
Next: <a href="Creating-Guile-Modules.html" accesskey="n" rel="next">Creating Guile Modules</a>, Previous: <a href="General-Information-about-Modules.html" accesskey="p" rel="prev">General Information about Modules</a>, Up: <a href="Modules.html" accesskey="u" rel="up">Modules</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<h4 class="subsection" id="Using-Guile-Modules-1"><span>6.18.2 Using Guile Modules<a class="copiable-link" href="#Using-Guile-Modules-1"> ¶</a></span></h4>
|
|
|
|
<p>To use a Guile module is to access either its public interface or a
|
|
custom interface (see <a class="pxref" href="General-Information-about-Modules.html">General Information about Modules</a>). Both
|
|
types of access are handled by the syntactic form <code class="code">use-modules</code>,
|
|
which accepts one or more interface specifications and, upon evaluation,
|
|
arranges for those interfaces to be available to the current module.
|
|
This process may include locating and loading code for a given module if
|
|
that code has not yet been loaded, following <code class="code">%load-path</code>
|
|
(see <a class="pxref" href="Modules-and-the-File-System.html">Modules and the File System</a>).
|
|
</p>
|
|
<p>An <em class="dfn">interface specification</em> has one of two forms. The first
|
|
variation is simply to name the module, in which case its public
|
|
interface is the one accessed. For example:
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">(use-modules (ice-9 popen))
|
|
</pre></div>
|
|
|
|
<p>Here, the interface specification is <code class="code">(ice-9 popen)</code>, and the
|
|
result is that the current module now has access to <code class="code">open-pipe</code>,
|
|
<code class="code">close-pipe</code>, <code class="code">open-input-pipe</code>, and so on (see <a class="pxref" href="Pipes.html">Pipes</a>).
|
|
</p>
|
|
<p>Note in the previous example that if the current module had already
|
|
defined <code class="code">open-pipe</code>, that definition would be overwritten by the
|
|
definition in <code class="code">(ice-9 popen)</code>. For this reason (and others), there
|
|
is a second variation of interface specification that not only names a
|
|
module to be accessed, but also selects bindings from it and renames
|
|
them to suit the current module’s needs. For example:
|
|
</p>
|
|
<a class="index-entry-id" id="index-binding-renamer"></a>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">(use-modules ((ice-9 popen)
|
|
#:select ((open-pipe . pipe-open) close-pipe)
|
|
#:renamer (symbol-prefix-proc 'unixy:)))
|
|
</pre></div>
|
|
|
|
<p>or more simply:
|
|
</p>
|
|
<a class="index-entry-id" id="index-prefix"></a>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">(use-modules ((ice-9 popen)
|
|
#:select ((open-pipe . pipe-open) close-pipe)
|
|
#:prefix unixy:))
|
|
</pre></div>
|
|
|
|
<p>Here, the interface specification is more complex than before, and the
|
|
result is that a custom interface with only two bindings is created and
|
|
subsequently accessed by the current module. The mapping of old to new
|
|
names is as follows:
|
|
</p>
|
|
<div class="example smallexample">
|
|
<pre class="example-preformatted">(ice-9 popen) sees: current module sees:
|
|
open-pipe unixy:pipe-open
|
|
close-pipe unixy:close-pipe
|
|
</pre></div>
|
|
|
|
<p>This example also shows how to use the convenience procedure
|
|
<code class="code">symbol-prefix-proc</code>.
|
|
</p>
|
|
<p>You can also directly refer to bindings in a module by using the
|
|
<code class="code">@</code> syntax. For example, instead of using the
|
|
<code class="code">use-modules</code> statement from above and writing
|
|
<code class="code">unixy:pipe-open</code> to refer to the <code class="code">pipe-open</code> from the
|
|
<code class="code">(ice-9 popen)</code>, you could also write <code class="code">(@ (ice-9 popen)
|
|
open-pipe)</code>. Thus an alternative to the complete <code class="code">use-modules</code>
|
|
statement would be
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted">(define unixy:pipe-open (@ (ice-9 popen) open-pipe))
|
|
(define unixy:close-pipe (@ (ice-9 popen) close-pipe))
|
|
</pre></div>
|
|
|
|
<p>There is also <code class="code">@@</code>, which can be used like <code class="code">@</code>, but does
|
|
not check whether the variable that is being accessed is actually
|
|
exported. Thus, <code class="code">@@</code> can be thought of as the impolite version
|
|
of <code class="code">@</code> and should only be used as a last resort or for
|
|
debugging, for example.
|
|
</p>
|
|
<p>Note that just as with a <code class="code">use-modules</code> statement, any module that
|
|
has not yet been loaded will be loaded when referenced by a <code class="code">@</code> or
|
|
<code class="code">@@</code> form.
|
|
</p>
|
|
<p>You can also use the <code class="code">@</code> and <code class="code">@@</code> syntaxes as the target
|
|
of a <code class="code">set!</code> when the binding refers to a variable.
|
|
</p>
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-symbol_002dprefix_002dproc"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">symbol-prefix-proc</strong> <var class="def-var-arguments">prefix-sym</var><a class="copiable-link" href="#index-symbol_002dprefix_002dproc"> ¶</a></span></dt>
|
|
<dd><p>Return a procedure that prefixes its arg (a symbol) with
|
|
<var class="var">prefix-sym</var>.
|
|
</p></dd></dl>
|
|
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-use_002dmodules"><span class="category-def">syntax: </span><span><strong class="def-name">use-modules</strong> <var class="def-var-arguments">spec …</var><a class="copiable-link" href="#index-use_002dmodules"> ¶</a></span></dt>
|
|
<dd><p>Resolve each interface specification <var class="var">spec</var> into an interface and
|
|
arrange for these to be accessible by the current module. The return
|
|
value is unspecified.
|
|
</p>
|
|
<p><var class="var">spec</var> can be a list of symbols, in which case it names a module
|
|
whose public interface is found and used.
|
|
</p>
|
|
<p><var class="var">spec</var> can also be of the form:
|
|
</p>
|
|
<a class="index-entry-id" id="index-binding-renamer-1"></a>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted"> (MODULE-NAME [#:select SELECTION]
|
|
[#:prefix PREFIX]
|
|
[#:renamer RENAMER])
|
|
</pre></div>
|
|
|
|
<p>in which case a custom interface is newly created and used.
|
|
<var class="var">module-name</var> is a list of symbols, as above; <var class="var">selection</var> is a
|
|
list of selection-specs; <var class="var">prefix</var> is a symbol that is prepended to
|
|
imported names; and <var class="var">renamer</var> is a procedure that takes a symbol and
|
|
returns its new name. A selection-spec is either a symbol or a pair of
|
|
symbols <code class="code">(ORIG . SEEN)</code>, where <var class="var">orig</var> is the name in the used
|
|
module and <var class="var">seen</var> is the name in the using module. Note that
|
|
<var class="var">seen</var> is also modified by <var class="var">prefix</var> and <var class="var">renamer</var>.
|
|
</p>
|
|
<p>The <code class="code">#:select</code>, <code class="code">#:prefix</code>, and <code class="code">#:renamer</code> clauses are
|
|
optional. If all are omitted, the returned interface has no bindings.
|
|
If the <code class="code">#:select</code> clause is omitted, <var class="var">prefix</var> and <var class="var">renamer</var>
|
|
operate on the used module’s public interface.
|
|
</p>
|
|
<p>In addition to the above, <var class="var">spec</var> can also include a <code class="code">#:version</code>
|
|
clause, of the form:
|
|
</p>
|
|
<div class="example lisp">
|
|
<pre class="lisp-preformatted"> #:version VERSION-SPEC
|
|
</pre></div>
|
|
|
|
<p>where <var class="var">version-spec</var> is an R6RS-compatible version reference. An
|
|
error will be signaled in the case in which a module with the same name
|
|
has already been loaded, if that module specifies a version and that
|
|
version is not compatible with <var class="var">version-spec</var>. See <a class="xref" href="R6RS-Version-References.html">R6RS Version References</a>, for more on version references.
|
|
</p>
|
|
<p>If the module name is not resolvable, <code class="code">use-modules</code> will signal an
|
|
error.
|
|
</p></dd></dl>
|
|
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-_0040"><span class="category-def">syntax: </span><span><strong class="def-name">@</strong> <var class="def-var-arguments">module-name binding-name</var><a class="copiable-link" href="#index-_0040"> ¶</a></span></dt>
|
|
<dd><p>Refer to the binding named <var class="var">binding-name</var> in module
|
|
<var class="var">module-name</var>. The binding must have been exported by the module.
|
|
</p></dd></dl>
|
|
|
|
<dl class="first-deffn">
|
|
<dt class="deffn" id="index-_0040_0040"><span class="category-def">syntax: </span><span><strong class="def-name">@@</strong> <var class="def-var-arguments">module-name binding-name</var><a class="copiable-link" href="#index-_0040_0040"> ¶</a></span></dt>
|
|
<dd><p>Refer to the binding named <var class="var">binding-name</var> in module
|
|
<var class="var">module-name</var>. The binding must not have been exported by the
|
|
module. This syntax is only intended for debugging purposes or as a
|
|
last resort. See <a class="xref" href="Declarative-Modules.html">Declarative Modules</a>, for some limitations on the
|
|
use of <code class="code">@@</code>.
|
|
</p></dd></dl>
|
|
|
|
</div>
|
|
<hr>
|
|
<div class="nav-panel">
|
|
<p>
|
|
Next: <a href="Creating-Guile-Modules.html">Creating Guile Modules</a>, Previous: <a href="General-Information-about-Modules.html">General Information about Modules</a>, Up: <a href="Modules.html">Modules</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|