| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Guile Reference Manual. |
| 3 | @c Copyright (C) 2006, 2010, 2011, 2012, 2013 |
| 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 |
| 17 | scheme@@(guile-user)> (+ 3 4 5) |
| 18 | $1 = 12 |
| 19 | scheme@@(guile-user)> (display "Hello world!\n") |
| 20 | Hello world! |
| 21 | scheme@@(guile-user)> (values 'a 'b) |
| 22 | $2 = a |
| 23 | $3 = b |
| 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 | |
| 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 | |
| 37 | @menu |
| 38 | * Init File:: |
| 39 | * Readline:: |
| 40 | * Value History:: |
| 41 | * REPL Commands:: |
| 42 | * Error Handling:: |
| 43 | * Interactive Debugging:: |
| 44 | @end menu |
| 45 | |
| 46 | |
| 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 | |
| 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 |
| 73 | scheme@@(guile-user)> (use-modules (ice-9 readline)) |
| 74 | scheme@@(guile-user)> (activate-readline) |
| 75 | @end lisp |
| 76 | |
| 77 | It's a good idea to put these two lines (without the |
| 78 | @code{scheme@@(guile-user)>} prompts) in your @file{.guile} file. |
| 79 | @xref{Init File}, for more on @file{.guile}. |
| 80 | |
| 81 | |
| 82 | @node Value History |
| 83 | @subsection Value History |
| 84 | |
| 85 | Just as Readline helps you to reuse a previous input line, @dfn{value |
| 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. |
| 91 | |
| 92 | @lisp |
| 93 | scheme@@(guile-user)> (iota 10) |
| 94 | $1 = (0 1 2 3 4 5 6 7 8 9) |
| 95 | scheme@@(guile-user)> (apply * (cdr $1)) |
| 96 | $2 = 362880 |
| 97 | scheme@@(guile-user)> (sqrt $2) |
| 98 | $3 = 602.3952191045344 |
| 99 | scheme@@(guile-user)> (cons $2 $1) |
| 100 | $4 = (362880 0 1 2 3 4 5 6 7 8 9) |
| 101 | @end lisp |
| 102 | |
| 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 if value history is enabled, or false otherwise. |
| 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 |
| 143 | |
| 144 | |
| 145 | @node REPL Commands |
| 146 | @subsection REPL Commands |
| 147 | |
| 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}. |
| 153 | |
| 154 | The previous section had an example of a command, in the form of |
| 155 | @code{,option}. |
| 156 | |
| 157 | @lisp |
| 158 | scheme@@(guile-user)> ,option value-history #t |
| 159 | @end lisp |
| 160 | |
| 161 | @noindent |
| 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. |
| 166 | |
| 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}. |
| 170 | |
| 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. |
| 174 | |
| 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 |
| 185 | |
| 186 | @node Help Commands |
| 187 | @subsubsection Help Commands |
| 188 | |
| 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. |
| 193 | |
| 194 | @deffn {REPL Command} help [@code{all} | group | @code{[-c]} command] |
| 195 | Show help. |
| 196 | |
| 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. |
| 200 | |
| 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. |
| 203 | |
| 204 | Without any argument, a list of help commands and command groups |
| 205 | are displayed. |
| 206 | @end deffn |
| 207 | |
| 208 | @deffn {REPL Command} show [topic] |
| 209 | Gives information about Guile. |
| 210 | |
| 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'). |
| 214 | |
| 215 | Without any argument, a list of topics is displayed. |
| 216 | @end deffn |
| 217 | |
| 218 | @deffn {REPL Command} apropos regexp |
| 219 | Find bindings/modules/packages. |
| 220 | @end deffn |
| 221 | |
| 222 | @deffn {REPL Command} describe obj |
| 223 | Show description/documentation. |
| 224 | @end deffn |
| 225 | |
| 226 | @node Module Commands |
| 227 | @subsubsection Module Commands |
| 228 | |
| 229 | @deffn {REPL Command} module [module] |
| 230 | Change modules / Show current module. |
| 231 | @end deffn |
| 232 | |
| 233 | @deffn {REPL Command} import module @dots{} |
| 234 | Import modules / List those imported. |
| 235 | @end deffn |
| 236 | |
| 237 | @deffn {REPL Command} load file |
| 238 | Load a file in the current module. |
| 239 | @end deffn |
| 240 | |
| 241 | @deffn {REPL Command} reload [module] |
| 242 | Reload the given module, or the current module if none was given. |
| 243 | @end deffn |
| 244 | |
| 245 | @deffn {REPL Command} binding |
| 246 | List current bindings. |
| 247 | @end deffn |
| 248 | |
| 249 | @deffn {REPL Command} in module expression |
| 250 | @deffnx {REPL Command} in module command arg @dots{} |
| 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 | |
| 256 | @node Language Commands |
| 257 | @subsubsection Language Commands |
| 258 | |
| 259 | @deffn {REPL Command} language language |
| 260 | Change languages. |
| 261 | @end deffn |
| 262 | |
| 263 | @node Compile Commands |
| 264 | @subsubsection Compile Commands |
| 265 | |
| 266 | @deffn {REPL Command} compile exp |
| 267 | Generate compiled code. |
| 268 | @end deffn |
| 269 | |
| 270 | @deffn {REPL Command} compile-file file |
| 271 | Compile a file. |
| 272 | @end deffn |
| 273 | |
| 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 | |
| 282 | @deffn {REPL Command} disassemble exp |
| 283 | Disassemble a compiled procedure. |
| 284 | @end deffn |
| 285 | |
| 286 | @deffn {REPL Command} disassemble-file file |
| 287 | Disassemble a file. |
| 288 | @end deffn |
| 289 | |
| 290 | @node Profile Commands |
| 291 | @subsubsection Profile Commands |
| 292 | |
| 293 | @deffn {REPL Command} time exp |
| 294 | Time execution. |
| 295 | @end deffn |
| 296 | |
| 297 | @deffn {REPL Command} profile exp |
| 298 | Profile execution. |
| 299 | @end deffn |
| 300 | |
| 301 | @deffn {REPL Command} trace exp [#:width w] [#:max-indent i] |
| 302 | Trace execution. |
| 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. |
| 308 | @end deffn |
| 309 | |
| 310 | @node Debug Commands |
| 311 | @subsubsection Debug Commands |
| 312 | |
| 313 | These debugging commands are only available within a recursive REPL; |
| 314 | they do not work at the top level. |
| 315 | |
| 316 | @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f] |
| 317 | Print a backtrace. |
| 318 | |
| 319 | Print a backtrace of all stack frames, or innermost @var{count} frames. |
| 320 | If @var{count} is negative, the last @var{count} frames will be shown. |
| 321 | @end deffn |
| 322 | |
| 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. |
| 328 | @end deffn |
| 329 | |
| 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. |
| 335 | @end deffn |
| 336 | |
| 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 |
| 343 | |
| 344 | @deffn {REPL Command} procedure |
| 345 | Print the procedure for the selected frame. |
| 346 | @end deffn |
| 347 | |
| 348 | @deffn {REPL Command} locals |
| 349 | Show local variables. |
| 350 | |
| 351 | Show locally-bound variables in the selected frame. |
| 352 | @end deffn |
| 353 | |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 410 | |
| 411 | @node Inspect Commands |
| 412 | @subsubsection Inspect Commands |
| 413 | |
| 414 | @deffn {REPL Command} inspect exp |
| 415 | Inspect the result(s) of evaluating @var{exp}. |
| 416 | @end deffn |
| 417 | |
| 418 | @deffn {REPL Command} pretty-print exp |
| 419 | Pretty-print the result(s) of evaluating @var{exp}. |
| 420 | @end deffn |
| 421 | |
| 422 | @node System Commands |
| 423 | @subsubsection System Commands |
| 424 | |
| 425 | @deffn {REPL Command} gc |
| 426 | Garbage collection. |
| 427 | @end deffn |
| 428 | |
| 429 | @deffn {REPL Command} statistics |
| 430 | Display statistics. |
| 431 | @end deffn |
| 432 | |
| 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}. |
| 438 | @end deffn |
| 439 | |
| 440 | @deffn {REPL Command} quit |
| 441 | Quit this session. |
| 442 | @end deffn |
| 443 | |
| 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. |
| 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. |
| 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 | |
| 472 | @deffn {Scheme Procedure} repl-default-option-set! key value |
| 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 | |
| 477 | |
| 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 | |
| 648 | @node Using Guile in Emacs |
| 649 | @section Using Guile in Emacs |
| 650 | |
| 651 | @cindex Emacs |
| 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 |
| 671 | The second is |
| 672 | @iftex |
| 673 | Jos@'e |
| 674 | @end iftex |
| 675 | @ifnottex |
| 676 | José |
| 677 | @end ifnottex |
| 678 | Antonio Ortega Ruiz's |
| 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: |
| 685 | |
| 686 | @itemize @bullet |
| 687 | @item |
| 688 | Form evaluation in the context of the current file's module. |
| 689 | @item |
| 690 | Macro expansion. |
| 691 | @item |
| 692 | File/module loading and/or compilation. |
| 693 | @item |
| 694 | Namespace-aware identifier completion (including local bindings, names |
| 695 | visible in the current module, and module names). |
| 696 | @item |
| 697 | Autodoc: the echo area shows information about the signature of the |
| 698 | procedure/macro around point automatically. |
| 699 | @item |
| 700 | Jump to definition of identifier at point. |
| 701 | @item |
| 702 | Access to documentation (including docstrings when the implementation |
| 703 | provides it). |
| 704 | @item |
| 705 | Listings of identifiers exported by a given module. |
| 706 | @item |
| 707 | Listings of callers/callees of procedures. |
| 708 | @item |
| 709 | Rudimentary support for debugging and error navigation. |
| 710 | @item |
| 711 | Support for multiple, simultaneous REPLs. |
| 712 | @end itemize |
| 713 | |
| 714 | See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more |
| 715 | information. |
| 716 | |
| 717 | |
| 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 |
| 727 | invoked using the @code{guild} program. |
| 728 | |
| 729 | @example |
| 730 | $ guild compile -o foo.go foo.scm |
| 731 | wrote `foo.go' |
| 732 | @end example |
| 733 | |
| 734 | This program used to be called @code{guile-tools} up to |
| 735 | Guile version 2.0.1, and for backward |
| 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 | |
| 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 |
| 755 | @findex %site-ccache-dir |
| 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 |
| 766 | is installed and not part of Guile itself. @xref{Load Paths}, for more |
| 767 | on load paths. |
| 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 |
| 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 |
| 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 |
| 796 | your Scheme files first, and your compiled files second. @code{Load |
| 797 | Paths}, for more on the loading process. |
| 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 | |
| 807 | @c Local Variables: |
| 808 | @c TeX-master: "guile.texi" |
| 809 | @c End: |