New HACKING file

[geiser.git] / doc / repl.texi

@node The REPL
@chapter The REPL
@anchor{quick-start}
If you've followed the instructions in @ref{Installation}, 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::
* Seeing is believing::
* 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 invoke 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 @altr{active-implementations,below,Customization and tips,.}
Tabbing for completion will offer you, as of this writing, @code{guile},
@code{racket}, @code{chicken}, @code{mit}, @code{chibi} and @code{chez}.
Just choose your poison, and a new REPL buffer will pop up (by default,
the REPL will appear in a new window: if that annoys you, just set
@code{geiser-repl-use-other-window} to @code{nil} and the current window
will be used).

@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 in
@altr{impl-binary,a moment,Customization and tips,.}
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 and Chicken's top namespaces don't have a name;
cf. discussion in
@altr{Switching context,,Switching context,).}
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 REPL, faces
@cindex faces, in the REPL
If you're not happy with the faces Geiser is using for the REPL's prompt
and evaluated input, you can customise
@code{geiser-font-lock-repl-prompt} and
@code{geiser-font-lock-repl-input} to better-looking faces.

@subsubheading Connecting to an external Scheme
@cindex remote REPL
@cindex connect to server
There's an alternative way of starting a Geiser REPL: you can connect to
an external Scheme process, provided it's running a REPL server at some
known port.  How to make that happen depends on the Scheme implementation.

@cindex Guile's REPL server
If you use Guile, you just need to start your Guile process (possibly
outside Emacs) passing to it the flag @code{--listen}.  This flag accepts
an optional port as argument (as in @code{--listen=1969}), if you don't
want to use the default.

@cindex Racket's REPL server
In Racket, you have to use the REPL server that comes with Geiser.  To
that end, put Geiser's Racket @file{scheme} directory in Racket's
collection search path and invoke @code{start-geiser} (a procedure in
the module @code{geiser/server}) somewhere in your program, passing it
the desired port and, if desired, network interface name.  This
procedure will start the REPL server in a separate thread.  For an
example of how to do that, see the script @file{bin/geiser-racket.sh} in
the source distribution, or, if you've compiled Geiser,
@file{bin/geiser-racket-noinst} in the build directory, or, if you've
installed Geiser, @file{geiser-racket} in
@file{<installation-prefix>/bin}.  These scripts start a new interactive
Racket that is also running a REPL server (they also load the errortrace
library to provide better diagnostics, but that's not strictly needed).

With your external Scheme process running and serving, come back to
Emacs and execute @kbd{M-x geiser-connect}, @kbd{M-x connect-to-guile}
or @kbd{M-x connect-to-racket}.  You'll be asked for a host and a port,
and, voila, you'll have a Geiser REPL that is served by the remote
Scheme process in a dedicated thread, meaning that your external program
can go on doing whatever it was doing while you tinker with it from
Emacs.  Note, however, that all Scheme 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 your
(re)definitions will be visible everywhere.  That's dangerous, but will
come in handy when you need to debug your running web server.

@cindex remote connections
The connection between Emacs and the Scheme process goes over TCP, so it
can be as remote as you need, perhaps with the intervention of an SSH
tunnel.

@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-based 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.  If worse comes to worst and the process is dead, @kbd{C-c
C-z} will restart it.  However, the same shortcut, issued when the REPL is
alive, will bring you back to the buffer you came from, as explained
in
@altr{switching-repl-buff,this section,The source and the REPL,.}

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
@cindex ,enter vs. enter!
In tune with Geiser's
@ifhtml
@ref{current-module,,modus operandi},
@end ifhtml
@ifnothtml
@i{modus operandi},
@end ifnothtml
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 Chicken and the
(geiser-defined) @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.  In
Racket, @command{,enter} works like Racket's standard @code{enter!}
form, but you can also provide a path string as its argument (e.g.,
@command{,enter "/tmp/foo.rkt"} is equivalent to @command{,enter (file
"/tmp/foo.rkt")}).  Like @code{enter!}, @command{,enter} accepts also
module names (as in, say, @command{,enter geiser/main}).  As
mentioned, in Guile and Chicken, @command{,m} is used @i{as is}.

@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, at the REPL
We've already seen Geiser completion of module names in action at the
minibuffer.  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.  If no completion is found, @kbd{@key{TAB}} will try
to complete the prefix after point as a module name.

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 @kbd{@key{RET}}.  When your cursor is away from
the last prompt, @kbd{@key{TAB}} will move to the next error in the
buffer, and you can use @kbd{@key{BACKTAB}} everywhere to go to the
previous one.

@subheading Caveat about completion & the REPL
@anchor{completion-caveat}

It is possible for Geiser to hang your Emacs process when trying to
complete symbols. This can happen in the REPL itself or even in a
Scheme buffer that is attached to the REPL process. If this happens,
you've probably entered a module that changes the REPL prompt from
what Geiser was expecting to see.

Unfortunately, there's no general solution for this issue right now (as
it is a daunting task to try to make a regexp that can encompass all
possible REPL prompts). The best solution for now is to fix this issue
on a case-by-case basis by adjusting your prompt regexp variable so
that it matches the default prompt as well as your Scheme module's
special prompt.

