diff options
Diffstat (limited to 'doc/repl.texi')
| -rw-r--r-- | doc/repl.texi | 116 |
1 files changed, 71 insertions, 45 deletions
diff --git a/doc/repl.texi b/doc/repl.texi index b1d3b5a..03fb42a 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -1,4 +1,4 @@ -@node The REPL, Fun between the parens, Installation, Top +@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 @@ -18,14 +18,14 @@ ready, just come back here and proceed to the following sections. @section Starting the REPL @cindex REPL -To start a Scheme @repl{} (meaning, a scheme process offering you a +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. +choose your poison, and a new REPL buffer will pop-up. @imgc{repls} @@ -33,7 +33,7 @@ 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{}, +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 @@ -43,36 +43,58 @@ 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{}. +file that will be reloaded whenever you restart the REPL. +@subsubheading Connecting to an external Scheme @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! +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 scheme directory in the 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. 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)defintions will be visible everywhere. That's dangerous, but will +come in handy when you need to debug your running webserver. + +@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 +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 @@ -97,13 +119,13 @@ 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 +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 +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. @@ -113,14 +135,14 @@ The remaining commands are meatier, and deserve sections of their own. @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 +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 +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 +you can freely use said native ways directly at the REPL, and Geiser will be happy to oblige. @cindex current module, change @@ -139,7 +161,7 @@ a prefix-aware list of available module names. @imgc{mod-completion} -Which brings me to the next group of @repl{} commands. +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 @@ -147,13 +169,14 @@ Which brings me to the next group of @repl{} commands. @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 +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. +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 @@ -164,7 +187,9 @@ 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. +the REPL and pressing @kbd{RET}. When your cursor is away from the last +prompt, @kbd{TAB} will move to the next error in the buffer, and you can +use @kbd{BACKTAB} everywhere to go to the previous one. @node Autodoc and friends, Customization and tips, Completion and error handling, The REPL @section Autodoc and friends @@ -175,7 +200,7 @@ 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 +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 @@ -222,15 +247,16 @@ identifiers exported by a given module: all you need to do is press 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 it's 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). +sections (but just perusing its associated key bindings, by any of the +methods we've already mentioned, will give you enough information to use +it). Racketeers will be pleased (i hope) to note that contracts are part +of the information displayed. @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 +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 @@ -258,7 +284,7 @@ forget about the richness of the Scheme ecosystem with something like @cindex scheme binary @cindex scheme executable path -@anchor{impl-binary} When starting a new @repl{}, Geiser assumes, by +@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 @@ -279,7 +305,7 @@ for Racket are @code{geiser-racket-collects} and 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: +@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: @@ -294,11 +320,11 @@ directory. @cindex autodoc, disabling @cindex peace and quiet -If you happen to love peace and quiet and prefer to keep your @repl{}'s +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}. +disabled by default in new REPLs. You can always bring the fairies +back, on a per REPL basis, using @kbd{C-c C-a}. @subsubheading Remote connections |