Commit | Line | Data |
---|---|---|
46f7666d NJ |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
36c210d1 | 3 | @c Copyright (C) 2006, 2010, 2011, 2012, 2013 |
46f7666d NJ |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @node Using Guile Interactively | |
8 | @section Using Guile Interactively | |
9 | ||
10 | When you start up Guile by typing just @code{guile}, without a | |
11 | @code{-c} argument or the name of a script to execute, you get an | |
12 | interactive interpreter where you can enter Scheme expressions, and | |
13 | Guile will evaluate them and print the results for you. Here are some | |
14 | simple examples. | |
15 | ||
16 | @lisp | |
749c2532 | 17 | scheme@@(guile-user)> (+ 3 4 5) |
dc3b2661 | 18 | $1 = 12 |
749c2532 | 19 | scheme@@(guile-user)> (display "Hello world!\n") |
46f7666d | 20 | Hello world! |
749c2532 | 21 | scheme@@(guile-user)> (values 'a 'b) |
dc3b2661 AW |
22 | $2 = a |
23 | $3 = b | |
46f7666d NJ |
24 | @end lisp |
25 | ||
26 | @noindent | |
27 | This mode of use is called a @dfn{REPL}, which is short for | |
28 | ``Read-Eval-Print Loop'', because the Guile interpreter first reads the | |
29 | expression that you have typed, then evaluates it, and then prints the | |
30 | result. | |
31 | ||
749c2532 AW |
32 | The prompt shows you what language and module you are in. In this case, the |
33 | current language is @code{scheme}, and the current module is | |
34 | @code{(guile-user)}. @xref{Other Languages}, for more information on Guile's | |
35 | support for languages other than Scheme. | |
36 | ||
46f7666d | 37 | @menu |
2460274d | 38 | * Init File:: |
3c0b7725 | 39 | * Readline:: |
ca290a89 | 40 | * Value History:: |
3c0b7725 AW |
41 | * REPL Commands:: |
42 | * Error Handling:: | |
43 | * Interactive Debugging:: | |
46f7666d NJ |
44 | @end menu |
45 | ||
46 | ||
2460274d AW |
47 | @node Init File |
48 | @subsection The Init File, @file{~/.guile} | |
49 | ||
50 | @cindex .guile | |
51 | When run interactively, Guile will load a local initialization file from | |
52 | @file{~/.guile}. This file should contain Scheme expressions for | |
53 | evaluation. | |
54 | ||
55 | This facility lets the user customize their interactive Guile | |
56 | environment, pulling in extra modules or parameterizing the REPL | |
57 | implementation. | |
58 | ||
59 | To run Guile without loading the init file, use the @code{-q} | |
60 | command-line option. | |
61 | ||
62 | ||
46f7666d NJ |
63 | @node Readline |
64 | @subsection Readline | |
65 | ||
66 | To make it easier for you to repeat and vary previously entered | |
67 | expressions, or to edit the expression that you're typing in, Guile | |
68 | can use the GNU Readline library. This is not enabled by default | |
69 | because of licensing reasons, but all you need to activate Readline is | |
70 | the following pair of lines. | |
71 | ||
72 | @lisp | |
749c2532 AW |
73 | scheme@@(guile-user)> (use-modules (ice-9 readline)) |
74 | scheme@@(guile-user)> (activate-readline) | |
46f7666d NJ |
75 | @end lisp |
76 | ||
ced9917e | 77 | It's a good idea to put these two lines (without the |
2460274d AW |
78 | @code{scheme@@(guile-user)>} prompts) in your @file{.guile} file. |
79 | @xref{Init File}, for more on @file{.guile}. | |
46f7666d NJ |
80 | |
81 | ||
ca290a89 | 82 | @node Value History |
46f7666d NJ |
83 | @subsection Value History |
84 | ||
85 | Just as Readline helps you to reuse a previous input line, @dfn{value | |
ced9917e AW |
86 | history} allows you to use the @emph{result} of a previous evaluation in |
87 | a new expression. When value history is enabled, each evaluation result | |
88 | is automatically assigned to the next in the sequence of variables | |
89 | @code{$1}, @code{$2}, @dots{}. You can then use these variables in | |
90 | subsequent expressions. | |
46f7666d NJ |
91 | |
92 | @lisp | |
749c2532 | 93 | scheme@@(guile-user)> (iota 10) |
46f7666d | 94 | $1 = (0 1 2 3 4 5 6 7 8 9) |
749c2532 | 95 | scheme@@(guile-user)> (apply * (cdr $1)) |
46f7666d | 96 | $2 = 362880 |
749c2532 | 97 | scheme@@(guile-user)> (sqrt $2) |
46f7666d | 98 | $3 = 602.3952191045344 |
749c2532 | 99 | scheme@@(guile-user)> (cons $2 $1) |
46f7666d NJ |
100 | $4 = (362880 0 1 2 3 4 5 6 7 8 9) |
101 | @end lisp | |
102 | ||
dc3b2661 AW |
103 | Value history is enabled by default, because Guile's REPL imports the |
104 | @code{(ice-9 history)} module. Value history may be turned off or on within the | |
105 | repl, using the options interface: | |
106 | ||
107 | @lisp | |
108 | scheme@@(guile-user)> ,option value-history #f | |
109 | scheme@@(guile-user)> 'foo | |
110 | foo | |
111 | scheme@@(guile-user)> ,option value-history #t | |
112 | scheme@@(guile-user)> 'bar | |
113 | $5 = bar | |
114 | @end lisp | |
115 | ||
116 | Note that previously recorded values are still accessible, even if value history | |
117 | is off. In rare cases, these references to past computations can cause Guile to | |
118 | use too much memory. One may clear these values, possibly enabling garbage | |
119 | collection, via the @code{clear-value-history!} procedure, described below. | |
120 | ||
121 | The programmatic interface to value history is in a module: | |
122 | ||
123 | @lisp | |
124 | (use-modules (ice-9 history)) | |
125 | @end lisp | |
126 | ||
127 | @deffn {Scheme Procedure} value-history-enabled? | |
a4b4fbbd | 128 | Return true if value history is enabled, or false otherwise. |
dc3b2661 AW |
129 | @end deffn |
130 | ||
131 | @deffn {Scheme Procedure} enable-value-history! | |
132 | Turn on value history, if it was off. | |
133 | @end deffn | |
134 | ||
135 | @deffn {Scheme Procedure} disable-value-history! | |
136 | Turn off value history, if it was on. | |
137 | @end deffn | |
138 | ||
139 | @deffn {Scheme Procedure} clear-value-history! | |
140 | Clear the value history. If the stored values are not captured by some other | |
141 | data structure or closure, they may then be reclaimed by the garbage collector. | |
142 | @end deffn | |
46f7666d NJ |
143 | |
144 | ||
3c0b7725 AW |
145 | @node REPL Commands |
146 | @subsection REPL Commands | |
46f7666d | 147 | |
3c0b7725 AW |
148 | @cindex commands |
149 | The REPL exists to read expressions, evaluate them, and then print their | |
150 | results. But sometimes one wants to tell the REPL to evaluate an | |
151 | expression in a different way, or to do something else altogether. A | |
152 | user can affect the way the REPL works with a @dfn{REPL command}. | |
46f7666d | 153 | |
3c0b7725 AW |
154 | The previous section had an example of a command, in the form of |
155 | @code{,option}. | |
46f7666d NJ |
156 | |
157 | @lisp | |
3c0b7725 | 158 | scheme@@(guile-user)> ,option value-history #t |
46f7666d NJ |
159 | @end lisp |
160 | ||
161 | @noindent | |
3c0b7725 AW |
162 | Commands are distinguished from expressions by their initial comma |
163 | (@samp{,}). Since a comma cannot begin an expression in most languages, | |
164 | it is an effective indicator to the REPL that the following text forms a | |
165 | command, not an expression. | |
46f7666d | 166 | |
3c0b7725 AW |
167 | REPL commands are convenient because they are always there. Even if the |
168 | current module doesn't have a binding for @code{pretty-print}, one can | |
169 | always @code{,pretty-print}. | |
46f7666d | 170 | |
3c0b7725 AW |
171 | The following sections document the various commands, grouped together |
172 | by functionality. Many of the commands have abbreviations; see the | |
173 | online help (@code{,help}) for more information. | |
46f7666d | 174 | |
3c0b7725 AW |
175 | @menu |
176 | * Help Commands:: | |
177 | * Module Commands:: | |
178 | * Language Commands:: | |
179 | * Compile Commands:: | |
180 | * Profile Commands:: | |
181 | * Debug Commands:: | |
182 | * Inspect Commands:: | |
183 | * System Commands:: | |
184 | @end menu | |
46f7666d | 185 | |
3c0b7725 AW |
186 | @node Help Commands |
187 | @subsubsection Help Commands | |
46f7666d | 188 | |
3c0b7725 AW |
189 | When Guile starts interactively, it notifies the user that help can be |
190 | had by typing @samp{,help}. Indeed, @code{help} is a command, and a | |
191 | particularly useful one, as it allows the user to discover the rest of | |
192 | the commands. | |
46f7666d | 193 | |
ced9917e | 194 | @deffn {REPL Command} help [@code{all} | group | @code{[-c]} command] |
3c0b7725 | 195 | Show help. |
46f7666d | 196 | |
3c0b7725 AW |
197 | With one argument, tries to look up the argument as a group name, giving |
198 | help on that group if successful. Otherwise tries to look up the | |
199 | argument as a command, giving help on the command. | |
46f7666d | 200 | |
3c0b7725 AW |
201 | If there is a command whose name is also a group name, use the @samp{-c |
202 | @var{command}} form to give help on the command instead of the group. | |
46f7666d | 203 | |
3c0b7725 AW |
204 | Without any argument, a list of help commands and command groups |
205 | are displayed. | |
206 | @end deffn | |
46f7666d | 207 | |
3c0b7725 AW |
208 | @deffn {REPL Command} show [topic] |
209 | Gives information about Guile. | |
46f7666d | 210 | |
3c0b7725 AW |
211 | With one argument, tries to show a particular piece of information; |
212 | currently supported topics are `warranty' (or `w'), `copying' (or `c'), | |
213 | and `version' (or `v'). | |
46f7666d | 214 | |
3c0b7725 AW |
215 | Without any argument, a list of topics is displayed. |
216 | @end deffn | |
46f7666d | 217 | |
3c0b7725 AW |
218 | @deffn {REPL Command} apropos regexp |
219 | Find bindings/modules/packages. | |
220 | @end deffn | |
46f7666d | 221 | |
3c0b7725 AW |
222 | @deffn {REPL Command} describe obj |
223 | Show description/documentation. | |
224 | @end deffn | |
46f7666d | 225 | |
3c0b7725 AW |
226 | @node Module Commands |
227 | @subsubsection Module Commands | |
ee6be719 | 228 | |
3c0b7725 AW |
229 | @deffn {REPL Command} module [module] |
230 | Change modules / Show current module. | |
ee6be719 NJ |
231 | @end deffn |
232 | ||
df0a1002 | 233 | @deffn {REPL Command} import module @dots{} |
3c0b7725 AW |
234 | Import modules / List those imported. |
235 | @end deffn | |
46f7666d | 236 | |
3c0b7725 AW |
237 | @deffn {REPL Command} load file |
238 | Load a file in the current module. | |
239 | @end deffn | |
46f7666d | 240 | |
cdab9fc6 AW |
241 | @deffn {REPL Command} reload [module] |
242 | Reload the given module, or the current module if none was given. | |
243 | @end deffn | |
244 | ||
3c0b7725 AW |
245 | @deffn {REPL Command} binding |
246 | List current bindings. | |
247 | @end deffn | |
46f7666d | 248 | |
8fdd85f8 | 249 | @deffn {REPL Command} in module expression |
df0a1002 | 250 | @deffnx {REPL Command} in module command arg @dots{} |
8fdd85f8 AR |
251 | Evaluate an expression, or alternatively, execute another meta-command |
252 | in the context of a module. For example, @samp{,in (foo bar) ,binding} | |
253 | will show the bindings in the module @code{(foo bar)}. | |
254 | @end deffn | |
255 | ||
3c0b7725 AW |
256 | @node Language Commands |
257 | @subsubsection Language Commands | |
46f7666d | 258 | |
3c0b7725 AW |
259 | @deffn {REPL Command} language language |
260 | Change languages. | |
46f7666d NJ |
261 | @end deffn |
262 | ||
3c0b7725 AW |
263 | @node Compile Commands |
264 | @subsubsection Compile Commands | |
46f7666d | 265 | |
3c0b7725 AW |
266 | @deffn {REPL Command} compile exp |
267 | Generate compiled code. | |
268 | @end deffn | |
46f7666d | 269 | |
3c0b7725 AW |
270 | @deffn {REPL Command} compile-file file |
271 | Compile a file. | |
272 | @end deffn | |
46f7666d | 273 | |
d62dd766 AW |
274 | @deffn {REPL Command} expand exp |
275 | Expand any macros in a form. | |
276 | @end deffn | |
277 | ||
278 | @deffn {REPL Command} optimize exp | |
279 | Run the optimizer on a piece of code and print the result. | |
280 | @end deffn | |
281 | ||
3c0b7725 AW |
282 | @deffn {REPL Command} disassemble exp |
283 | Disassemble a compiled procedure. | |
284 | @end deffn | |
46f7666d | 285 | |
3c0b7725 AW |
286 | @deffn {REPL Command} disassemble-file file |
287 | Disassemble a file. | |
288 | @end deffn | |
46f7666d | 289 | |
3c0b7725 AW |
290 | @node Profile Commands |
291 | @subsubsection Profile Commands | |
46f7666d | 292 | |
3c0b7725 AW |
293 | @deffn {REPL Command} time exp |
294 | Time execution. | |
46f7666d NJ |
295 | @end deffn |
296 | ||
3c0b7725 AW |
297 | @deffn {REPL Command} profile exp |
298 | Profile execution. | |
46f7666d NJ |
299 | @end deffn |
300 | ||
36c210d1 | 301 | @deffn {REPL Command} trace exp [#:width w] [#:max-indent i] |
3c0b7725 | 302 | Trace execution. |
36c210d1 AW |
303 | |
304 | By default, the trace will limit its width to the width of your | |
305 | terminal, or @var{width} if specified. Nested procedure invocations | |
306 | will be printed farther to the right, though if the width of the | |
307 | indentation passes the @var{max-indent}, the indentation is abbreviated. | |
46f7666d NJ |
308 | @end deffn |
309 | ||
3c0b7725 AW |
310 | @node Debug Commands |
311 | @subsubsection Debug Commands | |
46f7666d | 312 | |
3c0b7725 AW |
313 | These debugging commands are only available within a recursive REPL; |
314 | they do not work at the top level. | |
46f7666d | 315 | |
3c0b7725 AW |
316 | @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f] |
317 | Print a backtrace. | |
46f7666d | 318 | |
64de6db5 | 319 | Print a backtrace of all stack frames, or innermost @var{count} frames. |
3c0b7725 | 320 | If @var{count} is negative, the last @var{count} frames will be shown. |
46f7666d NJ |
321 | @end deffn |
322 | ||
3c0b7725 AW |
323 | @deffn {REPL Command} up [count] |
324 | Select a calling stack frame. | |
325 | ||
326 | Select and print stack frames that called this one. | |
327 | An argument says how many frames up to go. | |
46f7666d NJ |
328 | @end deffn |
329 | ||
3c0b7725 AW |
330 | @deffn {REPL Command} down [count] |
331 | Select a called stack frame. | |
332 | ||
333 | Select and print stack frames called by this one. | |
334 | An argument says how many frames down to go. | |
46f7666d NJ |
335 | @end deffn |
336 | ||
3c0b7725 AW |
337 | @deffn {REPL Command} frame [idx] |
338 | Show a frame. | |
339 | ||
340 | Show the selected frame. With an argument, select a frame by index, | |
341 | then show it. | |
342 | @end deffn | |
46f7666d | 343 | |
3c0b7725 AW |
344 | @deffn {REPL Command} procedure |
345 | Print the procedure for the selected frame. | |
346 | @end deffn | |
46f7666d | 347 | |
3c0b7725 AW |
348 | @deffn {REPL Command} locals |
349 | Show local variables. | |
46f7666d | 350 | |
3c0b7725 | 351 | Show locally-bound variables in the selected frame. |
46f7666d NJ |
352 | @end deffn |
353 | ||
54d9a994 JOR |
354 | @deffn {REPL Command} error-message |
355 | @deffnx {REPL Command} error | |
356 | Show error message. | |
357 | ||
358 | Display the message associated with the error that started the current | |
359 | debugging REPL. | |
360 | @end deffn | |
361 | ||
1ecf39a6 AW |
362 | @deffn {REPL Command} registers |
363 | Show the VM registers associated with the current frame. | |
364 | ||
365 | @xref{Stack Layout}, for more information on VM stack frames. | |
366 | @end deffn | |
367 | ||
47b86dbf MG |
368 | @deffn {REPL Command} width [cols] |
369 | Sets the number of display columns in the output of @code{,backtrace} | |
370 | and @code{,locals} to @var{cols}. If @var{cols} is not given, the width | |
371 | of the terminal is used. | |
372 | @end deffn | |
373 | ||
1ecf39a6 AW |
374 | The next 3 commands work at any REPL. |
375 | ||
376 | @deffn {REPL Command} break proc | |
377 | Set a breakpoint at @var{proc}. | |
378 | @end deffn | |
379 | ||
380 | @deffn {REPL Command} break-at-source file line | |
381 | Set a breakpoint at the given source location. | |
382 | @end deffn | |
383 | ||
384 | @deffn {REPL Command} tracepoint proc | |
385 | Set a tracepoint on the given procedure. This will cause all calls to | |
386 | the procedure to print out a tracing message. @xref{Tracing Traps}, for | |
387 | more information. | |
388 | @end deffn | |
389 | ||
390 | The rest of the commands in this subsection all apply only when the | |
391 | stack is @dfn{continuable} --- in other words when it makes sense for | |
392 | the program that the stack comes from to continue running. Usually this | |
393 | means that the program stopped because of a trap or a breakpoint. | |
394 | ||
395 | @deffn {REPL Command} step | |
396 | Tell the debugged program to step to the next source location. | |
397 | @end deffn | |
398 | ||
399 | @deffn {REPL Command} next | |
400 | Tell the debugged program to step to the next source location in the | |
401 | same frame. (See @ref{Traps} for the details of how this works.) | |
402 | @end deffn | |
403 | ||
404 | @deffn {REPL Command} finish | |
405 | Tell the program being debugged to continue running until the completion | |
406 | of the current stack frame, and at that time to print the result and | |
407 | reenter the REPL. | |
408 | @end deffn | |
409 | ||
3c0b7725 AW |
410 | |
411 | @node Inspect Commands | |
412 | @subsubsection Inspect Commands | |
413 | ||
64de6db5 | 414 | @deffn {REPL Command} inspect exp |
3c0b7725 AW |
415 | Inspect the result(s) of evaluating @var{exp}. |
416 | @end deffn | |
46f7666d | 417 | |
64de6db5 | 418 | @deffn {REPL Command} pretty-print exp |
3c0b7725 AW |
419 | Pretty-print the result(s) of evaluating @var{exp}. |
420 | @end deffn | |
46f7666d | 421 | |
3c0b7725 AW |
422 | @node System Commands |
423 | @subsubsection System Commands | |
46f7666d | 424 | |
3c0b7725 AW |
425 | @deffn {REPL Command} gc |
426 | Garbage collection. | |
46f7666d NJ |
427 | @end deffn |
428 | ||
3c0b7725 AW |
429 | @deffn {REPL Command} statistics |
430 | Display statistics. | |
46f7666d NJ |
431 | @end deffn |
432 | ||
8d48877d AW |
433 | @deffn {REPL Command} option [name] [exp] |
434 | With no arguments, lists all options. With one argument, shows the | |
435 | current value of the @var{name} option. With two arguments, sets the | |
436 | @var{name} option to the result of evaluating the Scheme expression | |
437 | @var{exp}. | |
46f7666d NJ |
438 | @end deffn |
439 | ||
3c0b7725 AW |
440 | @deffn {REPL Command} quit |
441 | Quit this session. | |
46f7666d NJ |
442 | @end deffn |
443 | ||
2460274d AW |
444 | Current REPL options include: |
445 | ||
446 | @table @code | |
447 | @item compile-options | |
448 | The options used when compiling expressions entered at the REPL. | |
449 | @xref{Compilation}, for more on compilation options. | |
450 | @item interp | |
451 | Whether to interpret or compile expressions given at the REPL, if such a | |
452 | choice is available. Off by default (indicating compilation). | |
453 | @item prompt | |
454 | A customized REPL prompt. @code{#f} by default, indicating the default | |
455 | prompt. | |
afdf5467 DH |
456 | @item print |
457 | A procedure of two arguments used to print the result of evaluating each | |
458 | expression. The arguments are the current REPL and the value to print. | |
459 | By default, @code{#f}, to use the default procedure. | |
2460274d AW |
460 | @item value-history |
461 | Whether value history is on or not. @xref{Value History}. | |
462 | @item on-error | |
463 | What to do when an error happens. By default, @code{debug}, meaning to | |
464 | enter the debugger. Other values include @code{backtrace}, to show a | |
465 | backtrace without entering the debugger, or @code{report}, to simply | |
466 | show a short error printout. | |
467 | @end table | |
468 | ||
469 | Default values for REPL options may be set using | |
470 | @code{repl-default-option-set!} from @code{(system repl common)}: | |
471 | ||
ead2496f | 472 | @deffn {Scheme Procedure} repl-default-option-set! key value |
2460274d AW |
473 | Set the default value of a REPL option. This function is particularly |
474 | useful in a user's init file. @xref{Init File}. | |
475 | @end deffn | |
476 | ||
46f7666d | 477 | |
3c0b7725 AW |
478 | @node Error Handling |
479 | @subsection Error Handling | |
480 | ||
481 | When code being evaluated from the REPL hits an error, Guile enters a | |
482 | new prompt, allowing you to inspect the context of the error. | |
483 | ||
484 | @lisp | |
485 | scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d)) | |
486 | ERROR: In procedure string-append: | |
487 | ERROR: Wrong type (expecting string): #\d | |
488 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
489 | scheme@@(guile-user) [1]> | |
490 | @end lisp | |
491 | ||
492 | The new prompt runs inside the old one, in the dynamic context of the | |
493 | error. It is a recursive REPL, augmented with a reified representation | |
494 | of the stack, ready for debugging. | |
495 | ||
496 | @code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call | |
497 | stack at the point where the error occurred: | |
498 | ||
499 | @lisp | |
500 | scheme@@(guile-user) [1]> ,bt | |
501 | 1 (map #<procedure string-append _> ("a" "b") ("c" #\d)) | |
502 | 0 (string-append "b" #\d) | |
503 | @end lisp | |
504 | ||
505 | In the above example, the backtrace doesn't have much source | |
506 | information, as @code{map} and @code{string-append} are both | |
507 | primitives. But in the general case, the space on the left of the | |
508 | backtrace indicates the line and column in which a given procedure calls | |
509 | another. | |
510 | ||
511 | You can exit a recursive REPL in the same way that you exit any REPL: | |
512 | via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or | |
513 | @kbd{C-d}, among other options. | |
514 | ||
515 | ||
516 | @node Interactive Debugging | |
517 | @subsection Interactive Debugging | |
518 | ||
519 | A recursive debugging REPL exposes a number of other meta-commands that | |
520 | inspect the state of the computation at the time of the error. These | |
521 | commands allow you to | |
522 | ||
523 | @itemize @bullet | |
524 | @item | |
525 | display the Scheme call stack at the point where the error occurred; | |
526 | ||
527 | @item | |
528 | move up and down the call stack, to see in detail the expression being | |
529 | evaluated, or the procedure being applied, in each @dfn{frame}; and | |
530 | ||
531 | @item | |
532 | examine the values of variables and expressions in the context of each | |
533 | frame. | |
534 | @end itemize | |
535 | ||
536 | @noindent | |
537 | @xref{Debug Commands}, for documentation of the individual | |
538 | commands. This section aims to give more of a walkthrough of a typical | |
539 | debugging session. | |
540 | ||
541 | First, we're going to need a good error. Let's try to macroexpand the | |
542 | expression @code{(unquote foo)}, outside of a @code{quasiquote} form, | |
543 | and see how the macroexpander reports this error. | |
544 | ||
545 | @lisp | |
546 | scheme@@(guile-user)> (macroexpand '(unquote foo)) | |
547 | ERROR: In procedure macroexpand: | |
548 | ERROR: unquote: expression not valid outside of quasiquote in (unquote foo) | |
549 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
550 | scheme@@(guile-user) [1]> | |
551 | @end lisp | |
552 | ||
553 | The @code{backtrace} command, which can also be invoked as @code{bt}, | |
554 | displays the call stack (aka backtrace) at the point where the debugger | |
555 | was entered: | |
556 | ||
557 | @lisp | |
558 | scheme@@(guile-user) [1]> ,bt | |
559 | In ice-9/psyntax.scm: | |
560 | 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #)) | |
561 | 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f) | |
562 | 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...) | |
563 | In unknown file: | |
564 | 0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f) | |
565 | @end lisp | |
566 | ||
567 | A call stack consists of a sequence of stack @dfn{frames}, with each | |
568 | frame describing one procedure which is waiting to do something with the | |
569 | values returned by another. Here we see that there are four frames on | |
570 | the stack. | |
571 | ||
572 | Note that @code{macroexpand} is not on the stack -- it must have made a | |
573 | tail call to @code{chi-top}, as indeed we would find if we searched | |
574 | @code{ice-9/psyntax.scm} for its definition. | |
575 | ||
576 | When you enter the debugger, the innermost frame is selected, which | |
577 | means that the commands for getting information about the ``current'' | |
578 | frame, or for evaluating expressions in the context of the current | |
579 | frame, will do so by default with respect to the innermost frame. To | |
580 | select a different frame, so that these operations will apply to it | |
581 | instead, use the @code{up}, @code{down} and @code{frame} commands like | |
582 | this: | |
583 | ||
584 | @lisp | |
585 | scheme@@(guile-user) [1]> ,up | |
586 | In ice-9/psyntax.scm: | |
587 | 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...) | |
588 | scheme@@(guile-user) [1]> ,frame 3 | |
589 | In ice-9/psyntax.scm: | |
590 | 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #)) | |
591 | scheme@@(guile-user) [1]> ,down | |
592 | In ice-9/psyntax.scm: | |
593 | 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f) | |
594 | @end lisp | |
595 | ||
596 | Perhaps we're interested in what's going on in frame 2, so we take a | |
597 | look at its local variables: | |
598 | ||
599 | @lisp | |
600 | scheme@@(guile-user) [1]> ,locals | |
601 | Local variables: | |
602 | $1 = e = (unquote foo) | |
603 | $2 = r = () | |
604 | $3 = w = ((top)) | |
605 | $4 = s = #f | |
606 | $5 = rib = #f | |
607 | $6 = mod = (hygiene guile-user) | |
608 | $7 = for-car? = #f | |
609 | $8 = first = unquote | |
610 | $9 = ftype = macro | |
611 | $10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)> | |
612 | $11 = fe = unquote | |
613 | $12 = fw = ((top)) | |
614 | $13 = fs = #f | |
615 | $14 = fmod = (hygiene guile-user) | |
616 | @end lisp | |
617 | ||
618 | All of the values are accessible by their value-history names | |
619 | (@code{$@var{n}}): | |
620 | ||
621 | @lisp | |
622 | scheme@@(guile-user) [1]> $10 | |
623 | $15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)> | |
624 | @end lisp | |
625 | ||
626 | We can even invoke the procedure at the REPL directly: | |
627 | ||
628 | @lisp | |
629 | scheme@@(guile-user) [1]> ($10 'not-going-to-work) | |
630 | ERROR: In procedure macroexpand: | |
631 | ERROR: source expression failed to match any pattern in not-going-to-work | |
632 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
633 | @end lisp | |
634 | ||
635 | Well at this point we've caused an error within an error. Let's just | |
636 | quit back to the top level: | |
637 | ||
638 | @lisp | |
639 | scheme@@(guile-user) [2]> ,q | |
640 | scheme@@(guile-user) [1]> ,q | |
641 | scheme@@(guile-user)> | |
642 | @end lisp | |
643 | ||
644 | Finally, as a word to the wise: hackers close their REPL prompts with | |
645 | @kbd{C-d}. | |
646 | ||
647 | ||
46f7666d NJ |
648 | @node Using Guile in Emacs |
649 | @section Using Guile in Emacs | |
650 | ||
b20ef3a6 | 651 | @cindex Emacs |
767dbb1a AW |
652 | Any text editor can edit Scheme, but some are better than others. Emacs |
653 | is the best, of course, and not just because it is a fine text editor. | |
654 | Emacs has good support for Scheme out of the box, with sensible | |
655 | indentation rules, parenthesis-matching, syntax highlighting, and even a | |
656 | set of keybindings for structural editing, allowing navigation, | |
657 | cut-and-paste, and transposition operations that work on balanced | |
658 | S-expressions. | |
659 | ||
660 | As good as it is, though, two things will vastly improve your experience | |
661 | with Emacs and Guile. | |
662 | ||
663 | @cindex Paredit | |
664 | The first is Taylor Campbell's | |
665 | @uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not | |
666 | code in any dialect of Lisp without Paredit. (They say that | |
667 | unopinionated writing is boring---hence this tone---but it's the | |
668 | truth, regardless.) Paredit is the bee's knees. | |
669 | ||
670 | @cindex Geiser | |
917b2bf6 NJ |
671 | The second is |
672 | @iftex | |
673 | Jos@'e | |
674 | @end iftex | |
675 | @ifnottex | |
676 | José | |
677 | @end ifnottex | |
678 | Antonio Ortega Ruiz's | |
767dbb1a AW |
679 | @uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs' |
680 | @code{scheme-mode} with tight integration to running Guile processes via | |
681 | a @code{comint-mode} REPL buffer. | |
682 | ||
683 | Of course there are keybindings to switch to the REPL, and a good REPL | |
684 | environment, but Geiser goes beyond that, providing: | |
01d2ee15 | 685 | |
767dbb1a | 686 | @itemize @bullet |
46f7666d | 687 | @item |
767dbb1a | 688 | Form evaluation in the context of the current file's module. |
46f7666d | 689 | @item |
767dbb1a | 690 | Macro expansion. |
46f7666d | 691 | @item |
767dbb1a | 692 | File/module loading and/or compilation. |
46f7666d | 693 | @item |
767dbb1a AW |
694 | Namespace-aware identifier completion (including local bindings, names |
695 | visible in the current module, and module names). | |
46f7666d | 696 | @item |
767dbb1a AW |
697 | Autodoc: the echo area shows information about the signature of the |
698 | procedure/macro around point automatically. | |
46f7666d | 699 | @item |
767dbb1a | 700 | Jump to definition of identifier at point. |
46f7666d | 701 | @item |
767dbb1a AW |
702 | Access to documentation (including docstrings when the implementation |
703 | provides it). | |
46f7666d | 704 | @item |
767dbb1a | 705 | Listings of identifiers exported by a given module. |
62ae9557 | 706 | @item |
767dbb1a | 707 | Listings of callers/callees of procedures. |
94a2c24a | 708 | @item |
767dbb1a | 709 | Rudimentary support for debugging and error navigation. |
62ae9557 | 710 | @item |
767dbb1a | 711 | Support for multiple, simultaneous REPLs. |
62ae9557 NJ |
712 | @end itemize |
713 | ||
767dbb1a AW |
714 | See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more |
715 | information. | |
62ae9557 NJ |
716 | |
717 | ||
715146aa AW |
718 | @node Using Guile Tools |
719 | @section Using Guile Tools | |
720 | ||
721 | @cindex guild | |
722 | @cindex guile-tools | |
723 | @cindex wizards | |
724 | Guile also comes with a growing number of command-line utilities: a | |
725 | compiler, a disassembler, some module inspectors, and in the future, a | |
726 | system to install Guile packages from the internet. These tools may be | |
8698e810 | 727 | invoked using the @code{guild} program. |
715146aa AW |
728 | |
729 | @example | |
730 | $ guild compile -o foo.go foo.scm | |
731 | wrote `foo.go' | |
732 | @end example | |
733 | ||
8698e810 LC |
734 | This program used to be called @code{guile-tools} up to |
735 | Guile version 2.0.1, and for backward | |
715146aa AW |
736 | compatibility it still may be called as such. However we changed the |
737 | name to @code{guild}, not only because it is pleasantly shorter and | |
738 | easier to read, but also because this tool will serve to bind Guile | |
739 | wizards together, by allowing hackers to share code with each other | |
740 | using a CPAN-like system. | |
741 | ||
742 | @xref{Compilation}, for more on @code{guild compile}. | |
743 | ||
744 | A complete list of guild scripts can be had by invoking @code{guild | |
745 | list}, or simply @code{guild}. | |
746 | ||
24cc7832 AW |
747 | |
748 | @node Installing Site Packages | |
749 | @section Installing Site Packages | |
750 | ||
751 | @cindex site | |
752 | @cindex site path | |
753 | @cindex load path | |
754 | @findex %site-dir | |
988ca6b2 | 755 | @findex %site-ccache-dir |
24cc7832 AW |
756 | |
757 | At some point, you will probably want to share your code with other | |
758 | people. To do so effectively, it is important to follow a set of common | |
759 | conventions, to make it easy for the user to install and use your | |
760 | package. | |
761 | ||
762 | The first thing to do is to install your Scheme files where Guile can | |
763 | find them. When Guile goes to find a Scheme file, it will search a | |
764 | @dfn{load path} to find the file: first in Guile's own path, then in | |
765 | paths for @dfn{site packages}. A site package is any Scheme code that | |
925172cf AW |
766 | is installed and not part of Guile itself. @xref{Load Paths}, for more |
767 | on load paths. | |
24cc7832 AW |
768 | |
769 | There are several site paths, for historical reasons, but the one that | |
770 | should generally be used can be obtained by invoking the | |
771 | @code{%site-dir} procedure. @xref{Build Config}. If Guile | |
772 | @value{EFFECTIVE-VERSION} is installed on your system in @code{/usr/}, | |
773 | then @code{(%site-dir)} will be | |
774 | @code{/usr/share/guile/site/@value{EFFECTIVE-VERSION}}. Scheme files | |
775 | should be installed there. | |
776 | ||
777 | If you do not install compiled @code{.go} files, Guile will compile your | |
778 | modules and programs when they are first used, and cache them in the | |
779 | user's home directory. @xref{Compilation}, for more on | |
780 | auto-compilation. However, it is better to compile the files before | |
781 | they are installed, and to just copy the files to a place that Guile can | |
782 | find them. | |
783 | ||
784 | As with Scheme files, Guile searches a path to find compiled @code{.go} | |
785 | files, the @code{%load-compiled-path}. By default, this path has two | |
786 | entries: a path for Guile's files, and a path for site packages. You | |
988ca6b2 JE |
787 | should install your @code{.go} files into the latter directory, whose |
788 | value is returned by invoking the @code{%site-ccache-dir} procedure. As | |
789 | in the previous example, if Guile @value{EFFECTIVE-VERSION} is installed | |
790 | on your system in @code{/usr/}, then @code{(%site-ccache-dir)} site | |
791 | packages will be | |
24cc7832 AW |
792 | @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/site-ccache}. |
793 | ||
794 | Note that a @code{.go} file will only be loaded in preference to a | |
795 | @code{.scm} file if it is newer. For that reason, you should install | |
0740cb49 AW |
796 | your Scheme files first, and your compiled files second. @code{Load |
797 | Paths}, for more on the loading process. | |
24cc7832 AW |
798 | |
799 | Finally, although this section is only about Scheme, sometimes you need | |
800 | to install C extensions too. Shared libraries should be installed in | |
801 | the @dfn{extensions dir}. This value can be had from the build config | |
802 | (@pxref{Build Config}). Again, if Guile @value{EFFECTIVE-VERSION} is | |
803 | installed on your system in @code{/usr/}, then the extensions dir will | |
804 | be @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/extensions}. | |
805 | ||
806 | ||
46f7666d NJ |
807 | @c Local Variables: |
808 | @c TeX-master: "guile.texi" | |
809 | @c End: |