The same sort of parenthesised form is used for a macro invocation,
but in that case the arguments are not evaluated. See the
descriptions of macros for more on this (@pxref{Macros}, and
@pxref{Syntax Rules}).

@nicode constant

Number, string, character and boolean constants evaluate “to
themselves”, so can appear as literals.

123 ⇒ 123
99.9 ⇒ 99.9
"hello" ⇒ "hello"
#\z ⇒ #\z
#t ⇒ #t

Note that an application must not attempt to modify literal strings,
since they may be in read-only memory.

@nicode (quote data)

@nicode ’data

Quoting is used to obtain a literal symbol (instead of a variable
reference), a literal list (instead of a function call), or a literal
vector. @nicode{’} is simply a shorthand for a quote form.
For example,

Note that an application must not attempt to modify literal lists or
vectors obtained from a quote form, since they may be in
read-only memory.

@nicode (quasiquote data)

@nicode ‘data

Backquote quasi-quotation is like quote, but selected
sub-expressions are evaluated. This is a convenient way to construct
a list or vector structure most of which is constant, but at certain
points should have expressions substituted.

The same effect can always be had with suitable list,
cons or vector calls, but quasi-quoting is often easier.

@nicode (unquote expr)

@nicode ,expr

Within the quasiquote data, unquote or , indicates
an expression to be evaluated and inserted. The comma syntax ,
is simply a shorthand for an unquote form. For example,

Within the quasiquote data, unquote-splicing or
,@ indicates an expression to be evaluated and the elements of
the returned list inserted. expr must evaluate to a list. The
“comma-at” syntax ,@ is simply a shorthand for an
unquote-splicing form.

1.1.2 Comments

Comments in Scheme source files are written by starting them with a
semicolon character (;). The comment then reaches up to the end
of the line. Comments can begin at any column, and the may be inserted
on the same line as Scheme code.

It is common to use a single semicolon for comments following
expressions on a line, to use two semicolons for comments which are
indented like code, and three semicolons for comments which start at
column 0, even if they are inside an indented code block. This
convention is used when indenting code in Emacs’ Scheme mode.

1.1.3 Block Comments

In addition to the standard line comments defined by R5RS, Guile has
another comment type for multiline comments, called block
comments. This type of comment begins with the character sequence
#! and ends with the characters !#, which must appear on a
line of their own. These comments are compatible with the block
comments in the Scheme Shell ‘scsh’ (@pxref{The Scheme shell
(scsh)}). The characters #! were chosen because they are the
magic characters used in shell scripts for indicating that the name of
the program for executing the script follows on the same line.

Thus a Guile script often starts like this.

#! /usr/local/bin/guile -s
!#

More details on Guile scripting can be found in the scripting section
(@pxref{Guile Scripting}).

Similarly, Guile (starting from version 2.0) supports nested block
comments as specified by R6RS and
SRFI-30:

