dotemacs

repl.texi (23959B)

---

 @node The REPL, Between the parens, Installation, Top
 @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{geiser}. If you invoke it (via, as is customary in Emacs,
 @kbd{M-x 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{geiser-repl-switch-to-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{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 whether 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 geiser-add-to-load-path
 @cindex geiser-repl-add-project-paths
 @subsubheading Init files and load paths
 The startup behaviour of the REPL can be also fine tuned with a couple
 more initialisation parameters.
 
 Many Scheme implementations provide a configuration variable to specify
 a Geiser-specific init file (e.g., @code{geiser-guile-init-file} for
 Guile), and, sometimes a global list of paths to add to the
 interpreter's load path (that'd be @code{geiser-guile-load-path} for
 Guile).
 
 @cindex default directory
 There is also a generic mechanism to specify how to add directories to
 the initial load path when @code{geiser-repl-current-project-function}
 is set: you can then customize @code{geiser-repl-add-project-paths} to a
 list of subdirectories of the project's root to add to the load path.
 When this option is set, the working directory of the REPL's buffer
 (i.e., the value of the elisp variable @code{default-directory}) will be
 set to the directory returned by
 @code{geiser-repl-current-project-function}).
 
 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 Startup waiting time
 
 @cindex startup timeout
 @cindex timeout
 When starting a scheme implementation in old or very busy 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: