| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Guile Reference Manual. |
| 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010 |
| 4 | @c Free Software Foundation, Inc. |
| 5 | @c See the file guile.texi for copying conditions. |
| 6 | |
| 7 | @node Read/Load/Eval/Compile |
| 8 | @section Reading and Evaluating Scheme Code |
| 9 | |
| 10 | This chapter describes Guile functions that are concerned with reading, |
| 11 | loading, evaluating, and compiling Scheme code at run time. |
| 12 | |
| 13 | @menu |
| 14 | * Scheme Syntax:: Standard and extended Scheme syntax. |
| 15 | * Scheme Read:: Reading Scheme code. |
| 16 | * Scheme Write:: Writing Scheme values to a port. |
| 17 | * Fly Evaluation:: Procedures for on the fly evaluation. |
| 18 | * Compilation:: How to compile Scheme files and procedures. |
| 19 | * Loading:: Loading Scheme code from file. |
| 20 | * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file. |
| 21 | * Delayed Evaluation:: Postponing evaluation until it is needed. |
| 22 | @end menu |
| 23 | |
| 24 | |
| 25 | @node Scheme Syntax |
| 26 | @subsection Scheme Syntax: Standard and Guile Extensions |
| 27 | |
| 28 | @menu |
| 29 | * Expression Syntax:: |
| 30 | * Comments:: |
| 31 | * Block Comments:: |
| 32 | * Case Sensitivity:: |
| 33 | * Keyword Syntax:: |
| 34 | * Reader Extensions:: |
| 35 | @end menu |
| 36 | |
| 37 | |
| 38 | @node Expression Syntax |
| 39 | @subsubsection Expression Syntax |
| 40 | |
| 41 | An expression to be evaluated takes one of the following forms. |
| 42 | |
| 43 | @table @nicode |
| 44 | |
| 45 | @item @var{symbol} |
| 46 | A symbol is evaluated by dereferencing. A binding of that symbol is |
| 47 | sought and the value there used. For example, |
| 48 | |
| 49 | @example |
| 50 | (define x 123) |
| 51 | x @result{} 123 |
| 52 | @end example |
| 53 | |
| 54 | @item (@var{proc} @var{args}@dots{}) |
| 55 | A parenthesised expression is a function call. @var{proc} and each |
| 56 | argument are evaluated, then the function (which @var{proc} evaluated |
| 57 | to) is called with those arguments. |
| 58 | |
| 59 | The order in which @var{proc} and the arguments are evaluated is |
| 60 | unspecified, so be careful when using expressions with side effects. |
| 61 | |
| 62 | @example |
| 63 | (max 1 2 3) @result{} 3 |
| 64 | |
| 65 | (define (get-some-proc) min) |
| 66 | ((get-some-proc) 1 2 3) @result{} 1 |
| 67 | @end example |
| 68 | |
| 69 | The same sort of parenthesised form is used for a macro invocation, |
| 70 | but in that case the arguments are not evaluated. See the |
| 71 | descriptions of macros for more on this (@pxref{Macros}, and |
| 72 | @pxref{Syntax Rules}). |
| 73 | |
| 74 | @item @var{constant} |
| 75 | Number, string, character and boolean constants evaluate ``to |
| 76 | themselves'', so can appear as literals. |
| 77 | |
| 78 | @example |
| 79 | 123 @result{} 123 |
| 80 | 99.9 @result{} 99.9 |
| 81 | "hello" @result{} "hello" |
| 82 | #\z @result{} #\z |
| 83 | #t @result{} #t |
| 84 | @end example |
| 85 | |
| 86 | Note that an application must not attempt to modify literal strings, |
| 87 | since they may be in read-only memory. |
| 88 | |
| 89 | @item (quote @var{data}) |
| 90 | @itemx '@var{data} |
| 91 | @findex quote |
| 92 | @findex ' |
| 93 | Quoting is used to obtain a literal symbol (instead of a variable |
| 94 | reference), a literal list (instead of a function call), or a literal |
| 95 | vector. @nicode{'} is simply a shorthand for a @code{quote} form. |
| 96 | For example, |
| 97 | |
| 98 | @example |
| 99 | 'x @result{} x |
| 100 | '(1 2 3) @result{} (1 2 3) |
| 101 | '#(1 (2 3) 4) @result{} #(1 (2 3) 4) |
| 102 | (quote x) @result{} x |
| 103 | (quote (1 2 3)) @result{} (1 2 3) |
| 104 | (quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4) |
| 105 | @end example |
| 106 | |
| 107 | Note that an application must not attempt to modify literal lists or |
| 108 | vectors obtained from a @code{quote} form, since they may be in |
| 109 | read-only memory. |
| 110 | |
| 111 | @item (quasiquote @var{data}) |
| 112 | @itemx `@var{data} |
| 113 | @findex quasiquote |
| 114 | @findex ` |
| 115 | Backquote quasi-quotation is like @code{quote}, but selected |
| 116 | sub-expressions are evaluated. This is a convenient way to construct |
| 117 | a list or vector structure most of which is constant, but at certain |
| 118 | points should have expressions substituted. |
| 119 | |
| 120 | The same effect can always be had with suitable @code{list}, |
| 121 | @code{cons} or @code{vector} calls, but quasi-quoting is often easier. |
| 122 | |
| 123 | @table @nicode |
| 124 | |
| 125 | @item (unquote @var{expr}) |
| 126 | @itemx ,@var{expr} |
| 127 | @findex unquote |
| 128 | @findex , |
| 129 | Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates |
| 130 | an expression to be evaluated and inserted. The comma syntax @code{,} |
| 131 | is simply a shorthand for an @code{unquote} form. For example, |
| 132 | |
| 133 | @example |
| 134 | `(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4) |
| 135 | `(1 (unquote (+ 1 1)) 3) @result{} (1 2 3) |
| 136 | `#(1 ,(/ 12 2)) @result{} #(1 6) |
| 137 | @end example |
| 138 | |
| 139 | @item (unquote-splicing @var{expr}) |
| 140 | @itemx ,@@@var{expr} |
| 141 | @findex unquote-splicing |
| 142 | @findex ,@@ |
| 143 | Within the quasiquote @var{data}, @code{unquote-splicing} or |
| 144 | @code{,@@} indicates an expression to be evaluated and the elements of |
| 145 | the returned list inserted. @var{expr} must evaluate to a list. The |
| 146 | ``comma-at'' syntax @code{,@@} is simply a shorthand for an |
| 147 | @code{unquote-splicing} form. |
| 148 | |
| 149 | @example |
| 150 | (define x '(2 3)) |
| 151 | `(1 ,@@x 4) @result{} (1 2 3 4) |
| 152 | `(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4) |
| 153 | `#(9 ,@@x 9) @result{} #(9 2 3 9) |
| 154 | @end example |
| 155 | |
| 156 | Notice @code{,@@} differs from plain @code{,} in the way one level of |
| 157 | nesting is stripped. For @code{,@@} the elements of a returned list |
| 158 | are inserted, whereas with @code{,} it would be the list itself |
| 159 | inserted. |
| 160 | @end table |
| 161 | |
| 162 | @c |
| 163 | @c FIXME: What can we say about the mutability of a quasiquote |
| 164 | @c result? R5RS doesn't seem to specify anything, though where it |
| 165 | @c says backquote without commas is the same as plain quote then |
| 166 | @c presumably the "fixed" portions of a quasiquote expression must be |
| 167 | @c treated as immutable. |
| 168 | @c |
| 169 | |
| 170 | @end table |
| 171 | |
| 172 | |
| 173 | @node Comments |
| 174 | @subsubsection Comments |
| 175 | |
| 176 | @c FIXME::martin: Review me! |
| 177 | |
| 178 | Comments in Scheme source files are written by starting them with a |
| 179 | semicolon character (@code{;}). The comment then reaches up to the end |
| 180 | of the line. Comments can begin at any column, and the may be inserted |
| 181 | on the same line as Scheme code. |
| 182 | |
| 183 | @lisp |
| 184 | ; Comment |
| 185 | ;; Comment too |
| 186 | (define x 1) ; Comment after expression |
| 187 | (let ((y 1)) |
| 188 | ;; Display something. |
| 189 | (display y) |
| 190 | ;;; Comment at left margin. |
| 191 | (display (+ y 1))) |
| 192 | @end lisp |
| 193 | |
| 194 | It is common to use a single semicolon for comments following |
| 195 | expressions on a line, to use two semicolons for comments which are |
| 196 | indented like code, and three semicolons for comments which start at |
| 197 | column 0, even if they are inside an indented code block. This |
| 198 | convention is used when indenting code in Emacs' Scheme mode. |
| 199 | |
| 200 | |
| 201 | @node Block Comments |
| 202 | @subsubsection Block Comments |
| 203 | @cindex multiline comments |
| 204 | @cindex block comments |
| 205 | @cindex #! |
| 206 | @cindex !# |
| 207 | |
| 208 | @c FIXME::martin: Review me! |
| 209 | |
| 210 | In addition to the standard line comments defined by R5RS, Guile has |
| 211 | another comment type for multiline comments, called @dfn{block |
| 212 | comments}. This type of comment begins with the character sequence |
| 213 | @code{#!} and ends with the characters @code{!#}, which must appear on a |
| 214 | line of their own. These comments are compatible with the block |
| 215 | comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell |
| 216 | (scsh)}). The characters @code{#!} were chosen because they are the |
| 217 | magic characters used in shell scripts for indicating that the name of |
| 218 | the program for executing the script follows on the same line. |
| 219 | |
| 220 | Thus a Guile script often starts like this. |
| 221 | |
| 222 | @lisp |
| 223 | #! /usr/local/bin/guile -s |
| 224 | !# |
| 225 | @end lisp |
| 226 | |
| 227 | More details on Guile scripting can be found in the scripting section |
| 228 | (@pxref{Guile Scripting}). |
| 229 | |
| 230 | @cindex R6RS block comments |
| 231 | @cindex SRFI-30 block comments |
| 232 | Similarly, Guile (starting from version 2.0) supports nested block |
| 233 | comments as specified by R6RS and |
| 234 | @url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}: |
| 235 | |
| 236 | @lisp |
| 237 | (+ #| this is a #| nested |# block comment |# 2) |
| 238 | @result{} 3 |
| 239 | @end lisp |
| 240 | |
| 241 | For backward compatibility, this syntax can be overridden with |
| 242 | @code{read-hash-extend} (@pxref{Reader Extensions, |
| 243 | @code{read-hash-extend}}). |
| 244 | |
| 245 | There is one special case where the contents of a comment can actually |
| 246 | affect the interpretation of code. When a character encoding |
| 247 | declaration, such as @code{coding: utf-8} appears in one of the first |
| 248 | few lines of a source file, it indicates to Guile's default reader |
| 249 | that this source code file is not ASCII. For details see @ref{Character |
| 250 | Encoding of Source Files}. |
| 251 | |
| 252 | @node Case Sensitivity |
| 253 | @subsubsection Case Sensitivity |
| 254 | |
| 255 | @c FIXME::martin: Review me! |
| 256 | |
| 257 | Scheme as defined in R5RS is not case sensitive when reading symbols. |
| 258 | Guile, on the contrary is case sensitive by default, so the identifiers |
| 259 | |
| 260 | @lisp |
| 261 | guile-whuzzy |
| 262 | Guile-Whuzzy |
| 263 | @end lisp |
| 264 | |
| 265 | are the same in R5RS Scheme, but are different in Guile. |
| 266 | |
| 267 | It is possible to turn off case sensitivity in Guile by setting the |
| 268 | reader option @code{case-insensitive}. For more information on reader |
| 269 | options, @xref{Scheme Read}. |
| 270 | |
| 271 | @lisp |
| 272 | (read-enable 'case-insensitive) |
| 273 | @end lisp |
| 274 | |
| 275 | Note that this is seldom a problem, because Scheme programmers tend not |
| 276 | to use uppercase letters in their identifiers anyway. |
| 277 | |
| 278 | |
| 279 | @node Keyword Syntax |
| 280 | @subsubsection Keyword Syntax |
| 281 | |
| 282 | |
| 283 | @node Reader Extensions |
| 284 | @subsubsection Reader Extensions |
| 285 | |
| 286 | @deffn {Scheme Procedure} read-hash-extend chr proc |
| 287 | @deffnx {C Function} scm_read_hash_extend (chr, proc) |
| 288 | Install the procedure @var{proc} for reading expressions |
| 289 | starting with the character sequence @code{#} and @var{chr}. |
| 290 | @var{proc} will be called with two arguments: the character |
| 291 | @var{chr} and the port to read further data from. The object |
| 292 | returned will be the return value of @code{read}. |
| 293 | Passing @code{#f} for @var{proc} will remove a previous setting. |
| 294 | |
| 295 | @end deffn |
| 296 | |
| 297 | |
| 298 | @node Scheme Read |
| 299 | @subsection Reading Scheme Code |
| 300 | |
| 301 | @rnindex read |
| 302 | @deffn {Scheme Procedure} read [port] |
| 303 | @deffnx {C Function} scm_read (port) |
| 304 | Read an s-expression from the input port @var{port}, or from |
| 305 | the current input port if @var{port} is not specified. |
| 306 | Any whitespace before the next token is discarded. |
| 307 | @end deffn |
| 308 | |
| 309 | The behaviour of Guile's Scheme reader can be modified by manipulating |
| 310 | its read options. |
| 311 | |
| 312 | @cindex options - read |
| 313 | @cindex read options |
| 314 | @deffn {Scheme Procedure} read-options [setting] |
| 315 | Display the current settings of the read options. If @var{setting} is |
| 316 | omitted, only a short form of the current read options is printed. |
| 317 | Otherwise if @var{setting} is the symbol @code{help}, a complete options |
| 318 | description is displayed. |
| 319 | @end deffn |
| 320 | |
| 321 | The set of available options, and their default values, may be had by |
| 322 | invoking @code{read-options} at the prompt. |
| 323 | |
| 324 | @smalllisp |
| 325 | scheme@@(guile-user)> (read-options) |
| 326 | (square-brackets keywords #f positions) |
| 327 | scheme@@(guile-user)> (read-options 'help) |
| 328 | copy no Copy source code expressions. |
| 329 | positions yes Record positions of source code expressions. |
| 330 | case-insensitive no Convert symbols to lower case. |
| 331 | keywords #f Style of keyword recognition: #f, 'prefix or 'postfix. |
| 332 | r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes. |
| 333 | square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility. |
| 334 | @end smalllisp |
| 335 | |
| 336 | The boolean options may be toggled with @code{read-enable} and |
| 337 | @code{read-disable}. The non-boolean @code{keywords} option must be set |
| 338 | using @code{read-set!}. |
| 339 | |
| 340 | @deffn {Scheme Procedure} read-enable option-name |
| 341 | @deffnx {Scheme Procedure} read-disable option-name |
| 342 | @deffnx {Scheme Procedure} read-set! option-name value |
| 343 | Modify the read options. @code{read-enable} should be used with boolean |
| 344 | options and switches them on, @code{read-disable} switches them off. |
| 345 | @code{read-set!} can be used to set an option to a specific value. |
| 346 | @end deffn |
| 347 | |
| 348 | For example, to make @code{read} fold all symbols to their lower case |
| 349 | (perhaps for compatibility with older Scheme code), you can enter: |
| 350 | |
| 351 | @lisp |
| 352 | (read-enable 'case-insensitive) |
| 353 | @end lisp |
| 354 | |
| 355 | For more information on the effect of the @code{r6rs-hex-escapes} option, see |
| 356 | (@pxref{String Syntax}). |
| 357 | |
| 358 | |
| 359 | @node Scheme Write |
| 360 | @subsection Writing Scheme Values |
| 361 | |
| 362 | Any scheme value may be written to a port. Not all values may be read |
| 363 | back in (@pxref{Scheme Read}), however. |
| 364 | |
| 365 | @rnindex write |
| 366 | @rnindex print |
| 367 | @deffn {Scheme Procedure} write obj [port] |
| 368 | Send a representation of @var{obj} to @var{port} or to the current |
| 369 | output port if not given. |
| 370 | |
| 371 | The output is designed to be machine readable, and can be read back |
| 372 | with @code{read} (@pxref{Scheme Read}). Strings are printed in |
| 373 | double quotes, with escapes if necessary, and characters are printed in |
| 374 | @samp{#\} notation. |
| 375 | @end deffn |
| 376 | |
| 377 | @rnindex display |
| 378 | @deffn {Scheme Procedure} display obj [port] |
| 379 | Send a representation of @var{obj} to @var{port} or to the current |
| 380 | output port if not given. |
| 381 | |
| 382 | The output is designed for human readability, it differs from |
| 383 | @code{write} in that strings are printed without double quotes and |
| 384 | escapes, and characters are printed as per @code{write-char}, not in |
| 385 | @samp{#\} form. |
| 386 | @end deffn |
| 387 | |
| 388 | As was the case with the Scheme reader, there are a few options that |
| 389 | affect the behavior of the Scheme printer. |
| 390 | |
| 391 | @cindex options - print |
| 392 | @cindex print options |
| 393 | @deffn {Scheme Procedure} print-options [setting] |
| 394 | Display the current settings of the read options. If @var{setting} is |
| 395 | omitted, only a short form of the current read options is |
| 396 | printed. Otherwise if @var{setting} is the symbol @code{help}, a |
| 397 | complete options description is displayed. |
| 398 | @end deffn |
| 399 | |
| 400 | The set of available options, and their default values, may be had by |
| 401 | invoking @code{print-options} at the prompt. |
| 402 | |
| 403 | @smalllisp |
| 404 | scheme@@(guile-user)> (print-options) |
| 405 | (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{") |
| 406 | scheme@@(guile-user)> (print-options 'help) |
| 407 | highlight-prefix @{ The string to print before highlighted values. |
| 408 | highlight-suffix @} The string to print after highlighted values. |
| 409 | quote-keywordish-symbols reader How to print symbols that have a colon |
| 410 | as their first or last character. The |
| 411 | value '#f' does not quote the colons; |
| 412 | '#t' quotes them; 'reader' quotes them |
| 413 | when the reader option 'keywords' is |
| 414 | not '#f'. |
| 415 | @end smalllisp |
| 416 | |
| 417 | These options may be modified with the print-set! procedure. |
| 418 | |
| 419 | @deffn {Scheme Procedure} print-set! option-name value |
| 420 | Modify the print options. |
| 421 | @end deffn |
| 422 | |
| 423 | |
| 424 | @node Fly Evaluation |
| 425 | @subsection Procedures for On the Fly Evaluation |
| 426 | |
| 427 | @xref{Environments}. |
| 428 | |
| 429 | @rnindex eval |
| 430 | @c ARGFIXME environment/environment specifier |
| 431 | @deffn {Scheme Procedure} eval exp module_or_state |
| 432 | @deffnx {C Function} scm_eval (exp, module_or_state) |
| 433 | Evaluate @var{exp}, a list representing a Scheme expression, |
| 434 | in the top-level environment specified by @var{module}. |
| 435 | While @var{exp} is evaluated (using @code{primitive-eval}), |
| 436 | @var{module} is made the current module. The current module |
| 437 | is reset to its previous value when @var{eval} returns. |
| 438 | XXX - dynamic states. |
| 439 | Example: (eval '(+ 1 2) (interaction-environment)) |
| 440 | @end deffn |
| 441 | |
| 442 | @rnindex interaction-environment |
| 443 | @deffn {Scheme Procedure} interaction-environment |
| 444 | @deffnx {C Function} scm_interaction_environment () |
| 445 | Return a specifier for the environment that contains |
| 446 | implementation--defined bindings, typically a superset of those |
| 447 | listed in the report. The intent is that this procedure will |
| 448 | return the environment in which the implementation would |
| 449 | evaluate expressions dynamically typed by the user. |
| 450 | @end deffn |
| 451 | |
| 452 | @deffn {Scheme Procedure} eval-string string [module] |
| 453 | @deffnx {C Function} scm_eval_string (string) |
| 454 | @deffnx {C Function} scm_eval_string_in_module (string, module) |
| 455 | Evaluate @var{string} as the text representation of a Scheme form or |
| 456 | forms, and return whatever value they produce. Evaluation takes place |
| 457 | in the given module, or in the current module when no module is given. |
| 458 | While the code is evaluated, the given module is made the current one. |
| 459 | The current module is restored when this procedure returns. |
| 460 | @end deffn |
| 461 | |
| 462 | @deftypefn {C Function} SCM scm_c_eval_string (const char *string) |
| 463 | @code{scm_eval_string}, but taking a C string instead of an |
| 464 | @code{SCM}. |
| 465 | @end deftypefn |
| 466 | |
| 467 | @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst |
| 468 | @deffnx {C Function} scm_apply_0 (proc, arglst) |
| 469 | @deffnx {C Function} scm_apply_1 (proc, arg1, arglst) |
| 470 | @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst) |
| 471 | @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst) |
| 472 | @deffnx {C Function} scm_apply (proc, arg, rest) |
| 473 | @rnindex apply |
| 474 | Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the |
| 475 | elements of the @var{arglst} list. |
| 476 | |
| 477 | @code{scm_apply} takes parameters corresponding to a Scheme level |
| 478 | @code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the |
| 479 | last element of the @var{rest} list make up |
| 480 | @var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the |
| 481 | @var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL} |
| 482 | then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the |
| 483 | @var{arglst}. |
| 484 | |
| 485 | @var{arglst} is not modified, but the @var{rest} list passed to |
| 486 | @code{scm_apply} is modified. |
| 487 | @end deffn |
| 488 | |
| 489 | @deffn {C Function} scm_call_0 (proc) |
| 490 | @deffnx {C Function} scm_call_1 (proc, arg1) |
| 491 | @deffnx {C Function} scm_call_2 (proc, arg1, arg2) |
| 492 | @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3) |
| 493 | @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4) |
| 494 | Call @var{proc} with the given arguments. |
| 495 | @end deffn |
| 496 | |
| 497 | @deffn {Scheme Procedure} apply:nconc2last lst |
| 498 | @deffnx {C Function} scm_nconc2last (lst) |
| 499 | @var{lst} should be a list (@var{arg1} @dots{} @var{argN} |
| 500 | @var{arglst}), with @var{arglst} being a list. This function returns |
| 501 | a list comprising @var{arg1} to @var{argN} plus the elements of |
| 502 | @var{arglst}. @var{lst} is modified to form the return. @var{arglst} |
| 503 | is not modified, though the return does share structure with it. |
| 504 | |
| 505 | This operation collects up the arguments from a list which is |
| 506 | @code{apply} style parameters. |
| 507 | @end deffn |
| 508 | |
| 509 | @deffn {Scheme Procedure} primitive-eval exp |
| 510 | @deffnx {C Function} scm_primitive_eval (exp) |
| 511 | Evaluate @var{exp} in the top-level environment specified by |
| 512 | the current module. |
| 513 | @end deffn |
| 514 | |
| 515 | |
| 516 | @node Compilation |
| 517 | @subsection Compiling Scheme Code |
| 518 | |
| 519 | The @code{eval} procedure directly interprets the S-expression |
| 520 | representation of Scheme. An alternate strategy for evaluation is to |
| 521 | determine ahead of time what computations will be necessary to |
| 522 | evaluate the expression, and then use that recipe to produce the |
| 523 | desired results. This is known as @dfn{compilation}. |
| 524 | |
| 525 | While it is possible to compile simple Scheme expressions such as |
| 526 | @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most |
| 527 | interesting in the context of procedures. Compiling a lambda expression |
| 528 | produces a compiled procedure, which is just like a normal procedure |
| 529 | except typically much faster, because it can bypass the generic |
| 530 | interpreter. |
| 531 | |
| 532 | Functions from system modules in a Guile installation are normally |
| 533 | compiled already, so they load and run quickly. |
| 534 | |
| 535 | Note that well-written Scheme programs will not typically call the |
| 536 | procedures in this section, for the same reason that it is often bad |
| 537 | taste to use @code{eval}. The normal interface to the compiler is the |
| 538 | command-line file compiler, which can be invoked from the shell as |
| 539 | @code{guile-tools compile foo.scm}. |
| 540 | |
| 541 | (Why are calls to @code{eval} and @code{compile} usually in bad taste? |
| 542 | Because they are limited, in that they can only really make sense for |
| 543 | top-level expressions. Also, most needs for ``compile-time'' |
| 544 | computation are fulfilled by macros and closures. Of course one good |
| 545 | counterexample is the REPL itself, or any code that reads expressions |
| 546 | from a port.) |
| 547 | |
| 548 | For more information on the compiler itself, see @ref{Compiling to the |
| 549 | Virtual Machine}. For information on the virtual machine, see @ref{A |
| 550 | Virtual Machine for Guile}. |
| 551 | |
| 552 | The command-line interface to Guile's compiler is the @command{guile-tools |
| 553 | compile} command: |
| 554 | |
| 555 | @deffn {Command} {guile-tools compile} [@option{option}...] @var{file}... |
| 556 | Compile @var{file}, a source file, and store bytecode in the compilation cache |
| 557 | or in the file specified by the @option{-o} option. The following options are |
| 558 | available: |
| 559 | |
| 560 | @table @option |
| 561 | |
| 562 | @item -L @var{dir} |
| 563 | @itemx --load-path=@var{dir} |
| 564 | Add @var{dir} to the front of the module load path. |
| 565 | |
| 566 | @item -o @var{ofile} |
| 567 | @itemx --output=@var{ofile} |
| 568 | Write output bytecode to @var{ofile}. By convention, bytecode file names end |
| 569 | in @code{.go}. |
| 570 | |
| 571 | @item -W @var{warning} |
| 572 | @itemx --warn=@var{warning} |
| 573 | Emit warnings of type @var{warning}; use @code{--warn=help} for a list |
| 574 | of available warnings and their description. Currently recognized |
| 575 | warnings include @code{unused-variable}, @code{unused-toplevel}, |
| 576 | @code{unbound-variable}, @code{arity-mismatch}, and @code{format}. |
| 577 | |
| 578 | @item -f @var{lang} |
| 579 | @itemx --from=@var{lang} |
| 580 | Use @var{lang} as the source language of @var{file}. If this option is omitted, |
| 581 | @code{scheme} is assumed. |
| 582 | |
| 583 | @item -t @var{lang} |
| 584 | @itemx --to=@var{lang} |
| 585 | Use @var{lang} as the target language of @var{file}. If this option is omitted, |
| 586 | @code{objcode} is assumed. |
| 587 | |
| 588 | @end table |
| 589 | |
| 590 | @end deffn |
| 591 | |
| 592 | The compiler can also be invoked directly by Scheme code using the procedures |
| 593 | below: |
| 594 | |
| 595 | @deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()] |
| 596 | Compile the expression @var{exp} in the environment @var{env}. If |
| 597 | @var{exp} is a procedure, the result will be a compiled procedure; |
| 598 | otherwise @code{compile} is mostly equivalent to @code{eval}. |
| 599 | |
| 600 | For a discussion of languages and compiler options, @xref{Compiling to |
| 601 | the Virtual Machine}. |
| 602 | @end deffn |
| 603 | |
| 604 | @deffn {Scheme Procedure} compile-file file [to=objcode] [opts='()] |
| 605 | Compile the file named @var{file}. |
| 606 | |
| 607 | Output will be written to a file in the current directory whose name |
| 608 | is computed as @code{(compiled-file-name @var{file})}. |
| 609 | @end deffn |
| 610 | |
| 611 | @deffn {Scheme Procedure} compiled-file-name file |
| 612 | Compute an appropriate name for a compiled version of a Scheme file |
| 613 | named @var{file}. |
| 614 | |
| 615 | Usually, the result will be the original file name with the |
| 616 | @code{.scm} suffix replaced with @code{.go}, but the exact behavior |
| 617 | depends on the contents of the @code{%load-extensions} and |
| 618 | @code{%load-compiled-extensions} lists. |
| 619 | @end deffn |
| 620 | |
| 621 | @node Loading |
| 622 | @subsection Loading Scheme Code from File |
| 623 | |
| 624 | @rnindex load |
| 625 | @deffn {Scheme Procedure} load filename [reader] |
| 626 | Load @var{filename} and evaluate its contents in the top-level |
| 627 | environment. The load paths are not searched. |
| 628 | |
| 629 | @var{reader} if provided should be either @code{#f}, or a procedure with |
| 630 | the signature @code{(lambda (port) @dots{})} which reads the next |
| 631 | expression from @var{port}. If @var{reader} is @code{#f} or absent, |
| 632 | Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}). |
| 633 | |
| 634 | The @var{reader} argument takes effect by setting the value of the |
| 635 | @code{current-reader} fluid (see below) before loading the file, and |
| 636 | restoring its previous value when loading is complete. The Scheme code |
| 637 | inside @var{filename} can itself change the current reader procedure on |
| 638 | the fly by setting @code{current-reader} fluid. |
| 639 | |
| 640 | If the variable @code{%load-hook} is defined, it should be bound to a |
| 641 | procedure that will be called before any code is loaded. See |
| 642 | documentation for @code{%load-hook} later in this section. |
| 643 | @end deffn |
| 644 | |
| 645 | @deffn {Scheme Procedure} load-compiled filename |
| 646 | Load the compiled file named @var{filename}. The load paths are not |
| 647 | searched. |
| 648 | |
| 649 | Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then |
| 650 | calling @code{load-compiled} on the resulting file is equivalent to |
| 651 | calling @code{load} on the source file. |
| 652 | @end deffn |
| 653 | |
| 654 | @deffn {Scheme Procedure} load-from-path filename |
| 655 | Similar to @code{load}, but searches for @var{filename} in the load |
| 656 | paths. Preferentially loads a compiled version of the file, if it is |
| 657 | available and up-to-date. |
| 658 | @end deffn |
| 659 | |
| 660 | @deffn {Scheme Procedure} primitive-load filename |
| 661 | @deffnx {C Function} scm_primitive_load (filename) |
| 662 | Load the file named @var{filename} and evaluate its contents in |
| 663 | the top-level environment. The load paths are not searched; |
| 664 | @var{filename} must either be a full pathname or be a pathname |
| 665 | relative to the current directory. If the variable |
| 666 | @code{%load-hook} is defined, it should be bound to a procedure |
| 667 | that will be called before any code is loaded. See the |
| 668 | documentation for @code{%load-hook} later in this section. |
| 669 | @end deffn |
| 670 | |
| 671 | @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename) |
| 672 | @code{scm_primitive_load}, but taking a C string instead of an |
| 673 | @code{SCM}. |
| 674 | @end deftypefn |
| 675 | |
| 676 | @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found] |
| 677 | @deffnx {C Function} scm_primitive_load_path (filename) |
| 678 | Search @code{%load-path} for the file named @var{filename} and |
| 679 | load it into the top-level environment. If @var{filename} is a |
| 680 | relative pathname and is not found in the list of search paths, |
| 681 | an error is signalled. Preferentially loads a compiled version of the |
| 682 | file, if it is available and up-to-date. |
| 683 | |
| 684 | By default or if @var{exception-on-not-found} is true, an exception is |
| 685 | raised if @var{filename} is not found. If @var{exception-on-not-found} |
| 686 | is @code{#f} and @var{filename} is not found, no exception is raised and |
| 687 | @code{#f} is returned. For compatibility with Guile 1.8 and earlier, |
| 688 | the C function takes only one argument, which can be either a string |
| 689 | (the file name) or an argument list. |
| 690 | @end deffn |
| 691 | |
| 692 | @deffn {Scheme Procedure} %search-load-path filename |
| 693 | @deffnx {C Function} scm_sys_search_load_path (filename) |
| 694 | Search @code{%load-path} for the file named @var{filename}, |
| 695 | which must be readable by the current user. If @var{filename} |
| 696 | is found in the list of paths to search or is an absolute |
| 697 | pathname, return its full pathname. Otherwise, return |
| 698 | @code{#f}. Filenames may have any of the optional extensions |
| 699 | in the @code{%load-extensions} list; @code{%search-load-path} |
| 700 | will try each extension automatically. |
| 701 | @end deffn |
| 702 | |
| 703 | @defvar current-reader |
| 704 | @code{current-reader} holds the read procedure that is currently being |
| 705 | used by the above loading procedures to read expressions (from the file |
| 706 | that they are loading). @code{current-reader} is a fluid, so it has an |
| 707 | independent value in each dynamic root and should be read and set using |
| 708 | @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic |
| 709 | States}). |
| 710 | |
| 711 | Changing @code{current-reader} is typically useful to introduce local |
| 712 | syntactic changes, such that code following the @code{fluid-set!} call |
| 713 | is read using the newly installed reader. The @code{current-reader} |
| 714 | change should take place at evaluation time when the code is evaluated, |
| 715 | or at compilation time when the code is compiled: |
| 716 | |
| 717 | @findex eval-when |
| 718 | @example |
| 719 | (eval-when (compile eval) |
| 720 | (fluid-set! current-reader my-own-reader)) |
| 721 | @end example |
| 722 | |
| 723 | The @code{eval-when} form above ensures that the @code{current-reader} |
| 724 | change occurs at the right time. |
| 725 | @end defvar |
| 726 | |
| 727 | @defvar %load-hook |
| 728 | A procedure to be called @code{(%load-hook @var{filename})} whenever a |
| 729 | file is loaded, or @code{#f} for no such call. @code{%load-hook} is |
| 730 | used by all of the above loading functions (@code{load}, |
| 731 | @code{load-path}, @code{primitive-load} and |
| 732 | @code{primitive-load-path}). |
| 733 | |
| 734 | For example an application can set this to show what's loaded, |
| 735 | |
| 736 | @example |
| 737 | (set! %load-hook (lambda (filename) |
| 738 | (format #t "Loading ~a ...\n" filename))) |
| 739 | (load-from-path "foo.scm") |
| 740 | @print{} Loading /usr/local/share/guile/site/foo.scm ... |
| 741 | @end example |
| 742 | @end defvar |
| 743 | |
| 744 | @deffn {Scheme Procedure} current-load-port |
| 745 | @deffnx {C Function} scm_current_load_port () |
| 746 | Return the current-load-port. |
| 747 | The load port is used internally by @code{primitive-load}. |
| 748 | @end deffn |
| 749 | |
| 750 | @defvar %load-extensions |
| 751 | A list of default file extensions for files containing Scheme code. |
| 752 | @code{%search-load-path} tries each of these extensions when looking for |
| 753 | a file to load. By default, @code{%load-extensions} is bound to the |
| 754 | list @code{("" ".scm")}. |
| 755 | @end defvar |
| 756 | |
| 757 | @node Character Encoding of Source Files |
| 758 | @subsection Character Encoding of Source Files |
| 759 | |
| 760 | @cindex source file encoding |
| 761 | @cindex primitive-load |
| 762 | @cindex load |
| 763 | Scheme source code files are usually encoded in ASCII, but, the |
| 764 | built-in reader can interpret other character encodings. The |
| 765 | procedure @code{primitive-load}, and by extension the functions that |
| 766 | call it, such as @code{load}, first scan the top 500 characters of the |
| 767 | file for a coding declaration. |
| 768 | |
| 769 | A coding declaration has the form @code{coding: XXXXXX}, where |
| 770 | @code{XXXXXX} is the name of a character encoding in which the source |
| 771 | code file has been encoded. The coding declaration must appear in a |
| 772 | scheme comment. It can either be a semicolon-initiated comment or a block |
| 773 | @code{#!} comment. |
| 774 | |
| 775 | The name of the character encoding in the coding declaration is |
| 776 | typically lower case and containing only letters, numbers, and hyphens, |
| 777 | as recognized by @code{set-port-encoding!} (@pxref{Ports, |
| 778 | @code{set-port-encoding!}}). Common examples of character encoding |
| 779 | names are @code{utf-8} and @code{iso-8859-1}, |
| 780 | @url{http://www.iana.org/assignments/character-sets, as defined by |
| 781 | IANA}. Thus, the coding declaration is mostly compatible with Emacs. |
| 782 | |
| 783 | However, there are some differences in encoding names recognized by |
| 784 | Emacs and encoding names defined by IANA, the latter being essentially a |
| 785 | subset of the former. For instance, @code{latin-1} is a valid encoding |
| 786 | name for Emacs, but it's not according to the IANA standard, which Guile |
| 787 | follows; instead, you should use @code{iso-8859-1}, which is both |
| 788 | understood by Emacs and dubbed by IANA (IANA writes it uppercase but |
| 789 | Emacs wants it lowercase and Guile is case insensitive.) |
| 790 | |
| 791 | For source code, only a subset of all possible character encodings can |
| 792 | be interpreted by the built-in source code reader. Only those |
| 793 | character encodings in which ASCII text appears unmodified can be |
| 794 | used. This includes @code{UTF-8} and @code{ISO-8859-1} through |
| 795 | @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16} |
| 796 | and @code{UTF-32} may not be used because they are not compatible with |
| 797 | ASCII. |
| 798 | |
| 799 | @cindex read |
| 800 | @cindex encoding |
| 801 | @cindex port encoding |
| 802 | @findex set-port-encoding! |
| 803 | There might be a scenario in which one would want to read non-ASCII |
| 804 | code from a port, such as with the function @code{read}, instead of |
| 805 | with @code{load}. If the port's character encoding is the same as the |
| 806 | encoding of the code to be read by the port, not other special |
| 807 | handling is necessary. The port will automatically do the character |
| 808 | encoding conversion. The functions @code{setlocale} or by |
| 809 | @code{set-port-encoding!} are used to set port encodings |
| 810 | (@pxref{Ports}). |
| 811 | |
| 812 | If a port is used to read code of unknown character encoding, it can |
| 813 | accomplish this in three steps. First, the character encoding of the |
| 814 | port should be set to ISO-8859-1 using @code{set-port-encoding!}. |
| 815 | Then, the procedure @code{file-encoding}, described below, is used to |
| 816 | scan for a coding declaration when reading from the port. As a side |
| 817 | effect, it rewinds the port after its scan is complete. After that, |
| 818 | the port's character encoding should be set to the encoding returned |
| 819 | by @code{file-encoding}, if any, again by using |
| 820 | @code{set-port-encoding!}. Then the code can be read as normal. |
| 821 | |
| 822 | @deffn {Scheme Procedure} file-encoding port |
| 823 | @deffnx {C Function} scm_file_encoding port |
| 824 | Scan the port for an Emacs-like character coding declaration near the |
| 825 | top of the contents of a port with random-accessible contents |
| 826 | (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs, |
| 827 | The GNU Emacs Reference Manual}). The coding declaration is of the form |
| 828 | @code{coding: XXXXX} and must appear in a Scheme comment. Return a |
| 829 | string containing the character encoding of the file if a declaration |
| 830 | was found, or @code{#f} otherwise. The port is rewound. |
| 831 | @end deffn |
| 832 | |
| 833 | |
| 834 | @node Delayed Evaluation |
| 835 | @subsection Delayed Evaluation |
| 836 | @cindex delayed evaluation |
| 837 | @cindex promises |
| 838 | |
| 839 | Promises are a convenient way to defer a calculation until its result |
| 840 | is actually needed, and to run such a calculation only once. |
| 841 | |
| 842 | @deffn syntax delay expr |
| 843 | @rnindex delay |
| 844 | Return a promise object which holds the given @var{expr} expression, |
| 845 | ready to be evaluated by a later @code{force}. |
| 846 | @end deffn |
| 847 | |
| 848 | @deffn {Scheme Procedure} promise? obj |
| 849 | @deffnx {C Function} scm_promise_p (obj) |
| 850 | Return true if @var{obj} is a promise. |
| 851 | @end deffn |
| 852 | |
| 853 | @rnindex force |
| 854 | @deffn {Scheme Procedure} force p |
| 855 | @deffnx {C Function} scm_force (p) |
| 856 | Return the value obtained from evaluating the @var{expr} in the given |
| 857 | promise @var{p}. If @var{p} has previously been forced then its |
| 858 | @var{expr} is not evaluated again, instead the value obtained at that |
| 859 | time is simply returned. |
| 860 | |
| 861 | During a @code{force}, an @var{expr} can call @code{force} again on |
| 862 | its own promise, resulting in a recursive evaluation of that |
| 863 | @var{expr}. The first evaluation to return gives the value for the |
| 864 | promise. Higher evaluations run to completion in the normal way, but |
| 865 | their results are ignored, @code{force} always returns the first |
| 866 | value. |
| 867 | @end deffn |
| 868 | |
| 869 | |
| 870 | @c Local Variables: |
| 871 | @c TeX-master: "guile.texi" |
| 872 | @c End: |