path: root/doc/fun.texi

@node Fun between the parens
@chapter Fun 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::
* Autodoc redux::
* Evaluating Scheme code::
* Jumping around::
* Geiser writes for you::
* In good company::
@end menu

@node Activating Geiser, The source and the REPL, Fun between the parens, Fun between the parens
@section Activating Geiser
@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} Scheme
files, 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.

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.

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
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

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, Autodoc redux, 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
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
To determine what Scheme implementation corresponds to a given source
file, Geiser uses the following algorithm:
@enumerate
@item
If the file-local variable @var{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 @var{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
@var{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
@var{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 @var{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 @var{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
@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}.

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.

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 Autodoc redux, Evaluating Scheme code, The source and the REPL, Fun between the parens
@section Autodoc redux

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.

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
@var{geiser-mode-autodoc-p} to @code{nil} in your customization files.

@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.

@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).

You can change the way Geiser displays the module/identifier combo by
customizing @var{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
(@var{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 (@var{geiser-font-lock-autodoc-current-arg}) that
controls how the current argument position is highlighted.

@node Evaluating Scheme code, Jumping around, Autodoc redux, Fun between the parens
@section Evaluating Scheme code

@node Jumping around, Geiser writes for you, Evaluating Scheme code, Fun between the parens
@section Jumping around

@node Geiser writes for you, In good company, Jumping around, Fun between the parens
@section Geiser writes for you

@node In good company,  , Geiser writes for you, Fun between the parens
@section In good company

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