Better module help

[geiser.git] / doc / parens.texi

@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, customizing @code{geiser-mode-auto-p} to
@code{nil} will do the trick.

@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-scm, 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 list of optional arguments, if any,
enclosed in parenthesis. When an optional argument has a default value
(or a form defining its default value), autodoc will display it after
the argument name. When the optional arguments are keywords, their names
are prefixed with ``#:'' (i.e., their names @i{are} keywords). An
ellipsis (@dots{}) serves 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 autodoc message 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).

There's also this little command, @code{geiser-squarify}, which will
toggle the delimiters of the innermost list around point between round
and square brackets. It is bound to @kbd{C-c C-e [}. With a numeric
prefix (as in, say, @kbd{M-2 C-c C-e [}), it will perform that many
toggles, forward for positive values and backward for negative ones.

@c Local Variables:
@c mode: texinfo
@c TeX-master: "geiser"
@c End: