Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
f6fd2c03 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012, 2013 |
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. |
925172cf | 20 | * Load Paths:: Where Guile looks for code. |
8748ffea | 21 | * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file. |
07d83abe | 22 | * Delayed Evaluation:: Postponing evaluation until it is needed. |
d062a8c1 | 23 | * Local Evaluation:: Evaluation in a local lexical environment. |
eb7da3d8 | 24 | * Local Inclusion:: Compile-time inclusion of one file in another. |
10d278fd | 25 | * REPL Servers:: Serving a REPL over a socket. |
07d83abe MV |
26 | @end menu |
27 | ||
28 | ||
29 | @node Scheme Syntax | |
30 | @subsection Scheme Syntax: Standard and Guile Extensions | |
31 | ||
32 | @menu | |
33 | * Expression Syntax:: | |
34 | * Comments:: | |
35 | * Block Comments:: | |
36 | * Case Sensitivity:: | |
37 | * Keyword Syntax:: | |
38 | * Reader Extensions:: | |
39 | @end menu | |
40 | ||
41 | ||
42 | @node Expression Syntax | |
43 | @subsubsection Expression Syntax | |
44 | ||
45 | An expression to be evaluated takes one of the following forms. | |
46 | ||
47 | @table @nicode | |
48 | ||
49 | @item @var{symbol} | |
50 | A symbol is evaluated by dereferencing. A binding of that symbol is | |
51 | sought and the value there used. For example, | |
52 | ||
53 | @example | |
54 | (define x 123) | |
55 | x @result{} 123 | |
56 | @end example | |
57 | ||
58 | @item (@var{proc} @var{args}@dots{}) | |
59 | A parenthesised expression is a function call. @var{proc} and each | |
60 | argument are evaluated, then the function (which @var{proc} evaluated | |
61 | to) is called with those arguments. | |
62 | ||
63 | The order in which @var{proc} and the arguments are evaluated is | |
64 | unspecified, so be careful when using expressions with side effects. | |
65 | ||
66 | @example | |
67 | (max 1 2 3) @result{} 3 | |
68 | ||
69 | (define (get-some-proc) min) | |
70 | ((get-some-proc) 1 2 3) @result{} 1 | |
71 | @end example | |
72 | ||
73 | The same sort of parenthesised form is used for a macro invocation, | |
74 | but in that case the arguments are not evaluated. See the | |
75 | descriptions of macros for more on this (@pxref{Macros}, and | |
76 | @pxref{Syntax Rules}). | |
77 | ||
78 | @item @var{constant} | |
79 | Number, string, character and boolean constants evaluate ``to | |
80 | themselves'', so can appear as literals. | |
81 | ||
82 | @example | |
83 | 123 @result{} 123 | |
84 | 99.9 @result{} 99.9 | |
85 | "hello" @result{} "hello" | |
86 | #\z @result{} #\z | |
87 | #t @result{} #t | |
88 | @end example | |
89 | ||
90 | Note that an application must not attempt to modify literal strings, | |
91 | since they may be in read-only memory. | |
92 | ||
93 | @item (quote @var{data}) | |
94 | @itemx '@var{data} | |
95 | @findex quote | |
96 | @findex ' | |
97 | Quoting is used to obtain a literal symbol (instead of a variable | |
98 | reference), a literal list (instead of a function call), or a literal | |
99 | vector. @nicode{'} is simply a shorthand for a @code{quote} form. | |
100 | For example, | |
101 | ||
102 | @example | |
103 | 'x @result{} x | |
104 | '(1 2 3) @result{} (1 2 3) | |
105 | '#(1 (2 3) 4) @result{} #(1 (2 3) 4) | |
106 | (quote x) @result{} x | |
107 | (quote (1 2 3)) @result{} (1 2 3) | |
108 | (quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4) | |
109 | @end example | |
110 | ||
111 | Note that an application must not attempt to modify literal lists or | |
112 | vectors obtained from a @code{quote} form, since they may be in | |
113 | read-only memory. | |
114 | ||
115 | @item (quasiquote @var{data}) | |
116 | @itemx `@var{data} | |
117 | @findex quasiquote | |
118 | @findex ` | |
119 | Backquote quasi-quotation is like @code{quote}, but selected | |
120 | sub-expressions are evaluated. This is a convenient way to construct | |
121 | a list or vector structure most of which is constant, but at certain | |
122 | points should have expressions substituted. | |
123 | ||
124 | The same effect can always be had with suitable @code{list}, | |
125 | @code{cons} or @code{vector} calls, but quasi-quoting is often easier. | |
126 | ||
127 | @table @nicode | |
128 | ||
129 | @item (unquote @var{expr}) | |
130 | @itemx ,@var{expr} | |
131 | @findex unquote | |
132 | @findex , | |
133 | Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates | |
134 | an expression to be evaluated and inserted. The comma syntax @code{,} | |
135 | is simply a shorthand for an @code{unquote} form. For example, | |
136 | ||
137 | @example | |
138 | `(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4) | |
139 | `(1 (unquote (+ 1 1)) 3) @result{} (1 2 3) | |
140 | `#(1 ,(/ 12 2)) @result{} #(1 6) | |
141 | @end example | |
142 | ||
143 | @item (unquote-splicing @var{expr}) | |
144 | @itemx ,@@@var{expr} | |
145 | @findex unquote-splicing | |
146 | @findex ,@@ | |
147 | Within the quasiquote @var{data}, @code{unquote-splicing} or | |
148 | @code{,@@} indicates an expression to be evaluated and the elements of | |
149 | the returned list inserted. @var{expr} must evaluate to a list. The | |
150 | ``comma-at'' syntax @code{,@@} is simply a shorthand for an | |
151 | @code{unquote-splicing} form. | |
152 | ||
153 | @example | |
154 | (define x '(2 3)) | |
155 | `(1 ,@@x 4) @result{} (1 2 3 4) | |
156 | `(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4) | |
157 | `#(9 ,@@x 9) @result{} #(9 2 3 9) | |
158 | @end example | |
159 | ||
160 | Notice @code{,@@} differs from plain @code{,} in the way one level of | |
161 | nesting is stripped. For @code{,@@} the elements of a returned list | |
162 | are inserted, whereas with @code{,} it would be the list itself | |
163 | inserted. | |
164 | @end table | |
165 | ||
166 | @c | |
167 | @c FIXME: What can we say about the mutability of a quasiquote | |
168 | @c result? R5RS doesn't seem to specify anything, though where it | |
169 | @c says backquote without commas is the same as plain quote then | |
170 | @c presumably the "fixed" portions of a quasiquote expression must be | |
171 | @c treated as immutable. | |
172 | @c | |
173 | ||
174 | @end table | |
175 | ||
176 | ||
177 | @node Comments | |
178 | @subsubsection Comments | |
179 | ||
180 | @c FIXME::martin: Review me! | |
181 | ||
182 | Comments in Scheme source files are written by starting them with a | |
183 | semicolon character (@code{;}). The comment then reaches up to the end | |
184 | of the line. Comments can begin at any column, and the may be inserted | |
185 | on the same line as Scheme code. | |
186 | ||
187 | @lisp | |
188 | ; Comment | |
189 | ;; Comment too | |
190 | (define x 1) ; Comment after expression | |
191 | (let ((y 1)) | |
192 | ;; Display something. | |
193 | (display y) | |
194 | ;;; Comment at left margin. | |
195 | (display (+ y 1))) | |
196 | @end lisp | |
197 | ||
198 | It is common to use a single semicolon for comments following | |
199 | expressions on a line, to use two semicolons for comments which are | |
200 | indented like code, and three semicolons for comments which start at | |
201 | column 0, even if they are inside an indented code block. This | |
202 | convention is used when indenting code in Emacs' Scheme mode. | |
203 | ||
204 | ||
205 | @node Block Comments | |
206 | @subsubsection Block Comments | |
456f797b KR |
207 | @cindex multiline comments |
208 | @cindex block comments | |
209 | @cindex #! | |
210 | @cindex !# | |
07d83abe MV |
211 | |
212 | @c FIXME::martin: Review me! | |
213 | ||
07d83abe MV |
214 | In addition to the standard line comments defined by R5RS, Guile has |
215 | another comment type for multiline comments, called @dfn{block | |
216 | comments}. This type of comment begins with the character sequence | |
217 | @code{#!} and ends with the characters @code{!#}, which must appear on a | |
218 | line of their own. These comments are compatible with the block | |
219 | comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell | |
220 | (scsh)}). The characters @code{#!} were chosen because they are the | |
221 | magic characters used in shell scripts for indicating that the name of | |
222 | the program for executing the script follows on the same line. | |
223 | ||
224 | Thus a Guile script often starts like this. | |
225 | ||
226 | @lisp | |
227 | #! /usr/local/bin/guile -s | |
228 | !# | |
229 | @end lisp | |
230 | ||
231 | More details on Guile scripting can be found in the scripting section | |
232 | (@pxref{Guile Scripting}). | |
233 | ||
620c8965 LC |
234 | @cindex R6RS block comments |
235 | @cindex SRFI-30 block comments | |
236 | Similarly, Guile (starting from version 2.0) supports nested block | |
237 | comments as specified by R6RS and | |
238 | @url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}: | |
239 | ||
240 | @lisp | |
241 | (+ #| this is a #| nested |# block comment |# 2) | |
242 | @result{} 3 | |
243 | @end lisp | |
244 | ||
245 | For backward compatibility, this syntax can be overridden with | |
246 | @code{read-hash-extend} (@pxref{Reader Extensions, | |
247 | @code{read-hash-extend}}). | |
248 | ||
8748ffea MG |
249 | There is one special case where the contents of a comment can actually |
250 | affect the interpretation of code. When a character encoding | |
251 | declaration, such as @code{coding: utf-8} appears in one of the first | |
252 | few lines of a source file, it indicates to Guile's default reader | |
253 | that this source code file is not ASCII. For details see @ref{Character | |
254 | Encoding of Source Files}. | |
07d83abe MV |
255 | |
256 | @node Case Sensitivity | |
257 | @subsubsection Case Sensitivity | |
9331ffd8 MW |
258 | @cindex fold-case |
259 | @cindex no-fold-case | |
07d83abe MV |
260 | |
261 | @c FIXME::martin: Review me! | |
262 | ||
263 | Scheme as defined in R5RS is not case sensitive when reading symbols. | |
264 | Guile, on the contrary is case sensitive by default, so the identifiers | |
265 | ||
266 | @lisp | |
267 | guile-whuzzy | |
268 | Guile-Whuzzy | |
269 | @end lisp | |
270 | ||
271 | are the same in R5RS Scheme, but are different in Guile. | |
272 | ||
273 | It is possible to turn off case sensitivity in Guile by setting the | |
1518f649 AW |
274 | reader option @code{case-insensitive}. For more information on reader |
275 | options, @xref{Scheme Read}. | |
07d83abe MV |
276 | |
277 | @lisp | |
278 | (read-enable 'case-insensitive) | |
279 | @end lisp | |
280 | ||
9331ffd8 MW |
281 | It is also possible to disable (or enable) case sensitivity within a |
282 | single file by placing the reader directives @code{#!fold-case} (or | |
283 | @code{#!no-fold-case}) within the file itself. | |
07d83abe MV |
284 | |
285 | @node Keyword Syntax | |
286 | @subsubsection Keyword Syntax | |
287 | ||
288 | ||
289 | @node Reader Extensions | |
290 | @subsubsection Reader Extensions | |
291 | ||
292 | @deffn {Scheme Procedure} read-hash-extend chr proc | |
293 | @deffnx {C Function} scm_read_hash_extend (chr, proc) | |
294 | Install the procedure @var{proc} for reading expressions | |
295 | starting with the character sequence @code{#} and @var{chr}. | |
296 | @var{proc} will be called with two arguments: the character | |
297 | @var{chr} and the port to read further data from. The object | |
3323ec06 NJ |
298 | returned will be the return value of @code{read}. |
299 | Passing @code{#f} for @var{proc} will remove a previous setting. | |
300 | ||
07d83abe MV |
301 | @end deffn |
302 | ||
303 | ||
304 | @node Scheme Read | |
305 | @subsection Reading Scheme Code | |
306 | ||
307 | @rnindex read | |
308 | @deffn {Scheme Procedure} read [port] | |
309 | @deffnx {C Function} scm_read (port) | |
310 | Read an s-expression from the input port @var{port}, or from | |
311 | the current input port if @var{port} is not specified. | |
312 | Any whitespace before the next token is discarded. | |
313 | @end deffn | |
314 | ||
315 | The behaviour of Guile's Scheme reader can be modified by manipulating | |
1518f649 | 316 | its read options. |
07d83abe | 317 | |
1518f649 AW |
318 | @cindex options - read |
319 | @cindex read options | |
07d83abe | 320 | @deffn {Scheme Procedure} read-options [setting] |
9331ffd8 MW |
321 | Display the current settings of the global read options. If |
322 | @var{setting} is omitted, only a short form of the current read options | |
323 | is printed. Otherwise if @var{setting} is the symbol @code{help}, a | |
324 | complete options description is displayed. | |
07d83abe MV |
325 | @end deffn |
326 | ||
1518f649 AW |
327 | The set of available options, and their default values, may be had by |
328 | invoking @code{read-options} at the prompt. | |
329 | ||
330 | @smalllisp | |
331 | scheme@@(guile-user)> (read-options) | |
332 | (square-brackets keywords #f positions) | |
333 | scheme@@(guile-user)> (read-options 'help) | |
334 | copy no Copy source code expressions. | |
335 | positions yes Record positions of source code expressions. | |
336 | case-insensitive no Convert symbols to lower case. | |
337 | keywords #f Style of keyword recognition: #f, 'prefix or 'postfix. | |
338 | r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes. | |
339 | square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility. | |
c869f0c1 AW |
340 | hungry-eol-escapes no In strings, consume leading whitespace after an |
341 | escaped end-of-line. | |
bf9eb54a | 342 | curly-infix no Support SRFI-105 curly infix expressions. |
1518f649 AW |
343 | @end smalllisp |
344 | ||
9331ffd8 MW |
345 | Note that Guile also includes a preliminary mechanism for setting read |
346 | options on a per-port basis. For instance, the @code{case-insensitive} | |
347 | read option is set (or unset) on the port when the reader encounters the | |
bf9eb54a MW |
348 | @code{#!fold-case} or @code{#!no-fold-case} reader directives. |
349 | Similarly, the @code{#!curly-infix} reader directive sets the | |
350 | @code{curly-infix} read option on the port, and | |
351 | @code{#!curly-infix-and-bracket-lists} sets @code{curly-infix} and | |
352 | unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is | |
9331ffd8 MW |
353 | currently no other way to access or set the per-port read options. |
354 | ||
1518f649 AW |
355 | The boolean options may be toggled with @code{read-enable} and |
356 | @code{read-disable}. The non-boolean @code{keywords} option must be set | |
357 | using @code{read-set!}. | |
358 | ||
07d83abe MV |
359 | @deffn {Scheme Procedure} read-enable option-name |
360 | @deffnx {Scheme Procedure} read-disable option-name | |
1233b383 | 361 | @deffnx {Scheme Syntax} read-set! option-name value |
07d83abe MV |
362 | Modify the read options. @code{read-enable} should be used with boolean |
363 | options and switches them on, @code{read-disable} switches them off. | |
1233b383 AW |
364 | |
365 | @code{read-set!} can be used to set an option to a specific value. Due | |
366 | to historical oddities, it is a macro that expects an unquoted option | |
367 | name. | |
07d83abe MV |
368 | @end deffn |
369 | ||
1518f649 AW |
370 | For example, to make @code{read} fold all symbols to their lower case |
371 | (perhaps for compatibility with older Scheme code), you can enter: | |
372 | ||
373 | @lisp | |
374 | (read-enable 'case-insensitive) | |
375 | @end lisp | |
376 | ||
c869f0c1 AW |
377 | For more information on the effect of the @code{r6rs-hex-escapes} and |
378 | @code{hungry-eol-escapes} options, see (@pxref{String Syntax}). | |
1518f649 AW |
379 | |
380 | ||
381 | @node Scheme Write | |
382 | @subsection Writing Scheme Values | |
383 | ||
384 | Any scheme value may be written to a port. Not all values may be read | |
385 | back in (@pxref{Scheme Read}), however. | |
386 | ||
387 | @rnindex write | |
388 | @rnindex print | |
389 | @deffn {Scheme Procedure} write obj [port] | |
390 | Send a representation of @var{obj} to @var{port} or to the current | |
391 | output port if not given. | |
392 | ||
393 | The output is designed to be machine readable, and can be read back | |
394 | with @code{read} (@pxref{Scheme Read}). Strings are printed in | |
395 | double quotes, with escapes if necessary, and characters are printed in | |
396 | @samp{#\} notation. | |
397 | @end deffn | |
398 | ||
399 | @rnindex display | |
400 | @deffn {Scheme Procedure} display obj [port] | |
401 | Send a representation of @var{obj} to @var{port} or to the current | |
402 | output port if not given. | |
403 | ||
404 | The output is designed for human readability, it differs from | |
405 | @code{write} in that strings are printed without double quotes and | |
406 | escapes, and characters are printed as per @code{write-char}, not in | |
407 | @samp{#\} form. | |
408 | @end deffn | |
409 | ||
410 | As was the case with the Scheme reader, there are a few options that | |
411 | affect the behavior of the Scheme printer. | |
412 | ||
413 | @cindex options - print | |
414 | @cindex print options | |
415 | @deffn {Scheme Procedure} print-options [setting] | |
416 | Display the current settings of the read options. If @var{setting} is | |
417 | omitted, only a short form of the current read options is | |
418 | printed. Otherwise if @var{setting} is the symbol @code{help}, a | |
419 | complete options description is displayed. | |
420 | @end deffn | |
421 | ||
422 | The set of available options, and their default values, may be had by | |
423 | invoking @code{print-options} at the prompt. | |
424 | ||
425 | @smalllisp | |
426 | scheme@@(guile-user)> (print-options) | |
427 | (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{") | |
428 | scheme@@(guile-user)> (print-options 'help) | |
429 | highlight-prefix @{ The string to print before highlighted values. | |
430 | highlight-suffix @} The string to print after highlighted values. | |
431 | quote-keywordish-symbols reader How to print symbols that have a colon | |
432 | as their first or last character. The | |
433 | value '#f' does not quote the colons; | |
434 | '#t' quotes them; 'reader' quotes them | |
435 | when the reader option 'keywords' is | |
436 | not '#f'. | |
e2e8ca42 AW |
437 | escape-newlines yes Render newlines as \n when printing |
438 | using `write'. | |
1518f649 AW |
439 | @end smalllisp |
440 | ||
1233b383 | 441 | These options may be modified with the print-set! syntax. |
1518f649 | 442 | |
1233b383 AW |
443 | @deffn {Scheme Syntax} print-set! option-name value |
444 | Modify the print options. Due to historical oddities, @code{print-set!} | |
445 | is a macro that expects an unquoted option name. | |
07d83abe MV |
446 | @end deffn |
447 | ||
448 | ||
449 | @node Fly Evaluation | |
450 | @subsection Procedures for On the Fly Evaluation | |
451 | ||
c2e56d9b AW |
452 | Scheme has the lovely property that its expressions may be represented |
453 | as data. The @code{eval} procedure takes a Scheme datum and evaluates | |
454 | it as code. | |
07d83abe MV |
455 | |
456 | @rnindex eval | |
457 | @c ARGFIXME environment/environment specifier | |
b4fddbbe MV |
458 | @deffn {Scheme Procedure} eval exp module_or_state |
459 | @deffnx {C Function} scm_eval (exp, module_or_state) | |
07d83abe | 460 | Evaluate @var{exp}, a list representing a Scheme expression, |
64de6db5 | 461 | in the top-level environment specified by @var{module_or_state}. |
07d83abe | 462 | While @var{exp} is evaluated (using @code{primitive-eval}), |
64de6db5 BT |
463 | @var{module_or_state} is made the current module. The current module |
464 | is reset to its previous value when @code{eval} returns. | |
b4fddbbe MV |
465 | XXX - dynamic states. |
466 | Example: (eval '(+ 1 2) (interaction-environment)) | |
07d83abe MV |
467 | @end deffn |
468 | ||
469 | @rnindex interaction-environment | |
470 | @deffn {Scheme Procedure} interaction-environment | |
471 | @deffnx {C Function} scm_interaction_environment () | |
472 | Return a specifier for the environment that contains | |
473 | implementation--defined bindings, typically a superset of those | |
474 | listed in the report. The intent is that this procedure will | |
475 | return the environment in which the implementation would | |
476 | evaluate expressions dynamically typed by the user. | |
477 | @end deffn | |
478 | ||
c2e56d9b AW |
479 | @xref{Environments}, for other environments. |
480 | ||
481 | One does not always receive code as Scheme data, of course, and this is | |
482 | especially the case for Guile's other language implementations | |
483 | (@pxref{Other Languages}). For the case in which all you have is a | |
484 | string, we have @code{eval-string}. There is a legacy version of this | |
485 | procedure in the default environment, but you really want the one from | |
486 | @code{(ice-9 eval-string)}, so load it up: | |
487 | ||
488 | @example | |
489 | (use-modules (ice-9 eval-string)) | |
490 | @end example | |
491 | ||
994d87be BT |
492 | @deffn {Scheme Procedure} eval-string string [#:module=#f] [#:file=#f] @ |
493 | [#:line=#f] [#:column=#f] @ | |
494 | [#:lang=(current-language)] @ | |
495 | [#:compile?=#f] | |
c2e56d9b AW |
496 | Parse @var{string} according to the current language, normally Scheme. |
497 | Evaluate or compile the expressions it contains, in order, returning the | |
498 | last expression. | |
499 | ||
500 | If the @var{module} keyword argument is set, save a module excursion | |
501 | (@pxref{Module System Reflection}) and set the current module to | |
502 | @var{module} before evaluation. | |
503 | ||
504 | The @var{file}, @var{line}, and @var{column} keyword arguments can be | |
505 | used to indicate that the source string begins at a particular source | |
506 | location. | |
507 | ||
508 | Finally, @var{lang} is a language, defaulting to the current language, | |
509 | and the expression is compiled if @var{compile?} is true or there is no | |
510 | evaluator for the given language. | |
511 | @end deffn | |
512 | ||
513 | @deffn {C Function} scm_eval_string (string) | |
07d83abe | 514 | @deffnx {C Function} scm_eval_string_in_module (string, module) |
c2e56d9b AW |
515 | These C bindings call @code{eval-string} from @code{(ice-9 |
516 | eval-string)}, evaluating within @var{module} or the current module. | |
07d83abe MV |
517 | @end deffn |
518 | ||
40296bab | 519 | @deftypefn {C Function} SCM scm_c_eval_string (const char *string) |
c2e56d9b AW |
520 | @code{scm_eval_string}, but taking a C string in locale encoding instead |
521 | of an @code{SCM}. | |
40296bab KR |
522 | @end deftypefn |
523 | ||
df0a1002 | 524 | @deffn {Scheme Procedure} apply proc arg @dots{} arglst |
07d83abe MV |
525 | @deffnx {C Function} scm_apply_0 (proc, arglst) |
526 | @deffnx {C Function} scm_apply_1 (proc, arg1, arglst) | |
527 | @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst) | |
528 | @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst) | |
529 | @deffnx {C Function} scm_apply (proc, arg, rest) | |
530 | @rnindex apply | |
df0a1002 | 531 | Call @var{proc} with arguments @var{arg} @dots{} and the |
07d83abe MV |
532 | elements of the @var{arglst} list. |
533 | ||
534 | @code{scm_apply} takes parameters corresponding to a Scheme level | |
df0a1002 BT |
535 | @code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the |
536 | last element of the @var{rest} list make up @var{arg} @dots{}, and the | |
537 | last element of @var{rest} is the @var{arglst} list. Or if @var{rest} | |
538 | is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and | |
539 | (@var{arg1}) is the @var{arglst}. | |
07d83abe MV |
540 | |
541 | @var{arglst} is not modified, but the @var{rest} list passed to | |
542 | @code{scm_apply} is modified. | |
543 | @end deffn | |
544 | ||
545 | @deffn {C Function} scm_call_0 (proc) | |
546 | @deffnx {C Function} scm_call_1 (proc, arg1) | |
547 | @deffnx {C Function} scm_call_2 (proc, arg1, arg2) | |
548 | @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3) | |
8d596b11 | 549 | @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4) |
13459a96 AW |
550 | @deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5) |
551 | @deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6) | |
741b8a23 MW |
552 | @deffnx {C Function} scm_call_7 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7) |
553 | @deffnx {C Function} scm_call_8 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) | |
554 | @deffnx {C Function} scm_call_9 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) | |
07d83abe MV |
555 | Call @var{proc} with the given arguments. |
556 | @end deffn | |
557 | ||
07c2ca0f | 558 | @deffn {C Function} scm_call (proc, ...) |
741b8a23 MW |
559 | Call @var{proc} with any number of arguments. The argument list must be |
560 | terminated by @code{SCM_UNDEFINED}. For example: | |
561 | ||
562 | @example | |
07c2ca0f MW |
563 | scm_call (scm_c_public_ref ("guile", "+"), |
564 | scm_from_int (1), | |
565 | scm_from_int (2), | |
566 | SCM_UNDEFINED); | |
741b8a23 MW |
567 | @end example |
568 | @end deffn | |
569 | ||
13459a96 AW |
570 | @deffn {C Function} scm_call_n (proc, argv, nargs) |
571 | Call @var{proc} with the array of arguments @var{argv}, as a | |
572 | @code{SCM*}. The length of the arguments should be passed in | |
573 | @var{nargs}, as a @code{size_t}. | |
574 | @end deffn | |
575 | ||
07d83abe MV |
576 | @deffn {Scheme Procedure} apply:nconc2last lst |
577 | @deffnx {C Function} scm_nconc2last (lst) | |
578 | @var{lst} should be a list (@var{arg1} @dots{} @var{argN} | |
579 | @var{arglst}), with @var{arglst} being a list. This function returns | |
580 | a list comprising @var{arg1} to @var{argN} plus the elements of | |
581 | @var{arglst}. @var{lst} is modified to form the return. @var{arglst} | |
582 | is not modified, though the return does share structure with it. | |
583 | ||
584 | This operation collects up the arguments from a list which is | |
585 | @code{apply} style parameters. | |
586 | @end deffn | |
587 | ||
588 | @deffn {Scheme Procedure} primitive-eval exp | |
589 | @deffnx {C Function} scm_primitive_eval (exp) | |
590 | Evaluate @var{exp} in the top-level environment specified by | |
591 | the current module. | |
592 | @end deffn | |
593 | ||
594 | ||
00ce5125 AW |
595 | @node Compilation |
596 | @subsection Compiling Scheme Code | |
597 | ||
598 | The @code{eval} procedure directly interprets the S-expression | |
599 | representation of Scheme. An alternate strategy for evaluation is to | |
600 | determine ahead of time what computations will be necessary to | |
601 | evaluate the expression, and then use that recipe to produce the | |
602 | desired results. This is known as @dfn{compilation}. | |
603 | ||
604 | While it is possible to compile simple Scheme expressions such as | |
605 | @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most | |
ca445ba5 | 606 | interesting in the context of procedures. Compiling a lambda expression |
00ce5125 AW |
607 | produces a compiled procedure, which is just like a normal procedure |
608 | except typically much faster, because it can bypass the generic | |
609 | interpreter. | |
610 | ||
611 | Functions from system modules in a Guile installation are normally | |
612 | compiled already, so they load and run quickly. | |
613 | ||
14d2ee31 | 614 | @cindex automatic compilation |
00ce5125 AW |
615 | Note that well-written Scheme programs will not typically call the |
616 | procedures in this section, for the same reason that it is often bad | |
14d2ee31 LC |
617 | taste to use @code{eval}. By default, Guile automatically compiles any |
618 | files it encounters that have not been compiled yet (@pxref{Invoking | |
619 | Guile, @code{--auto-compile}}). The compiler can also be invoked | |
b8b06598 | 620 | explicitly from the shell as @code{guild compile foo.scm}. |
00ce5125 AW |
621 | |
622 | (Why are calls to @code{eval} and @code{compile} usually in bad taste? | |
623 | Because they are limited, in that they can only really make sense for | |
624 | top-level expressions. Also, most needs for ``compile-time'' | |
625 | computation are fulfilled by macros and closures. Of course one good | |
626 | counterexample is the REPL itself, or any code that reads expressions | |
627 | from a port.) | |
628 | ||
1e56cff2 AW |
629 | Automatic compilation generally works transparently, without any need |
630 | for user intervention. However Guile does not yet do proper dependency | |
631 | tracking, so that if file @file{@var{a}.scm} uses macros from | |
632 | @file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm} | |
633 | would not be automatically recompiled. To forcibly invalidate the | |
634 | auto-compilation cache, pass the @code{--fresh-auto-compile} option to | |
635 | Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to | |
636 | @code{fresh} (instead of to @code{0} or @code{1}). | |
637 | ||
ca445ba5 AW |
638 | For more information on the compiler itself, see @ref{Compiling to the |
639 | Virtual Machine}. For information on the virtual machine, see @ref{A | |
00ce5125 AW |
640 | Virtual Machine for Guile}. |
641 | ||
b8b06598 | 642 | The command-line interface to Guile's compiler is the @command{guild |
788cf402 LC |
643 | compile} command: |
644 | ||
b8b06598 | 645 | @deffn {Command} {guild compile} [@option{option}...] @var{file}... |
788cf402 LC |
646 | Compile @var{file}, a source file, and store bytecode in the compilation cache |
647 | or in the file specified by the @option{-o} option. The following options are | |
648 | available: | |
649 | ||
650 | @table @option | |
651 | ||
652 | @item -L @var{dir} | |
653 | @itemx --load-path=@var{dir} | |
654 | Add @var{dir} to the front of the module load path. | |
655 | ||
656 | @item -o @var{ofile} | |
657 | @itemx --output=@var{ofile} | |
eda06220 LC |
658 | Write output bytecode to @var{ofile}. By convention, bytecode file |
659 | names end in @code{.go}. When @option{-o} is omitted, the output file | |
660 | name is as for @code{compile-file} (see below). | |
788cf402 LC |
661 | |
662 | @item -W @var{warning} | |
663 | @itemx --warn=@var{warning} | |
ffd901eb | 664 | @cindex warnings, compiler |
75365375 LC |
665 | Emit warnings of type @var{warning}; use @code{--warn=help} for a list |
666 | of available warnings and their description. Currently recognized | |
667 | warnings include @code{unused-variable}, @code{unused-toplevel}, | |
679a3556 LC |
668 | @code{unbound-variable}, @code{arity-mismatch}, @code{format}, |
669 | @code{duplicate-case-datum}, and @code{bad-case-datum}. | |
788cf402 LC |
670 | |
671 | @item -f @var{lang} | |
672 | @itemx --from=@var{lang} | |
673 | Use @var{lang} as the source language of @var{file}. If this option is omitted, | |
674 | @code{scheme} is assumed. | |
675 | ||
676 | @item -t @var{lang} | |
677 | @itemx --to=@var{lang} | |
678 | Use @var{lang} as the target language of @var{file}. If this option is omitted, | |
679 | @code{objcode} is assumed. | |
680 | ||
d4b88945 LC |
681 | @item -T @var{target} |
682 | @itemx --target=@var{target} | |
683 | Produce bytecode for @var{target} instead of @var{%host-type} | |
684 | (@pxref{Build Config, %host-type}). Target must be a valid GNU triplet, | |
685 | such as @code{armv5tel-unknown-linux-gnueabi} (@pxref{Specifying Target | |
686 | Triplets,,, autoconf, GNU Autoconf Manual}). | |
687 | ||
788cf402 LC |
688 | @end table |
689 | ||
eda06220 LC |
690 | Each @var{file} is assumed to be UTF-8-encoded, unless it contains a |
691 | coding declaration as recognized by @code{file-encoding} | |
692 | (@pxref{Character Encoding of Source Files}). | |
788cf402 LC |
693 | @end deffn |
694 | ||
695 | The compiler can also be invoked directly by Scheme code using the procedures | |
696 | below: | |
697 | ||
994d87be BT |
698 | @deffn {Scheme Procedure} compile exp [#:env=#f] @ |
699 | [#:from=(current-language)] @ | |
700 | [#:to=value] [#:opts=()] | |
00ce5125 AW |
701 | Compile the expression @var{exp} in the environment @var{env}. If |
702 | @var{exp} is a procedure, the result will be a compiled procedure; | |
703 | otherwise @code{compile} is mostly equivalent to @code{eval}. | |
704 | ||
705 | For a discussion of languages and compiler options, @xref{Compiling to | |
706 | the Virtual Machine}. | |
707 | @end deffn | |
708 | ||
994d87be BT |
709 | @deffn {Scheme Procedure} compile-file file [#:output-file=#f] @ |
710 | [#:from=(current-language)] [#:to='objcode] @ | |
711 | [#:env=(default-environment from)] @ | |
712 | [#:opts='()] @ | |
713 | [#:canonicalization='relative] | |
00ce5125 AW |
714 | Compile the file named @var{file}. |
715 | ||
043bca03 AW |
716 | Output will be written to a @var{output-file}. If you do not supply an |
717 | output file name, output is written to a file in the cache directory, as | |
718 | computed by @code{(compiled-file-name @var{file})}. | |
719 | ||
720 | @var{from} and @var{to} specify the source and target languages. | |
721 | @xref{Compiling to the Virtual Machine}, for more information on these | |
722 | options, and on @var{env} and @var{opts}. | |
eda06220 | 723 | |
b8b06598 | 724 | As with @command{guild compile}, @var{file} is assumed to be |
eda06220 | 725 | UTF-8-encoded unless it contains a coding declaration. |
00ce5125 AW |
726 | @end deffn |
727 | ||
728 | @deffn {Scheme Procedure} compiled-file-name file | |
043bca03 AW |
729 | Compute a cached location for a compiled version of a Scheme file named |
730 | @var{file}. | |
731 | ||
732 | This file will usually be below the @file{$HOME/.cache/guile/ccache} | |
733 | directory, depending on the value of the @env{XDG_CACHE_HOME} | |
734 | environment variable. The intention is that @code{compiled-file-name} | |
735 | provides a fallback location for caching auto-compiled files. If you | |
736 | want to place a compile file in the @code{%load-compiled-path}, you | |
737 | should pass the @var{output-file} option to @code{compile-file}, | |
738 | explicitly. | |
00ce5125 AW |
739 | @end deffn |
740 | ||
14d2ee31 LC |
741 | @defvr {Scheme Variable} %auto-compilation-options |
742 | This variable contains the options passed to the @code{compile-file} | |
743 | procedure when auto-compiling source files. By default, it enables | |
744 | useful compilation warnings. It can be customized from @file{~/.guile}. | |
745 | @end defvr | |
746 | ||
07d83abe MV |
747 | @node Loading |
748 | @subsection Loading Scheme Code from File | |
749 | ||
750 | @rnindex load | |
ec3a8ace | 751 | @deffn {Scheme Procedure} load filename [reader] |
07d83abe | 752 | Load @var{filename} and evaluate its contents in the top-level |
925172cf | 753 | environment. |
ec3a8ace NJ |
754 | |
755 | @var{reader} if provided should be either @code{#f}, or a procedure with | |
756 | the signature @code{(lambda (port) @dots{})} which reads the next | |
757 | expression from @var{port}. If @var{reader} is @code{#f} or absent, | |
758 | Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}). | |
759 | ||
760 | The @var{reader} argument takes effect by setting the value of the | |
761 | @code{current-reader} fluid (see below) before loading the file, and | |
762 | restoring its previous value when loading is complete. The Scheme code | |
763 | inside @var{filename} can itself change the current reader procedure on | |
764 | the fly by setting @code{current-reader} fluid. | |
765 | ||
766 | If the variable @code{%load-hook} is defined, it should be bound to a | |
767 | procedure that will be called before any code is loaded. See | |
768 | documentation for @code{%load-hook} later in this section. | |
07d83abe MV |
769 | @end deffn |
770 | ||
00ce5125 | 771 | @deffn {Scheme Procedure} load-compiled filename |
925172cf | 772 | Load the compiled file named @var{filename}. |
00ce5125 AW |
773 | |
774 | Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then | |
775 | calling @code{load-compiled} on the resulting file is equivalent to | |
776 | calling @code{load} on the source file. | |
777 | @end deffn | |
778 | ||
07d83abe MV |
779 | @deffn {Scheme Procedure} primitive-load filename |
780 | @deffnx {C Function} scm_primitive_load (filename) | |
925172cf AW |
781 | Load the file named @var{filename} and evaluate its contents in the |
782 | top-level environment. @var{filename} must either be a full pathname or | |
783 | be a pathname relative to the current directory. If the variable | |
784 | @code{%load-hook} is defined, it should be bound to a procedure that | |
785 | will be called before any code is loaded. See the documentation for | |
786 | @code{%load-hook} later in this section. | |
07d83abe MV |
787 | @end deffn |
788 | ||
40296bab KR |
789 | @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename) |
790 | @code{scm_primitive_load}, but taking a C string instead of an | |
791 | @code{SCM}. | |
792 | @end deftypefn | |
793 | ||
ec3a8ace NJ |
794 | @defvar current-reader |
795 | @code{current-reader} holds the read procedure that is currently being | |
796 | used by the above loading procedures to read expressions (from the file | |
797 | that they are loading). @code{current-reader} is a fluid, so it has an | |
798 | independent value in each dynamic root and should be read and set using | |
799 | @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic | |
800 | States}). | |
1ebe6a63 LC |
801 | |
802 | Changing @code{current-reader} is typically useful to introduce local | |
803 | syntactic changes, such that code following the @code{fluid-set!} call | |
804 | is read using the newly installed reader. The @code{current-reader} | |
805 | change should take place at evaluation time when the code is evaluated, | |
806 | or at compilation time when the code is compiled: | |
807 | ||
808 | @findex eval-when | |
809 | @example | |
810 | (eval-when (compile eval) | |
811 | (fluid-set! current-reader my-own-reader)) | |
812 | @end example | |
813 | ||
814 | The @code{eval-when} form above ensures that the @code{current-reader} | |
815 | change occurs at the right time. | |
ec3a8ace NJ |
816 | @end defvar |
817 | ||
07d83abe | 818 | @defvar %load-hook |
42ad91f7 KR |
819 | A procedure to be called @code{(%load-hook @var{filename})} whenever a |
820 | file is loaded, or @code{#f} for no such call. @code{%load-hook} is | |
925172cf | 821 | used by all of the loading functions (@code{load} and |
21ad60a1 | 822 | @code{primitive-load}, and @code{load-from-path} and |
925172cf | 823 | @code{primitive-load-path} documented in the next section). |
42ad91f7 KR |
824 | |
825 | For example an application can set this to show what's loaded, | |
07d83abe MV |
826 | |
827 | @example | |
42ad91f7 KR |
828 | (set! %load-hook (lambda (filename) |
829 | (format #t "Loading ~a ...\n" filename))) | |
07d83abe | 830 | (load-from-path "foo.scm") |
42ad91f7 | 831 | @print{} Loading /usr/local/share/guile/site/foo.scm ... |
07d83abe | 832 | @end example |
07d83abe MV |
833 | @end defvar |
834 | ||
835 | @deffn {Scheme Procedure} current-load-port | |
836 | @deffnx {C Function} scm_current_load_port () | |
837 | Return the current-load-port. | |
838 | The load port is used internally by @code{primitive-load}. | |
839 | @end deffn | |
840 | ||
925172cf AW |
841 | @node Load Paths |
842 | @subsection Load Paths | |
843 | ||
844 | The procedure in the previous section look for Scheme code in the file | |
845 | system at specific location. Guile also has some procedures to search | |
846 | the load path for code. | |
847 | ||
0740cb49 AW |
848 | @defvar %load-path |
849 | List of directories which should be searched for Scheme modules and | |
bd31bce6 MW |
850 | libraries. When Guile starts up, @code{%load-path} is initialized to |
851 | the default load path @code{(list (%library-dir) (%site-dir) | |
852 | (%global-site-dir) (%package-data-dir))}. The @env{GUILE_LOAD_PATH} | |
853 | environment variable can be used to prepend or append additional | |
854 | directories (@pxref{Environment Variables}). | |
855 | ||
856 | @xref{Build Config}, for more on @code{%site-dir} and related | |
857 | procedures. | |
0740cb49 | 858 | @end defvar |
925172cf AW |
859 | |
860 | @deffn {Scheme Procedure} load-from-path filename | |
861 | Similar to @code{load}, but searches for @var{filename} in the load | |
862 | paths. Preferentially loads a compiled version of the file, if it is | |
863 | available and up-to-date. | |
864 | @end deffn | |
865 | ||
866 | A user can extend the load path by calling @code{add-to-load-path}. | |
867 | ||
868 | @deffn {Scheme Syntax} add-to-load-path dir | |
869 | Add @var{dir} to the load path. | |
0740cb49 | 870 | @end deffn |
925172cf AW |
871 | |
872 | For example, a script might include this form to add the directory that | |
873 | it is in to the load path: | |
874 | ||
875 | @example | |
876 | (add-to-load-path (dirname (current-filename))) | |
877 | @end example | |
925172cf AW |
878 | |
879 | It's better to use @code{add-to-load-path} than to modify | |
880 | @code{%load-path} directly, because @code{add-to-load-path} takes care | |
881 | of modifying the path both at compile-time and at run-time. | |
882 | ||
925172cf AW |
883 | @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found] |
884 | @deffnx {C Function} scm_primitive_load_path (filename) | |
885 | Search @code{%load-path} for the file named @var{filename} and | |
886 | load it into the top-level environment. If @var{filename} is a | |
887 | relative pathname and is not found in the list of search paths, | |
f6fd2c03 | 888 | an error is signalled. Preferentially loads a compiled version of the |
925172cf AW |
889 | file, if it is available and up-to-date. |
890 | ||
f6fd2c03 AW |
891 | If @var{filename} is a relative pathname and is not found in the list of |
892 | search paths, one of three things may happen, depending on the optional | |
893 | second argument, @var{exception-on-not-found}. If it is @code{#f}, | |
894 | @code{#f} will be returned. If it is a procedure, it will be called | |
895 | with no arguments. (This allows a distinction to be made between | |
896 | exceptions raised by loading a file, and exceptions related to the | |
897 | loader itself.) Otherwise an error is signalled. | |
898 | ||
899 | For compatibility with Guile 1.8 and earlier, the C function takes only | |
900 | one argument, which can be either a string (the file name) or an | |
901 | argument list. | |
925172cf AW |
902 | @end deffn |
903 | ||
904 | @deffn {Scheme Procedure} %search-load-path filename | |
905 | @deffnx {C Function} scm_sys_search_load_path (filename) | |
0740cb49 AW |
906 | Search @code{%load-path} for the file named @var{filename}, which must |
907 | be readable by the current user. If @var{filename} is found in the list | |
908 | of paths to search or is an absolute pathname, return its full pathname. | |
909 | Otherwise, return @code{#f}. Filenames may have any of the optional | |
910 | extensions in the @code{%load-extensions} list; @code{%search-load-path} | |
925172cf AW |
911 | will try each extension automatically. |
912 | @end deffn | |
913 | ||
07d83abe MV |
914 | @defvar %load-extensions |
915 | A list of default file extensions for files containing Scheme code. | |
916 | @code{%search-load-path} tries each of these extensions when looking for | |
917 | a file to load. By default, @code{%load-extensions} is bound to the | |
918 | list @code{("" ".scm")}. | |
919 | @end defvar | |
920 | ||
0740cb49 AW |
921 | As mentioned above, when Guile searches the @code{%load-path} for a |
922 | source file, it will also search the @code{%load-compiled-path} for a | |
923 | corresponding compiled file. If the compiled file is as new or newer | |
924 | than the source file, it will be loaded instead of the source file, | |
925 | using @code{load-compiled}. | |
926 | ||
927 | @defvar %load-compiled-path | |
928 | Like @code{%load-path}, but for compiled files. By default, this path | |
929 | has two entries: one for compiled files from Guile itself, and one for | |
bd31bce6 MW |
930 | site packages. The @env{GUILE_LOAD_COMPILED_PATH} environment variable |
931 | can be used to prepend or append additional directories | |
932 | (@pxref{Environment Variables}). | |
0740cb49 AW |
933 | @end defvar |
934 | ||
935 | When @code{primitive-load-path} searches the @code{%load-compiled-path} | |
936 | for a corresponding compiled file for a relative path it does so by | |
937 | appending @code{.go} to the relative path. For example, searching for | |
938 | @code{ice-9/popen} could find | |
939 | @code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of | |
940 | @code{/usr/share/guile/2.0/ice-9/popen.scm}. | |
941 | ||
942 | If @code{primitive-load-path} does not find a corresponding @code{.go} | |
943 | file in the @code{%load-compiled-path}, or the @code{.go} file is out of | |
944 | date, it will search for a corresponding auto-compiled file in the | |
945 | fallback path, possibly creating one if one does not exist. | |
946 | ||
947 | @xref{Installing Site Packages}, for more on how to correctly install | |
948 | site packages. @xref{Modules and the File System}, for more on the | |
949 | relationship between load paths and modules. @xref{Compilation}, for | |
950 | more on the fallback path and auto-compilation. | |
951 | ||
952 | Finally, there are a couple of helper procedures for general path | |
953 | manipulation. | |
954 | ||
955 | @deffn {Scheme Procedure} parse-path path [tail] | |
956 | @deffnx {C Function} scm_parse_path (path, tail) | |
957 | Parse @var{path}, which is expected to be a colon-separated string, into | |
958 | a list and return the resulting list with @var{tail} appended. If | |
959 | @var{path} is @code{#f}, @var{tail} is returned. | |
960 | @end deffn | |
961 | ||
bd31bce6 MW |
962 | @deffn {Scheme Procedure} parse-path-with-ellipsis path base |
963 | @deffnx {C Function} scm_parse_path_with_ellipsis (path, base) | |
964 | Parse @var{path}, which is expected to be a colon-separated string, into | |
965 | a list and return the resulting list with @var{base} (a list) spliced in | |
966 | place of the @code{...} path component, if present, or else @var{base} | |
967 | is added to the end. If @var{path} is @code{#f}, @var{base} is | |
968 | returned. | |
969 | @end deffn | |
970 | ||
0740cb49 AW |
971 | @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]] |
972 | @deffnx {C Function} scm_search_path (path, filename, rest) | |
973 | Search @var{path} for a directory containing a file named | |
974 | @var{filename}. The file must be readable, and not a directory. If we | |
975 | find one, return its full filename; otherwise, return @code{#f}. If | |
976 | @var{filename} is absolute, return it unchanged. If given, | |
977 | @var{extensions} is a list of strings; for each directory in @var{path}, | |
978 | we search for @var{filename} concatenated with each @var{extension}. If | |
979 | @var{require-exts?} is true, require that the returned file name have | |
980 | one of the given extensions; if @var{require-exts?} is not given, it | |
981 | defaults to @code{#f}. | |
982 | ||
983 | For compatibility with Guile 1.8 and earlier, the C function takes only | |
984 | three arguments. | |
985 | @end deffn | |
986 | ||
925172cf | 987 | |
8748ffea MG |
988 | @node Character Encoding of Source Files |
989 | @subsection Character Encoding of Source Files | |
990 | ||
4c7b9975 | 991 | @cindex source file encoding |
8748ffea MG |
992 | @cindex primitive-load |
993 | @cindex load | |
994 | Scheme source code files are usually encoded in ASCII, but, the | |
995 | built-in reader can interpret other character encodings. The | |
996 | procedure @code{primitive-load}, and by extension the functions that | |
997 | call it, such as @code{load}, first scan the top 500 characters of the | |
998 | file for a coding declaration. | |
999 | ||
1000 | A coding declaration has the form @code{coding: XXXXXX}, where | |
1001 | @code{XXXXXX} is the name of a character encoding in which the source | |
1002 | code file has been encoded. The coding declaration must appear in a | |
1003 | scheme comment. It can either be a semicolon-initiated comment or a block | |
1004 | @code{#!} comment. | |
1005 | ||
1006 | The name of the character encoding in the coding declaration is | |
4c7b9975 LC |
1007 | typically lower case and containing only letters, numbers, and hyphens, |
1008 | as recognized by @code{set-port-encoding!} (@pxref{Ports, | |
1009 | @code{set-port-encoding!}}). Common examples of character encoding | |
1010 | names are @code{utf-8} and @code{iso-8859-1}, | |
1011 | @url{http://www.iana.org/assignments/character-sets, as defined by | |
1012 | IANA}. Thus, the coding declaration is mostly compatible with Emacs. | |
1013 | ||
1014 | However, there are some differences in encoding names recognized by | |
1015 | Emacs and encoding names defined by IANA, the latter being essentially a | |
1016 | subset of the former. For instance, @code{latin-1} is a valid encoding | |
1017 | name for Emacs, but it's not according to the IANA standard, which Guile | |
a270e133 LC |
1018 | follows; instead, you should use @code{iso-8859-1}, which is both |
1019 | understood by Emacs and dubbed by IANA (IANA writes it uppercase but | |
1020 | Emacs wants it lowercase and Guile is case insensitive.) | |
8748ffea MG |
1021 | |
1022 | For source code, only a subset of all possible character encodings can | |
1023 | be interpreted by the built-in source code reader. Only those | |
1024 | character encodings in which ASCII text appears unmodified can be | |
1025 | used. This includes @code{UTF-8} and @code{ISO-8859-1} through | |
1026 | @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16} | |
1027 | and @code{UTF-32} may not be used because they are not compatible with | |
1028 | ASCII. | |
1029 | ||
1030 | @cindex read | |
d6a6989e LC |
1031 | @cindex encoding |
1032 | @cindex port encoding | |
1033 | @findex set-port-encoding! | |
8748ffea MG |
1034 | There might be a scenario in which one would want to read non-ASCII |
1035 | code from a port, such as with the function @code{read}, instead of | |
1036 | with @code{load}. If the port's character encoding is the same as the | |
1037 | encoding of the code to be read by the port, not other special | |
1038 | handling is necessary. The port will automatically do the character | |
1039 | encoding conversion. The functions @code{setlocale} or by | |
d6a6989e LC |
1040 | @code{set-port-encoding!} are used to set port encodings |
1041 | (@pxref{Ports}). | |
8748ffea MG |
1042 | |
1043 | If a port is used to read code of unknown character encoding, it can | |
1044 | accomplish this in three steps. First, the character encoding of the | |
1045 | port should be set to ISO-8859-1 using @code{set-port-encoding!}. | |
1046 | Then, the procedure @code{file-encoding}, described below, is used to | |
1047 | scan for a coding declaration when reading from the port. As a side | |
1048 | effect, it rewinds the port after its scan is complete. After that, | |
1049 | the port's character encoding should be set to the encoding returned | |
1050 | by @code{file-encoding}, if any, again by using | |
1051 | @code{set-port-encoding!}. Then the code can be read as normal. | |
1052 | ||
1053 | @deffn {Scheme Procedure} file-encoding port | |
5f6ffd66 | 1054 | @deffnx {C Function} scm_file_encoding (port) |
4c7b9975 LC |
1055 | Scan the port for an Emacs-like character coding declaration near the |
1056 | top of the contents of a port with random-accessible contents | |
1057 | (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs, | |
1058 | The GNU Emacs Reference Manual}). The coding declaration is of the form | |
1059 | @code{coding: XXXXX} and must appear in a Scheme comment. Return a | |
1060 | string containing the character encoding of the file if a declaration | |
1061 | was found, or @code{#f} otherwise. The port is rewound. | |
8748ffea MG |
1062 | @end deffn |
1063 | ||
07d83abe MV |
1064 | |
1065 | @node Delayed Evaluation | |
1066 | @subsection Delayed Evaluation | |
1067 | @cindex delayed evaluation | |
1068 | @cindex promises | |
1069 | ||
1070 | Promises are a convenient way to defer a calculation until its result | |
41502bd0 MW |
1071 | is actually needed, and to run such a calculation only once. Also |
1072 | @pxref{SRFI-45}. | |
07d83abe MV |
1073 | |
1074 | @deffn syntax delay expr | |
1075 | @rnindex delay | |
1076 | Return a promise object which holds the given @var{expr} expression, | |
1077 | ready to be evaluated by a later @code{force}. | |
1078 | @end deffn | |
1079 | ||
1080 | @deffn {Scheme Procedure} promise? obj | |
1081 | @deffnx {C Function} scm_promise_p (obj) | |
1082 | Return true if @var{obj} is a promise. | |
1083 | @end deffn | |
1084 | ||
1085 | @rnindex force | |
1086 | @deffn {Scheme Procedure} force p | |
1087 | @deffnx {C Function} scm_force (p) | |
1088 | Return the value obtained from evaluating the @var{expr} in the given | |
1089 | promise @var{p}. If @var{p} has previously been forced then its | |
1090 | @var{expr} is not evaluated again, instead the value obtained at that | |
1091 | time is simply returned. | |
1092 | ||
1093 | During a @code{force}, an @var{expr} can call @code{force} again on | |
1094 | its own promise, resulting in a recursive evaluation of that | |
1095 | @var{expr}. The first evaluation to return gives the value for the | |
1096 | promise. Higher evaluations run to completion in the normal way, but | |
1097 | their results are ignored, @code{force} always returns the first | |
1098 | value. | |
1099 | @end deffn | |
1100 | ||
1101 | ||
d062a8c1 AW |
1102 | @node Local Evaluation |
1103 | @subsection Local Evaluation | |
1104 | ||
68c31a42 AW |
1105 | Guile includes a facility to capture a lexical environment, and later |
1106 | evaluate a new expression within that environment. This code is | |
1107 | implemented in a module. | |
1108 | ||
1109 | @example | |
1110 | (use-modules (ice-9 local-eval)) | |
1111 | @end example | |
1112 | ||
d062a8c1 AW |
1113 | @deffn syntax the-environment |
1114 | Captures and returns a lexical environment for use with | |
1115 | @code{local-eval} or @code{local-compile}. | |
1116 | @end deffn | |
1117 | ||
1118 | @deffn {Scheme Procedure} local-eval exp env | |
1119 | @deffnx {C Function} scm_local_eval (exp, env) | |
68c31a42 AW |
1120 | @deffnx {Scheme Procedure} local-compile exp env [opts=()] |
1121 | Evaluate or compile the expression @var{exp} in the lexical environment | |
1122 | @var{env}. | |
1123 | @end deffn | |
1124 | ||
1125 | Here is a simple example, illustrating that it is the variable | |
1126 | that gets captured, not just its value at one point in time. | |
1127 | ||
1128 | @example | |
1129 | (define e (let ((x 100)) (the-environment))) | |
1130 | (define fetch-x (local-eval '(lambda () x) e)) | |
1131 | (fetch-x) | |
1132 | @result{} 100 | |
1133 | (local-eval '(set! x 42) e) | |
1134 | (fetch-x) | |
1135 | @result{} 42 | |
1136 | @end example | |
1137 | ||
1138 | While @var{exp} is evaluated within the lexical environment of | |
1139 | @code{(the-environment)}, it has the dynamic environment of the call to | |
1140 | @code{local-eval}. | |
1141 | ||
1142 | @code{local-eval} and @code{local-compile} can only evaluate | |
1143 | expressions, not definitions. | |
1144 | ||
1145 | @example | |
1146 | (local-eval '(define foo 42) | |
1147 | (let ((x 100)) (the-environment))) | |
1148 | @result{} syntax error: definition in expression context | |
1149 | @end example | |
1150 | ||
1151 | Note that the current implementation of @code{(the-environment)} only | |
1152 | captures ``normal'' lexical bindings, and pattern variables bound by | |
1153 | @code{syntax-case}. It does not currently capture local syntax | |
1154 | transformers bound by @code{let-syntax}, @code{letrec-syntax} or | |
1155 | non-top-level @code{define-syntax} forms. Any attempt to reference such | |
1156 | captured syntactic keywords via @code{local-eval} or | |
1157 | @code{local-compile} produces an error. | |
d062a8c1 AW |
1158 | |
1159 | ||
eb7da3d8 AW |
1160 | @node Local Inclusion |
1161 | @subsection Local Inclusion | |
1162 | ||
1163 | This section has discussed various means of linking Scheme code | |
1164 | together: fundamentally, loading up files at run-time using @code{load} | |
1165 | and @code{load-compiled}. Guile provides another option to compose | |
1166 | parts of programs together at expansion-time instead of at run-time. | |
1167 | ||
1168 | @deffn {Scheme Syntax} include file-name | |
1169 | Open @var{file-name}, at expansion-time, and read the Scheme forms that | |
1170 | it contains, splicing them into the location of the @code{include}, | |
1171 | within a @code{begin}. | |
84f5a825 AW |
1172 | |
1173 | If @var{file-name} is a relative path, it is searched for relative to | |
1174 | the path that contains the file that the @code{include} for appears in. | |
eb7da3d8 AW |
1175 | @end deffn |
1176 | ||
1177 | If you are a C programmer, if @code{load} in Scheme is like | |
1178 | @code{dlopen} in C, consider @code{include} to be like the C | |
1179 | preprocessor's @code{#include}. When you use @code{include}, it is as | |
1180 | if the contents of the included file were typed in instead of the | |
1181 | @code{include} form. | |
1182 | ||
1183 | Because the code is included at compile-time, it is available to the | |
1184 | macroexpander. Syntax definitions in the included file are available to | |
1185 | later code in the form in which the @code{include} appears, without the | |
1186 | need for @code{eval-when}. (@xref{Eval When}.) | |
1187 | ||
1188 | For the same reason, compiling a form that uses @code{include} results | |
1189 | in one compilation unit, composed of multiple files. Loading the | |
1190 | compiled file is one @code{stat} operation for the compilation unit, | |
1191 | instead of @code{2*@var{n}} in the case of @code{load} (once for each | |
1192 | loaded source file, and once each corresponding compiled file, in the | |
1193 | best case). | |
1194 | ||
1195 | Unlike @code{load}, @code{include} also works within nested lexical | |
1196 | contexts. It so happens that the optimizer works best within a lexical | |
1197 | context, because all of the uses of bindings in a lexical context are | |
1198 | visible, so composing files by including them within a @code{(let () | |
1199 | ...)} can sometimes lead to important speed improvements. | |
1200 | ||
1201 | On the other hand, @code{include} does have all the disadvantages of | |
1202 | early binding: once the code with the @code{include} is compiled, no | |
1203 | change to the included file is reflected in the future behavior of the | |
1204 | including form. | |
1205 | ||
1206 | Also, the particular form of @code{include}, which requires an absolute | |
1207 | path, or a path relative to the current directory at compile-time, is | |
1208 | not very amenable to compiling the source in one place, but then | |
1209 | installing the source to another place. For this reason, Guile provides | |
1210 | another form, @code{include-from-path}, which looks for the source file | |
1211 | to include within a load path. | |
1212 | ||
1213 | @deffn {Scheme Syntax} include-from-path file-name | |
1214 | Like @code{include}, but instead of expecting @code{file-name} to be an | |
1215 | absolute file name, it is expected to be a relative path to search in | |
1216 | the @code{%load-path}. | |
1217 | @end deffn | |
1218 | ||
1219 | @code{include-from-path} is more useful when you want to install all of | |
1220 | the source files for a package (as you should!). It makes it possible | |
1221 | to evaluate an installed file from source, instead of relying on the | |
1222 | @code{.go} file being up to date. | |
1223 | ||
10d278fd IP |
1224 | @node REPL Servers |
1225 | @subsection REPL Servers | |
1226 | ||
1227 | @cindex REPL server | |
1228 | ||
1229 | The procedures in this section are provided by | |
1230 | @lisp | |
1231 | (use-modules (system repl server)) | |
1232 | @end lisp | |
1233 | ||
1234 | When an application is written in Guile, it is often convenient to | |
1235 | allow the user to be able to interact with it by evaluating Scheme | |
1236 | expressions in a REPL. | |
1237 | ||
1238 | The procedures of this module allow you to spawn a @dfn{REPL server}, | |
1239 | which permits interaction over a local or TCP connection. Guile itself | |
1240 | uses them internally to implement the @option{--listen} switch, | |
1241 | @ref{Command-line Options}. | |
1242 | ||
1243 | @deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @ | |
1244 | [#:addr] [#:port=37146] | |
1245 | Return a stream socket bound to a given address @var{addr} and port | |
1246 | number @var{port}. If the @var{host} is given, and @var{addr} is not, | |
1247 | then the @var{host} string is converted to an address. If neither is | |
1248 | given, we use the loopback address. | |
1249 | @end deffn | |
1250 | ||
1251 | @deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"] | |
1252 | Return a UNIX domain socket, bound to a given @var{path}. | |
1253 | @end deffn | |
1254 | ||
1255 | @deffn {Scheme Procedure} run-server [server-socket] | |
1256 | @deffnx {Scheme Procedure} spawn-server [server-socket] | |
1257 | Create and run a REPL, making it available over the given | |
1258 | @var{server-socket}. If @var{server-socket} is not provided, it | |
1259 | defaults to the socket created by calling @code{make-tcp-server-socket} | |
1260 | with no arguments. | |
1261 | ||
1262 | @code{run-server} runs the server in the current thread, whereas | |
1263 | @code{spawn-server} runs the server in a new thread. | |
1264 | @end deffn | |
1265 | ||
1266 | @deffn {Scheme Procedure} stop-server-and-clients! | |
1267 | Closes the connection on all running server sockets. | |
1268 | @end deffn | |
1269 | ||
07d83abe MV |
1270 | @c Local Variables: |
1271 | @c TeX-master: "guile.texi" | |
1272 | @c End: |