For example, XREPL is a Racket module that implements a better Racket
REPL. You might be interested in toying around with some of its
functions, but when you try to enter XREPL via, say, @kbd{C-c C-m
xrepl}, you'll notice that the REPL prompt has changed to something
like this:

@example
<pkgs>/xrepl-lib/xrepl/main> 
@end example

If you start typing symbols, and then you try to auto-complete those
symbols, your Emacs process may hang. This is because Geiser expects
the REPL prompt to match this regexp (for Racket):

@example
"\\(mzscheme\\|racket\\)@@[^ ]*> "
@end example

Therefore, we can fix this issue by changing our default prompt regexp
like so:

@example
(setq geiser-racket--prompt-regexp "<pkgs>.*> \\|\\(mzscheme\\|racket\\)@@[^ ]*> ")
@end example

Note that you may have to run @kbd{M-x geiser-reload} after setting
this variable so that your changes will take effect.

Again, you'll have to change the regexp to fit every prompt that
causes this issue, but the only alternative (that we can think of
right now) is to create a regexp that will match every possible
prompt. Obviously, that is going to be more than a little
tricky. However, if you have a better solution than that, please share
it with the Geiser developers; we'll be more than happy to hear it.

@node Autodoc and friends, Seeing is believing, 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 echo area 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 silence them with @kbd{C-c C-d 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
parentheses.  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 has ``#:'' as a prefix.

@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.
This buffer will contain implementation-specific information about the
identifier (e.g., its docstring for Guile, or its contract, if any,
for Racket), and a handy button to open the corresponding manual entry
for the symbol, which will open an HTML page (for Racket and Chicken)
or the texinfo manual (for Guile). If you'd rather go directly to the
manual, try @kbd{C-c C-d i}, which invokes
@code{geiser-doc-look-up-manual} as the handy button does.

@cindex module exports
@anchor{repl-mod} Geiser can also 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, again, in a buffer belonging to
Geiser's documentation browser, where you have at your disposal a bunch
of navigation commands listed in
@altr{Documentation browser,our cheat-sheet,Documentation browser,.}

We'll have a bit more to say about the documentation browser in
@altr{doc-browser,a later section,Documentation helpers,.}

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

@node Seeing is believing, Customization and tips, Autodoc and friends, The REPL
@section Seeing is believing

@cindex image support
In schemes that support images as values (currently, that means
Racket), the REPL will display them inline if you're using them in a
graphics-aware Emacs.

@imgc{repl-images}

@cindex external image viewer
@cindex image viewer
For the terminal, images will appear as buttons: press return on them to
invoke an external viewer (configurable via @code{geiser-image-viewer})
that will show you the image at hand.  You can also ask for the same
behaviour on all emacsen by customising
@code{geiser-repl-inline-images-p} to @code{nil}.

@cindex image cache
Geiser keeps a cache of the last displayed images in the directory
@code{geiser-image-cache-dir}, which defaults to the system's temp
directory, with up to @code{geiser-image-cache-keep-last} files.  You
can invoke the external image viewer on any of them with @command{M-x
geiser-view-last-image}, which takes a prefix argument to indicate which
image number you want, 0 corresponding to the newest one.

@node Customization and tips,  , Seeing is believing, 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 initialisation files (as a rule, all knobs in Geiser are tunable
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 directly
start your Scheme of choice using any of the following commands:
@itemize @bullet
@item @command{run-racket}
@item @command{run-guile}
@item @command{run-chicken}
@item @command{run-mit}
@item @command{run-chibi}
@item @command{run-chez}
@end itemize
  @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 (depending on which Scheme you choose):
@itemize @bullet
@item @code{geiser-guile-binary}
@item @code{geiser-racket-binary}
@item @code{geiser-chicken-binary}
@item @code{geiser-mit-binary}
@item @code{geiser-chibi-binary}
@item @code{geiser-chez-binary}
@end itemize
They should be set to a string with the full path to the requisite binary.

@cindex Version checking
Before starting the REPL, Geiser will check wether the version of your
Scheme interpreter is good enough.  This means that it will spend a
couple tenths of a second launching and quickly discarding a Scheme
process, but also that the error message you'll get if you're on the
wrong Scheme version will be much more informative.  If you one to
avoid version checks, just check
@code{geiser-repl-skip-version-check-p} to @code{t} in your
configuration.

@cindex scheme load path
@cindex scheme init file
@cindex GUILE_LOAD_PATH
@cindex GUILE_LOAD_COMPILED_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 (and its compiled load path) when it's started, while
@code{geiser-guile-init-file} is the path to an initialisation file to
be loaded on start-up.  The equivalent variables for Racket are
@code{geiser-racket-collects} and @code{geiser-racket-init-file}.

Note, however, that specifying @code{geiser-guile-init-file} is @i{not}
equivalent to changing Guile's initialization file (@file{~/.guile}),
because the former is loaded using the @code{-l} flag, together with
@code{-q} to disable loading the second.  But there are subtle
differences in the way Guile loads the initialization file versus how it
loads a file specified via the @code{-l} flag.  If what you want is just
loading @file{~/.guile}, leave @code{geiser-guile-init-file} alone and
set @code{geiser-guile-load-init-file-p} to @code{t} instead.

These variables controlling your scheme's initialisation process are
good candidates for an entry in a project's @file{.dir-locals.el} file,
so that they are automatically set to a sensible value whenever you
start a REPL in the project's directory.

@subsubheading Racket startup time

@cindex startup timeout
@cindex timeout
When starting Racket in little computers, Geiser might have to wait a
bit more than it expects (which is ten seconds, or ten thousand
milliseconds, by default).  If you find that Geiser is giving up too
quickly and complaining that no prompt was found, try to increase the
value of @code{geiser-repl-startup-time} to, say, twenty seconds:

@example
(setq geiser-repl-startup-time 20000)
@end example

@noindent
If you prefer, you can use the customize interface to, well, customise
the above variable's value.

@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 REPLs.  You can always bring the fairies
back, on a per-REPL basis, using @kbd{C-c C-d C-a}.

@subsubheading Remote connections

@cindex port, default
@cindex host, default
When using any of the connection commands (e.g. @code{geiser-connect},
@code{connect-to-guile}, @code{connect-to-racket}, etc.) 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},
respectively.

@subsubheading Killing REPLs

@cindex ask on kill, don't
If you don't want Emacs to ask for confirmation when you're about to
kill a live REPL buffer (as will happen, for instance, if you're exiting
Emacs before closing all your REPLs), you can set the flag
@code{geiser-repl-query-on-kill-p} to @code{nil}.  On a related note,
the customizable variable @code{geiser-repl-query-on-exit-p} controls
whether Geiser should ask for confirmation when you exit the REPL
explicitly (via, say, @kbd{C-c C-q}, as opposed to killing the buffer),
and is set to @code{nil} by default.

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