Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
c869f0c1 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
00ce5125 | 7 | @node Read/Load/Eval/Compile |
07d83abe MV |
8 | @section Reading and Evaluating Scheme Code |
9 | ||
10 | This chapter describes Guile functions that are concerned with reading, | |
00ce5125 | 11 | loading, evaluating, and compiling Scheme code at run time. |
07d83abe MV |
12 | |
13 | @menu | |
14 | * Scheme Syntax:: Standard and extended Scheme syntax. | |
15 | * Scheme Read:: Reading Scheme code. | |
1518f649 | 16 | * Scheme Write:: Writing Scheme values to a port. |
07d83abe | 17 | * Fly Evaluation:: Procedures for on the fly evaluation. |
00ce5125 | 18 | * Compilation:: How to compile Scheme files and procedures. |
07d83abe | 19 | * Loading:: Loading Scheme code from file. |
8748ffea | 20 | * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file. |
07d83abe | 21 | * Delayed Evaluation:: Postponing evaluation until it is needed. |
07d83abe MV |
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 | |
456f797b KR |
203 | @cindex multiline comments |
204 | @cindex block comments | |
205 | @cindex #! | |
206 | @cindex !# | |
07d83abe MV |
207 | |
208 | @c FIXME::martin: Review me! | |
209 | ||
07d83abe MV |
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 | ||
620c8965 LC |
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 | ||
8748ffea MG |
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}. | |
07d83abe MV |
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 | |
1518f649 AW |
268 | reader option @code{case-insensitive}. For more information on reader |
269 | options, @xref{Scheme Read}. | |
07d83abe MV |
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 | |
3323ec06 NJ |
292 | returned will be the return value of @code{read}. |
293 | Passing @code{#f} for @var{proc} will remove a previous setting. | |
294 | ||
07d83abe MV |
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 | |
1518f649 | 310 | its read options. |
07d83abe | 311 | |
1518f649 AW |
312 | @cindex options - read |
313 | @cindex read options | |
07d83abe MV |
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. | |
1518f649 AW |
317 | Otherwise if @var{setting} is the symbol @code{help}, a complete options |
318 | description is displayed. | |
07d83abe MV |
319 | @end deffn |
320 | ||
1518f649 AW |
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. | |
c869f0c1 AW |
334 | hungry-eol-escapes no In strings, consume leading whitespace after an |
335 | escaped end-of-line. | |
1518f649 AW |
336 | @end smalllisp |
337 | ||
338 | The boolean options may be toggled with @code{read-enable} and | |
339 | @code{read-disable}. The non-boolean @code{keywords} option must be set | |
340 | using @code{read-set!}. | |
341 | ||
07d83abe MV |
342 | @deffn {Scheme Procedure} read-enable option-name |
343 | @deffnx {Scheme Procedure} read-disable option-name | |
344 | @deffnx {Scheme Procedure} read-set! option-name value | |
345 | Modify the read options. @code{read-enable} should be used with boolean | |
346 | options and switches them on, @code{read-disable} switches them off. | |
347 | @code{read-set!} can be used to set an option to a specific value. | |
348 | @end deffn | |
349 | ||
1518f649 AW |
350 | For example, to make @code{read} fold all symbols to their lower case |
351 | (perhaps for compatibility with older Scheme code), you can enter: | |
352 | ||
353 | @lisp | |
354 | (read-enable 'case-insensitive) | |
355 | @end lisp | |
356 | ||
c869f0c1 AW |
357 | For more information on the effect of the @code{r6rs-hex-escapes} and |
358 | @code{hungry-eol-escapes} options, see (@pxref{String Syntax}). | |
1518f649 AW |
359 | |
360 | ||
361 | @node Scheme Write | |
362 | @subsection Writing Scheme Values | |
363 | ||
364 | Any scheme value may be written to a port. Not all values may be read | |
365 | back in (@pxref{Scheme Read}), however. | |
366 | ||
367 | @rnindex write | |
368 | @rnindex print | |
369 | @deffn {Scheme Procedure} write obj [port] | |
370 | Send a representation of @var{obj} to @var{port} or to the current | |
371 | output port if not given. | |
372 | ||
373 | The output is designed to be machine readable, and can be read back | |
374 | with @code{read} (@pxref{Scheme Read}). Strings are printed in | |
375 | double quotes, with escapes if necessary, and characters are printed in | |
376 | @samp{#\} notation. | |
377 | @end deffn | |
378 | ||
379 | @rnindex display | |
380 | @deffn {Scheme Procedure} display obj [port] | |
381 | Send a representation of @var{obj} to @var{port} or to the current | |
382 | output port if not given. | |
383 | ||
384 | The output is designed for human readability, it differs from | |
385 | @code{write} in that strings are printed without double quotes and | |
386 | escapes, and characters are printed as per @code{write-char}, not in | |
387 | @samp{#\} form. | |
388 | @end deffn | |
389 | ||
390 | As was the case with the Scheme reader, there are a few options that | |
391 | affect the behavior of the Scheme printer. | |
392 | ||
393 | @cindex options - print | |
394 | @cindex print options | |
395 | @deffn {Scheme Procedure} print-options [setting] | |
396 | Display the current settings of the read options. If @var{setting} is | |
397 | omitted, only a short form of the current read options is | |
398 | printed. Otherwise if @var{setting} is the symbol @code{help}, a | |
399 | complete options description is displayed. | |
400 | @end deffn | |
401 | ||
402 | The set of available options, and their default values, may be had by | |
403 | invoking @code{print-options} at the prompt. | |
404 | ||
405 | @smalllisp | |
406 | scheme@@(guile-user)> (print-options) | |
407 | (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{") | |
408 | scheme@@(guile-user)> (print-options 'help) | |
409 | highlight-prefix @{ The string to print before highlighted values. | |
410 | highlight-suffix @} The string to print after highlighted values. | |
411 | quote-keywordish-symbols reader How to print symbols that have a colon | |
412 | as their first or last character. The | |
413 | value '#f' does not quote the colons; | |
414 | '#t' quotes them; 'reader' quotes them | |
415 | when the reader option 'keywords' is | |
416 | not '#f'. | |
417 | @end smalllisp | |
418 | ||
419 | These options may be modified with the print-set! procedure. | |
420 | ||
421 | @deffn {Scheme Procedure} print-set! option-name value | |
422 | Modify the print options. | |
07d83abe MV |
423 | @end deffn |
424 | ||
425 | ||
426 | @node Fly Evaluation | |
427 | @subsection Procedures for On the Fly Evaluation | |
428 | ||
429 | @xref{Environments}. | |
430 | ||
431 | @rnindex eval | |
432 | @c ARGFIXME environment/environment specifier | |
b4fddbbe MV |
433 | @deffn {Scheme Procedure} eval exp module_or_state |
434 | @deffnx {C Function} scm_eval (exp, module_or_state) | |
07d83abe MV |
435 | Evaluate @var{exp}, a list representing a Scheme expression, |
436 | in the top-level environment specified by @var{module}. | |
437 | While @var{exp} is evaluated (using @code{primitive-eval}), | |
438 | @var{module} is made the current module. The current module | |
439 | is reset to its previous value when @var{eval} returns. | |
b4fddbbe MV |
440 | XXX - dynamic states. |
441 | Example: (eval '(+ 1 2) (interaction-environment)) | |
07d83abe MV |
442 | @end deffn |
443 | ||
444 | @rnindex interaction-environment | |
445 | @deffn {Scheme Procedure} interaction-environment | |
446 | @deffnx {C Function} scm_interaction_environment () | |
447 | Return a specifier for the environment that contains | |
448 | implementation--defined bindings, typically a superset of those | |
449 | listed in the report. The intent is that this procedure will | |
450 | return the environment in which the implementation would | |
451 | evaluate expressions dynamically typed by the user. | |
452 | @end deffn | |
453 | ||
454 | @deffn {Scheme Procedure} eval-string string [module] | |
455 | @deffnx {C Function} scm_eval_string (string) | |
456 | @deffnx {C Function} scm_eval_string_in_module (string, module) | |
457 | Evaluate @var{string} as the text representation of a Scheme form or | |
458 | forms, and return whatever value they produce. Evaluation takes place | |
459 | in the given module, or in the current module when no module is given. | |
460 | While the code is evaluated, the given module is made the current one. | |
461 | The current module is restored when this procedure returns. | |
462 | @end deffn | |
463 | ||
40296bab KR |
464 | @deftypefn {C Function} SCM scm_c_eval_string (const char *string) |
465 | @code{scm_eval_string}, but taking a C string instead of an | |
466 | @code{SCM}. | |
467 | @end deftypefn | |
468 | ||
07d83abe MV |
469 | @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst |
470 | @deffnx {C Function} scm_apply_0 (proc, arglst) | |
471 | @deffnx {C Function} scm_apply_1 (proc, arg1, arglst) | |
472 | @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst) | |
473 | @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst) | |
474 | @deffnx {C Function} scm_apply (proc, arg, rest) | |
475 | @rnindex apply | |
476 | Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the | |
477 | elements of the @var{arglst} list. | |
478 | ||
479 | @code{scm_apply} takes parameters corresponding to a Scheme level | |
480 | @code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the | |
481 | last element of the @var{rest} list make up | |
482 | @var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the | |
483 | @var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL} | |
484 | then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the | |
485 | @var{arglst}. | |
486 | ||
487 | @var{arglst} is not modified, but the @var{rest} list passed to | |
488 | @code{scm_apply} is modified. | |
489 | @end deffn | |
490 | ||
491 | @deffn {C Function} scm_call_0 (proc) | |
492 | @deffnx {C Function} scm_call_1 (proc, arg1) | |
493 | @deffnx {C Function} scm_call_2 (proc, arg1, arg2) | |
494 | @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3) | |
8d596b11 | 495 | @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4) |
13459a96 AW |
496 | @deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5) |
497 | @deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6) | |
07d83abe MV |
498 | Call @var{proc} with the given arguments. |
499 | @end deffn | |
500 | ||
13459a96 AW |
501 | @deffn {C Function} scm_call_n (proc, argv, nargs) |
502 | Call @var{proc} with the array of arguments @var{argv}, as a | |
503 | @code{SCM*}. The length of the arguments should be passed in | |
504 | @var{nargs}, as a @code{size_t}. | |
505 | @end deffn | |
506 | ||
07d83abe MV |
507 | @deffn {Scheme Procedure} apply:nconc2last lst |
508 | @deffnx {C Function} scm_nconc2last (lst) | |
509 | @var{lst} should be a list (@var{arg1} @dots{} @var{argN} | |
510 | @var{arglst}), with @var{arglst} being a list. This function returns | |
511 | a list comprising @var{arg1} to @var{argN} plus the elements of | |
512 | @var{arglst}. @var{lst} is modified to form the return. @var{arglst} | |
513 | is not modified, though the return does share structure with it. | |
514 | ||
515 | This operation collects up the arguments from a list which is | |
516 | @code{apply} style parameters. | |
517 | @end deffn | |
518 | ||
519 | @deffn {Scheme Procedure} primitive-eval exp | |
520 | @deffnx {C Function} scm_primitive_eval (exp) | |
521 | Evaluate @var{exp} in the top-level environment specified by | |
522 | the current module. | |
523 | @end deffn | |
524 | ||
525 | ||
00ce5125 AW |
526 | @node Compilation |
527 | @subsection Compiling Scheme Code | |
528 | ||
529 | The @code{eval} procedure directly interprets the S-expression | |
530 | representation of Scheme. An alternate strategy for evaluation is to | |
531 | determine ahead of time what computations will be necessary to | |
532 | evaluate the expression, and then use that recipe to produce the | |
533 | desired results. This is known as @dfn{compilation}. | |
534 | ||
535 | While it is possible to compile simple Scheme expressions such as | |
536 | @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most | |
ca445ba5 | 537 | interesting in the context of procedures. Compiling a lambda expression |
00ce5125 AW |
538 | produces a compiled procedure, which is just like a normal procedure |
539 | except typically much faster, because it can bypass the generic | |
540 | interpreter. | |
541 | ||
542 | Functions from system modules in a Guile installation are normally | |
543 | compiled already, so they load and run quickly. | |
544 | ||
14d2ee31 | 545 | @cindex automatic compilation |
00ce5125 AW |
546 | Note that well-written Scheme programs will not typically call the |
547 | procedures in this section, for the same reason that it is often bad | |
14d2ee31 LC |
548 | taste to use @code{eval}. By default, Guile automatically compiles any |
549 | files it encounters that have not been compiled yet (@pxref{Invoking | |
550 | Guile, @code{--auto-compile}}). The compiler can also be invoked | |
551 | explicitly from the shell as @code{guile-tools compile foo.scm}. | |
00ce5125 AW |
552 | |
553 | (Why are calls to @code{eval} and @code{compile} usually in bad taste? | |
554 | Because they are limited, in that they can only really make sense for | |
555 | top-level expressions. Also, most needs for ``compile-time'' | |
556 | computation are fulfilled by macros and closures. Of course one good | |
557 | counterexample is the REPL itself, or any code that reads expressions | |
558 | from a port.) | |
559 | ||
ca445ba5 AW |
560 | For more information on the compiler itself, see @ref{Compiling to the |
561 | Virtual Machine}. For information on the virtual machine, see @ref{A | |
00ce5125 AW |
562 | Virtual Machine for Guile}. |
563 | ||
788cf402 LC |
564 | The command-line interface to Guile's compiler is the @command{guile-tools |
565 | compile} command: | |
566 | ||
567 | @deffn {Command} {guile-tools compile} [@option{option}...] @var{file}... | |
568 | Compile @var{file}, a source file, and store bytecode in the compilation cache | |
569 | or in the file specified by the @option{-o} option. The following options are | |
570 | available: | |
571 | ||
572 | @table @option | |
573 | ||
574 | @item -L @var{dir} | |
575 | @itemx --load-path=@var{dir} | |
576 | Add @var{dir} to the front of the module load path. | |
577 | ||
578 | @item -o @var{ofile} | |
579 | @itemx --output=@var{ofile} | |
eda06220 LC |
580 | Write output bytecode to @var{ofile}. By convention, bytecode file |
581 | names end in @code{.go}. When @option{-o} is omitted, the output file | |
582 | name is as for @code{compile-file} (see below). | |
788cf402 LC |
583 | |
584 | @item -W @var{warning} | |
585 | @itemx --warn=@var{warning} | |
75365375 LC |
586 | Emit warnings of type @var{warning}; use @code{--warn=help} for a list |
587 | of available warnings and their description. Currently recognized | |
588 | warnings include @code{unused-variable}, @code{unused-toplevel}, | |
589 | @code{unbound-variable}, @code{arity-mismatch}, and @code{format}. | |
788cf402 LC |
590 | |
591 | @item -f @var{lang} | |
592 | @itemx --from=@var{lang} | |
593 | Use @var{lang} as the source language of @var{file}. If this option is omitted, | |
594 | @code{scheme} is assumed. | |
595 | ||
596 | @item -t @var{lang} | |
597 | @itemx --to=@var{lang} | |
598 | Use @var{lang} as the target language of @var{file}. If this option is omitted, | |
599 | @code{objcode} is assumed. | |
600 | ||
601 | @end table | |
602 | ||
eda06220 LC |
603 | Each @var{file} is assumed to be UTF-8-encoded, unless it contains a |
604 | coding declaration as recognized by @code{file-encoding} | |
605 | (@pxref{Character Encoding of Source Files}). | |
788cf402 LC |
606 | @end deffn |
607 | ||
608 | The compiler can also be invoked directly by Scheme code using the procedures | |
609 | below: | |
610 | ||
00ce5125 AW |
611 | @deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()] |
612 | Compile the expression @var{exp} in the environment @var{env}. If | |
613 | @var{exp} is a procedure, the result will be a compiled procedure; | |
614 | otherwise @code{compile} is mostly equivalent to @code{eval}. | |
615 | ||
616 | For a discussion of languages and compiler options, @xref{Compiling to | |
617 | the Virtual Machine}. | |
618 | @end deffn | |
619 | ||
043bca03 AW |
620 | @deffn {Scheme Procedure} compile-file file [output-file=#f] @ |
621 | [from=(current-language)] [to='objcode] @ | |
622 | [env=(default-environment from)] [opts='()] @ | |
623 | [canonicalization 'relative] | |
00ce5125 AW |
624 | Compile the file named @var{file}. |
625 | ||
043bca03 AW |
626 | Output will be written to a @var{output-file}. If you do not supply an |
627 | output file name, output is written to a file in the cache directory, as | |
628 | computed by @code{(compiled-file-name @var{file})}. | |
629 | ||
630 | @var{from} and @var{to} specify the source and target languages. | |
631 | @xref{Compiling to the Virtual Machine}, for more information on these | |
632 | options, and on @var{env} and @var{opts}. | |
eda06220 LC |
633 | |
634 | As with @command{guile-tools compile}, @var{file} is assumed to be | |
635 | UTF-8-encoded unless it contains a coding declaration. | |
00ce5125 AW |
636 | @end deffn |
637 | ||
638 | @deffn {Scheme Procedure} compiled-file-name file | |
043bca03 AW |
639 | Compute a cached location for a compiled version of a Scheme file named |
640 | @var{file}. | |
641 | ||
642 | This file will usually be below the @file{$HOME/.cache/guile/ccache} | |
643 | directory, depending on the value of the @env{XDG_CACHE_HOME} | |
644 | environment variable. The intention is that @code{compiled-file-name} | |
645 | provides a fallback location for caching auto-compiled files. If you | |
646 | want to place a compile file in the @code{%load-compiled-path}, you | |
647 | should pass the @var{output-file} option to @code{compile-file}, | |
648 | explicitly. | |
00ce5125 AW |
649 | @end deffn |
650 | ||
14d2ee31 LC |
651 | @defvr {Scheme Variable} %auto-compilation-options |
652 | This variable contains the options passed to the @code{compile-file} | |
653 | procedure when auto-compiling source files. By default, it enables | |
654 | useful compilation warnings. It can be customized from @file{~/.guile}. | |
655 | @end defvr | |
656 | ||
07d83abe MV |
657 | @node Loading |
658 | @subsection Loading Scheme Code from File | |
659 | ||
660 | @rnindex load | |
ec3a8ace | 661 | @deffn {Scheme Procedure} load filename [reader] |
07d83abe | 662 | Load @var{filename} and evaluate its contents in the top-level |
ec3a8ace NJ |
663 | environment. The load paths are not searched. |
664 | ||
665 | @var{reader} if provided should be either @code{#f}, or a procedure with | |
666 | the signature @code{(lambda (port) @dots{})} which reads the next | |
667 | expression from @var{port}. If @var{reader} is @code{#f} or absent, | |
668 | Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}). | |
669 | ||
670 | The @var{reader} argument takes effect by setting the value of the | |
671 | @code{current-reader} fluid (see below) before loading the file, and | |
672 | restoring its previous value when loading is complete. The Scheme code | |
673 | inside @var{filename} can itself change the current reader procedure on | |
674 | the fly by setting @code{current-reader} fluid. | |
675 | ||
676 | If the variable @code{%load-hook} is defined, it should be bound to a | |
677 | procedure that will be called before any code is loaded. See | |
678 | documentation for @code{%load-hook} later in this section. | |
07d83abe MV |
679 | @end deffn |
680 | ||
00ce5125 AW |
681 | @deffn {Scheme Procedure} load-compiled filename |
682 | Load the compiled file named @var{filename}. The load paths are not | |
683 | searched. | |
684 | ||
685 | Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then | |
686 | calling @code{load-compiled} on the resulting file is equivalent to | |
687 | calling @code{load} on the source file. | |
688 | @end deffn | |
689 | ||
07d83abe MV |
690 | @deffn {Scheme Procedure} load-from-path filename |
691 | Similar to @code{load}, but searches for @var{filename} in the load | |
00ce5125 AW |
692 | paths. Preferentially loads a compiled version of the file, if it is |
693 | available and up-to-date. | |
07d83abe MV |
694 | @end deffn |
695 | ||
696 | @deffn {Scheme Procedure} primitive-load filename | |
697 | @deffnx {C Function} scm_primitive_load (filename) | |
698 | Load the file named @var{filename} and evaluate its contents in | |
699 | the top-level environment. The load paths are not searched; | |
700 | @var{filename} must either be a full pathname or be a pathname | |
701 | relative to the current directory. If the variable | |
702 | @code{%load-hook} is defined, it should be bound to a procedure | |
703 | that will be called before any code is loaded. See the | |
704 | documentation for @code{%load-hook} later in this section. | |
705 | @end deffn | |
706 | ||
40296bab KR |
707 | @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename) |
708 | @code{scm_primitive_load}, but taking a C string instead of an | |
709 | @code{SCM}. | |
710 | @end deftypefn | |
711 | ||
31ab99de | 712 | @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found] |
07d83abe | 713 | @deffnx {C Function} scm_primitive_load_path (filename) |
5c132e68 | 714 | Search @code{%load-path} for the file named @var{filename} and |
07d83abe MV |
715 | load it into the top-level environment. If @var{filename} is a |
716 | relative pathname and is not found in the list of search paths, | |
00ce5125 AW |
717 | an error is signalled. Preferentially loads a compiled version of the |
718 | file, if it is available and up-to-date. | |
31ab99de LC |
719 | |
720 | By default or if @var{exception-on-not-found} is true, an exception is | |
721 | raised if @var{filename} is not found. If @var{exception-on-not-found} | |
722 | is @code{#f} and @var{filename} is not found, no exception is raised and | |
723 | @code{#f} is returned. For compatibility with Guile 1.8 and earlier, | |
724 | the C function takes only one argument, which can be either a string | |
725 | (the file name) or an argument list. | |
07d83abe MV |
726 | @end deffn |
727 | ||
728 | @deffn {Scheme Procedure} %search-load-path filename | |
729 | @deffnx {C Function} scm_sys_search_load_path (filename) | |
5c132e68 | 730 | Search @code{%load-path} for the file named @var{filename}, |
07d83abe MV |
731 | which must be readable by the current user. If @var{filename} |
732 | is found in the list of paths to search or is an absolute | |
733 | pathname, return its full pathname. Otherwise, return | |
734 | @code{#f}. Filenames may have any of the optional extensions | |
735 | in the @code{%load-extensions} list; @code{%search-load-path} | |
736 | will try each extension automatically. | |
737 | @end deffn | |
738 | ||
ec3a8ace NJ |
739 | @defvar current-reader |
740 | @code{current-reader} holds the read procedure that is currently being | |
741 | used by the above loading procedures to read expressions (from the file | |
742 | that they are loading). @code{current-reader} is a fluid, so it has an | |
743 | independent value in each dynamic root and should be read and set using | |
744 | @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic | |
745 | States}). | |
1ebe6a63 LC |
746 | |
747 | Changing @code{current-reader} is typically useful to introduce local | |
748 | syntactic changes, such that code following the @code{fluid-set!} call | |
749 | is read using the newly installed reader. The @code{current-reader} | |
750 | change should take place at evaluation time when the code is evaluated, | |
751 | or at compilation time when the code is compiled: | |
752 | ||
753 | @findex eval-when | |
754 | @example | |
755 | (eval-when (compile eval) | |
756 | (fluid-set! current-reader my-own-reader)) | |
757 | @end example | |
758 | ||
759 | The @code{eval-when} form above ensures that the @code{current-reader} | |
760 | change occurs at the right time. | |
ec3a8ace NJ |
761 | @end defvar |
762 | ||
07d83abe | 763 | @defvar %load-hook |
42ad91f7 KR |
764 | A procedure to be called @code{(%load-hook @var{filename})} whenever a |
765 | file is loaded, or @code{#f} for no such call. @code{%load-hook} is | |
766 | used by all of the above loading functions (@code{load}, | |
767 | @code{load-path}, @code{primitive-load} and | |
768 | @code{primitive-load-path}). | |
769 | ||
770 | For example an application can set this to show what's loaded, | |
07d83abe MV |
771 | |
772 | @example | |
42ad91f7 KR |
773 | (set! %load-hook (lambda (filename) |
774 | (format #t "Loading ~a ...\n" filename))) | |
07d83abe | 775 | (load-from-path "foo.scm") |
42ad91f7 | 776 | @print{} Loading /usr/local/share/guile/site/foo.scm ... |
07d83abe | 777 | @end example |
07d83abe MV |
778 | @end defvar |
779 | ||
780 | @deffn {Scheme Procedure} current-load-port | |
781 | @deffnx {C Function} scm_current_load_port () | |
782 | Return the current-load-port. | |
783 | The load port is used internally by @code{primitive-load}. | |
784 | @end deffn | |
785 | ||
786 | @defvar %load-extensions | |
787 | A list of default file extensions for files containing Scheme code. | |
788 | @code{%search-load-path} tries each of these extensions when looking for | |
789 | a file to load. By default, @code{%load-extensions} is bound to the | |
790 | list @code{("" ".scm")}. | |
791 | @end defvar | |
792 | ||
8748ffea MG |
793 | @node Character Encoding of Source Files |
794 | @subsection Character Encoding of Source Files | |
795 | ||
4c7b9975 | 796 | @cindex source file encoding |
8748ffea MG |
797 | @cindex primitive-load |
798 | @cindex load | |
799 | Scheme source code files are usually encoded in ASCII, but, the | |
800 | built-in reader can interpret other character encodings. The | |
801 | procedure @code{primitive-load}, and by extension the functions that | |
802 | call it, such as @code{load}, first scan the top 500 characters of the | |
803 | file for a coding declaration. | |
804 | ||
805 | A coding declaration has the form @code{coding: XXXXXX}, where | |
806 | @code{XXXXXX} is the name of a character encoding in which the source | |
807 | code file has been encoded. The coding declaration must appear in a | |
808 | scheme comment. It can either be a semicolon-initiated comment or a block | |
809 | @code{#!} comment. | |
810 | ||
811 | The name of the character encoding in the coding declaration is | |
4c7b9975 LC |
812 | typically lower case and containing only letters, numbers, and hyphens, |
813 | as recognized by @code{set-port-encoding!} (@pxref{Ports, | |
814 | @code{set-port-encoding!}}). Common examples of character encoding | |
815 | names are @code{utf-8} and @code{iso-8859-1}, | |
816 | @url{http://www.iana.org/assignments/character-sets, as defined by | |
817 | IANA}. Thus, the coding declaration is mostly compatible with Emacs. | |
818 | ||
819 | However, there are some differences in encoding names recognized by | |
820 | Emacs and encoding names defined by IANA, the latter being essentially a | |
821 | subset of the former. For instance, @code{latin-1} is a valid encoding | |
822 | name for Emacs, but it's not according to the IANA standard, which Guile | |
a270e133 LC |
823 | follows; instead, you should use @code{iso-8859-1}, which is both |
824 | understood by Emacs and dubbed by IANA (IANA writes it uppercase but | |
825 | Emacs wants it lowercase and Guile is case insensitive.) | |
8748ffea MG |
826 | |
827 | For source code, only a subset of all possible character encodings can | |
828 | be interpreted by the built-in source code reader. Only those | |
829 | character encodings in which ASCII text appears unmodified can be | |
830 | used. This includes @code{UTF-8} and @code{ISO-8859-1} through | |
831 | @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16} | |
832 | and @code{UTF-32} may not be used because they are not compatible with | |
833 | ASCII. | |
834 | ||
835 | @cindex read | |
d6a6989e LC |
836 | @cindex encoding |
837 | @cindex port encoding | |
838 | @findex set-port-encoding! | |
8748ffea MG |
839 | There might be a scenario in which one would want to read non-ASCII |
840 | code from a port, such as with the function @code{read}, instead of | |
841 | with @code{load}. If the port's character encoding is the same as the | |
842 | encoding of the code to be read by the port, not other special | |
843 | handling is necessary. The port will automatically do the character | |
844 | encoding conversion. The functions @code{setlocale} or by | |
d6a6989e LC |
845 | @code{set-port-encoding!} are used to set port encodings |
846 | (@pxref{Ports}). | |
8748ffea MG |
847 | |
848 | If a port is used to read code of unknown character encoding, it can | |
849 | accomplish this in three steps. First, the character encoding of the | |
850 | port should be set to ISO-8859-1 using @code{set-port-encoding!}. | |
851 | Then, the procedure @code{file-encoding}, described below, is used to | |
852 | scan for a coding declaration when reading from the port. As a side | |
853 | effect, it rewinds the port after its scan is complete. After that, | |
854 | the port's character encoding should be set to the encoding returned | |
855 | by @code{file-encoding}, if any, again by using | |
856 | @code{set-port-encoding!}. Then the code can be read as normal. | |
857 | ||
858 | @deffn {Scheme Procedure} file-encoding port | |
859 | @deffnx {C Function} scm_file_encoding port | |
4c7b9975 LC |
860 | Scan the port for an Emacs-like character coding declaration near the |
861 | top of the contents of a port with random-accessible contents | |
862 | (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs, | |
863 | The GNU Emacs Reference Manual}). The coding declaration is of the form | |
864 | @code{coding: XXXXX} and must appear in a Scheme comment. Return a | |
865 | string containing the character encoding of the file if a declaration | |
866 | was found, or @code{#f} otherwise. The port is rewound. | |
8748ffea MG |
867 | @end deffn |
868 | ||
07d83abe MV |
869 | |
870 | @node Delayed Evaluation | |
871 | @subsection Delayed Evaluation | |
872 | @cindex delayed evaluation | |
873 | @cindex promises | |
874 | ||
875 | Promises are a convenient way to defer a calculation until its result | |
876 | is actually needed, and to run such a calculation only once. | |
877 | ||
878 | @deffn syntax delay expr | |
879 | @rnindex delay | |
880 | Return a promise object which holds the given @var{expr} expression, | |
881 | ready to be evaluated by a later @code{force}. | |
882 | @end deffn | |
883 | ||
884 | @deffn {Scheme Procedure} promise? obj | |
885 | @deffnx {C Function} scm_promise_p (obj) | |
886 | Return true if @var{obj} is a promise. | |
887 | @end deffn | |
888 | ||
889 | @rnindex force | |
890 | @deffn {Scheme Procedure} force p | |
891 | @deffnx {C Function} scm_force (p) | |
892 | Return the value obtained from evaluating the @var{expr} in the given | |
893 | promise @var{p}. If @var{p} has previously been forced then its | |
894 | @var{expr} is not evaluated again, instead the value obtained at that | |
895 | time is simply returned. | |
896 | ||
897 | During a @code{force}, an @var{expr} can call @code{force} again on | |
898 | its own promise, resulting in a recursive evaluation of that | |
899 | @var{expr}. The first evaluation to return gives the value for the | |
900 | promise. Higher evaluations run to completion in the normal way, but | |
901 | their results are ignored, @code{force} always returns the first | |
902 | value. | |
903 | @end deffn | |
904 | ||
905 | ||
07d83abe MV |
906 | @c Local Variables: |
907 | @c TeX-master: "guile.texi" | |
908 | @c End: |