Reading and Evaluating Scheme Code
==================================

This chapter describes Guile functions that are concerned with reading, loading, evaluating, and compiling Scheme code at run time.

Scheme Syntax: Standard and Guile Extensions
--------------------------------------------

Expression Syntax
.................

An expression to be evaluated takes one of the following forms.

SYMBOL
     A symbol is evaluated by dereferencing.  A binding of that symbol is sought and the value there used.  For example,

          (define x 123)
          x => 123

(PROC ARGS...)
     A parenthesised expression is a function call.  PROC and each argument are evaluated, then the function (which PROC evaluated to) is called with those arguments.

     The order in which PROC and the arguments are evaluated is unspecified, so be careful when using expressions with side effects.

          (max 1 2 3) => 3

          (define (get-some-proc)  min)
          ((get-some-proc) 1 2 3) => 1

     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 (see Macros, and see Syntax Rules).

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.

(quote DATA)
'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.  ' is simply a shorthand for a quote form. For example,

          'x                   => x
          '(1 2 3)             => (1 2 3)
          '#(1 (2 3) 4)        => #(1 (2 3) 4)
          (quote x)            => x
          (quote (1 2 3))      => (1 2 3)
          (quote #(1 (2 3) 4)) => #(1 (2 3) 4)

     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.

(quasiquote DATA)
`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.

     (unquote EXPR)
     ,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,

               `(1 2 ,(* 9 9) 3 4)      => (1 2 81 3 4)
               `(1 (unquote (+ 1 1)) 3) => (1 2 3)
               `#(1 ,(/ 12 2))          => #(1 6)

     (unquote-splicing EXPR)
     ,@EXPR
          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.

               (define x '(2 3))
               `(1 ,@x 4)                         => (1 2 3 4)
               `(1 (unquote-splicing (map 1+ x))) => (1 3 4)
               `#(9 ,@x 9)                        => #(9 2 3 9)

          Notice ,@ differs from plain , in the way one level of nesting is stripped.  For ,@ the elements of a returned list are inserted, whereas with , it would be the list itself inserted.

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.

     ; Comment
     ;; Comment too
     (define x 1)        ; Comment after expression
     (let ((y 1))
       ;; Display something.
       (display y)
     ;;; Comment at left margin.
       (display (+ y 1)))

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.

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 (see 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 (see Guile Scripting).

Similarly, Guile (starting from version 2.0) supports nested block comments as specified by R6RS and SRFI-30 (http://srfi.schemers.org/srfi-30/srfi-30.html):

     (+  #| this is a #| nested |# block comment |# 2)
     => 3

For backward compatibility, this syntax can be overridden with read-hash-extend (see 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.

Case Sensitivity
................

Scheme as defined in R5RS is not case sensitive when reading symbols. Guile, on the contrary is case sensitive by default, so the identifiers

     guile-whuzzy
     Guile-Whuzzy

are the same in R5RS Scheme, but are different in Guile.

It is possible to turn off case sensitivity in Guile by setting the reader option case-insensitive.  More on reader options can be found at (see Reader options).

     (read-enable 'case-insensitive)

Note that this is seldom a problem, because Scheme programmers tend not to use uppercase letters in their identifiers anyway.

Keyword Syntax
..............

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.

Reading Scheme Code
-------------------

 -- Scheme Procedure: read [port]
 -- C Function: scm_read (port)
     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.  For more information about options, see User level options interfaces.  If you want to know which reader options are available, see Reader options.

 -- Scheme Procedure: read-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, SETTING should be one of the following symbols:

     help
          Display the complete option settings.

     full
          Like help, but also print programmer options.

 -- Scheme Procedure: read-enable option-name
 -- Scheme Procedure: read-disable option-name
 -- Scheme Procedure: 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.

 -- Scheme Procedure: read-options-interface [setting]
 -- C Function: scm_read_options (setting)
     Option interface for the read options. Instead of using this procedure directly, use the procedures read-enable, read-disable, read-set! and read-options.

Procedures for On the Fly Evaluation
------------------------------------

See Environments.

 -- 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. While EXP is evaluated (using primitive-eval), MODULE 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.

 -- Scheme Procedure: eval-string string [module]
 -- C Function: scm_eval_string (string)
 -- C Function: scm_eval_string_in_module (string, module)
     Evaluate STRING as the text representation of a Scheme form or forms, and return whatever value they produce.  Evaluation takes place in the given module, or in the current module when no module is given. While the code is evaluated, the given module is made the current one. The current module is restored when this procedure returns.

 -- C Function: SCM scm_c_eval_string (const char *string)
     scm_eval_string, but taking a C string instead of an SCM.

 -- Scheme Procedure: apply proc arg1 ... argN 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 ARG1 ... ARGN plus the elements of the ARGLST list.

     scm_apply takes parameters corresponding to a Scheme level (lambda (proc arg . rest) ...).  So ARG and all but the last element of the REST list make up ARG1...ARGN and the last element of REST is the ARGLST list.  Or if REST is the empty list SCM_EOL then there's no ARG1...ARGN and ARG is the ARGLST.

     ARGLST is not modified, but the REST list passed to scm_apply is modified.

 -- C Function: scm_call_0 (proc)
 -- C Function: scm_call_1 (proc, arg1)
 -- C Function: scm_call_2 (proc, arg1, arg2)
 -- C Function: scm_call_3 (proc, arg1, arg2, arg3)
 -- C Function: scm_call_4 (proc, arg1, arg2, arg3, arg4)
     Call PROC with the given arguments.

 -- Scheme Procedure: apply:nconc2last lst
 -- C Function: scm_nconc2last (lst)
     LST should be a list (ARG1 ... ARGN ARGLST), 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.

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. The normal interface to the compiler is the command-line file compiler, which can be invoked from the shell as guile-tools 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.)

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

The command-line interface to Guile's compiler is the guile-tools compile command:

 -- Command: guile-tools 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.

     -W WARNING
     --warn=WARNING
          Emit warnings of type WARNING; use --warn=help for a list of available warnings.  Currently recognized warnings include unused-variable, unused-toplevel, unbound-variable, and arity-mismatch.

     -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.

The compiler can also be invoked directly by Scheme code using the procedures below:

 -- Scheme Procedure: compile exp [env=#f] [from=(current-language)] [to=value] [opts=()]
     Compile the expression EXP in the environment ENV. If EXP is a procedure, the result will be a compiled procedure; otherwise compile is mostly equivalent to eval.

     For a discussion of languages and compiler options, see Compiling to the Virtual Machine.

 -- Scheme Procedure: compile-file file [to=objcode] [opts='()]
     Compile the file named FILE.

     Output will be written to a file in the current directory whose name is computed as (compiled-file-name FILE).

 -- Scheme Procedure: compiled-file-name file
     Compute an appropriate name for a compiled version of a Scheme file named FILE.

     Usually, the result will be the original file name with the .scm suffix replaced with .go, but the exact behavior depends on the contents of the %load-extensions and %load-compiled-extensions lists.

Loading Scheme Code from File
-----------------------------

 -- Scheme Procedure: load filename [reader]
     Load FILENAME and evaluate its contents in the top-level environment.  The load paths are not searched.

     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 Scheme Read).

     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. The load paths are not searched.

     Compiling a source file (see Read/Load/Eval/Compile) and then calling load-compiled on the resulting file is equivalent to calling load on the source file.

 -- 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.

 -- 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. The load paths are not searched; 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: SCM scm_c_primitive_load (const char *filename)
     scm_primitive_load, but taking a C string instead of an SCM.

 -- Scheme Procedure: primitive-load-path filename [exception-on-not-found]
 -- C Function: scm_primitive_load_path (filename)
     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.

     By default or if EXCEPTION-ON-NOT-FOUND is true, an exception is raised if FILENAME is not found.  If EXCEPTION-ON-NOT-FOUND is #f and FILENAME is not found, no exception is raised and #f is returned.  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: 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! (see 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 above loading functions (load, load-path, primitive-load and primitive-load-path).

     For example an application can set this to show what's loaded,

          (set! %load-hook (lambda (filename)
                             (format #t "Loading ~a ...\n" filename)))
          (load-from-path "foo.scm")
          -| Loading /usr/local/share/guile/site/foo.scm ...

 -- Scheme Procedure: current-load-port
 -- C Function: scm_current_load_port ()
     Return the current-load-port. The load port is used internally by primitive-load.

 -- 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").

Character Encoding of Source Files
----------------------------------

Scheme source code files are usually encoded in ASCII, but, the built-in reader can interpret other character encodings.  The procedure primitive-load, and by extension the functions that call it, such as load, first scan the top 500 characters of the file for a coding declaration.

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 a block #! comment.

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! (see set-port-encoding!).  Common examples of character encoding names are utf-8 and iso-8859-1, as defined by IANA (http://www.iana.org/assignments/character-sets).  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 (see 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.

 -- Scheme Procedure: file-encoding port
 -- C Function: scm_file_encoding port
     Scan the port for an Emacs-like character coding declaration near the top of the contents of a port with random-accessible contents (see how Emacs recognizes file encoding (The GNU Emacs Reference Manual)).  The coding declaration is of the form coding: XXXXX and must appear in a Scheme comment.  Return a string containing the character encoding of the file if a declaration was found, or #f otherwise.  The port is rewound.

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.

 -- 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.

Local Evaluation
----------------

[the-environment]

 -- Scheme Procedure: local-eval exp [env]
 -- C Function: scm_local_eval (exp, env)
     Evaluate EXP in its environment.  If ENV is supplied, it is the environment in which to evaluate EXP.  Otherwise, EXP must be a memoized code object (in which case, its environment is implicit).

Evaluator Behaviour
-------------------

The behaviour of Guile's evaluator can be modified by manipulating the evaluator options.  For more information about options, see User level options interfaces.  If you want to know which evaluator options are available, see Evaluator options.

 -- Scheme Procedure: eval-options [setting]
     Display the current settings of the evaluator options.  If SETTING is omitted, only a short form of the current evaluator options is printed.  Otherwise, SETTING should be one of the following symbols:

     help
          Display the complete option settings.

     full
          Like help, but also print programmer options.

 -- Scheme Procedure: eval-enable option-name
 -- Scheme Procedure: eval-disable option-name
 -- Scheme Procedure: eval-set! option-name value
     Modify the evaluator options.  eval-enable should be used with boolean options and switches them on, eval-disable switches them off. eval-set! can be used to set an option to a specific value.

 -- Scheme Procedure: eval-options-interface [setting]
 -- C Function: scm_eval_options_interface (setting)
     Option interface for the evaluation options. Instead of using this procedure directly, use the procedures eval-enable, eval-disable, eval-set! and eval-options.

 -- Scheme Procedure: traps [setting]
     Display the current settings of the evaluator traps options.  If SETTING is omitted, only a short form of the current evaluator traps options is printed.  Otherwise, SETTING should be one of the following symbols:

     help
          Display the complete option settings.

     full
          Like help, but also print programmer options.

 -- Scheme Procedure: trap-enable option-name
 -- Scheme Procedure: trap-disable option-name
 -- Scheme Procedure: trap-set! option-name value
     Modify the evaluator options.  trap-enable should be used with boolean options and switches them on, trap-disable switches them off. trap-set! can be used to set an option to a specific value.

     See Evaluator trap options for more information on the available trap handlers.

 -- Scheme Procedure: evaluator-traps-interface [setting]
 -- C Function: scm_evaluator_traps (setting)
     Option interface for the evaluator trap options.

VM Behaviour
------------

Like the procedures from the previous section that operate on the evaluator, there are also procedures to modify the behavior of a virtual machine.

The most useful thing that a user can do is to add to one of the virtual machine's predefined hooks:

 -- Scheme Procedure: vm-next-hook vm
 -- Scheme Procedure: vm-apply-hook vm
 -- Scheme Procedure: vm-boot-hook vm
 -- Scheme Procedure: vm-return-hook vm
 -- Scheme Procedure: vm-break-hook vm
 -- Scheme Procedure: vm-exit-hook vm
 -- Scheme Procedure: vm-halt-hook vm
 -- Scheme Procedure: vm-enter-hook vm
     Accessors to a virtual machine's hooks. Usually you pass (the-vm) as the VM.

 -- Scheme Procedure: vm-trace-level vm
     Retrieve the ``trace level'' of the VM. If positive, the trace hooks associated with VM will be run. The initial trace level is 0.

 -- Scheme Procedure: set-vm-trace-level! vm level
     Set the ``trace level'' of the VM.

See A Virtual Machine for Guile, for more information on Guile's virtual machine.