doc/ref/scheme-evaluation.texi

   1 @page
   2 @node Read/Load/Eval
   3 @chapter Reading and Evaluating Scheme Code
   4
   5 This chapter describes Guile functions that are concerned with reading,
   6 loading and evaluating Scheme code at run time.
   7
   8 @menu
   9 * Scheme Syntax::               Standard and extended Scheme syntax.
  10 * Scheme Read::                 Reading Scheme code.
  11 * Fly Evaluation::              Procedures for on the fly evaluation.
  12 * Loading::                     Loading Scheme code from file.
  13 * Delayed Evaluation::          Postponing evaluation until it is needed.
  14 * Local Evaluation::            Evaluation in a local environment.
  15 * Evaluator Behaviour::         Modifying Guile's evaluator.
  16 @end menu
  17
  18
  19 @node Scheme Syntax
  20 @section Scheme Syntax: Standard and Guile Extensions
  21
  22 @menu
  23 * Expression Syntax::
  24 * Comments::
  25 * Block Comments::
  26 * Case Sensitivity::
  27 * Keyword Syntax::
  28 * Reader Extensions::
  29 @end menu
  30
  31
  32 @node Expression Syntax
  33 @subsection Expression Syntax
  34
  35
  36 @node Comments
  37 @subsection Comments
  38
  39 @c FIXME::martin: Review me!
  40
  41 Comments in Scheme source files are written by starting them with a
  42 semicolon character (@code{;}).  The comment then reaches up to the end
  43 of the line.  Comments can begin at any column, and the may be inserted
  44 on the same line as Scheme code.
  45
  46 @lisp
  47 ; Comment
  48 ;; Comment too
  49 (define x 1)        ; Comment after expression
  50 (let ((y 1))
  51   ;; Display something.
  52   (display y)
  53 ;;; Comment at left margin.
  54   (display (+ y 1)))
  55 @end lisp
  56
  57 It is common to use a single semicolon for comments following
  58 expressions on a line, to use two semicolons for comments which are
  59 indented like code, and three semicolons for comments which start at
  60 column 0, even if they are inside an indented code block.  This
  61 convention is used when indenting code in Emacs' Scheme mode.
  62
  63
  64 @node Block Comments
  65 @subsection Block Comments
  66
  67 @c FIXME::martin: Review me!
  68
  69 @cindex multiline comments
  70 In addition to the standard line comments defined by R5RS, Guile has
  71 another comment type for multiline comments, called @dfn{block
  72 comments}.  This type of comment begins with the character sequence
  73 @code{#!} and ends with the characters @code{!#}, which must appear on a
  74 line of their own.  These comments are compatible with the block
  75 comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
  76 (scsh)}).  The characters @code{#!} were chosen because they are the
  77 magic characters used in shell scripts for indicating that the name of
  78 the program for executing the script follows on the same line.
  79
  80 Thus a Guile script often starts like this.
  81
  82 @lisp
  83 #! /usr/local/bin/guile -s
  84 !#
  85 @end lisp
  86
  87 More details on Guile scripting can be found in the scripting section
  88 (@pxref{Guile Scripting}).
  89
  90
  91 @node Case Sensitivity
  92 @subsection Case Sensitivity
  93
  94 @c FIXME::martin: Review me!
  95
  96 Scheme as defined in R5RS is not case sensitive when reading symbols.
  97 Guile, on the contrary is case sensitive by default, so the identifiers
  98
  99 @lisp
 100 guile-whuzzy
 101 Guile-Whuzzy
 102 @end lisp
 103
 104 are the same in R5RS Scheme, but are different in Guile.
 105
 106 It is possible to turn off case sensitivity in Guile by setting the
 107 reader option @code{case-insensitive}.  More on reader options can be
 108 found at (@pxref{Reader options}).
 109
 110 @lisp
 111 (read-enable 'case-insensitive)
 112 @end lisp
 113
 114 Note that this is seldom a problem, because Scheme programmers tend not
 115 to use uppercase letters in their identifiers anyway.
 116
 117
 118 @node Keyword Syntax
 119 @subsection Keyword Syntax
 120
 121
 122 @node Reader Extensions
 123 @subsection Reader Extensions
 124
 125 @deffn {Scheme Procedure} read-hash-extend chr proc
 126 @deffnx {C Function} scm_read_hash_extend (chr, proc)
 127 Install the procedure @var{proc} for reading expressions
 128 starting with the character sequence @code{#} and @var{chr}.
 129 @var{proc} will be called with two arguments:  the character
 130 @var{chr} and the port to read further data from. The object
 131 returned will be the return value of @code{read}.
 132 @end deffn
 133
 134
 135 @node Scheme Read
 136 @section Reading Scheme Code
 137
 138 @rnindex read
 139 @deffn {Scheme Procedure} read [port]
 140 @deffnx {C Function} scm_read (port)
 141 Read an s-expression from the input port @var{port}, or from
 142 the current input port if @var{port} is not specified.
 143 Any whitespace before the next token is discarded.
 144 @end deffn
 145
 146 The behaviour of Guile's Scheme reader can be modified by manipulating
 147 its read options.  For more information about options, @xref{General
 148 option interface}.  If you want to know which reader options are
 149 available, @xref{Reader options}.
 150
 151 @c FIXME::martin: This is taken from libguile/options.c.  Is there
 152 @c actually a difference between 'help and 'full?
 153
 154 @deffn {Scheme Procedure} read-options [setting]
 155 Display the current settings of the read options.  If @var{setting} is
 156 omitted, only a short form of the current read options is printed.
 157 Otherwise, @var{setting} should be one of the following symbols:
 158 @table @code
 159 @item help
 160 Display the complete option settings.
 161 @item full
 162 Like @code{help}, but also print programmer options.
 163 @end table
 164 @end deffn
 165
 166 @deffn {Scheme Procedure} read-enable option-name
 167 @deffnx {Scheme Procedure} read-disable option-name
 168 @deffnx {Scheme Procedure} read-set! option-name value
 169 Modify the read options.  @code{read-enable} should be used with boolean
 170 options and switches them on, @code{read-disable} switches them off.
 171 @code{read-set!} can be used to set an option to a specific value.
 172 @end deffn
 173
 174 @deffn {Scheme Procedure} read-options-interface [setting]
 175 @deffnx {C Function} scm_read_options (setting)
 176 Option interface for the read options. Instead of using
 177 this procedure directly, use the procedures @code{read-enable},
 178 @code{read-disable}, @code{read-set!} and @var{read-options}.
 179 @end deffn
 180
 181
 182 @node Fly Evaluation
 183 @section Procedures for On the Fly Evaluation
 184
 185 @rnindex eval
 186 @c ARGFIXME environment/environment specifier
 187 @deffn {Scheme Procedure} eval exp module
 188 @deffnx {C Function} scm_eval (exp, module)
 189 Evaluate @var{exp}, a list representing a Scheme expression,
 190 in the top-level environment specified by @var{module}.
 191 While @var{exp} is evaluated (using @code{primitive-eval}),
 192 @var{module} is made the current module.  The current module
 193 is reset to its previous value when @var{eval} returns.
 194 @end deffn
 195
 196 @rnindex interaction-environment
 197 @deffn {Scheme Procedure} interaction-environment
 198 @deffnx {C Function} scm_interaction_environment ()
 199 Return a specifier for the environment that contains
 200 implementation--defined bindings, typically a superset of those
 201 listed in the report.  The intent is that this procedure will
 202 return the environment in which the implementation would
 203 evaluate expressions dynamically typed by the user.
 204 @end deffn
 205
 206 @deffn {Scheme Procedure} eval-string string
 207 @deffnx {C Function} scm_eval_string (string)
 208 Evaluate @var{string} as the text representation of a Scheme
 209 form or forms, and return whatever value they produce.
 210 Evaluation takes place in the environment returned by the
 211 procedure @code{interaction-environment}.
 212 @end deffn
 213
 214 @deffn {Scheme Procedure} apply:nconc2last lst
 215 @deffnx {C Function} scm_nconc2last (lst)
 216 Given a list (@var{arg1} @dots{} @var{args}), this function
 217 conses the @var{arg1} @dots{} arguments onto the front of
 218 @var{args}, and returns the resulting list. Note that
 219 @var{args} is a list; thus, the argument to this function is
 220 a list whose last element is a list.
 221 Note: Rather than do new consing, @code{apply:nconc2last}
 222 destroys its argument, so use with care.
 223 @end deffn
 224
 225 @rnindex apply
 226 @deffn {Scheme Procedure} apply proc arg1 @dots{} args
 227 @var{proc} must be a procedure and @var{args} must be a list.  Call
 228 @var{proc} with the elements of the list @code{(append (list @var{arg1}
 229 @dots{}) @var{args})} as the actual arguments.
 230 @end deffn
 231
 232 @deffn {Scheme Procedure} primitive-eval exp
 233 @deffnx {C Function} scm_primitive_eval (exp)
 234 Evaluate @var{exp} in the top-level environment specified by
 235 the current module.
 236 @end deffn
 237
 238
 239 @node Loading
 240 @section Loading Scheme Code from File
 241
 242 @rnindex load
 243 @deffn {Scheme Procedure} load filename
 244 Load @var{filename} and evaluate its contents in the top-level
 245 environment.  The load paths are not searched.  If the variable
 246 @code{%load-hook} is defined, it should be bound to a procedure that
 247 will be called before any code is loaded.  See documentation for
 248 @code{%load-hook} later in this section.
 249 @end deffn
 250
 251 @deffn {Scheme Procedure} load-from-path filename
 252 Similar to @code{load}, but searches for @var{filename} in the load
 253 paths.
 254 @end deffn
 255
 256 @deffn {Scheme Procedure} primitive-load filename
 257 @deffnx {C Function} scm_primitive_load (filename)
 258 Load the file named @var{filename} and evaluate its contents in
 259 the top-level environment. The load paths are not searched;
 260 @var{filename} must either be a full pathname or be a pathname
 261 relative to the current directory.  If the  variable
 262 @code{%load-hook} is defined, it should be bound to a procedure
 263 that will be called before any code is loaded.  See the
 264 documentation for @code{%load-hook} later in this section.
 265 @end deffn
 266
 267 @deffn {Scheme Procedure} primitive-load-path filename
 268 @deffnx {C Function} scm_primitive_load_path (filename)
 269 Search @var{%load-path} for the file named @var{filename} and
 270 load it into the top-level environment.  If @var{filename} is a
 271 relative pathname and is not found in the list of search paths,
 272 an error is signalled.
 273 @end deffn
 274
 275 @deffn {Scheme Procedure} %search-load-path filename
 276 @deffnx {C Function} scm_sys_search_load_path (filename)
 277 Search @var{%load-path} for the file named @var{filename},
 278 which must be readable by the current user.  If @var{filename}
 279 is found in the list of paths to search or is an absolute
 280 pathname, return its full pathname.  Otherwise, return
 281 @code{#f}.  Filenames may have any of the optional extensions
 282 in the @code{%load-extensions} list; @code{%search-load-path}
 283 will try each extension automatically.
 284 @end deffn
 285
 286 @defvar %load-hook
 287 A procedure to be run whenever @code{primitive-load} is called.  If this
 288 procedure is defined, it will be called with the filename argument that
 289 was passed to @code{primitive-load}.
 290
 291 @example
 292 (define %load-hook (lambda (file)
 293                      (display "Loading ")
 294                      (display file)
 295                      (write-line "...."))) @result{} undefined
 296 (load-from-path "foo.scm")
 297 @print{} Loading /usr/local/share/guile/site/foo.scm....
 298 @end example
 299
 300 @end defvar
 301
 302 @deffn {Scheme Procedure} current-load-port
 303 @deffnx {C Function} scm_current_load_port ()
 304 Return the current-load-port.
 305 The load port is used internally by @code{primitive-load}.
 306 @end deffn
 307
 308 @defvar %load-extensions
 309 A list of default file extensions for files containing Scheme code.
 310 @code{%search-load-path} tries each of these extensions when looking for
 311 a file to load.  By default, @code{%load-extensions} is bound to the
 312 list @code{("" ".scm")}.
 313 @end defvar
 314
 315
 316 @node Delayed Evaluation
 317 @section Delayed Evaluation
 318
 319 [delay]
 320
 321 @deffn {Scheme Procedure} promise? obj
 322 @deffnx {C Function} scm_promise_p (obj)
 323 Return true if @var{obj} is a promise, i.e. a delayed computation
 324 (@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
 325 @end deffn
 326
 327 @rnindex force
 328 @deffn {Scheme Procedure} force x
 329 @deffnx {C Function} scm_force (x)
 330 If the promise @var{x} has not been computed yet, compute and
 331 return @var{x}, otherwise just return the previously computed
 332 value.
 333 @end deffn
 334
 335
 336 @node Local Evaluation
 337 @section Local Evaluation
 338
 339 [the-environment]
 340
 341 @deffn {Scheme Procedure} local-eval exp [env]
 342 @deffnx {C Function} scm_local_eval (exp, env)
 343 Evaluate @var{exp} in its environment.  If @var{env} is supplied,
 344 it is the environment in which to evaluate @var{exp}.  Otherwise,
 345 @var{exp} must be a memoized code object (in which case, its environment
 346 is implicit).
 347 @end deffn
 348
 349
 350 @node Evaluator Behaviour
 351 @section Evaluator Behaviour
 352
 353 @c FIXME::martin: Maybe this node name is bad, but the old name clashed with
 354 @c `Evaluator options' under `Options and Config'.
 355
 356 The behaviour of Guile's evaluator can be modified by manipulating the
 357 evaluator options.  For more information about options, @xref{General
 358 option interface}.  If you want to know which evaluator options are
 359 available, @xref{Evaluator options}.
 360
 361 @c FIXME::martin: This is taken from libguile/options.c.  Is there
 362 @c actually a difference between 'help and 'full?
 363
 364 @deffn {Scheme Procedure} eval-options [setting]
 365 Display the current settings of the evaluator options.  If @var{setting}
 366 is omitted, only a short form of the current evaluator options is
 367 printed.  Otherwise, @var{setting} should be one of the following
 368 symbols:
 369 @table @code
 370 @item help
 371 Display the complete option settings.
 372 @item full
 373 Like @code{help}, but also print programmer options.
 374 @end table
 375 @end deffn
 376
 377 @deffn {Scheme Procedure} eval-enable option-name
 378 @deffnx {Scheme Procedure} eval-disable option-name
 379 @deffnx {Scheme Procedure} eval-set! option-name value
 380 Modify the evaluator options.  @code{eval-enable} should be used with boolean
 381 options and switches them on, @code{eval-disable} switches them off.
 382 @code{eval-set!} can be used to set an option to a specific value.
 383 @end deffn
 384
 385 @deffn {Scheme Procedure} eval-options-interface [setting]
 386 @deffnx {C Function} scm_eval_options_interface (setting)
 387 Option interface for the evaluation options. Instead of using
 388 this procedure directly, use the procedures @code{eval-enable},
 389 @code{eval-disable}, @code{eval-set!} and @var{eval-options}.
 390 @end deffn
 391
 392 @c FIXME::martin: Why aren't these procedure named like the other options
 393 @c procedures?
 394
 395 @deffn {Scheme Procedure} traps [setting]
 396 Display the current settings of the evaluator traps options.  If
 397 @var{setting} is omitted, only a short form of the current evaluator
 398 traps options is printed.  Otherwise, @var{setting} should be one of the
 399 following symbols:
 400 @table @code
 401 @item help
 402 Display the complete option settings.
 403 @item full
 404 Like @code{help}, but also print programmer options.
 405 @end table
 406 @end deffn
 407
 408 @deffn {Scheme Procedure} trap-enable option-name
 409 @deffnx {Scheme Procedure} trap-disable option-name
 410 @deffnx {Scheme Procedure} trap-set! option-name value
 411 Modify the evaluator options.  @code{trap-enable} should be used with boolean
 412 options and switches them on, @code{trap-disable} switches them off.
 413 @code{trap-set!} can be used to set an option to a specific value.
 414 @end deffn
 415
 416 @deffn {Scheme Procedure} evaluator-traps-interface [setting]
 417 @deffnx {C Function} scm_evaluator_traps (setting)
 418 Option interface for the evaluator trap options.
 419 @end deffn
 420
 421
 422 @c Local Variables:
 423 @c TeX-master: "guile.texi"
 424 @c End: