Commit | Line | Data |
---|---|---|
46f7666d NJ |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
2460274d | 3 | @c Copyright (C) 2006, 2010, 2011 |
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? | |
128 | Return true iff value history is enabled. | |
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 | ||
3c0b7725 AW |
233 | @deffn {REPL Command} import [module ...] |
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 AR |
249 | @deffn {REPL Command} in module expression |
250 | @deffnx {REPL Command} in module command [args ...] | |
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 | ||
3c0b7725 AW |
301 | @deffn {REPL Command} trace exp |
302 | Trace execution. | |
46f7666d NJ |
303 | @end deffn |
304 | ||
3c0b7725 AW |
305 | @node Debug Commands |
306 | @subsubsection Debug Commands | |
46f7666d | 307 | |
3c0b7725 AW |
308 | These debugging commands are only available within a recursive REPL; |
309 | they do not work at the top level. | |
46f7666d | 310 | |
3c0b7725 AW |
311 | @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f] |
312 | Print a backtrace. | |
46f7666d | 313 | |
3c0b7725 AW |
314 | Print a backtrace of all stack frames, or innermost @var{COUNT} frames. |
315 | If @var{count} is negative, the last @var{count} frames will be shown. | |
46f7666d NJ |
316 | @end deffn |
317 | ||
3c0b7725 AW |
318 | @deffn {REPL Command} up [count] |
319 | Select a calling stack frame. | |
320 | ||
321 | Select and print stack frames that called this one. | |
322 | An argument says how many frames up to go. | |
46f7666d NJ |
323 | @end deffn |
324 | ||
3c0b7725 AW |
325 | @deffn {REPL Command} down [count] |
326 | Select a called stack frame. | |
327 | ||
328 | Select and print stack frames called by this one. | |
329 | An argument says how many frames down to go. | |
46f7666d NJ |
330 | @end deffn |
331 | ||
3c0b7725 AW |
332 | @deffn {REPL Command} frame [idx] |
333 | Show a frame. | |
334 | ||
335 | Show the selected frame. With an argument, select a frame by index, | |
336 | then show it. | |
337 | @end deffn | |
46f7666d | 338 | |
3c0b7725 AW |
339 | @deffn {REPL Command} procedure |
340 | Print the procedure for the selected frame. | |
341 | @end deffn | |
46f7666d | 342 | |
3c0b7725 AW |
343 | @deffn {REPL Command} locals |
344 | Show local variables. | |
46f7666d | 345 | |
3c0b7725 | 346 | Show locally-bound variables in the selected frame. |
46f7666d NJ |
347 | @end deffn |
348 | ||
54d9a994 JOR |
349 | @deffn {REPL Command} error-message |
350 | @deffnx {REPL Command} error | |
351 | Show error message. | |
352 | ||
353 | Display the message associated with the error that started the current | |
354 | debugging REPL. | |
355 | @end deffn | |
356 | ||
1ecf39a6 AW |
357 | @deffn {REPL Command} registers |
358 | Show the VM registers associated with the current frame. | |
359 | ||
360 | @xref{Stack Layout}, for more information on VM stack frames. | |
361 | @end deffn | |
362 | ||
47b86dbf MG |
363 | @deffn {REPL Command} width [cols] |
364 | Sets the number of display columns in the output of @code{,backtrace} | |
365 | and @code{,locals} to @var{cols}. If @var{cols} is not given, the width | |
366 | of the terminal is used. | |
367 | @end deffn | |
368 | ||
1ecf39a6 AW |
369 | The next 3 commands work at any REPL. |
370 | ||
371 | @deffn {REPL Command} break proc | |
372 | Set a breakpoint at @var{proc}. | |
373 | @end deffn | |
374 | ||
375 | @deffn {REPL Command} break-at-source file line | |
376 | Set a breakpoint at the given source location. | |
377 | @end deffn | |
378 | ||
379 | @deffn {REPL Command} tracepoint proc | |
380 | Set a tracepoint on the given procedure. This will cause all calls to | |
381 | the procedure to print out a tracing message. @xref{Tracing Traps}, for | |
382 | more information. | |
383 | @end deffn | |
384 | ||
385 | The rest of the commands in this subsection all apply only when the | |
386 | stack is @dfn{continuable} --- in other words when it makes sense for | |
387 | the program that the stack comes from to continue running. Usually this | |
388 | means that the program stopped because of a trap or a breakpoint. | |
389 | ||
390 | @deffn {REPL Command} step | |
391 | Tell the debugged program to step to the next source location. | |
392 | @end deffn | |
393 | ||
394 | @deffn {REPL Command} next | |
395 | Tell the debugged program to step to the next source location in the | |
396 | same frame. (See @ref{Traps} for the details of how this works.) | |
397 | @end deffn | |
398 | ||
399 | @deffn {REPL Command} finish | |
400 | Tell the program being debugged to continue running until the completion | |
401 | of the current stack frame, and at that time to print the result and | |
402 | reenter the REPL. | |
403 | @end deffn | |
404 | ||
3c0b7725 AW |
405 | |
406 | @node Inspect Commands | |
407 | @subsubsection Inspect Commands | |
408 | ||
409 | @deffn {REPL Command} inspect EXP | |
410 | Inspect the result(s) of evaluating @var{exp}. | |
411 | @end deffn | |
46f7666d | 412 | |
3c0b7725 AW |
413 | @deffn {REPL Command} pretty-print EXP |
414 | Pretty-print the result(s) of evaluating @var{exp}. | |
415 | @end deffn | |
46f7666d | 416 | |
3c0b7725 AW |
417 | @node System Commands |
418 | @subsubsection System Commands | |
46f7666d | 419 | |
3c0b7725 AW |
420 | @deffn {REPL Command} gc |
421 | Garbage collection. | |
46f7666d NJ |
422 | @end deffn |
423 | ||
3c0b7725 AW |
424 | @deffn {REPL Command} statistics |
425 | Display statistics. | |
46f7666d NJ |
426 | @end deffn |
427 | ||
3c0b7725 AW |
428 | @deffn {REPL Command} option [key value] |
429 | List/show/set options. | |
46f7666d NJ |
430 | @end deffn |
431 | ||
3c0b7725 AW |
432 | @deffn {REPL Command} quit |
433 | Quit this session. | |
46f7666d NJ |
434 | @end deffn |
435 | ||
2460274d AW |
436 | Current REPL options include: |
437 | ||
438 | @table @code | |
439 | @item compile-options | |
440 | The options used when compiling expressions entered at the REPL. | |
441 | @xref{Compilation}, for more on compilation options. | |
442 | @item interp | |
443 | Whether to interpret or compile expressions given at the REPL, if such a | |
444 | choice is available. Off by default (indicating compilation). | |
445 | @item prompt | |
446 | A customized REPL prompt. @code{#f} by default, indicating the default | |
447 | prompt. | |
448 | @item value-history | |
449 | Whether value history is on or not. @xref{Value History}. | |
450 | @item on-error | |
451 | What to do when an error happens. By default, @code{debug}, meaning to | |
452 | enter the debugger. Other values include @code{backtrace}, to show a | |
453 | backtrace without entering the debugger, or @code{report}, to simply | |
454 | show a short error printout. | |
455 | @end table | |
456 | ||
457 | Default values for REPL options may be set using | |
458 | @code{repl-default-option-set!} from @code{(system repl common)}: | |
459 | ||
460 | @deffn {Scheme Procedure} repl-set-default-option! key value | |
461 | Set the default value of a REPL option. This function is particularly | |
462 | useful in a user's init file. @xref{Init File}. | |
463 | @end deffn | |
464 | ||
46f7666d | 465 | |
3c0b7725 AW |
466 | @node Error Handling |
467 | @subsection Error Handling | |
468 | ||
469 | When code being evaluated from the REPL hits an error, Guile enters a | |
470 | new prompt, allowing you to inspect the context of the error. | |
471 | ||
472 | @lisp | |
473 | scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d)) | |
474 | ERROR: In procedure string-append: | |
475 | ERROR: Wrong type (expecting string): #\d | |
476 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
477 | scheme@@(guile-user) [1]> | |
478 | @end lisp | |
479 | ||
480 | The new prompt runs inside the old one, in the dynamic context of the | |
481 | error. It is a recursive REPL, augmented with a reified representation | |
482 | of the stack, ready for debugging. | |
483 | ||
484 | @code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call | |
485 | stack at the point where the error occurred: | |
486 | ||
487 | @lisp | |
488 | scheme@@(guile-user) [1]> ,bt | |
489 | 1 (map #<procedure string-append _> ("a" "b") ("c" #\d)) | |
490 | 0 (string-append "b" #\d) | |
491 | @end lisp | |
492 | ||
493 | In the above example, the backtrace doesn't have much source | |
494 | information, as @code{map} and @code{string-append} are both | |
495 | primitives. But in the general case, the space on the left of the | |
496 | backtrace indicates the line and column in which a given procedure calls | |
497 | another. | |
498 | ||
499 | You can exit a recursive REPL in the same way that you exit any REPL: | |
500 | via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or | |
501 | @kbd{C-d}, among other options. | |
502 | ||
503 | ||
504 | @node Interactive Debugging | |
505 | @subsection Interactive Debugging | |
506 | ||
507 | A recursive debugging REPL exposes a number of other meta-commands that | |
508 | inspect the state of the computation at the time of the error. These | |
509 | commands allow you to | |
510 | ||
511 | @itemize @bullet | |
512 | @item | |
513 | display the Scheme call stack at the point where the error occurred; | |
514 | ||
515 | @item | |
516 | move up and down the call stack, to see in detail the expression being | |
517 | evaluated, or the procedure being applied, in each @dfn{frame}; and | |
518 | ||
519 | @item | |
520 | examine the values of variables and expressions in the context of each | |
521 | frame. | |
522 | @end itemize | |
523 | ||
524 | @noindent | |
525 | @xref{Debug Commands}, for documentation of the individual | |
526 | commands. This section aims to give more of a walkthrough of a typical | |
527 | debugging session. | |
528 | ||
529 | First, we're going to need a good error. Let's try to macroexpand the | |
530 | expression @code{(unquote foo)}, outside of a @code{quasiquote} form, | |
531 | and see how the macroexpander reports this error. | |
532 | ||
533 | @lisp | |
534 | scheme@@(guile-user)> (macroexpand '(unquote foo)) | |
535 | ERROR: In procedure macroexpand: | |
536 | ERROR: unquote: expression not valid outside of quasiquote in (unquote foo) | |
537 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
538 | scheme@@(guile-user) [1]> | |
539 | @end lisp | |
540 | ||
541 | The @code{backtrace} command, which can also be invoked as @code{bt}, | |
542 | displays the call stack (aka backtrace) at the point where the debugger | |
543 | was entered: | |
544 | ||
545 | @lisp | |
546 | scheme@@(guile-user) [1]> ,bt | |
547 | In ice-9/psyntax.scm: | |
548 | 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #)) | |
549 | 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f) | |
550 | 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...) | |
551 | In unknown file: | |
552 | 0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f) | |
553 | @end lisp | |
554 | ||
555 | A call stack consists of a sequence of stack @dfn{frames}, with each | |
556 | frame describing one procedure which is waiting to do something with the | |
557 | values returned by another. Here we see that there are four frames on | |
558 | the stack. | |
559 | ||
560 | Note that @code{macroexpand} is not on the stack -- it must have made a | |
561 | tail call to @code{chi-top}, as indeed we would find if we searched | |
562 | @code{ice-9/psyntax.scm} for its definition. | |
563 | ||
564 | When you enter the debugger, the innermost frame is selected, which | |
565 | means that the commands for getting information about the ``current'' | |
566 | frame, or for evaluating expressions in the context of the current | |
567 | frame, will do so by default with respect to the innermost frame. To | |
568 | select a different frame, so that these operations will apply to it | |
569 | instead, use the @code{up}, @code{down} and @code{frame} commands like | |
570 | this: | |
571 | ||
572 | @lisp | |
573 | scheme@@(guile-user) [1]> ,up | |
574 | In ice-9/psyntax.scm: | |
575 | 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...) | |
576 | scheme@@(guile-user) [1]> ,frame 3 | |
577 | In ice-9/psyntax.scm: | |
578 | 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #)) | |
579 | scheme@@(guile-user) [1]> ,down | |
580 | In ice-9/psyntax.scm: | |
581 | 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f) | |
582 | @end lisp | |
583 | ||
584 | Perhaps we're interested in what's going on in frame 2, so we take a | |
585 | look at its local variables: | |
586 | ||
587 | @lisp | |
588 | scheme@@(guile-user) [1]> ,locals | |
589 | Local variables: | |
590 | $1 = e = (unquote foo) | |
591 | $2 = r = () | |
592 | $3 = w = ((top)) | |
593 | $4 = s = #f | |
594 | $5 = rib = #f | |
595 | $6 = mod = (hygiene guile-user) | |
596 | $7 = for-car? = #f | |
597 | $8 = first = unquote | |
598 | $9 = ftype = macro | |
599 | $10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)> | |
600 | $11 = fe = unquote | |
601 | $12 = fw = ((top)) | |
602 | $13 = fs = #f | |
603 | $14 = fmod = (hygiene guile-user) | |
604 | @end lisp | |
605 | ||
606 | All of the values are accessible by their value-history names | |
607 | (@code{$@var{n}}): | |
608 | ||
609 | @lisp | |
610 | scheme@@(guile-user) [1]> $10 | |
611 | $15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)> | |
612 | @end lisp | |
613 | ||
614 | We can even invoke the procedure at the REPL directly: | |
615 | ||
616 | @lisp | |
617 | scheme@@(guile-user) [1]> ($10 'not-going-to-work) | |
618 | ERROR: In procedure macroexpand: | |
619 | ERROR: source expression failed to match any pattern in not-going-to-work | |
620 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
621 | @end lisp | |
622 | ||
623 | Well at this point we've caused an error within an error. Let's just | |
624 | quit back to the top level: | |
625 | ||
626 | @lisp | |
627 | scheme@@(guile-user) [2]> ,q | |
628 | scheme@@(guile-user) [1]> ,q | |
629 | scheme@@(guile-user)> | |
630 | @end lisp | |
631 | ||
632 | Finally, as a word to the wise: hackers close their REPL prompts with | |
633 | @kbd{C-d}. | |
634 | ||
635 | ||
46f7666d NJ |
636 | @node Using Guile in Emacs |
637 | @section Using Guile in Emacs | |
638 | ||
b20ef3a6 | 639 | @cindex Emacs |
767dbb1a AW |
640 | Any text editor can edit Scheme, but some are better than others. Emacs |
641 | is the best, of course, and not just because it is a fine text editor. | |
642 | Emacs has good support for Scheme out of the box, with sensible | |
643 | indentation rules, parenthesis-matching, syntax highlighting, and even a | |
644 | set of keybindings for structural editing, allowing navigation, | |
645 | cut-and-paste, and transposition operations that work on balanced | |
646 | S-expressions. | |
647 | ||
648 | As good as it is, though, two things will vastly improve your experience | |
649 | with Emacs and Guile. | |
650 | ||
651 | @cindex Paredit | |
652 | The first is Taylor Campbell's | |
653 | @uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not | |
654 | code in any dialect of Lisp without Paredit. (They say that | |
655 | unopinionated writing is boring---hence this tone---but it's the | |
656 | truth, regardless.) Paredit is the bee's knees. | |
657 | ||
658 | @cindex Geiser | |
917b2bf6 NJ |
659 | The second is |
660 | @iftex | |
661 | Jos@'e | |
662 | @end iftex | |
663 | @ifnottex | |
664 | José | |
665 | @end ifnottex | |
666 | Antonio Ortega Ruiz's | |
767dbb1a AW |
667 | @uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs' |
668 | @code{scheme-mode} with tight integration to running Guile processes via | |
669 | a @code{comint-mode} REPL buffer. | |
670 | ||
671 | Of course there are keybindings to switch to the REPL, and a good REPL | |
672 | environment, but Geiser goes beyond that, providing: | |
01d2ee15 | 673 | |
767dbb1a | 674 | @itemize @bullet |
46f7666d | 675 | @item |
767dbb1a | 676 | Form evaluation in the context of the current file's module. |
46f7666d | 677 | @item |
767dbb1a | 678 | Macro expansion. |
46f7666d | 679 | @item |
767dbb1a | 680 | File/module loading and/or compilation. |
46f7666d | 681 | @item |
767dbb1a AW |
682 | Namespace-aware identifier completion (including local bindings, names |
683 | visible in the current module, and module names). | |
46f7666d | 684 | @item |
767dbb1a AW |
685 | Autodoc: the echo area shows information about the signature of the |
686 | procedure/macro around point automatically. | |
46f7666d | 687 | @item |
767dbb1a | 688 | Jump to definition of identifier at point. |
46f7666d | 689 | @item |
767dbb1a AW |
690 | Access to documentation (including docstrings when the implementation |
691 | provides it). | |
46f7666d | 692 | @item |
767dbb1a | 693 | Listings of identifiers exported by a given module. |
62ae9557 | 694 | @item |
767dbb1a | 695 | Listings of callers/callees of procedures. |
94a2c24a | 696 | @item |
767dbb1a | 697 | Rudimentary support for debugging and error navigation. |
62ae9557 | 698 | @item |
767dbb1a | 699 | Support for multiple, simultaneous REPLs. |
62ae9557 NJ |
700 | @end itemize |
701 | ||
767dbb1a AW |
702 | See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more |
703 | information. | |
62ae9557 NJ |
704 | |
705 | ||
715146aa AW |
706 | @node Using Guile Tools |
707 | @section Using Guile Tools | |
708 | ||
709 | @cindex guild | |
710 | @cindex guile-tools | |
711 | @cindex wizards | |
712 | Guile also comes with a growing number of command-line utilities: a | |
713 | compiler, a disassembler, some module inspectors, and in the future, a | |
714 | system to install Guile packages from the internet. These tools may be | |
8698e810 | 715 | invoked using the @code{guild} program. |
715146aa AW |
716 | |
717 | @example | |
718 | $ guild compile -o foo.go foo.scm | |
719 | wrote `foo.go' | |
720 | @end example | |
721 | ||
8698e810 LC |
722 | This program used to be called @code{guile-tools} up to |
723 | Guile version 2.0.1, and for backward | |
715146aa AW |
724 | compatibility it still may be called as such. However we changed the |
725 | name to @code{guild}, not only because it is pleasantly shorter and | |
726 | easier to read, but also because this tool will serve to bind Guile | |
727 | wizards together, by allowing hackers to share code with each other | |
728 | using a CPAN-like system. | |
729 | ||
730 | @xref{Compilation}, for more on @code{guild compile}. | |
731 | ||
732 | A complete list of guild scripts can be had by invoking @code{guild | |
733 | list}, or simply @code{guild}. | |
734 | ||
46f7666d NJ |
735 | @c Local Variables: |
736 | @c TeX-master: "guile.texi" | |
737 | @c End: |