(+ 1 #| this is a #| nested |# block comment |# 2)
⇒ 3

For backward compatibility, this syntax can be overridden with
read-hash-extend (see section read-hash-extend).

There is one special case where the contents of a comment can actually
affect the interpretation of code. When a character encoding
declaration, such as coding: utf-8 appears in one of the first
few lines of a source file, it indicates to Guile’s default reader
that this source code file is not ASCII. For details see Character Encoding of Source Files.

1.1.5 Keyword Syntax

1.1.6 Reader Extensions

Scheme Procedure: read-hash-extend chr proc

C Function: scm_read_hash_extend (chr, proc)

Install the procedure proc for reading expressions
starting with the character sequence # and chr.
proc will be called with two arguments: the character
chr and the port to read further data from. The object
returned will be the return value of read.
Passing #f for proc will remove a previous setting.

1.2 Reading Scheme Code

Read an s-expression from the input port port, or from
the current input port if port is not specified.
Any whitespace before the next token is discarded.

The behaviour of Guile’s Scheme reader can be modified by manipulating
its read options.

Scheme Procedure: read-options [setting]

Display the current settings of the global read options. If
setting is omitted, only a short form of the current read options
is printed. Otherwise if setting is the symbol help, a
complete options description is displayed.

The set of available options, and their default values, may be had by
invoking read-options at the prompt.

Note that Guile also includes a preliminary mechanism for setting read
options on a per-port basis. For instance, the case-insensitive
read option is set (or unset) on the port when the reader encounters the
#!fold-case or #!no-fold-case reader directives.
Similarly, the #!curly-infix reader directive sets the
curly-infix read option on the port, and
#!curly-infix-and-bracket-lists sets curly-infix and
unsets square-brackets on the port (@pxref{SRFI-105}). There is
currently no other way to access or set the per-port read options.

The boolean options may be toggled with read-enable and
read-disable. The non-boolean keywords option must be set
using read-set!.

Scheme Procedure: read-enable option-name

Scheme Procedure: read-disable option-name

Scheme Syntax: read-set! option-name value

Modify the read options. read-enable should be used with boolean
options and switches them on, read-disable switches them off.

read-set! can be used to set an option to a specific value. Due
to historical oddities, it is a macro that expects an unquoted option
name.

For example, to make read fold all symbols to their lower case
(perhaps for compatibility with older Scheme code), you can enter:

(read-enable 'case-insensitive)

For more information on the effect of the r6rs-hex-escapes and
hungry-eol-escapes options, see (@pxref{String Syntax}).

For more information on the r7rs-symbols option, see
(@pxref{Symbol Read Syntax}).

1.3 Writing Scheme Values

Any scheme value may be written to a port. Not all values may be read
back in (see section Reading Scheme Code), however.

Scheme Procedure: write obj [port]

Send a representation of obj to port or to the current
output port if not given.

The output is designed to be machine readable, and can be read back
with read (see section Reading Scheme Code). Strings are printed in
double quotes, with escapes if necessary, and characters are printed in
‘#\’ notation.

Scheme Procedure: display obj [port]

Send a representation of obj to port or to the current
output port if not given.

The output is designed for human readability, it differs from
write in that strings are printed without double quotes and
escapes, and characters are printed as per write-char, not in
‘#\’ form.

As was the case with the Scheme reader, there are a few options that
affect the behavior of the Scheme printer.

Scheme Procedure: print-options [setting]

Display the current settings of the read options. If setting is
omitted, only a short form of the current read options is
printed. Otherwise if setting is the symbol help, a
complete options description is displayed.

The set of available options, and their default values, may be had by
invoking print-options at the prompt.

scheme@(guile-user)> (print-options)
(quote-keywordish-symbols reader highlight-suffix "}" highlight-prefix "{")
scheme@(guile-user)> (print-options 'help)
highlight-prefix { The string to print before highlighted values.
highlight-suffix } The string to print after highlighted values.
quote-keywordish-symbols reader How to print symbols that have a colon
as their first or last character. The
value '#f' does not quote the colons;
'#t' quotes them; 'reader' quotes them
when the reader option 'keywords' is
not '#f'.
escape-newlines yes Render newlines as \n when printing
using `write'.
r7rs-symbols no Escape symbols using R7RS |...| symbol
notation.

These options may be modified with the print-set! syntax.

Scheme Syntax: print-set! option-name value

Modify the print options. Due to historical oddities, print-set!
is a macro that expects an unquoted option name.

1.4 Procedures for On the Fly Evaluation

Scheme has the lovely property that its expressions may be represented
as data. The eval procedure takes a Scheme datum and evaluates
it as code.

Scheme Procedure: eval exp module_or_state

C Function: scm_eval (exp, module_or_state)

Evaluate exp, a list representing a Scheme expression,
in the top-level environment specified by module_or_state.
While exp is evaluated (using primitive-eval),
module_or_state is made the current module. The current module
is reset to its previous value when eval returns.
XXX - dynamic states.
Example: (eval ’(+ 1 2) (interaction-environment))

Scheme Procedure: interaction-environment

C Function: scm_interaction_environment ()

Return a specifier for the environment that contains
implementation–defined bindings, typically a superset of those
listed in the report. The intent is that this procedure will
return the environment in which the implementation would
evaluate expressions dynamically typed by the user.

@xref{Environments}, for other environments.

One does not always receive code as Scheme data, of course, and this is
especially the case for Guile’s other language implementations
(@pxref{Other Languages}). For the case in which all you have is a
string, we have eval-string. There is a legacy version of this
procedure in the default environment, but you really want the one from
(ice-9 eval-string), so load it up:

Parse string according to the current language, normally Scheme.
Evaluate or compile the expressions it contains, in order, returning the
last expression.

If the module keyword argument is set, save a module excursion
(@pxref{Module System Reflection}) and set the current module to
module before evaluation.

The file, line, and column keyword arguments can be
used to indicate that the source string begins at a particular source
location.

Finally, lang is a language, defaulting to the current language,
and the expression is compiled if compile? is true or there is no
evaluator for the given language.

C Function: scm_eval_string (string)

C Function: scm_eval_string_in_module (string, module)

These C bindings call eval-string from (ice-9
eval-string), evaluating within module or the current module.

C Function: SCMscm_c_eval_string (const char *string)

scm_eval_string, but taking a C string in locale encoding instead
of an SCM.

Scheme Procedure: apply proc arg … arglst

C Function: scm_apply_0 (proc, arglst)

C Function: scm_apply_1 (proc, arg1, arglst)

C Function: scm_apply_2 (proc, arg1, arg2, arglst)

C Function: scm_apply_3 (proc, arg1, arg2, arg3, arglst)

C Function: scm_apply (proc, arg, rest)

Call proc with arguments arg … and the
elements of the arglst list.

scm_apply takes parameters corresponding to a Scheme level
(lambda (proc arg1 . rest) ...). So arg1 and all but the
last element of the rest list make up arg …, and the
last element of rest is the arglst list. Or if rest
is the empty list SCM_EOL then there’s no arg …, and
(arg1) is the arglst.

arglst is not modified, but the rest list passed to
scm_apply is modified.

Call proc with the array of arguments argv, as a
SCM*. The length of the arguments should be passed in
nargs, as a size_t.

Scheme Procedure: apply:nconc2last lst

C Function: scm_nconc2last (lst)

lst should be a list (arg1 … argNarglst), with arglst being a list. This function returns
a list comprising arg1 to argN plus the elements of
arglst. lst is modified to form the return. arglst
is not modified, though the return does share structure with it.

This operation collects up the arguments from a list which is
apply style parameters.

Scheme Procedure: primitive-eval exp

C Function: scm_primitive_eval (exp)

Evaluate exp in the top-level environment specified by
the current module.

1.5 Compiling Scheme Code

The eval procedure directly interprets the S-expression
representation of Scheme. An alternate strategy for evaluation is to
determine ahead of time what computations will be necessary to
evaluate the expression, and then use that recipe to produce the
desired results. This is known as compilation.

While it is possible to compile simple Scheme expressions such as
(+ 2 2) or even "Hello world!", compilation is most
interesting in the context of procedures. Compiling a lambda expression
produces a compiled procedure, which is just like a normal procedure
except typically much faster, because it can bypass the generic
interpreter.

Functions from system modules in a Guile installation are normally
compiled already, so they load and run quickly.

Note that well-written Scheme programs will not typically call the
procedures in this section, for the same reason that it is often bad
taste to use eval. By default, Guile automatically compiles any
files it encounters that have not been compiled yet (@pxref{Invoking
Guile, @code{--auto-compile}}). The compiler can also be invoked
explicitly from the shell as guild compile foo.scm.

(Why are calls to eval and compile usually in bad taste?
Because they are limited, in that they can only really make sense for
top-level expressions. Also, most needs for “compile-time”
computation are fulfilled by macros and closures. Of course one good
counterexample is the REPL itself, or any code that reads expressions
from a port.)

Automatic compilation generally works transparently, without any need
for user intervention. However Guile does not yet do proper dependency
tracking, so that if file ‘a.scm’ uses macros from
‘b.scm’, and b.scm changes, a.scm
would not be automatically recompiled. To forcibly invalidate the
auto-compilation cache, pass the --fresh-auto-compile option to
Guile, or set the GUILE_AUTO_COMPILE environment variable to
fresh (instead of to 0 or 1).

For more information on the compiler itself, see @ref{Compiling to the
Virtual Machine}. For information on the virtual machine, see @ref{A
Virtual Machine for Guile}.

The command-line interface to Guile’s compiler is the guild
compile command:

Command: guild compile [‘option’...] file...

Compile file, a source file, and store bytecode in the compilation cache
or in the file specified by the ‘-o’ option. The following options are
available:

‘-L dir’

‘--load-path=dir’

Add dir to the front of the module load path.

‘-o ofile’

‘--output=ofile’

Write output bytecode to ofile. By convention, bytecode file
names end in .go. When ‘-o’ is omitted, the output file
name is as for compile-file (see below).

‘-W warning’

‘--warn=warning’

Emit warnings of type warning; use --warn=help for a list
of available warnings and their description. Currently recognized
warnings include unused-variable, unused-toplevel,
unbound-variable, arity-mismatch, format,
duplicate-case-datum, and bad-case-datum.

‘-f lang’

‘--from=lang’

Use lang as the source language of file. If this option is omitted,
scheme is assumed.

‘-t lang’

‘--to=lang’

Use lang as the target language of file. If this option is omitted,
objcode is assumed.

Output will be written to a output-file. If you do not supply an
output file name, output is written to a file in the cache directory, as
computed by (compiled-file-name file).

from and to specify the source and target languages.
@xref{Compiling to the Virtual Machine}, for more information on these
options, and on env and opts.

As with guild compile, file is assumed to be
UTF-8-encoded unless it contains a coding declaration.

Scheme Procedure: compiled-file-name file

Compute a cached location for a compiled version of a Scheme file named
file.

This file will usually be below the ‘$HOME/.cache/guile/ccache’
directory, depending on the value of the XDG_CACHE_HOME
environment variable. The intention is that compiled-file-name
provides a fallback location for caching auto-compiled files. If you
want to place a compile file in the %load-compiled-path, you
should pass the output-file option to compile-file,
explicitly.

Scheme Variable: %auto-compilation-options

This variable contains the options passed to the compile-file
procedure when auto-compiling source files. By default, it enables
useful compilation warnings. It can be customized from ‘~/.guile’.

1.6 Loading Scheme Code from File

Scheme Procedure: load filename [reader]

Load filename and evaluate its contents in the top-level
environment.

reader if provided should be either #f, or a procedure with
the signature (lambda (port) …) which reads the next
expression from port. If reader is #f or absent,
Guile’s built-in read procedure is used (see section Reading Scheme Code).

The reader argument takes effect by setting the value of the
current-reader fluid (see below) before loading the file, and
restoring its previous value when loading is complete. The Scheme code
inside filename can itself change the current reader procedure on
the fly by setting current-reader fluid.

If the variable %load-hook is defined, it should be bound to a
procedure that will be called before any code is loaded. See
documentation for %load-hook later in this section.

Scheme Procedure: load-compiled filename

Load the compiled file named filename.

Compiling a source file (see section Reading and Evaluating Scheme Code) and then
calling load-compiled on the resulting file is equivalent to
calling load on the source file.

Scheme Procedure: primitive-load filename

C Function: scm_primitive_load (filename)

Load the file named filename and evaluate its contents in the
top-level environment. filename must either be a full pathname or
be a pathname relative to the current directory. If the variable
%load-hook is defined, it should be bound to a procedure that
will be called before any code is loaded. See the documentation for
%load-hook later in this section.

C Function: SCMscm_c_primitive_load (const char *filename)

scm_primitive_load, but taking a C string instead of an
SCM.

Variable: current-reader

current-reader holds the read procedure that is currently being
used by the above loading procedures to read expressions (from the file
that they are loading). current-reader is a fluid, so it has an
independent value in each dynamic root and should be read and set using
fluid-ref and fluid-set! (@pxref{Fluids and Dynamic
States}).

Changing current-reader is typically useful to introduce local
syntactic changes, such that code following the fluid-set! call
is read using the newly installed reader. The current-reader
change should take place at evaluation time when the code is evaluated,
or at compilation time when the code is compiled:

(eval-when (compile eval)
(fluid-set! current-reader my-own-reader))

The eval-when form above ensures that the current-reader
change occurs at the right time.

Variable: %load-hook

A procedure to be called (%load-hook filename) whenever a
file is loaded, or #f for no such call. %load-hook is
used by all of the loading functions (load and
primitive-load, and load-from-path and
primitive-load-path documented in the next section).

1.7 Load Paths

The procedure in the previous section look for Scheme code in the file
system at specific location. Guile also has some procedures to search
the load path for code.

Variable: %load-path

List of directories which should be searched for Scheme modules and
libraries. When Guile starts up, %load-path is initialized to
the default load path (list (%library-dir) (%site-dir)
(%global-site-dir) (%package-data-dir)). The GUILE_LOAD_PATH
environment variable can be used to prepend or append additional
directories (@pxref{Environment Variables}).

@xref{Build Config}, for more on %site-dir and related
procedures.

Scheme Procedure: load-from-path filename

Similar to load, but searches for filename in the load
paths. Preferentially loads a compiled version of the file, if it is
available and up-to-date.

A user can extend the load path by calling add-to-load-path.

Scheme Syntax: add-to-load-path dir

Add dir to the load path.

For example, a script might include this form to add the directory that
it is in to the load path:

(add-to-load-path (dirname (current-filename)))

It’s better to use add-to-load-path than to modify
%load-path directly, because add-to-load-path takes care
of modifying the path both at compile-time and at run-time.

Search %load-path for the file named filename and
load it into the top-level environment. If filename is a
relative pathname and is not found in the list of search paths,
an error is signalled. Preferentially loads a compiled version of the
file, if it is available and up-to-date.

If filename is a relative pathname and is not found in the list of
search paths, one of three things may happen, depending on the optional
second argument, exception-on-not-found. If it is #f,
#f will be returned. If it is a procedure, it will be called
with no arguments. (This allows a distinction to be made between
exceptions raised by loading a file, and exceptions related to the
loader itself.) Otherwise an error is signalled.

For compatibility with Guile 1.8 and earlier, the C function takes only
one argument, which can be either a string (the file name) or an
argument list.

Scheme Procedure: %search-load-path filename

C Function: scm_sys_search_load_path (filename)

Search %load-path for the file named filename, which must
be readable by the current user. If filename is found in the list
of paths to search or is an absolute pathname, return its full pathname.
Otherwise, return #f. Filenames may have any of the optional
extensions in the %load-extensions list; %search-load-path
will try each extension automatically.

Variable: %load-extensions

A list of default file extensions for files containing Scheme code.
%search-load-path tries each of these extensions when looking for
a file to load. By default, %load-extensions is bound to the
list ("" ".scm").

As mentioned above, when Guile searches the %load-path for a
source file, it will also search the %load-compiled-path for a
corresponding compiled file. If the compiled file is as new or newer
than the source file, it will be loaded instead of the source file,
using load-compiled.

Variable: %load-compiled-path

Like %load-path, but for compiled files. By default, this path
has two entries: one for compiled files from Guile itself, and one for
site packages. The GUILE_LOAD_COMPILED_PATH environment variable
can be used to prepend or append additional directories
(@pxref{Environment Variables}).

When primitive-load-path searches the %load-compiled-path
for a corresponding compiled file for a relative path it does so by
appending .go to the relative path. For example, searching for
ice-9/popen could find
/usr/lib/guile/2.0/ccache/ice-9/popen.go, and use it instead of
/usr/share/guile/2.0/ice-9/popen.scm.

If primitive-load-path does not find a corresponding .go
file in the %load-compiled-path, or the .go file is out of
date, it will search for a corresponding auto-compiled file in the
fallback path, possibly creating one if one does not exist.

@xref{Installing Site Packages}, for more on how to correctly install
site packages. @xref{Modules and the File System}, for more on the
relationship between load paths and modules. See section Compiling Scheme Code, for
more on the fallback path and auto-compilation.

Finally, there are a couple of helper procedures for general path
manipulation.

Scheme Procedure: parse-path path [tail]

C Function: scm_parse_path (path, tail)

Parse path, which is expected to be a colon-separated string, into
a list and return the resulting list with tail appended. If
path is #f, tail is returned.

Scheme Procedure: parse-path-with-ellipsis path base

C Function: scm_parse_path_with_ellipsis (path, base)

Parse path, which is expected to be a colon-separated string, into
a list and return the resulting list with base (a list) spliced in
place of the ... path component, if present, or else base
is added to the end. If path is #f, base is
returned.

Search path for a directory containing a file named
filename. The file must be readable, and not a directory. If we
find one, return its full filename; otherwise, return #f. If
filename is absolute, return it unchanged. If given,
extensions is a list of strings; for each directory in path,
we search for filename concatenated with each extension. If
require-exts? is true, require that the returned file name have
one of the given extensions; if require-exts? is not given, it
defaults to #f.

For compatibility with Guile 1.8 and earlier, the C function takes only
three arguments.

1.8 Character Encoding of Source Files

Scheme source code files are usually encoded in ASCII or UTF-8, but the
built-in reader can interpret other character encodings as well. When
Guile loads Scheme source code, it uses the file-encoding
procedure (described below) to try to guess the encoding of the file.
In the absence of any hints, UTF-8 is assumed. One way to provide a
hint about the encoding of a source file is to place a coding
declaration in the top 500 characters of the file.

A coding declaration has the form coding: XXXXXX, where
XXXXXX is the name of a character encoding in which the source
code file has been encoded. The coding declaration must appear in a
scheme comment. It can either be a semicolon-initiated comment, or the
first block #! comment in the file.

The name of the character encoding in the coding declaration is
typically lower case and containing only letters, numbers, and hyphens,
as recognized by set-port-encoding! (@pxref{Ports,
@code{set-port-encoding!}}). Common examples of character encoding
names are utf-8 and iso-8859-1,
as defined by IANA. Thus, the coding declaration is mostly compatible with Emacs.

However, there are some differences in encoding names recognized by
Emacs and encoding names defined by IANA, the latter being essentially a
subset of the former. For instance, latin-1 is a valid encoding
name for Emacs, but it’s not according to the IANA standard, which Guile
follows; instead, you should use iso-8859-1, which is both
understood by Emacs and dubbed by IANA (IANA writes it uppercase but
Emacs wants it lowercase and Guile is case insensitive.)

For source code, only a subset of all possible character encodings can
be interpreted by the built-in source code reader. Only those
character encodings in which ASCII text appears unmodified can be
used. This includes UTF-8 and ISO-8859-1 through
ISO-8859-15. The multi-byte character encodings UTF-16
and UTF-32 may not be used because they are not compatible with
ASCII.

There might be a scenario in which one would want to read non-ASCII
code from a port, such as with the function read, instead of
with load. If the port’s character encoding is the same as the
encoding of the code to be read by the port, not other special
handling is necessary. The port will automatically do the character
encoding conversion. The functions setlocale or by
set-port-encoding! are used to set port encodings
(@pxref{Ports}).

If a port is used to read code of unknown character encoding, it can
accomplish this in three steps. First, the character encoding of the
port should be set to ISO-8859-1 using set-port-encoding!.
Then, the procedure file-encoding, described below, is used to
scan for a coding declaration when reading from the port. As a side
effect, it rewinds the port after its scan is complete. After that,
the port’s character encoding should be set to the encoding returned
by file-encoding, if any, again by using
set-port-encoding!. Then the code can be read as normal.

Alternatively, one can use the #:guess-encoding keyword argument
of open-file and related procedures. @xref{File Ports}.

Scheme Procedure: file-encoding port

C Function: scm_file_encoding (port)

Attempt to scan the first few hundred bytes from the port for
hints about its character encoding. Return a string containing the
encoding name or #f if the encoding cannot be determined. The
port is rewound.

Currently, the only supported method is to look for an Emacs-like
character coding declaration (see how Emacs recognizes file encoding in The GNU Emacs Reference Manual). The
coding declaration is of the form coding: XXXXX and must appear
in a Scheme comment. Additional heuristics may be added in the future.

1.9 Delayed Evaluation

Promises are a convenient way to defer a calculation until its result
is actually needed, and to run such a calculation only once. Also
@pxref{SRFI-45}.

syntax: delay expr

Return a promise object which holds the given expr expression,
ready to be evaluated by a later force.

Scheme Procedure: promise? obj

C Function: scm_promise_p (obj)

Return true if obj is a promise.

Scheme Procedure: force p

C Function: scm_force (p)

Return the value obtained from evaluating the expr in the given
promise p. If p has previously been forced then its
expr is not evaluated again, instead the value obtained at that
time is simply returned.

During a force, an expr can call force again on
its own promise, resulting in a recursive evaluation of that
expr. The first evaluation to return gives the value for the
promise. Higher evaluations run to completion in the normal way, but
their results are ignored, force always returns the first
value.

Note that the current implementation of (the-environment) only
captures “normal” lexical bindings, and pattern variables bound by
syntax-case. It does not currently capture local syntax
transformers bound by let-syntax, letrec-syntax or
non-top-level define-syntax forms. Any attempt to reference such
captured syntactic keywords via local-eval or
local-compile produces an error.

1.11 Local Inclusion

This section has discussed various means of linking Scheme code
together: fundamentally, loading up files at run-time using load
and load-compiled. Guile provides another option to compose
parts of programs together at expansion-time instead of at run-time.

Scheme Syntax: include file-name

Open file-name, at expansion-time, and read the Scheme forms that
it contains, splicing them into the location of the include,
within a begin.

If file-name is a relative path, it is searched for relative to
the path that contains the file that the include for appears in.

If you are a C programmer, if load in Scheme is like
dlopen in C, consider include to be like the C
preprocessor’s #include. When you use include, it is as
if the contents of the included file were typed in instead of the
include form.

Because the code is included at compile-time, it is available to the
macroexpander. Syntax definitions in the included file are available to
later code in the form in which the include appears, without the
need for eval-when. (@xref{Eval When}.)

For the same reason, compiling a form that uses include results
in one compilation unit, composed of multiple files. Loading the
compiled file is one stat operation for the compilation unit,
instead of 2*n in the case of load (once for each
loaded source file, and once each corresponding compiled file, in the
best case).

Unlike load, include also works within nested lexical
contexts. It so happens that the optimizer works best within a lexical
context, because all of the uses of bindings in a lexical context are
visible, so composing files by including them within a (let ()
...) can sometimes lead to important speed improvements.

On the other hand, include does have all the disadvantages of
early binding: once the code with the include is compiled, no
change to the included file is reflected in the future behavior of the
including form.

Also, the particular form of include, which requires an absolute
path, or a path relative to the current directory at compile-time, is
not very amenable to compiling the source in one place, but then
installing the source to another place. For this reason, Guile provides
another form, include-from-path, which looks for the source file
to include within a load path.

Scheme Syntax: include-from-path file-name

Like include, but instead of expecting file-name to be an
absolute file name, it is expected to be a relative path to search in
the %load-path.

include-from-path is more useful when you want to install all of
the source files for a package (as you should!). It makes it possible
to evaluate an installed file from source, instead of relying on the
.go file being up to date.

1.12 REPL Servers

When an application is written in Guile, it is often convenient to
allow the user to be able to interact with it by evaluating Scheme
expressions in a REPL.

The procedures of this module allow you to spawn a REPL server,
which permits interaction over a local or TCP connection. Guile itself
uses them internally to implement the ‘--listen’ switch,
@ref{Command-line Options}.

Return a stream socket bound to a given address addr and port
number port. If the host is given, and addr is not,
then the host string is converted to an address. If neither is
given, we use the loopback address.

Create and run a REPL, making it available over the given
server-socket. If server-socket is not provided, it
defaults to the socket created by calling make-tcp-server-socket
with no arguments.

run-server runs the server in the current thread, whereas
spawn-server runs the server in a new thread.

Scheme Procedure: stop-server-and-clients!

Closes the connection on all running server sockets.

Please note that in the current implementation, the REPL threads are
cancelled without unwinding their stacks. If any of them are holding
mutexes or are within a critical section, the results are unspecified.

1.13 Cooperative REPL Servers

The procedures in this section are provided by

(use-modules (system repl coop-server))

Whereas ordinary REPL servers run in their own threads (see section REPL Servers), sometimes it is more convenient to provide REPLs that run at
specified times within an existing thread, for example in programs
utilizing an event loop or in single-threaded programs. This allows for
safe access and mutation of a program’s data structures from the REPL,
without concern for thread synchronization.

Although the REPLs are run in the thread that calls
spawn-coop-repl-server and poll-coop-repl-server,
dedicated threads are spawned so that the calling thread is not blocked.
The spawned threads read input for the REPLs and to listen for new
connections.

Cooperative REPL servers must be polled periodically to evaluate any
pending expressions by calling poll-coop-repl-server with the
object returned from spawn-coop-repl-server. The thread that
calls poll-coop-repl-server will be blocked for as long as the
expression takes to be evaluated or if the debugger is entered.

Scheme Procedure: spawn-coop-repl-server [server-socket]

Create and return a new cooperative REPL server object, and spawn a new
thread to listen for connections on server-socket. Proper
functioning of the REPL server requires that
poll-coop-repl-server be called periodically on the returned
server object.

Scheme Procedure: poll-coop-repl-server coop-server

Poll the cooperative REPL server coop-server and apply a pending
operation if there is one, such as evaluating an expression typed at the
REPL prompt. This procedure must be called from the same thread that
called spawn-coop-repl-server.