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

This chapter describes Guile functions that are concerned with reading, loading and evaluating 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).

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.

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.

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-from-path filename
     Similar to load, but searches for FILENAME in the load paths.

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

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

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

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.