28. Reading and Evaluating Scheme Code

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

28.1 Scheme Syntax: Standard and Guile Extensions		Standard and extended Scheme syntax.
28.2 Reading Scheme Code		Reading Scheme code.
28.3 Procedures for On the Fly Evaluation		Procedures for on the fly evaluation.
28.4 Loading Scheme Code from File		Loading Scheme code from file.
28.5 Delayed Evaluation		Postponing evaluation until it is needed.
28.6 Local Evaluation		Evaluation in a local environment.
28.7 Evaluator Behaviour		Modifying Guile's evaluator.

28.1 Scheme Syntax: Standard and Guile Extensions

28.1.1 Expression Syntax
28.1.2 Comments
28.1.3 Block Comments
28.1.4 Case Sensitivity
28.1.5 Keyword Syntax
28.1.6 Reader Extensions

28.1.1 Expression Syntax

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

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

28.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' (see section 46. 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 section 9. Guile Scripting).

28.1.4 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 section 33.2 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.

28.1.5 Keyword Syntax

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

28.2 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 section 33.1 General option interface. If you want to know which reader options are available, See section 33.2 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.

28.3 Procedures for On the Fly Evaluation

See section 31.2 Environments.

Scheme Procedure: eval exp module

C Function: scm_eval (exp, module)

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.

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

C Function: scm_eval_string (string)

Evaluate string as the text representation of a Scheme form or forms, and return whatever value they produce. Evaluation takes place in the environment returned by the procedure interaction-environment.

Scheme Procedure: apply:nconc2last lst

C Function: scm_nconc2last (lst)

Given a list (arg1 ... args), this function conses the arg1 ... arguments onto the front of args, and returns the resulting list. Note that args is a list; thus, the argument to this function is a list whose last element is a list. Note: Rather than do new consing, apply:nconc2last destroys its argument, so use with care.

Scheme Procedure: apply proc arg1 ... args

proc must be a procedure and args must be a list. Call proc with the elements of the list (append (list arg1 ...) args) as the actual arguments.

Scheme Procedure: primitive-eval exp

C Function: scm_primitive_eval (exp)

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

28.4 Loading Scheme Code from File

Scheme Procedure: load filename

Load filename and evaluate its contents in the top-level environment. The load paths are not searched. 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.

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: %load-hook

A procedure to be run whenever primitive-load is called. If this procedure is defined, it will be called with the filename argument that was passed to primitive-load.

(define %load-hook (lambda (file) (display "Loading ") (display file) (write-line "...."))) => undefined (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").

28.5 Delayed Evaluation

[delay]

Scheme Procedure: promise? obj

C Function: scm_promise_p (obj)

Return true if obj is a promise, i.e. a delayed computation (see section `Delayed evaluation' in The Revised^5 Report on Scheme).

Scheme Procedure: force x

C Function: scm_force (x)

If the promise x has not been computed yet, compute and return x, otherwise just return the previously computed value.

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

28.7 Evaluator Behaviour

The behaviour of Guile's evaluator can be modified by manipulating the evaluator options. For more information about options, See section 33.1 General option interface. If you want to know which evaluator options are available, See section 33.4 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.

Scheme Procedure: evaluator-traps-interface [setting]

C Function: scm_evaluator_traps (setting)

Option interface for the evaluator trap options.