Documentation tweaking

[geiser.git] / doc / repl.texi

@node The REPL, Between the parens, Installation, Top
@chapter The REPL
@anchor{quick-start}
If you've followed the indications in @ref{Setting it up}, your Emacs is
now ready to start playing. Otherwise, i'll wait for you: when you're
ready, just come back here and proceed to the following sections.

@menu
* Starting the REPL::
* First aids::
* Switching context::
* Completion and error handling::
* Autodoc and friends::
* Customization and tips::
@end menu

@node Starting the REPL, First aids, The REPL, The REPL
@section Starting the REPL

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

@imgc{repls}

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
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
pretty much equivalent to having a command-line interpreter in a
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{}.

@cindex remote REPL
@cindex connect to server
If you use Guile, there's an alternative way of starting a Geiser REPL:
you can connect to a remote Guile process, provided the latter is
running a REPL server. For that to happen, you just need to start your
Guile process (outside Emacs) passing to it the flag @code{--listen}.
Then, come back to Emacs and execute @kbd{M-x connect-to-guile}. You'll
be asked for a host and a port, with suitable default values (Guile's
@code{--listen} flag accepts an optional port as argument (as in
@code{--listen=1969}), if you don't want to use the default). And voila,
you'll have a Geiser REPL that is served by the remote Guile process in
a dedicated thread, meaning that your Guile can go on doing whatever it
was doing while you tinker with it from Emacs. Note, however,
that all Guile threads share the heap, so that you'll be able to
interact with those other threads in the running scheme from Emacs in a
variety of ways. For starters, all you (re)defintions will be visible
everywhere. That's dangerous, but will come in handy when you need to
debug your running webserver.

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
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
run Emacs inside a terminal, but one can always use
@uref{http://www.emacswiki.org/emacs/LaCarte, La Carte} to access the
menus in a convenient enough fashion.

Or just press @kbd{C-h m} and be done with that.

Among the commands at your disposal, we find the familiar input
navigation keys, with a couple twists. By default, @kbd{M-p} and
@kbd{M-n} are bound to @i{matching} items in your input history. That
is, they'll find the previous or next sexp that starts with the current
input prefix (defined as the text between the end of the prompt and your
current position, a.k.a. @dfn{point}, in the buffer). For going up and
down the list unconditionally, just use @kbd{C-c M-p} and @kbd{C-c M-n}.
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 gently ask it to quit, while @kbd{C-u C-c C-q} will
mercilessly kill the process (but not before stowing your history in the
file system). Unless you're using a remote REPL, that is, in which case
both commands will just sever the connection and leave the remote
process alone. A softer nuke is performed by @kbd{C-c 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 or
closing your connection. 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 remaining commands are meatier, and deserve sections of their own.

@node Switching context, Completion and error handling, First aids, The REPL
@section Switching context

@cindex current module, in REPL
In tune with Geiser's @ref{current-module,,modus operandi}, evaluations
in the @repl{} take place in 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 a couple of meta-commands provided by the Scheme
@repl{} (the stock @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.

@cindex current module, change
Once you enter a new module, only those bindings visible in its
namespace will be available to your evaluations. All schemes supported
by Geiser provide a way to import new modules in the current namespace.
Again, there's a Geiser command, @command{geiser-repl-import-module}, to
invoke such functionality, bound this time to @kbd{C-c C-i}. And, again,
you'll see Geiser just introducing the native incantation for you, and
you're free to use such incantations by hand whenever you want.

One convenience provided by these two Geiser commands is that completion
is available when introducing the new module name, using the
@kbd{@key{TAB}} key. Pressing it at the command's prompt will offer you
a prefix-aware list of available module names.

@imgc{mod-completion}

Which brings me to the next group of @repl{} commands.

@node Completion and error handling, Autodoc and friends, Switching context, The REPL
@section Completion and error handling

@cindex completion, module name
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.

REPL buffers use Emacs' compilation mode to highlight errors reported by
the Scheme interpreter, and you can use the @command{next-error} command
(@kbd{M-g n}) to jump to their location. By default, every time you
enter a new expression for evaluation old error messages are forgotten,
so that @kbd{M-g n} will always jump to errors related to the last
evaluation request, if any. If you prefer a not so forgetful REPL, set
the customization variable @code{geiser-repl-forget-old-errors-p} to
@code{nil}. Note, however, that even when that variable is left as
@kbd{t}, you can always jump to an old error by moving to its line at
the REPL and pressing return.

@node Autodoc and friends, Customization and tips, Completion and error handling, The REPL
@section Autodoc and friends

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.

@cindex autodoc, in the REPL
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
better name, its @dfn{autodoc} mode. Whenever it's active (did you
notice that @i{A} in the mode-line?), Geiser's gerbils will be scanning
what you type and showing (unless you silent them with @kbd{C-c C-a})
information about the identifier nearest to point.

@imgc{repl-autodoc}

If that identifier corresponds to a variable visible in the current
namespace, you'll see the module it belongs to and its value. For
procedures and macros, autodoc will display, instead of their value, the
argument names (or an underscore if Geiser cannot determine the name
used in the definition). Optional arguments are surrounded by square
brackets, and, when the optional argument has a default value, it's
represented by a list made up of its name and that value. When the
argument is a keyword argument, its name is preceded by a colon.

@cindex help on identifier
If that's not enough documentation for you, @kbd{C-c C-d d} will open a
separate documentation buffer with help on the symbol at point. For some
implementations (e.g. Racket), this separate buffer will actually be a
web page displaying the corresponding page in the manual, while for
implementations supporting docstrings (e.g. (you guessed it) Guile)
it'll be a real Emacs buffer displaying that information.

@cindex jump, at the REPL
If that's still not enough, Geiser can jump, via @kbd{M-.}, to the
symbol's definition. A buffer with the corresponding file will pop up,
with its point resting upon the identifier's defining form. When you're
done inspecting, @kbd{M-,} will bring you back to where you were. As we
will see, these commands are also available in scheme buffers. @kbd{M-.}
also works for modules: if your point is on an unambiguous module name,
the file where it's defined will be opened for you.

@cindex module exports
@anchor{repl-mod}
Finally, Geiser can produce for you a list, classified by kind, of the
identifiers exported by a given module: all you need to do is press
@kbd{C-c C-d m}, and type or complete the desired module's name.

@imgc{repl-mod}

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 its associated key bindings, by any of the
methods we've already used for the @repl{}, will give you enough
information to use it effectively enough).

@node Customization and tips,  , Autodoc and friends, The REPL
@section Customization and tips

@cindex REPL customization
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
Emacs initialization files (as a rule, all knobs in Geiser are turnable
this way: you don't need to use customization buffers if you don't like
them).

I'm documenting below a proper subset of those settings, together with
some related tips.

@subsubheading Choosing a Scheme implementation
@cindex scheme implementation, choosing
@anchor{choosing-impl}
Instead of using the generic @command{run-geiser} command, you can start
directly your Scheme of choice via @command{run-racket} or
@command{run-guile}. @anchor{active-implementations} In addition, the
variable @code{geiser-active-implementations} contains a list of those
Schemes Geiser should be aware of. Thus, if you happen to be, say, a
racketeer not to be beguiled by other schemes, you can tell Geiser to
forget about the richness of the Scheme ecosystem with something like
@example
(setq geiser-active-implementations '(racket))
@end example
@noindent in your initialisation files.

@cindex scheme binary
@cindex scheme executable path
@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
full path to the requisite binary.

@cindex scheme load path
@cindex scheme init file
@cindex GUILE_LOAD_PATH
@cindex PLTCOLLECTS
You can also specify a couple more initialisation parameters. For Guile,
@code{geiser-guile-load-path} is a list of paths to add to its load path
when it's started, while @code{geiser-guile-init-file} is the path to an
initialisation file to be loaded on startup. The equivalent variables
for Racket are @code{geiser-racket-collects} and
@code{geiser-racket-init-file}.

@subsubheading History

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:
@example
(setq geiser-repl-history-filename "~/.emacs.d/geiser-history")
@end example
@noindent which makes the files @file{geiser-history.guile} and
@file{geiser-history.racket} to live inside my home's @file{.emacs.d}
directory.

@subsubheading Autodoc

@cindex autodoc, disabling
@cindex peace and quiet
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 @repl{}s. You can always bring the fairies
back, on a per @repl{} basis, using @kbd{C-c C-a}.

@subsubheading Remote connections

@cindex port, default
@cindex host, default
When using @code{connect-to-guile} or @code{geiser-connect}, you'll be
prompted for a host and a port, defaulting to localhost and 37146. You
can change those defaults customizing @code{geiser-repl-default-host}
and @code{geiser-repl-default-port}, respectfully.

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