diff options
Diffstat (limited to 'doc/parens.texi')
| -rw-r--r-- | doc/parens.texi | 488 |
1 files changed, 488 insertions, 0 deletions
diff --git a/doc/parens.texi b/doc/parens.texi new file mode 100644 index 0000000..7ae5420 --- /dev/null +++ b/doc/parens.texi @@ -0,0 +1,488 @@ +@node Between the parens, Cheat sheet, The REPL, Top +@chapter Between the parens + +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 +included for about any language on Earth, and just the best one when +that language is sexpy (specially if you use @ref{paredit,,Paredit}). +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. + +@menu +* Activating Geiser:: +* The source and the REPL:: +* Documentation helpers:: +* To eval or not to eval:: +* To err perchance to debug:: +* Jumping around:: +* Geiser writes for you:: +@end menu + +@node Activating Geiser, The source and the REPL, Between the parens, Between the parens +@section Activating Geiser + +@cindex geiser-mode +@img{geiser-mode, right} With Geiser installed following any of the +procedures described in @ref{Setting it up}, Emacs will automatically +activate @i{geiser-mode} when opening a Scheme buffer. Geiser also +instructs Emacs to consider files with the extension @file{rkt} part of +the family, so that, in principle, there's nothing you need to do to +ensure that Geiser's extensions will be available, out of the box, when +you start editing Scheme code. + +Indications that everything is working according to plan include the +'Geiser' minor mode indicator in your mode-line and the appearance of a +new entry for Geiser in the menu bar. If, moreover, the mode-line +indicator is the name of a Scheme implementation, you're indeed in a +perfect world; otherwise, don't despair and keep on reading: i'll tell +you how to fix that in a moment. + +@cindex geiser-mode commands +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. You +might also want to take a glance at the @ref{Cheat sheet}. + +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 +functions @code{turn-on-geiser-mode} and @code{turn-off-geiser-mode}. +If, for some reason i cannot fathom, you prefer @i{geiser-mode} not +to be active by default, the following elisp incantation will do the +trick: +@example +(eval-after-load "geiser-mode" + (remove-hook 'scheme-mode-hook 'turn-on-geiser-mode)) +@end example +@cindex scheme file extensions +And if you happen to use a funky extension for your Scheme files that is +not recognised as such by Emacs, just tell her about it with: +@example +(add-to-list 'auto-mode-alist '("\\.funky-extension\\'" . scheme-mode)) +@end example + +@cindex useless wretch +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. + +@node The source and the REPL, Documentation helpers, Activating Geiser, 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 +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, +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 +described below. If you find that Geiser is already guessing right the +Scheme implementation, feel free to skip to the +@ref{switching-repl-buff,,next subsection}. + +@subsubheading How Geiser associates a REPL to your Scheme buffer +@cindex scheme implementation, choosing +To determine what Scheme implementation corresponds to a given source +file, Geiser uses the following algorithm: +@enumerate +@item +If the file-local variable @code{geiser-scheme-implementation} is +defined, its value is used. A common way of setting buffer-local +variables is to put them in a comment near the beginning of the file, +surrounded by @code{-*-} marks, as in: +@example +;; -*- geiser-scheme-implementation: guile -*- +@end example +@item +If you've customized @code{geiser-active-implementations} so that it's a +single-element list (as explained @ref{choosing-impl,,here}), that +element is used as the chosen implementation. +@item +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. +@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 +can provide your own rules by customizing this variable, as explained +below. +@item +If we haven't been lucky this far and you have customized +@code{geiser-default-implementation} to the name of a supported +implementation, we'll follow your lead. +@item +See? That's the problem of being a smart alec: one's always outsmarted +by people around. At this point, @i{geiser-mode} will humbly give up and +ask you to explicitly choose the Scheme implementation. +@end enumerate +As you can see in the list above, there are several ways to influence +Geiser's guessing by mean customizable variables. The most direct (and +most impoverishing) is probably limiting the active implementations to a +single one, while customizing @code{geiser-implementations-alist} is the +most flexible (and, unsurprisingly, also the most complex). Here's the +default value for the latter variable: +@example +(((regexp "\\.scm$") guile) + ((regexp "\\.ss$") racket) + ((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: +@example +(eval-after-load "geiser-impl" + '(add-to-list 'geiser-implementations-alist + '((dir "/home/jao/prj/frob") guile))) +@end example +will add a new rule that says that any file inside my +@file{/home/jao/prj/frob} directory (or, recursively, any of its +children) is to be assigned to Guile. Since rules are first matched, +first served, this new rule will take precedence over the default ones. + +@subsubheading Switching between source files and the REPL +@cindex switching to REPL +@cindex switching to source +@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}. + +@cindex switching to module +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 +@i{switch-to-geiser} instead of @i{switch-to-repl}, and what makes it +really handy, if you ask me. + +@cindex switching schemes +If for some reason you're not happy with the Scheme implementation that +Geiser has assigned to your file, you can change it with @kbd{C-c C-s}, +and probably take a look at @ref{switching-repl-buff,,the previous +subsection} to make sure that Geiser doesn't get confused again. + +@subsubheading A note about context +As explained before (@pxref{Modus operandi}), all Geiser activities take +place in the context of the @i{current namespace}, which, for Scheme +buffers, corresponds to the module that the Scheme implementation +associates to the source file at hand (for instance, in Racket, there's +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. + +@node Documentation helpers, To eval or not to eval, The source and the REPL, Between the parens +@section Documentation helpers + +@subsubheading Autodoc redux + +@cindex autodoc, in scheme buffers +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{To eval or not to eval}) their signatures will start appearing +in the echo area. + +@cindex disabling autodoc +Autodoc activation is controlled by a minor mode, @code{geiser-autodoc}, +which you can toggle with @kbd{M-x geiser-autodoc}, or its associated +keyboard shortcut, @kbd{C-c C-d a}. That @t{/A} indicator in the +mode-line is telling you that autodoc is active. If you prefer, for some +obscure reason, that it be inactive by default, just set +@code{geiser-mode-autodoc-p} to @code{nil} in your customization files. + +@cindex autodoc explained +@img{autodoc-req, right} The way autodoc displays information deserves +some explanation. It will first show the name of the module where the +identifier at hand is defined, followed by a colon and the identifier +itself. If the latter corresponds to a procedure or macro, it will be +followed by a list of argument names, starting with the ones that are +required. Then there comes a square-bracketed list of optional argument +names, if any. When an optional argument has a default value (or a form +defining its default value), instead of a plain name, autodoc will +display a list with the name followed by its initialisation form. When +the optional arguments are keywords, their names are prefixed with a +colon. An ellipsis (@dots{}) servers as a marker of an indeterminated +number of parameters, as is the case with @i{rest} arguments or when +autodoc cannot fathom the exact number of arguments (this is often the +case with macros defined using @code{syntax-case}). Another way in which +autodoc displays its ignorance is by using and underscore to display +parameters whose name is beyond its powers. + +@img{autodoc-multi, right} It can also be the case that a function or +macro has more than one signature (e.g., functions defined using +@code{case-lambda}, or some @code{syntax-rules} macros, for which Geiser +has often the black magic necessary to retrieve their actual arities). +In those cases, autodoc shows all known signatures (using the above +rules for each one) separated by a vertical bar (|). As you have already +noticed, the whole thing is enclosed in parenthesis. After all, we're +talking about Scheme here. + +@cindex autodoc for variables +@img{autodoc-var, right} Finally, life is much easier when your cursor +is on a symbol corresponding to a plain variable: you'll see in the echo +area its name, preceded by the module where it's defined, and followed +by its value, with an intervening arrow for greater effect. This time, +there are no enclosing parenthesis (i hope you see the logic in my +madness). + +@cindex autodoc customized +You can change the way Geiser displays the module/identifier combo by +customizing @code{geiser-autodoc-identifier-format}. For example, if you +wanted a tilde surrounded by spaces instead of a colon as a separator, +you would write something like +@example +(setq geiser-autodoc-identifier-format "%s ~ %s") +@end example +in your Emacs initialization files. There's also a face +(@code{geiser-font-lock-autodoc-identifier}) that you can customize (for +instance, with @kbd{M-x customize-face}) to change the appearance of the +text. And another one (@code{geiser-font-lock-autodoc-current-arg}) that +controls how the current argument position is highlighted. + +@subsubheading Other documentation commands + +Sometimes, autodoc won't provide enough information for you to +understand what a function does. In those cases, you can ask Geiser to +ask the running Scheme for further information on a given identifier or +module. + +@cindex documentation for symbol +@cindex docstrings, maybe +For symbols, the incantation is @kbd{M-x geiser-doc-symbol-at-point}, or +@kbd{C-c C-d C-d} for short. If the associated scheme supports +docstrings (as, for instance, Guile does), you'll be teleported to a new +Emacs buffer displaying Geiser's documentation browser, filled with +information about the identifier, including its docstring (if any; +unfortunately, that an implementation supports docstrings doesn't mean +that they're used everywhere). + +@imgc{docstring} + +Pressing @kbd{q} in the documentation buffer will bring you back, +enlightened, to where you were. There's also a handful of other +navigation commands available in that buffer, which you can discover by +means of its menu or via the good old @kbd{C-h m} command. + +For Racket, which does not support docstrings out of the box, this +command will invoke Racket's @code{help} procedure, thereby opening your +configured web browser with the corresponding manual page for you to +peruse. + +You can also ask Geiser to display information about a module, in the +form of a list of its exported identifiers, using @kbd{C-c C-d C-m}, +exactly as you would do @ref{repl-mod,,in the REPL}. This commands works +with all supported Schemes, no strings attached. + +@node To eval or not to eval, To err perchance to debug, Documentation helpers, Between the parens +@section To eval or not to eval + +@cindex philosophy +@cindex incremental development +One of Geiser's main goals is to facilitate incremental development. You +might have noticed that i've made a big fuss of Geiser's ability to +recognize context, by being aware of the namespace where its operations +happen. + +That awareness is specially important when evaluating code in your +scheme buffers, using the commands described below. They allow you to +send code to the running Scheme with a granularity ranging from whole +files to single s-expressions. That code will be evaluated in the module +associated with the file you're editing, allowing you to redefine values +and procedures to your heart's (and other modules') content. + +@cindex incremental development, evil +Macros are, of course, another kettle of fish: one needs to re-evaluate +uses of a macro after redefining it. That's not a limitation imposed by +Geiser, but a consequence of how macros work in Scheme (and other +Lisps). There's also the risk that you lose track of what's actually +defined and what's not during a given session. But, +@uref{http://programming-musings.org/2009/03/29/from-my-cold-prying-hands/,in +my opinion}, those are limitations we lispers are aware of, and they +don't force us to throw the baby with the bathwater and ditch +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. + +@cindex evaluation +@cindex incremental development, not evil +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 (@pxref{To err +perchance to debug}). + +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. + +@node To err perchance to debug, Jumping around, To eval or not to eval, Between the parens +@section To err: perchance to debug + +@cindex to err is schemey +@cindex backtraces +When an error occurs during evaluation, it will be reported according to +the capabilities of the underlying Scheme REPL. + +@cindex error buffer +In Racket, 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, and use @key{RET} or the mouse to +jump to the offending spot; or invoke Emacs' stock commands +@code{next-error} and @code{previous-error}, bound to @kbd{M-g n} and +@kbd{M-g p} by default). + +@imgc{eval-error} + +The Racket backtrace also highlights the exception type, making it +clickable. Following the link will open the documentation corresponding +to said exception type. Both the error and exception link faces are +customizable (@code{geiser-font-lock-error-link} and +@code{geiser-font-lock-doc-link}). + +On the other hand, Guile's reaction to evaluation errors is different: +it enters the debugger in its REPL. Accordingly, the REPL buffer will +pop up if your evaluation fails in a Guile file, and the error message +and backtrace will be displayed in there, again clickable and all. But +there you have the debugger at your disposal, with the REPL's current +module set to that of the offender, and a host of special debugging +commands that are described in Guile's fine documentation. + +@imgc{guile-eval-error} + +In addition, Guile will sometimes report warnings for otherwise +successful evaluations. In those cases, it won't enter the debugger, and +Geiser will report the warnings in a debug buffer, as it does for +Racket. You can control how picky Guile is reporting warnings by +customizing the variable @code{geiser-guile-warning-level}, whose +detailed docstring (which see, using, e.g. @kbd{C-h v}) allows me to +offer no further explanation here. The customization group +@i{geiser-guile} is also worth a glance, for a couple of options to fine +tune how Geiser interacts with Guile's debugger (and more). Same thing +for racketeers and @i{geiser-racket}. + +@node Jumping around, Geiser writes for you, To err perchance to debug, Between the parens +@section Jumping around + +@cindex jumping in scheme buffers +This one feature is as sweet as easy to explain: @kbd{M-.} +(@code{geiser-edit-symbol-at-point}) will open the file where the +identifier around point is defined and land your point on its +definition. To return to where you were, press @kbd{M-,} +(@code{geiser-pop-symbol-stack}). This command works also for module +names: Geiser first tries to locate a definition for the identifier at +point and, if that fails, a module with that name; if the latter +succeeds, the file where the module is defined will pop up. + +Sometimes, the underlying Scheme will tell Geiser only the file where +the symbol is defined, but Geiser will use some heuristics (read, +regular expressions) to locate the exact line and bring you there. Thus, +if you find Geiser systematically missing your definitions, send a +message to the mailing list and we'll try to make the algorithm smarter. + +@cindex jumping customized +You can control how the destination buffer pops up by setting +@code{geiser-edit-symbol-method} to either @code{nil} (to open the file +in the current window), @code{'window} (other window in the same frame) +or @code{'frame} (in a new frame). + +@node Geiser writes for you, , Jumping around, Between the parens +@section Geiser writes for you + +@cindex completion in scheme buffers +No self-respecting programming mode would be complete without +completion. In geiser-mode, identifier completion is bound to +@kbd{M-@key{TAB}}, and will offer all visible identifiers starting with +the prefix before point. Visible here means all symbols imported or +defined in the current namespace plus locally bound ones. E.g., if +you're at the end of the following partial expression: + +@example +(let ((default 42)) + (frob def +@end example + +and press @kbd{M-@key{TAB}}, one of the possible completions will be +@code{default}. + +@cindex smart tabs +If you find the @kbd{M} modifier annoying, you always have the option to +activate @code{geiser-smart-tab-mode}, which will make the @key{TAB} key +double duty as the regular Emacs indentation command (when the cursor is +not near a symbol) and Geiser's completion function. If you want this +smarty pants mode always on in Scheme buffers, customize +@code{geiser-mode-smart-tab-p} to @code{t}. + +@cindex completion for module names +Geiser also knows how to complete module names: if no completion for the +prefix at point is found among the currently visible bindings, it will +try to find a module name that matches it. You can also request +explicitly completion only over module names using @kbd{M-`} (that's a +backtick). + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "geiser" +@c End: |