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

Comments
--------

Block Comments
--------------

Case Sensitivity
----------------

Keyword Syntax
--------------

Reader Extensions
-----------------

 -- primitive: 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
===================

 -- primitive: 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 General option interface.  If you want to know which reader options are available, see Reader options.

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

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

 -- primitive: read-options-interface [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
====================================

 -- primitive: eval exp environment
     Evaluate EXP, a list representing a Scheme expression, in the environment given by ENVIRONMENT SPECIFIER.

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

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

 -- primitive: apply: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.

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

 -- primitive: primitive-eval exp
     Evaluate EXP in the top-level environment specified by the current module.

 -- primitive: eval2 obj env_thunk
     Evaluate EXP, a Scheme expression, in the environment designated by LOOKUP, a symbol-lookup function." Do not use this version of eval, it does not play well with the module system.  Use eval or primitive-eval instead.

 -- primitive: read-and-eval! [port]
     Read a form from PORT (standard input by default), and evaluate it (memoizing it in the process) in the top-level environment.  If no data is left to be read from PORT, an end-of-file error is signalled.

Loading Scheme Code from File
=============================

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

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

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

 -- primitive: %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....

 -- primitive: 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
==================

[delay]

 -- primitive: promise? obj
     Return true if OBJ is a promise, i.e. a delayed computation (see Delayed evaluation (The Revised^4 Report on Scheme)).

 -- primitive: force x
     If the promise X has not been computed yet, compute and return X, otherwise just return the previously computed value.

Local Evaluation
================

[the-environment]

 -- primitive: 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 General option interface.  If you want to know which reader options are available, see Evaluator options.

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

 -- procedure: eval-enable option-name
 -- procedure: eval-disable option-name
 -- 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.

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

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

 -- procedure: trap-enable option-name
 -- procedure: trap-disable option-name
 -- 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.

 -- primitive: evaluator-traps-interface [setting]
     Option interface for the evaluator trap options.