diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/fun.texi | 140 | ||||
| -rw-r--r-- | doc/geiser.texi | 35 | ||||
| -rw-r--r-- | doc/install.texi | 6 | ||||
| -rw-r--r-- | doc/intro.texi | 30 | ||||
| -rw-r--r-- | doc/macros.texi | 3 | ||||
| -rw-r--r-- | doc/repl.texi | 75 |
6 files changed, 178 insertions, 111 deletions
diff --git a/doc/fun.texi b/doc/fun.texi index 7fbd545..4bd7e33 100644 --- a/doc/fun.texi +++ b/doc/fun.texi @@ -1,7 +1,7 @@ -@node Fun between the parens +@node Fun between the parens, Index, The REPL, Top @chapter Fun between the parens -A good REPL is a must, but just about half the story of a good Scheme +A good @repl{} is a must, but just about half the story of a good Scheme hacking environment. Well, perhaps a bit more than a half; but, at any rate, one surely needs also a pleasant way of editing source code. Don't pay attention to naysayers: Emacs comes with an excellent editor @@ -11,7 +11,7 @@ Geiser's support for writing Scheme code adds to Emacs' @code{scheme-mode}, rather than supplanting it; and it does so by means of a minor mode (unimaginatively dubbed @code{geiser-mode}) that defines a bunch of new commands to try and, with the help of the same Scheme -process giving you the REPL, make those Scheme buffers come to life. +process giving you the @repl{}, make those Scheme buffers come to life. @menu * Activating Geiser:: @@ -42,12 +42,12 @@ you how to fix that in a moment. The menu provides a good synopsis of everthing Geiser brings to the party, including those keyboard shortcuts we Emacsers love. If you're seeing the name of your favourite Scheme implementation in the -mode-line, have a running REPL and are comfortable with Emacs, you can -stop reading now and, instead, discover Geiser's joys by yourself. I've -tried to make Geiser as self-documenting as any self-respecting Emacs -package should be. If you follow this route, make sure to take a look at -Geiser's customization buffers (@kbd{M-x customize-group @key{RET} -geiser}): there's lot of fine tunning available there. +mode-line, have a running @repl{} and are comfortable with Emacs, you +can stop reading now and, instead, discover Geiser's joys by yourself. +I've tried to make Geiser as self-documenting as any self-respecting +Emacs package should be. If you follow this route, make sure to take a +look at Geiser's customization buffers (@kbd{M-x customize-group +@key{RET} geiser}): there's lot of fine tunning available there. Since @i{geiser-mode} is a minor mode, you can toggle it with @kbd{M-x geiser-mode}, and control its activation in hooks with the @@ -67,21 +67,21 @@ not recognised as such by Emacs, just tell her about it with: Now, @i{geiser-mode} is just a useless wretch unless there's a running Scheme process backing it up. Meaning that virtually all the commands it -provides require a REPL up and running, preferably corresponding to the -correct Scheme implementation. In the following section, we'll see how -to make sure that that's actually the case. +provides require a @repl{} up and running, preferably corresponding to +the correct Scheme implementation. In the following section, we'll see +how to make sure that that's actually the case. @node The source and the REPL, Documentation helpers, Activating Geiser, Fun between the parens @section The source and the REPL As i've already mentioned a couple of times, @i{geiser-mode} needs a -running REPL to be operative. Thus, a common usage pattern will be for -you to first call @code{run-geiser} (or one of its variants, see +running @repl{} to be operative. Thus, a common usage pattern will be +for you to first call @code{run-geiser} (or one of its variants, see them described @ref{choosing-impl,,here}), and then open Scheme files; but there's nothing wrong in first opening a couple Scheme buffers and -then starting the REPL (you can even find it more convenient, since -pressing @kbd{C-c C-z} in a Scheme buffer will start the REPL for you). -Since Geiser supports more than one Scheme implementation, though, +then starting the @repl{} (you can even find it more convenient, since +pressing @kbd{C-c C-z} in a Scheme buffer will start the @repl{} for +you). Since Geiser supports more than one Scheme implementation, though, there's the problem of knowing which of them is to be associated with each Scheme source file. Serviceable as it is, @i{geiser-mode} will try to guess the correct implementation for you, according to the algorithm @@ -109,7 +109,7 @@ element is used as the chosen implementation. The contents of the file is scanned for hints on its associated implementation. For instance, files that contain a @code{#lang} directive will be considered Racket source code, while those with a -@code{define-module} form in them will be assigned to a Guile REPL. +@code{define-module} form in them will be assigned to a Guile @repl{}. @item The current buffer's file name is checked against the rules given in @code{geiser-implementations-alist}, and the first match is applied. You @@ -136,14 +136,14 @@ default value for the latter variable: ((regexp "\\.rkt$") racket)) @end example which describes the simple heuristic that files with @file{.scm} as -extension are by default associated to a Guile REPL while those ending -in @file{.ss} or @file{.rkt} correspond to Racket's implementation (with -the caveat that these rules are applied only if the previous heuristics -have failed to detect the correct implementation, and that they'll match -only if the corresponding implementation is active). You can add rules -to @code{geiser-implementations-alist} (or replace all of them) by -customizing it. Besides regular expressions, you can also use a -directory name; for instance, the following snippet: +extension are by default associated to a Guile @repl{} while those +ending in @file{.ss} or @file{.rkt} correspond to Racket's +implementation (with the caveat that these rules are applied only if the +previous heuristics have failed to detect the correct implementation, +and that they'll match only if the corresponding implementation is +active). You can add rules to @code{geiser-implementations-alist} (or +replace all of them) by customizing it. Besides regular expressions, you +can also use a directory name; for instance, the following snippet: @example (eval-after-load "geiser-impl" '(add-to-list 'geiser-implementations-alist @@ -156,18 +156,19 @@ first served, this new rule will take precedence over the default ones. @subsubheading Switching between source files and the REPL @anchor{switching-repl-buff} Once you have a working @i{geiser-mode}, -you can switch from Scheme source buffers to the REPL or @kbd{C-c C-z}. -Those shortcuts map to the interactive command @code{switch-to-geiser}. +you can switch from Scheme source buffers to the @repl{} or @kbd{C-c +C-z}. Those shortcuts map to the interactive command +@code{switch-to-geiser}. If you use a numeric prefix, as in @kbd{C-u C-c C-z}, besides being -teleported to the REPL, the latter will switch to the namespace of the -Scheme source file (as if you had used @kbd{C-c C-m} in the REPL, with -the source file's module as argument; cf. @ref{Switching context}). This -command is also bound to @kbd{C-c C-Z}, with a capital zed. - -Once you're in the REPL, the same @kbd{C-c C-z} shortcut will bring you -back to the buffer you jumped from, provided you don't kill the Scheme -process in between. This is why the command is called +teleported to the @repl{}, the latter will switch to the namespace of +the Scheme source file (as if you had used @kbd{C-c C-m} in the @repl{}, +with the source file's module as argument; cf. @ref{Switching context}). +This command is also bound to @kbd{C-c C-Z}, with a capital zed. + +Once you're in the @repl{}, the same @kbd{C-c C-z} shortcut will bring +you back to the buffer you jumped from, provided you don't kill the +Scheme process in between. This is why the command is called @i{switch-to-geiser} instead of @i{switch-to-repl}, and what makes it really handy, if you ask me. @@ -185,8 +186,8 @@ a one to one correspondence between paths and modules, while Guile relies on explicit @code{define-module} forms in the source file). Now that we have @code{geiser-mode} happily alive in our Scheme buffers -and communicating with the right REPL instance, let us see what it can -do for us, besides jumping to and fro. +and communicating with the right @repl{} instance, let us see what it +can do for us, besides jumping to and fro. @node Documentation helpers, Evaluating Scheme code, The source and the REPL, Fun between the parens @section Documentation helpers @@ -195,16 +196,17 @@ do for us, besides jumping to and fro. The first thing you will notice by moving around Scheme source is that, every now and then, the echo area lightens up with the same autodoc -messages we know and love from our REPL forays. This happens every time -the Scheme process is able to recognise an identifier in the buffer, and -provide information either on its value (for variables) or on its arity -and the name of its formal arguments (for procedures and macros). That -information will only be available if the module the identifier belongs -to has been loaded in the running Scheme image. So it can be the case -that, at first, no autodoc is shown for identifiers defined in the file -you're editing. But as soon as you evaluate them (either individually or -collectively using any of the devices described in @ref{Evaluating -Scheme code}) their signatures will start appearing in the echo area. +messages we know and love from our @repl{} forays. This happens every +time the Scheme process is able to recognise an identifier in the +buffer, and provide information either on its value (for variables) or +on its arity and the name of its formal arguments (for procedures and +macros). That information will only be available if the module the +identifier belongs to has been loaded in the running Scheme image. So it +can be the case that, at first, no autodoc is shown for identifiers +defined in the file you're editing. But as soon as you evaluate them +(either individually or collectively using any of the devices described +in @ref{Evaluating Scheme code}) their signatures will start appearing +in the echo area. Autodoc activation is controlled by a minor mode, @code{geiser-autodoc}, which you can toggle with @kbd{M-x geiser-autodoc}, or its associated @@ -318,10 +320,44 @@ incremental evaluation. Some people disagree; if you happen to find @uref{http://blog.racket-lang.org/2009/03/drscheme-repl-isnt-lisp.html, their arguments} convincing, you don't have to throw away Geiser together with the baby: @kbd{M-x geiser-restart-repl} will let you -restart the REPL as many times as you see fit. - -For all of you bearded old lispers still with me, here are the commands -performing incremental evaluation in Geiser: +restart the @repl{} as many times as you see fit. + +For all of you bearded old lispers still with me, here are some of the +commands performing incremental evaluation in Geiser. + +@code{geiser-eval-last-sexp}, bound to @kbd{C-x C-e}, will eval the +s-expression just before point. + +@code{geiser-eval-definition}, bound to @kbd{C-M-x}, finds the topmost +definition containing point and sends it for evaluation. The variant +@code{geiser-eval-definition-and-go} (@kbd{C-c M-e}) works in the same +way, but it also teleports you to @repl{} after the evaluation. + +@code{geiser-eval-region}, bound to @kbd{C-c C-r}, evals the current +region. Again, there's an @i{and go} version available, +@code{geiser-eval-region-and-go}, bound to @kbd{C-c M-r}. + +For all the commands above, the result of the evaluation is displayed in +the minibuffer, unless it causes a (scheme-side) error, in which case +Geiser will report the problem by opening a debug buffer with +information on what went wrong. + +At the risk of repeating myself, i'll remember you that all these +evaluations will take place in the namespace of the module corresponding +to the Scheme file from which you're sending your code, which, in +general, will be different from the @repl{}'s current module. And, if +all goes according to plan, (re)defined variables and procedures should +be immediately visible inside and, if exported, outside their module. + +Besides evaluating expressions, definitions and regions, you can also +macro-expand them. The corresponding keybindings start with the prefix +@kbd{C-c C-m} and end, respectively, with @kbd{C-e}, @kbd{C-x} and +@kbd{C-r}. The result of the macro expansion always appears in a pop up +buffer. + +When an error occurs during evaluation, you'll be presented with a +backtrace, in a new buffer where file paths locating the origin of the +error are clickable (you can navigate them using the @key{TAB} key). @node Jumping around, Geiser writes for you, Evaluating Scheme code, Fun between the parens @section Jumping around diff --git a/doc/geiser.texi b/doc/geiser.texi index e94f719..afd71e9 100644 --- a/doc/geiser.texi +++ b/doc/geiser.texi @@ -46,10 +46,6 @@ The document was typeset with @node Top, Introduction, (dir), (dir) @top Geiser -@include top.texi - -@insertcopying - @menu * Introduction:: * Installation:: @@ -60,6 +56,15 @@ The document was typeset with @detailmenu --- The Detailed Node Listing --- +Geiser + +* Introduction:: +* Installation:: +* The REPL:: +* Fun between the parens:: +* Index:: + + Introduction * Modus operandi:: @@ -79,9 +84,31 @@ The REPL * Let Geiser spy:: * Customization and tips:: +Fun between the parens + +* Activating Geiser:: +* The source and the REPL:: +* Documentation helpers:: +* Evaluating Scheme code:: +* Jumping around:: +* Geiser writes for you:: + @end detailmenu @end menu +@include top.texi + +@insertcopying + +@menu +* Introduction:: +* Installation:: +* The REPL:: +* Fun between the parens:: +* Index:: + +@end menu + @end ifnottex @include intro.texi diff --git a/doc/install.texi b/doc/install.texi index 3d7d762..2301e6d 100644 --- a/doc/install.texi +++ b/doc/install.texi @@ -17,9 +17,9 @@ at least one of the supported schemes, which right now are @uref{http://www.racket-lang.org, Racket} 5.0 (or better) and the latest and greatest @uref{http://www.gnu.org/software/guile, Guile} 1.9 directly compiled from a recent checkout of -@uref{http://www.gnu.org/software/guile/repository.html, its Git @i{master} -branch}. Since Geiser supports multiple REPLs, having both of them will -just add to the fun. +@uref{http://www.gnu.org/software/guile/repository.html, its Git +@i{master} branch}. Since Geiser supports multiple @repl{}s, having both +of them will just add to the fun. @cindex use the source, Luke You'll also need Geiser itself. Until version 0.1 is out (which will diff --git a/doc/intro.texi b/doc/intro.texi index 500a9b4..aafa4fc 100644 --- a/doc/intro.texi +++ b/doc/intro.texi @@ -23,18 +23,18 @@ allowing the reuse of the Emacs-side framework, which constitutes the bulk of the code. @cindex current module -@anchor{current-module} -While being as generic as possible, the Scheme-Elisp interface makes -some assumptions about the capabilities and interaction mode of the -corresponding REPL. In particular, Geiser expects the latter to support -namespaces in the form of a module system, and to provide a well defined -way to establish the REPL's current namespace (or module), as well as -the current's file module (or namespace). Thus, all evaluations -performed by Geiser either in the REPL or in a source code buffer happen -in the context of the current namespace. Every time you switch to a -different file, you're switching namespaces automatically; at the REPL, -you must request the switch explicitly (usually just using means -provided by the Scheme implementation itself). +@anchor{current-module} While being as generic as possible, the +Scheme-Elisp interface makes some assumptions about the capabilities and +interaction mode of the corresponding @repl{}. In particular, Geiser +expects the latter to support namespaces in the form of a module system, +and to provide a well defined way to establish the @repl{}'s current +namespace (or module), as well as the current's file module (or +namespace). Thus, all evaluations performed by Geiser either in the +@repl{} or in a source code buffer happen in the context of the current +namespace. Every time you switch to a different file, you're switching +namespaces automatically; at the @repl{}, you must request the switch +explicitly (usually just using means provided by the Scheme +implementation itself). If your favourite scheme supports the above modus operandi, it has all that's needed for a bare-bones Geiser mode. But Geiser can, and will, @@ -75,10 +75,10 @@ Listings of identifiers exported by a given module. @item Listings of callers/callees of procedures. @item -Rudimentary support for debugging (when the REPL provides a debugging) -and error navigation. +Rudimentary support for debugging (when the @repl{} provides a +debugging) and error navigation. @item -Support for multiple, simultaneous REPLs. +Support for multiple, simultaneous @repl{}s. @end itemize In the following pages, i'll try to explain what these features diff --git a/doc/macros.texi b/doc/macros.texi index cd3507a..b38d170 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -1,3 +1,6 @@ +@macro repl{} +@acronym{REPL} +@end macro @macro img{FILE, ALIGN} @ifhtml diff --git a/doc/repl.texi b/doc/repl.texi index 124d509..9e902d4 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -17,14 +17,14 @@ ready, just come back here and proceed to the following sections. @section Starting the REPL @cindex REPL -To start a Scheme REPL (meaning, a scheme process offering you a +To start a Scheme @repl{} (meaning, a scheme process offering you a Read-Eval-Print Loop), Geiser provides the generic interactive command @command{run-geiser}. If you run it (via, as is customary in Emacs, @kbd{M-x run-geiser}, you'll be saluted by a prompt asking which one of the supported implementations you want to launch (yes, you can stop the asking: see @ref{active-implementations,,below}). Tabbing for completion will offer you, as of this writing, @code{guile} and @code{racket}. Just -choose your poison, and a new REPL buffer will pop-up. +choose your poison, and a new @repl{} buffer will pop-up. @image{img/repls} @@ -32,8 +32,8 @@ If all went according to plan, you'll be facing an implementation-dependent banner, followed by an interactive prompt. Going according to plan includes having the executable of the Scheme you chose in your path. If that's not the case, you can tell Emacs where it -is, as described @ref{impl-binary,, below}. Returning to our REPL, the -first thing to notice is that the funny prompt is telling you your +is, as described @ref{impl-binary,, below}. Returning to our @repl{}, +the first thing to notice is that the funny prompt is telling you your current module: its name is the part just after the @@ sign (in Guile, that means @code{guile-user}, while Racket's top namespace doesn't have a name; cf. @ref{Switching context} below). Other than that, this is @@ -42,17 +42,17 @@ terminal, with a bunch of add-ons that we'll be reviewing below. You can start typing sexps right there: Geiser will only dispatch them for evaluation when they're complete, and will indent new lines properly until then. It will also keep track of your input, maintaining a history -file that will be reloaded whenever you restart the REPL. +file that will be reloaded whenever you restart the @repl{}. -Nothing that fanciful this far, but there's more to Geiser's REPL. On to -the next section! +Nothing that fanciful this far, but there's more to Geiser's @repl{}. On +to the next section! @node First aids, Switching context, Starting the REPL, The REPL @section First aids @img{repl-menu, right} @cindex REPL commands -A quick way of seeing what else Geiser's REPL can do for you, is to +A quick way of seeing what else Geiser's @repl{} can do for you, is to display the corresponding entry up there in your menu bar. No, i don't normally use menus either; but they can come in handy until you've memorized Geiser's commands, as a learning device. And yes, i usually @@ -74,14 +74,14 @@ In addition, navigation is sexp- rather than line-based. There are also a few commands to twiddle with the Scheme process. @kbd{C-c C-q} will mercilessly kill it (but not before stowing your history in the file system). A softer nuke is performed by @kbd{C-c -C-k}: some (rare, i promise) times, Geiser's REPL can get confused by +C-k}: some (rare, i promise) times, Geiser's @repl{} can get confused by the input received from then underlying Scheme (specially if you have multiple threads writing to the standard ports), and become irresponsive; you can try this command to try to revive it without killing the process. Finally, if worse comes to worst and the process is dead, @kbd{C-c C-z} will restart it (but the same shortcut, issued when -the REPL is alive, will bring you back to the buffer you came from, as -explained @ref{switching-repl-buff,,here}). +the @repl{} is alive, will bring you back to the buffer you came from, +as explained @ref{switching-repl-buff,,here}). The remaining commands are meatier, and deserve sections of their own. @@ -90,15 +90,15 @@ The remaining commands are meatier, and deserve sections of their own. @cindex current module In tune with Geiser's @ref{current-module,,modus operandi}, evaluations -in the REPL take place if the namespace of the current module. As noted -above, the REPL's prompt tells you the name of the current module. To -switch to a different one, you can use the command +in the @repl{} take place if the namespace of the current module. As +noted above, the @repl{}'s prompt tells you the name of the current +module. To switch to a different one, you can use the command @command{switch-to-geiser-module}, bound to @kbd{C-c C-m}. You'll notice -that Geiser simply uses the underlying Scheme's native namespace switching -facilities (@command{,m} in Guile and @command{enter!} in Racket), and -that it doesn't even try to hide that fact. That means that you can -freely use said native ways directly at the REPL, and Geiser will be -happy to oblige. +that Geiser simply uses the underlying Scheme's native namespace +switching facilities (@command{,m} in Guile and @command{enter!} in +Racket), and that it doesn't even try to hide that fact. That means that +you can freely use said native ways directly at the @repl{}, and Geiser +will be happy to oblige. Once you enter a new module, only those bindings visible in its namespace will be available to your evaluations. All schemes supported @@ -115,26 +115,27 @@ a prefix-aware list of available module names. @image{img/mod-completion} -Which brings me to the next group of REPL commands. +Which brings me to the next group of @repl{} commands. @node Let Geiser spy, Customization and tips, Switching context, The REPL @section Let Geiser spy, write and jump for you We've already seen Geiser completion of module names in action at the mini-buffer. You won't be surprised to know that it's also available at -the REPL buffer itself. There, you can use either @kbd{C-.} or @kbd{M-`} -to complete module names, and @kbd{@key{TAB}} or @kbd{M-@key{TAB}} to -complete identifiers. Geiser will know what identifiers are bound in the -current module and show you a list of those starting with the prefix at -point. Needless to say, this is not a static list, and it will grow as -you define or import new bindings in the namespace at hand. +the @repl{} buffer itself. There, you can use either @kbd{C-.} or +@kbd{M-`} to complete module names, and @kbd{@key{TAB}} or +@kbd{M-@key{TAB}} to complete identifiers. Geiser will know what +identifiers are bound in the current module and show you a list of those +starting with the prefix at point. Needless to say, this is not a static +list, and it will grow as you define or import new bindings in the +namespace at hand. But, oftentimes, there's more you'll want to know about an identifier besides its name: what module does it belong to? is it a procedure and, if so, what arguments does it take? Geiser tries to help you answering those questions too. -Actually, if you've been playing with the REPL as you read, you might +Actually, if you've been playing with the @repl{} as you read, you might have notice some frantic activity taking place in the minibuffer every now and then. That was Geiser trying to be helpful (while, hopefully, not being clippy), or, more concretely, what i call, for want of a @@ -177,13 +178,13 @@ identifiers exported by a given module: all you need to do is press The list of exported bindings is shown in a buffer belonging to Geiser's documentation browser, of which more details are given in forthcoming sections (but just perusing it's associated key bindings, by any of the -methods we've already used for the REPL, will give you enough +methods we've already used for the @repl{}, will give you enough information to use it effectively enough). @node Customization and tips, , Let Geiser spy, The REPL @section Customization and tips -The looks and ways of the REPL can be fine-tuned via a bunch of +The looks and ways of the @repl{} can be fine-tuned via a bunch of customization variables. You can see and modify them all in the corresponding customization group (by using the menu entry or the good old @kbd{M-x customize-group geiser-repl}), or by setting them in your @@ -208,7 +209,7 @@ forget about the richness of the Scheme ecosystem with something like @end example @noindent in your initialisation files. -@anchor{impl-binary} When starting a new REPL, Geiser assumes, by +@anchor{impl-binary} When starting a new @repl{}, Geiser assumes, by default, that the corresponding Scheme binary is in your path. If that's not the case, the variables to tweak are @code{geiser-guile-binary} and @code{geiser-racket-binary}, which should be set to a string with the @@ -218,10 +219,10 @@ full path to the requisite binary. By default, Geiser won't record duplicates in your input history. If you prefer it did, just set @code{geiser-repl-history-no-dups-p} to -@code{nil}. History entries are persistent across REPL sessions: they're -saved in implementation-specific files whose location is controlled by -the variable @code{geiser-repl-history-filename}. For example, my Geiser -configuration includes the following line: +@code{nil}. History entries are persistent across @repl{} sessions: +they're saved in implementation-specific files whose location is +controlled by the variable @code{geiser-repl-history-filename}. For +example, my Geiser configuration includes the following line: @example (setq geiser-repl-history-filename "~/.emacs.d/geiser-history") @end example @@ -231,11 +232,11 @@ directory. @subsubheading Autodoc -If you happen to love peace and quiet and prefer to keep your REPL's +If you happen to love peace and quiet and prefer to keep your @repl{}'s echo area free from autodoc's noise, @code{geiser-repl-autodoc-p} is the customization variable for you: set it to @code{nil} and autodoc will be -disabled by default in new REPLs. You can always bring the fairies back, -on a per REPL basis, using @kbd{C-c C-a}. +disabled by default in new @repl{}s. You can always bring the fairies +back, on a per @repl{} basis, using @kbd{C-c C-a}. @c Local Variables: @c mode: texinfo |