From 01300e3ee00e07a97cbb14e9c871823cc6b5e9a4 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Thu, 4 Nov 2010 22:36:03 +0100 Subject: Manual: image update and grammatical error --- doc/img/repl-mod.png | Bin 13151 -> 17604 bytes doc/repl.texi | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/img/repl-mod.png b/doc/img/repl-mod.png index d1060bd..a2dcb10 100644 Binary files a/doc/img/repl-mod.png and b/doc/img/repl-mod.png differ diff --git a/doc/repl.texi b/doc/repl.texi index b1d3b5a..169d782 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -222,7 +222,7 @@ 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 +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). -- cgit v1.2.3 From c54ebd679ac7702dd92da9686f0d2ec2f229b0d5 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Fri, 5 Nov 2010 02:57:15 +0100 Subject: Fix for TAB in REPL, and BACKTAB going to previous error --- doc/cheat.texi | 7 +++++++ elisp/geiser-repl.el | 13 +++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/cheat.texi b/doc/cheat.texi index 6087949..d83a540 100644 --- a/doc/cheat.texi +++ b/doc/cheat.texi @@ -110,6 +110,13 @@ @item M-. @tab geiser-edit-symbol-at-point @tab Edit identifier at point +@item TAB +@tab geiser-completion--tab +@tab Complete identifier at point or indent if none; away from +last prompt, go to next error in the buffer. +@item S-TAB (backtab) +@tab geiser-completion--previous-error +@tab Go to previous error in the REPL buffer @item TAB, M-TAB @tab geiser-completion--complete-symbol @tab Complete identifier at point diff --git a/elisp/geiser-repl.el b/elisp/geiser-repl.el index 57111f4..b84613b 100644 --- a/elisp/geiser-repl.el +++ b/elisp/geiser-repl.el @@ -505,11 +505,19 @@ With a prefix argument, force exit by killing the scheme process." (insert "\n")))))) (defun geiser-repl--tab (n) + "If we're after the last prompt, complete symbol or indent (if +there's no symbol at point). Otherwise, go to next error in the REPL +buffer." (interactive "p") (if (> (point) (geiser-repl--last-prompt-end)) (geiser-completion--maybe-complete) (compilation-next-error n))) +(defun geiser-repl--previous-error (n) + "Go to previous error in the REPL buffer." + (interactive "p") + (compilation-next-error (- n))) + (define-derived-mode geiser-repl-mode comint-mode "REPL" "Major mode for interacting with an inferior scheme repl process. \\{geiser-repl-mode-map}" @@ -535,13 +543,14 @@ With a prefix argument, force exit by killing the scheme process." (define-key geiser-repl-mode-map [return] 'geiser-repl--maybe-send) (define-key geiser-repl-mode-map "\C-j" 'geiser-repl--newline-and-indent) (define-key geiser-repl-mode-map (kbd "TAB") 'geiser-repl--tab) +(define-key geiser-repl-mode-map [backtab] 'geiser-repl--previous-error) (define-key geiser-repl-mode-map "\C-a" 'geiser-repl--bol) (define-key geiser-repl-mode-map (kbd "") 'geiser-repl--bol) (geiser-menu--defmenu repl geiser-repl-mode-map - ("Complete symbol" ((kbd "TAB") (kbd "M-TAB")) - geiser-completion--complete-symbol :enable (symbol-at-point)) + ("Complete symbol" ((kbd "M-TAB")) + geiser-repl--tab :enable (symbol-at-point)) ("Complete module name" ((kbd "C-.") (kbd "M-`")) geiser-completion--complete-module :enable (symbol-at-point)) ("Edit symbol" "\M-." geiser-edit-symbol-at-point -- cgit v1.2.3 From d27e2f151dde318731616d585e83ae8d5cea5ad6 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Fri, 5 Nov 2010 03:01:07 +0100 Subject: Documentation fix --- doc/cheat.texi | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/cheat.texi b/doc/cheat.texi index d83a540..6a9f88f 100644 --- a/doc/cheat.texi +++ b/doc/cheat.texi @@ -112,12 +112,11 @@ @tab Edit identifier at point @item TAB @tab geiser-completion--tab -@tab Complete identifier at point or indent if none; away from -last prompt, go to next error in the buffer. +@tab Complete, indent or go to next error @item S-TAB (backtab) @tab geiser-completion--previous-error @tab Go to previous error in the REPL buffer -@item TAB, M-TAB +@item M-TAB @tab geiser-completion--complete-symbol @tab Complete identifier at point @item M-`, C-. -- cgit v1.2.3 From b420c68157f3fb000be1cd6d20bb016d0f369aa1 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Fri, 5 Nov 2010 03:15:15 +0100 Subject: Documentation tweaking --- doc/cheat.texi | 13 +++++++------ doc/fun.texi | 18 +++++++++--------- doc/geiser.texi | 4 ++-- doc/repl.texi | 2 +- doc/web.texi | 2 +- 5 files changed, 20 insertions(+), 19 deletions(-) diff --git a/doc/cheat.texi b/doc/cheat.texi index 6a9f88f..adcc4d8 100644 --- a/doc/cheat.texi +++ b/doc/cheat.texi @@ -1,4 +1,4 @@ -@node Cheat sheet, No hacker is an island, Fun between the parens, Top +@node Cheat sheet, No hacker is an island, Between the parens, Top @chapter Cheat sheet @menu @@ -106,7 +106,7 @@ @tab Kill Scheme process @item C-c C-k @tab geiser-repl-nuke -@tab Nuke REPL: use it if the REPL becomes unresponsive +@tab Soft restart for unresponsive REPL @item M-. @tab geiser-edit-symbol-at-point @tab Edit identifier at point @@ -177,8 +177,9 @@ @tab Bury buffer @end multitable -@flushright -. -@end flushright - +@ifhtml +@html +
+@end html +@end ifhtml diff --git a/doc/fun.texi b/doc/fun.texi index 76301e2..f7a5238 100644 --- a/doc/fun.texi +++ b/doc/fun.texi @@ -1,5 +1,5 @@ -@node Fun between the parens, Cheat sheet, The REPL, Top -@chapter Fun between the parens +@node Between the parens, Cheat sheet, The REPL, Top +@chapter 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 @@ -23,7 +23,7 @@ process giving you the @repl{}, make those Scheme buffers come to life. * Geiser writes for you:: @end menu -@node Activating Geiser, The source and the REPL, Fun between the parens, Fun between the parens +@node Activating Geiser, The source and the REPL, Between the parens, Between the parens @section Activating Geiser @cindex geiser-mode @@ -78,7 +78,7 @@ 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, Documentation helpers, Activating Geiser, Fun between the parens +@node The source and the REPL, Documentation helpers, Activating Geiser, Between the parens @section The source and the REPL As i've already mentioned a couple of times, @i{geiser-mode} needs a @@ -201,7 +201,7 @@ 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 Documentation helpers, To eval or not to eval, The source and the REPL, Fun between the parens +@node Documentation helpers, To eval or not to eval, The source and the REPL, Between the parens @section Documentation helpers @subsubheading Autodoc redux @@ -312,7 +312,7 @@ form of a list of its exported identifiers, using @kbd{C-c C-d C-m}, exactly as you would do @ref{repl-mod,,in the REPL}. This commands works with all supported Schemes, no strings attached. -@node To eval or not to eval, To err perchance to debug, Documentation helpers, Fun between the parens +@node To eval or not to eval, To err perchance to debug, Documentation helpers, Between the parens @section To eval or not to eval @cindex philosophy @@ -378,7 +378,7 @@ macro-expand them. The corresponding keybindings start with the prefix @kbd{C-r}. The result of the macro expansion always appears in a pop up buffer. -@node To err perchance to debug, Jumping around, To eval or not to eval, Fun between the parens +@node To err perchance to debug, Jumping around, To eval or not to eval, Between the parens @section To err: perchance to debug @cindex to err is schemey @@ -423,7 +423,7 @@ offer no further explanation here. The customization group tune how Geiser interacts with Guile's debugger (and more). Same thing for racketeers and @i{geiser-racket}. -@node Jumping around, Geiser writes for you, To err perchance to debug, Fun between the parens +@node Jumping around, Geiser writes for you, To err perchance to debug, Between the parens @section Jumping around @cindex jumping in scheme buffers @@ -448,7 +448,7 @@ You can control how the destination buffer pops up by setting in the current window), @code{'window} (other window in the same frame) or @code{'frame} (in a new frame). -@node Geiser writes for you, , Jumping around, Fun between the parens +@node Geiser writes for you, , Jumping around, Between the parens @section Geiser writes for you @cindex completion in scheme buffers diff --git a/doc/geiser.texi b/doc/geiser.texi index 2e7ef93..3a65e22 100644 --- a/doc/geiser.texi +++ b/doc/geiser.texi @@ -50,7 +50,7 @@ The document was typeset with * Introduction:: * Installation:: * The REPL:: -* Fun between the parens:: +* Between the parens:: * Cheat sheet:: * No hacker is an island:: * Index:: @@ -78,7 +78,7 @@ The REPL * Autodoc and friends:: * Customization and tips:: -Fun between the parens +Between the parens * Activating Geiser:: * The source and the REPL:: diff --git a/doc/repl.texi b/doc/repl.texi index 169d782..9adb971 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 diff --git a/doc/web.texi b/doc/web.texi index 99f5165..19633c1 100644 --- a/doc/web.texi +++ b/doc/web.texi @@ -12,7 +12,7 @@ * Introduction:: * Installation:: * The REPL:: -* Fun between the parens:: +* Between the parens:: * Cheat sheet:: * No hacker is an island:: * Index:: -- cgit v1.2.3 From e0ed94dafd5bc383cc7c416552b0ae5c377613e4 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Fri, 5 Nov 2010 21:17:36 +0100 Subject: Documentation nits --- doc/repl.texi | 3 ++- doc/thanks.texi | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/repl.texi b/doc/repl.texi index 9adb971..19658fb 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -224,7 +224,8 @@ 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). +information to use it effectively enough). 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 diff --git a/doc/thanks.texi b/doc/thanks.texi index e6f0203..4d9662d 100644 --- a/doc/thanks.texi +++ b/doc/thanks.texi @@ -1,6 +1,6 @@ @node No hacker is an island, Index, Cheat sheet, Top @chapter No hacker is an island - +@cindex thanks Andy Wingo, Geiser's first user, has been a continuous source of encouragement and suggestions, and keeps improving Guile and heeding my feature requests. -- cgit v1.2.3 From 178a9175bf1ff7a268a3376a729cd7bc05dabd6d Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 6 Nov 2010 12:37:07 +0100 Subject: Manual: more precise docs on completion --- doc/fun.texi | 8 +++++--- doc/repl.texi | 13 ++++++++----- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/doc/fun.texi b/doc/fun.texi index f7a5238..08bdc33 100644 --- a/doc/fun.texi +++ b/doc/fun.texi @@ -476,9 +476,11 @@ smarty pants mode always on in Scheme buffers, customize @code{geiser-mode-smart-tab-p} to @code{t}. @cindex completion for module names -Geiser also knows how to complete module names, but it's not yet smart -enough to infer by context that that's what you want. Instead, you must -use a separate command, bound to @kbd{M-`} (that's a backtick). +Geiser also knows how to complete module names: if no completion for the +prefix at point is found among the currently visible bindings, it will +try to find a module name that matches it. You can also request +explicitly completion only over module names using @kbd{M-`} (that's a +backtick). @c Local Variables: @c mode: texinfo diff --git a/doc/repl.texi b/doc/repl.texi index 19658fb..d1ffc08 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -153,7 +153,8 @@ the @repl{} buffer itself. There, you can use either @kbd{C-.} or 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 +165,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 @@ -223,9 +226,9 @@ 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 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). Racketeers will be pleased (i -hope) to note that contracts are part of the information displayed. +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 -- cgit v1.2.3 From ab8f059cc19d0a7d9f52a4374636f704a9887f1d Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 6 Nov 2010 14:22:53 +0100 Subject: Manual nits --- doc/Makefile.am | 2 +- doc/fun.texi | 488 ------------------------------------------------------- doc/geiser.css | 1 + doc/geiser.texi | 2 +- doc/install.texi | 2 +- doc/intro.texi | 12 +- doc/macros.texi | 4 - doc/parens.texi | 488 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/repl.texi | 42 ++--- doc/web.texi | 2 +- 10 files changed, 520 insertions(+), 523 deletions(-) delete mode 100644 doc/fun.texi create mode 100644 doc/parens.texi diff --git a/doc/Makefile.am b/doc/Makefile.am index 247b03d..f2b16bb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -19,7 +19,7 @@ geiser_TEXINFOS = \ intro.texi \ install.texi \ repl.texi \ - fun.texi \ + parens.texi \ cheat.texi \ thanks.texi \ index.texi diff --git a/doc/fun.texi b/doc/fun.texi deleted file mode 100644 index 08bdc33..0000000 --- a/doc/fun.texi +++ /dev/null @@ -1,488 +0,0 @@ -@node Between the parens, Cheat sheet, The REPL, Top -@chapter 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:: -* Documentation helpers:: -* To eval or not to eval:: -* To err perchance to debug:: -* Jumping around:: -* Geiser writes for you:: -@end menu - -@node Activating Geiser, The source and the REPL, Between the parens, Between the parens -@section Activating Geiser - -@cindex geiser-mode -@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} part of -the family, 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. - -@cindex geiser-mode commands -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. You -might also want to take a glance at the @ref{Cheat sheet}. - -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 -@cindex scheme file extensions -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 - -@cindex useless wretch -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, Documentation helpers, Activating Geiser, 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 -@cindex scheme implementation, choosing -To determine what Scheme implementation corresponds to a given source -file, Geiser uses the following algorithm: -@enumerate -@item -If the file-local variable @code{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 @code{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 -@code{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 -@code{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 @code{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 @code{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 -@cindex switching to REPL -@cindex switching to source -@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}. - -@cindex switching to module -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. - -@cindex switching schemes -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 Documentation helpers, To eval or not to eval, The source and the REPL, Between the parens -@section Documentation helpers - -@subsubheading Autodoc redux - -@cindex autodoc, in scheme buffers -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{To eval or not to eval}) their signatures will start appearing -in the echo area. - -@cindex disabling autodoc -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 -@code{geiser-mode-autodoc-p} to @code{nil} in your customization files. - -@cindex autodoc explained -@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. - -@cindex autodoc for variables -@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). - -@cindex autodoc customized -You can change the way Geiser displays the module/identifier combo by -customizing @code{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 -(@code{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 (@code{geiser-font-lock-autodoc-current-arg}) that -controls how the current argument position is highlighted. - -@subsubheading Other documentation commands - -Sometimes, autodoc won't provide enough information for you to -understand what a function does. In those cases, you can ask Geiser to -ask the running Scheme for further information on a given identifier or -module. - -@cindex documentation for symbol -@cindex docstrings, maybe -For symbols, the incantation is @kbd{M-x geiser-doc-symbol-at-point}, or -@kbd{C-c C-d C-d} for short. If the associated scheme supports -docstrings (as, for instance, Guile does), you'll be teleported to a new -Emacs buffer displaying Geiser's documentation browser, filled with -information about the identifier, including its docstring (if any; -unfortunately, that an implementation supports docstrings doesn't mean -that they're used everywhere). - -@imgc{docstring} - -Pressing @kbd{q} in the documentation buffer will bring you back, -enlightened, to where you were. There's also a handful of other -navigation commands available in that buffer, which you can discover by -means of its menu or via the good old @kbd{C-h m} command. - -For Racket, which does not support docstrings out of the box, this -command will invoke Racket's @code{help} procedure, thereby opening your -configured web browser with the corresponding manual page for you to -peruse. - -You can also ask Geiser to display information about a module, in the -form of a list of its exported identifiers, using @kbd{C-c C-d C-m}, -exactly as you would do @ref{repl-mod,,in the REPL}. This commands works -with all supported Schemes, no strings attached. - -@node To eval or not to eval, To err perchance to debug, Documentation helpers, Between the parens -@section To eval or not to eval - -@cindex philosophy -@cindex incremental development -One of Geiser's main goals is to facilitate incremental development. You -might have noticed that i've made a big fuss of Geiser's ability to -recognize context, by being aware of the namespace where its operations -happen. - -That awareness is specially important when evaluating code in your -scheme buffers, using the commands described below. They allow you to -send code to the running Scheme with a granularity ranging from whole -files to single s-expressions. That code will be evaluated in the module -associated with the file you're editing, allowing you to redefine values -and procedures to your heart's (and other modules') content. - -@cindex incremental development, evil -Macros are, of course, another kettle of fish: one needs to re-evaluate -uses of a macro after redefining it. That's not a limitation imposed by -Geiser, but a consequence of how macros work in Scheme (and other -Lisps). There's also the risk that you lose track of what's actually -defined and what's not during a given session. But, -@uref{http://programming-musings.org/2009/03/29/from-my-cold-prying-hands/,in -my opinion}, those are limitations we lispers are aware of, and they -don't force us to throw the baby with the bathwater and ditch -incremental evaluation. Some people disagree; if you happen to find -@uref{http://blog.racket-lang.org/2009/03/drscheme-repl-isnt-lisp.html, -their arguments} convincing, you don't have to throw away Geiser -together with the baby: @kbd{M-x geiser-restart-repl} will let you -restart the @repl{} as many times as you see fit. - -@cindex evaluation -@cindex incremental development, not evil -For all of you bearded old lispers still with me, here are some of the -commands performing incremental evaluation in Geiser. - -@code{geiser-eval-last-sexp}, bound to @kbd{C-x C-e}, will eval the -s-expression just before point. - -@code{geiser-eval-definition}, bound to @kbd{C-M-x}, finds the topmost -definition containing point and sends it for evaluation. The variant -@code{geiser-eval-definition-and-go} (@kbd{C-c M-e}) works in the same -way, but it also teleports you to @repl{} after the evaluation. - -@code{geiser-eval-region}, bound to @kbd{C-c C-r}, evals the current -region. Again, there's an @i{and go} version available, -@code{geiser-eval-region-and-go}, bound to @kbd{C-c M-r}. - -For all the commands above, the result of the evaluation is displayed in -the minibuffer, unless it causes a (scheme-side) error (@pxref{To err -perchance to debug}). - -At the risk of repeating myself, i'll remember you that all these -evaluations will take place in the namespace of the module corresponding -to the Scheme file from which you're sending your code, which, in -general, will be different from the @repl{}'s current module. And, if -all goes according to plan, (re)defined variables and procedures should -be immediately visible inside and, if exported, outside their module. - -Besides evaluating expressions, definitions and regions, you can also -macro-expand them. The corresponding keybindings start with the prefix -@kbd{C-c C-m} and end, respectively, with @kbd{C-e}, @kbd{C-x} and -@kbd{C-r}. The result of the macro expansion always appears in a pop up -buffer. - -@node To err perchance to debug, Jumping around, To eval or not to eval, Between the parens -@section To err: perchance to debug - -@cindex to err is schemey -@cindex backtraces -When an error occurs during evaluation, it will be reported according to -the capabilities of the underlying Scheme REPL. - -@cindex error buffer -In Racket, you'll be presented with a backtrace, in a new buffer where -file paths locating the origin of the error are clickable (you can -navigate them using the @key{TAB} key, and use @key{RET} or the mouse to -jump to the offending spot; or invoke Emacs' stock commands -@code{next-error} and @code{previous-error}, bound to @kbd{M-g n} and -@kbd{M-g p} by default). - -@imgc{eval-error} - -The Racket backtrace also highlights the exception type, making it -clickable. Following the link will open the documentation corresponding -to said exception type. Both the error and exception link faces are -customizable (@code{geiser-font-lock-error-link} and -@code{geiser-font-lock-doc-link}). - -On the other hand, Guile's reaction to evaluation errors is different: -it enters the debugger in its REPL. Accordingly, the REPL buffer will -pop up if your evaluation fails in a Guile file, and the error message -and backtrace will be displayed in there, again clickable and all. But -there you have the debugger at your disposal, with the REPL's current -module set to that of the offender, and a host of special debugging -commands that are described in Guile's fine documentation. - -@imgc{guile-eval-error} - -In addition, Guile will sometimes report warnings for otherwise -successful evaluations. In those cases, it won't enter the debugger, and -Geiser will report the warnings in a debug buffer, as it does for -Racket. You can control how picky Guile is reporting warnings by -customizing the variable @code{geiser-guile-warning-level}, whose -detailed docstring (which see, using, e.g. @kbd{C-h v}) allows me to -offer no further explanation here. The customization group -@i{geiser-guile} is also worth a glance, for a couple of options to fine -tune how Geiser interacts with Guile's debugger (and more). Same thing -for racketeers and @i{geiser-racket}. - -@node Jumping around, Geiser writes for you, To err perchance to debug, Between the parens -@section Jumping around - -@cindex jumping in scheme buffers -This one feature is as sweet as easy to explain: @kbd{M-.} -(@code{geiser-edit-symbol-at-point}) will open the file where the -identifier around point is defined and land your point on its -definition. To return to where you were, press @kbd{M-,} -(@code{geiser-pop-symbol-stack}). This command works also for module -names: Geiser first tries to locate a definition for the identifier at -point and, if that fails, a module with that name; if the latter -succeeds, the file where the module is defined will pop up. - -Sometimes, the underlying Scheme will tell Geiser only the file where -the symbol is defined, but Geiser will use some heuristics (read, -regular expressions) to locate the exact line and bring you there. Thus, -if you find Geiser systematically missing your definitions, send a -message to the mailing list and we'll try to make the algorithm smarter. - -@cindex jumping customized -You can control how the destination buffer pops up by setting -@code{geiser-edit-symbol-method} to either @code{nil} (to open the file -in the current window), @code{'window} (other window in the same frame) -or @code{'frame} (in a new frame). - -@node Geiser writes for you, , Jumping around, Between the parens -@section Geiser writes for you - -@cindex completion in scheme buffers -No self-respecting programming mode would be complete without -completion. In geiser-mode, identifier completion is bound to -@kbd{M-@key{TAB}}, and will offer all visible identifiers starting with -the prefix before point. Visible here means all symbols imported or -defined in the current namespace plus locally bound ones. E.g., if -you're at the end of the following partial expression: - -@example -(let ((default 42)) - (frob def -@end example - -and press @kbd{M-@key{TAB}}, one of the possible completions will be -@code{default}. - -@cindex smart tabs -If you find the @kbd{M} modifier annoying, you always have the option to -activate @code{geiser-smart-tab-mode}, which will make the @key{TAB} key -double duty as the regular Emacs indentation command (when the cursor is -not near a symbol) and Geiser's completion function. If you want this -smarty pants mode always on in Scheme buffers, customize -@code{geiser-mode-smart-tab-p} to @code{t}. - -@cindex completion for module names -Geiser also knows how to complete module names: if no completion for the -prefix at point is found among the currently visible bindings, it will -try to find a module name that matches it. You can also request -explicitly completion only over module names using @kbd{M-`} (that's a -backtick). - -@c Local Variables: -@c mode: texinfo -@c TeX-master: "geiser" -@c End: diff --git a/doc/geiser.css b/doc/geiser.css index e0ffb18..d05f909 100644 --- a/doc/geiser.css +++ b/doc/geiser.css @@ -14,6 +14,7 @@ body { } a { color:black; weight=normal } +a:hover { color: #a22 } hr { height:0; color:white } diff --git a/doc/geiser.texi b/doc/geiser.texi index 3a65e22..0294246 100644 --- a/doc/geiser.texi +++ b/doc/geiser.texi @@ -106,7 +106,7 @@ Cheat sheet @include intro.texi @include install.texi @include repl.texi -@include fun.texi +@include parens.texi @include cheat.texi @include thanks.texi @include index.texi diff --git a/doc/install.texi b/doc/install.texi index b260504..a4ea362 100644 --- a/doc/install.texi +++ b/doc/install.texi @@ -19,7 +19,7 @@ at least one of the supported schemes, which right now are latest and greatest @uref{http://www.gnu.org/software/guile, Guile} 1.9 directly compiled from a recent checkout of @uref{http://www.gnu.org/software/guile/repository.html, its Git -@i{master} branch}. Since Geiser supports multiple @repl{}s, having both +@i{master} branch}. Since Geiser supports multiple REPLs, having both of them will just add to the fun. @cindex use the source, Luke diff --git a/doc/intro.texi b/doc/intro.texi index 0805eca..f26fa7b 100644 --- a/doc/intro.texi +++ b/doc/intro.texi @@ -26,14 +26,14 @@ bulk of the code. @cindex current module @anchor{current-module} While being as generic as possible, the Scheme-Elisp interface makes some assumptions about the capabilities and -interaction mode of the corresponding @repl{}. In particular, Geiser +interaction mode of the corresponding REPL. In particular, Geiser expects the latter to support namespaces in the form of a module system, -and to provide a well defined way to establish the @repl{}'s current +and to provide a well defined way to establish the REPL's current namespace (or module), as well as the current's file module (or namespace). Thus, all evaluations performed by Geiser either in the -@repl{} or in a source code buffer happen in the context of the current +REPL or in a source code buffer happen in the context of the current namespace. Every time you switch to a different file, you're switching -namespaces automatically; at the @repl{}, you must request the switch +namespaces automatically; at the REPL, you must request the switch explicitly (usually just using means provided by the Scheme implementation itself). @@ -76,10 +76,10 @@ Listings of identifiers exported by a given module. @item Listings of callers/callees of procedures. @item -Rudimentary support for debugging (when the @repl{} provides a +Rudimentary support for debugging (when the REPL provides a debugging) and error navigation. @item -Support for multiple, simultaneous @repl{}s. +Support for multiple, simultaneous REPLs. @end itemize In the following pages, i'll try to explain what these features diff --git a/doc/macros.texi b/doc/macros.texi index 712370a..4b235db 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -1,7 +1,3 @@ -@macro repl{} -@acronym{REPL} -@end macro - @macro img{FILE, ALIGN} @ifhtml @html diff --git a/doc/parens.texi b/doc/parens.texi new file mode 100644 index 0000000..7ae5420 --- /dev/null +++ b/doc/parens.texi @@ -0,0 +1,488 @@ +@node Between the parens, Cheat sheet, The REPL, Top +@chapter 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:: +* Documentation helpers:: +* To eval or not to eval:: +* To err perchance to debug:: +* Jumping around:: +* Geiser writes for you:: +@end menu + +@node Activating Geiser, The source and the REPL, Between the parens, Between the parens +@section Activating Geiser + +@cindex geiser-mode +@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} part of +the family, 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. + +@cindex geiser-mode commands +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. You +might also want to take a glance at the @ref{Cheat sheet}. + +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 +@cindex scheme file extensions +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 + +@cindex useless wretch +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, Documentation helpers, Activating Geiser, 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 +@cindex scheme implementation, choosing +To determine what Scheme implementation corresponds to a given source +file, Geiser uses the following algorithm: +@enumerate +@item +If the file-local variable @code{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 @code{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 +@code{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 +@code{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 @code{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 @code{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 +@cindex switching to REPL +@cindex switching to source +@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}. + +@cindex switching to module +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. + +@cindex switching schemes +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 Documentation helpers, To eval or not to eval, The source and the REPL, Between the parens +@section Documentation helpers + +@subsubheading Autodoc redux + +@cindex autodoc, in scheme buffers +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{To eval or not to eval}) their signatures will start appearing +in the echo area. + +@cindex disabling autodoc +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 +@code{geiser-mode-autodoc-p} to @code{nil} in your customization files. + +@cindex autodoc explained +@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. + +@cindex autodoc for variables +@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). + +@cindex autodoc customized +You can change the way Geiser displays the module/identifier combo by +customizing @code{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 +(@code{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 (@code{geiser-font-lock-autodoc-current-arg}) that +controls how the current argument position is highlighted. + +@subsubheading Other documentation commands + +Sometimes, autodoc won't provide enough information for you to +understand what a function does. In those cases, you can ask Geiser to +ask the running Scheme for further information on a given identifier or +module. + +@cindex documentation for symbol +@cindex docstrings, maybe +For symbols, the incantation is @kbd{M-x geiser-doc-symbol-at-point}, or +@kbd{C-c C-d C-d} for short. If the associated scheme supports +docstrings (as, for instance, Guile does), you'll be teleported to a new +Emacs buffer displaying Geiser's documentation browser, filled with +information about the identifier, including its docstring (if any; +unfortunately, that an implementation supports docstrings doesn't mean +that they're used everywhere). + +@imgc{docstring} + +Pressing @kbd{q} in the documentation buffer will bring you back, +enlightened, to where you were. There's also a handful of other +navigation commands available in that buffer, which you can discover by +means of its menu or via the good old @kbd{C-h m} command. + +For Racket, which does not support docstrings out of the box, this +command will invoke Racket's @code{help} procedure, thereby opening your +configured web browser with the corresponding manual page for you to +peruse. + +You can also ask Geiser to display information about a module, in the +form of a list of its exported identifiers, using @kbd{C-c C-d C-m}, +exactly as you would do @ref{repl-mod,,in the REPL}. This commands works +with all supported Schemes, no strings attached. + +@node To eval or not to eval, To err perchance to debug, Documentation helpers, Between the parens +@section To eval or not to eval + +@cindex philosophy +@cindex incremental development +One of Geiser's main goals is to facilitate incremental development. You +might have noticed that i've made a big fuss of Geiser's ability to +recognize context, by being aware of the namespace where its operations +happen. + +That awareness is specially important when evaluating code in your +scheme buffers, using the commands described below. They allow you to +send code to the running Scheme with a granularity ranging from whole +files to single s-expressions. That code will be evaluated in the module +associated with the file you're editing, allowing you to redefine values +and procedures to your heart's (and other modules') content. + +@cindex incremental development, evil +Macros are, of course, another kettle of fish: one needs to re-evaluate +uses of a macro after redefining it. That's not a limitation imposed by +Geiser, but a consequence of how macros work in Scheme (and other +Lisps). There's also the risk that you lose track of what's actually +defined and what's not during a given session. But, +@uref{http://programming-musings.org/2009/03/29/from-my-cold-prying-hands/,in +my opinion}, those are limitations we lispers are aware of, and they +don't force us to throw the baby with the bathwater and ditch +incremental evaluation. Some people disagree; if you happen to find +@uref{http://blog.racket-lang.org/2009/03/drscheme-repl-isnt-lisp.html, +their arguments} convincing, you don't have to throw away Geiser +together with the baby: @kbd{M-x geiser-restart-repl} will let you +restart the REPL as many times as you see fit. + +@cindex evaluation +@cindex incremental development, not evil +For all of you bearded old lispers still with me, here are some of the +commands performing incremental evaluation in Geiser. + +@code{geiser-eval-last-sexp}, bound to @kbd{C-x C-e}, will eval the +s-expression just before point. + +@code{geiser-eval-definition}, bound to @kbd{C-M-x}, finds the topmost +definition containing point and sends it for evaluation. The variant +@code{geiser-eval-definition-and-go} (@kbd{C-c M-e}) works in the same +way, but it also teleports you to REPL after the evaluation. + +@code{geiser-eval-region}, bound to @kbd{C-c C-r}, evals the current +region. Again, there's an @i{and go} version available, +@code{geiser-eval-region-and-go}, bound to @kbd{C-c M-r}. + +For all the commands above, the result of the evaluation is displayed in +the minibuffer, unless it causes a (scheme-side) error (@pxref{To err +perchance to debug}). + +At the risk of repeating myself, i'll remember you that all these +evaluations will take place in the namespace of the module corresponding +to the Scheme file from which you're sending your code, which, in +general, will be different from the REPL's current module. And, if +all goes according to plan, (re)defined variables and procedures should +be immediately visible inside and, if exported, outside their module. + +Besides evaluating expressions, definitions and regions, you can also +macro-expand them. The corresponding keybindings start with the prefix +@kbd{C-c C-m} and end, respectively, with @kbd{C-e}, @kbd{C-x} and +@kbd{C-r}. The result of the macro expansion always appears in a pop up +buffer. + +@node To err perchance to debug, Jumping around, To eval or not to eval, Between the parens +@section To err: perchance to debug + +@cindex to err is schemey +@cindex backtraces +When an error occurs during evaluation, it will be reported according to +the capabilities of the underlying Scheme REPL. + +@cindex error buffer +In Racket, you'll be presented with a backtrace, in a new buffer where +file paths locating the origin of the error are clickable (you can +navigate them using the @key{TAB} key, and use @key{RET} or the mouse to +jump to the offending spot; or invoke Emacs' stock commands +@code{next-error} and @code{previous-error}, bound to @kbd{M-g n} and +@kbd{M-g p} by default). + +@imgc{eval-error} + +The Racket backtrace also highlights the exception type, making it +clickable. Following the link will open the documentation corresponding +to said exception type. Both the error and exception link faces are +customizable (@code{geiser-font-lock-error-link} and +@code{geiser-font-lock-doc-link}). + +On the other hand, Guile's reaction to evaluation errors is different: +it enters the debugger in its REPL. Accordingly, the REPL buffer will +pop up if your evaluation fails in a Guile file, and the error message +and backtrace will be displayed in there, again clickable and all. But +there you have the debugger at your disposal, with the REPL's current +module set to that of the offender, and a host of special debugging +commands that are described in Guile's fine documentation. + +@imgc{guile-eval-error} + +In addition, Guile will sometimes report warnings for otherwise +successful evaluations. In those cases, it won't enter the debugger, and +Geiser will report the warnings in a debug buffer, as it does for +Racket. You can control how picky Guile is reporting warnings by +customizing the variable @code{geiser-guile-warning-level}, whose +detailed docstring (which see, using, e.g. @kbd{C-h v}) allows me to +offer no further explanation here. The customization group +@i{geiser-guile} is also worth a glance, for a couple of options to fine +tune how Geiser interacts with Guile's debugger (and more). Same thing +for racketeers and @i{geiser-racket}. + +@node Jumping around, Geiser writes for you, To err perchance to debug, Between the parens +@section Jumping around + +@cindex jumping in scheme buffers +This one feature is as sweet as easy to explain: @kbd{M-.} +(@code{geiser-edit-symbol-at-point}) will open the file where the +identifier around point is defined and land your point on its +definition. To return to where you were, press @kbd{M-,} +(@code{geiser-pop-symbol-stack}). This command works also for module +names: Geiser first tries to locate a definition for the identifier at +point and, if that fails, a module with that name; if the latter +succeeds, the file where the module is defined will pop up. + +Sometimes, the underlying Scheme will tell Geiser only the file where +the symbol is defined, but Geiser will use some heuristics (read, +regular expressions) to locate the exact line and bring you there. Thus, +if you find Geiser systematically missing your definitions, send a +message to the mailing list and we'll try to make the algorithm smarter. + +@cindex jumping customized +You can control how the destination buffer pops up by setting +@code{geiser-edit-symbol-method} to either @code{nil} (to open the file +in the current window), @code{'window} (other window in the same frame) +or @code{'frame} (in a new frame). + +@node Geiser writes for you, , Jumping around, Between the parens +@section Geiser writes for you + +@cindex completion in scheme buffers +No self-respecting programming mode would be complete without +completion. In geiser-mode, identifier completion is bound to +@kbd{M-@key{TAB}}, and will offer all visible identifiers starting with +the prefix before point. Visible here means all symbols imported or +defined in the current namespace plus locally bound ones. E.g., if +you're at the end of the following partial expression: + +@example +(let ((default 42)) + (frob def +@end example + +and press @kbd{M-@key{TAB}}, one of the possible completions will be +@code{default}. + +@cindex smart tabs +If you find the @kbd{M} modifier annoying, you always have the option to +activate @code{geiser-smart-tab-mode}, which will make the @key{TAB} key +double duty as the regular Emacs indentation command (when the cursor is +not near a symbol) and Geiser's completion function. If you want this +smarty pants mode always on in Scheme buffers, customize +@code{geiser-mode-smart-tab-p} to @code{t}. + +@cindex completion for module names +Geiser also knows how to complete module names: if no completion for the +prefix at point is found among the currently visible bindings, it will +try to find a module name that matches it. You can also request +explicitly completion only over module names using @kbd{M-`} (that's a +backtick). + +@c Local Variables: +@c mode: texinfo +@c TeX-master: "geiser" +@c End: diff --git a/doc/repl.texi b/doc/repl.texi index d1ffc08..e707e61 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -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,7 +43,7 @@ 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. @cindex remote REPL @cindex connect to server @@ -64,7 +64,7 @@ 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 +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 @@ -72,7 +72,7 @@ to the next section! @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 +97,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 +113,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 +139,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,7 +147,7 @@ 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 @@ -178,7 +178,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 @@ -234,7 +234,7 @@ of the information displayed. @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 @@ -262,7 +262,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 @@ -283,7 +283,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: @@ -298,11 +298,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 diff --git a/doc/web.texi b/doc/web.texi index 19633c1..828c02d 100644 --- a/doc/web.texi +++ b/doc/web.texi @@ -34,7 +34,7 @@ list  @include intro.texi @include install.texi @include repl.texi -@include fun.texi +@include parens.texi @include cheat.texi @include thanks.texi @include index.texi -- cgit v1.2.3 From dc8009f5cba70369368a4c1d73dd1d41aece0f84 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 6 Nov 2010 21:42:09 +0100 Subject: Racket: little evaluation nits --- elisp/geiser-eval.el | 1 + 1 file changed, 1 insertion(+) diff --git a/elisp/geiser-eval.el b/elisp/geiser-eval.el index df31594..ffe3306 100644 --- a/elisp/geiser-eval.el +++ b/elisp/geiser-eval.el @@ -113,6 +113,7 @@ module-exports, autodoc, callers, callees and generic-methods.") (mapconcat 'geiser-eval--scheme-str code " ") ")")))) ((symbolp code) (format "%s" code)) + ((stringp code) (format "%S" (substring-no-properties code))) (t (format "%S" code)))) -- cgit v1.2.3 From 580b2193b8f4bb11eb5e24db22bc69aeb3893a9b Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 6 Nov 2010 22:19:07 +0100 Subject: REPL: remembering last connection address --- elisp/geiser-repl.el | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/elisp/geiser-repl.el b/elisp/geiser-repl.el index b84613b..13b655e 100644 --- a/elisp/geiser-repl.el +++ b/elisp/geiser-repl.el @@ -156,9 +156,10 @@ expression, if any." (pop-to-buffer (or old (generate-new-buffer (format "* %s *" - (geiser-repl--repl-name impl))))))) - (geiser-repl-mode) - (geiser-impl--set-buffer-implementation impl)) + (geiser-repl--repl-name impl))))) + (unless old + (geiser-repl-mode) + (geiser-impl--set-buffer-implementation impl))))) (geiser-impl--define-caller geiser-repl--binary binary () "A variable or function returning the path to the scheme binary -- cgit v1.2.3 From f1684f872705bdbb8566f83529cb7707f89cc10b Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 6 Nov 2010 22:56:48 +0100 Subject: Doc fix --- doc/parens.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/parens.texi b/doc/parens.texi index 7ae5420..9ce0d05 100644 --- a/doc/parens.texi +++ b/doc/parens.texi @@ -61,7 +61,7 @@ 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" +(eval-after-load "geiser" (remove-hook 'scheme-mode-hook 'turn-on-geiser-mode)) @end example @cindex scheme file extensions -- cgit v1.2.3 From 0663d1ba075b1efda73de80b8b0d1e3b05f99868 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sat, 6 Nov 2010 23:18:51 +0100 Subject: Completion: falling back to module name completion for real --- elisp/geiser-completion.el | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/elisp/geiser-completion.el b/elisp/geiser-completion.el index d346190..46413cf 100644 --- a/elisp/geiser-completion.el +++ b/elisp/geiser-completion.el @@ -234,8 +234,11 @@ With prefix, complete module name." (completions (car result)) (partial (cdr result))) (cond ((null completions) - (geiser--respecting-message "Can't find completion for %S" prefix) - (geiser-completion--restore-window-cfg)) + (if (not arg) + (geiser-completion--complete-symbol t) + (geiser--respecting-message "Can't find completion for %S" + prefix) + (geiser-completion--restore-window-cfg))) (t (insert-and-inherit (substring partial (length prefix))) (cond ((= (length completions) 1) (geiser--respecting-message "Sole completion") -- cgit v1.2.3 From f4d25d65263c174b2ab54db521d5adf4cf79d8fb Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 7 Nov 2010 02:57:38 +0100 Subject: Completion: not completing the empty string --- elisp/geiser-completion.el | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/elisp/geiser-completion.el b/elisp/geiser-completion.el index 46413cf..f88fae6 100644 --- a/elisp/geiser-completion.el +++ b/elisp/geiser-completion.el @@ -228,9 +228,11 @@ we're looking for a module name.") Perform completion similar to Emacs' complete-symbol. With prefix, complete module name." (interactive "P") + (unless (geiser-syntax--symbol-at-point) + (error "No symbol at point")) (geiser--respecting-message "Retrieving completions...") (let* ((prefix (geiser-completion--prefix arg)) - (result (geiser-completion--complete prefix arg)) + (result (and prefix (geiser-completion--complete prefix arg))) (completions (car result)) (partial (cdr result))) (cond ((null completions) -- cgit v1.2.3 From 7c24433334bd1f021d30f4e1c44d804c44e6b496 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 7 Nov 2010 03:40:37 +0100 Subject: Nits --- elisp/geiser-connection.el | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index dfdb21d..2702f0f 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -274,8 +274,9 @@ (defun geiser-con--send-string/wait (buffer/proc str cont &optional timeout sbuf) (save-current-buffer - (let ((con (geiser-con--get-connection buffer/proc))) - (unless (geiser-con--connection-process con) + (let* ((con (geiser-con--get-connection buffer/proc)) + (proc (and con (geiser-con--connection-process con)))) + (unless proc (error geiser-con--error-message)) (with-current-buffer (geiser-con--connection-buffer con) (when (geiser-con--is-debugging) @@ -290,8 +291,8 @@ (while (and (> time 0) (geiser-con--connection-process con) (not (geiser-con--connection-completed-p con id))) - (accept-process-output nil waitsecs) - (setq time (- time step))) + (unless (accept-process-output nil waitsecs) + (setq time (- time step)))) (error (setq time 0))) (or (> time 0) (geiser-con--request-deactivate req) -- cgit v1.2.3 From afe08bd5db0a2b5494fa239d010bc1f2496161da Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 7 Nov 2010 17:31:09 +0100 Subject: Pumbling cleanups --- elisp/geiser-connection.el | 118 +++++++++++++++++++++++---------------------- elisp/geiser-repl.el | 3 +- 2 files changed, 62 insertions(+), 59 deletions(-) diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index 2702f0f..e24511b 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -35,12 +35,13 @@ ;;; Request datatype: -(defun geiser-con--make-request (str cont &optional sender-buffer) +(defun geiser-con--make-request (con str cont &optional sender-buffer) (list :geiser-connection-request - (cons :id (random)) + (cons :id (geiser-con--connection-inc-count con)) (cons :string str) (cons :continuation cont) - (cons :buffer (or sender-buffer (current-buffer))))) + (cons :buffer (or sender-buffer (current-buffer))) + (cons :connection con))) (defsubst geiser-con--request-p (req) (and (listp req) (eq (car req) :geiser-connection-request))) @@ -57,6 +58,9 @@ (defsubst geiser-con--request-buffer (req) (cdr (assoc :buffer req))) +(defsubst geiser-con--request-connection (req) + (cdr (assoc :connection req))) + (defsubst geiser-con--request-deactivate (req) (setcdr (assoc :continuation req) nil)) @@ -70,9 +74,16 @@ (list :geiser-connection (cons :requests (list)) (cons :current nil) + (cons :count 0) (cons :completed (make-hash-table :weakness 'value)) (cons :buffer buffer) - (cons :timer nil))) + (cons :timer nil) + (cons :reply (geiser-con--make-reply-buffer (buffer-name buffer))))) + +(defun geiser-con--make-reply-buffer (n) + (let ((rb (generate-new-buffer (concat " geiser-con-reply: " n)))) + (buffer-disable-undo rb) + rb)) (defsubst geiser-con--connection-p (c) (and (listp c) (eq (car c) :geiser-connection))) @@ -89,6 +100,9 @@ (defsubst geiser-con--connection-current-request (c) (cdr (assoc :current c))) +(defsubst geiser-con--connection-reply-buffer (c) + (cdr (assoc :reply c))) + (defun geiser-con--connection-clean-current-request (c) (let* ((cell (assoc :current c)) (req (cdr cell))) @@ -112,14 +126,11 @@ (geiser-con--connection-pop-request c) (cdr current)))) -(defun geiser-con--connection-start-timer (c) - (let ((cell (assoc :timer c))) - (when (cdr cell) (cancel-timer (cdr cell))) - (setcdr cell (run-at-time t 0.5 'geiser-con--process-next c)))) - -(defun geiser-con--connection-cancel-timer (c) - (let ((cell (assoc :timer c))) - (when (cdr cell) (cancel-timer (cdr cell))))) +(defun geiser-con--connection-inc-count (c) + (let* ((cnt (assoc :count c)) + (new (1+ (cdr cnt)))) + (setcdr cnt new) + new)) ;;; Connection setup: @@ -142,50 +153,45 @@ (overlay-end comint-last-prompt-overlay))))) -(defsubst geiser-con--has-entered-debugger () - (and geiser-con--debugging-prompt-regexp - (re-search-backward geiser-con--debugging-prompt-regexp nil t) - (or (null geiser-con--debugging-preamble-regexp) - (save-excursion - (re-search-backward geiser-con--debugging-preamble-regexp nil t))))) +(defsubst geiser-con--has-entered-debugger (con) + (with-current-buffer (geiser-con--connection-buffer con) + (and geiser-con--debugging-prompt-regexp + (re-search-backward geiser-con--debugging-prompt-regexp nil t) + (or (null geiser-con--debugging-preamble-regexp) + (save-excursion + (re-search-backward geiser-con--debugging-preamble-regexp + nil t)))))) -(defun geiser-con--cleanup-connection (c) - (geiser-con--connection-cancel-timer c)) +(defun geiser-con--connection-teardown () + (when geiser-con--connection + (kill-buffer + (geiser-con--connection-reply-buffer geiser-con--connection)))) (defun geiser-con--setup-connection (buffer prompt-regexp &optional debug-prompt-regexp debug-preamble-regexp) (with-current-buffer buffer - (when geiser-con--connection - (geiser-con--cleanup-connection geiser-con--connection)) + (geiser-con--connection-teardown) (setq geiser-con--debugging-prompt-regexp debug-prompt-regexp) (setq geiser-con--debugging-preamble-regexp debug-preamble-regexp) (setq geiser-con--connection (geiser-con--make-connection buffer)) - (geiser-con--setup-comint prompt-regexp debug-prompt-regexp) - (geiser-con--connection-start-timer geiser-con--connection) - (message "Geiser REPL up and running!"))) - -(defun geiser-con--setup-comint (prompt-regexp debug-prompt-regexp) - (set (make-local-variable 'comint-redirect-insert-matching-regexp) - (not (null debug-prompt-regexp))) - (set (make-local-variable 'comint-redirect-finished-regexp) - (if debug-prompt-regexp - (format "\\(%s\\)\\|\\(%s\\)" prompt-regexp debug-prompt-regexp) - prompt-regexp)) - (setq comint-prompt-regexp comint-redirect-finished-regexp) - (add-hook 'comint-redirect-hook 'geiser-con--comint-redirect-hook nil t)) + (set (make-local-variable 'comint-redirect-insert-matching-regexp) + (not (null debug-prompt-regexp))) + (set (make-local-variable 'comint-redirect-finished-regexp) + (if debug-prompt-regexp + (format "\\(%s\\)\\|\\(%s\\)" prompt-regexp debug-prompt-regexp) + prompt-regexp)) + (setq comint-prompt-regexp comint-redirect-finished-regexp) + (add-hook 'comint-redirect-hook 'geiser-con--comint-redirect-hook nil t))) ;;; Requests handling: -(defsubst geiser-con--comint-buffer () - (get-buffer-create " *geiser connection retort*")) - -(defun geiser-con--comint-buffer-form () - (with-current-buffer (geiser-con--comint-buffer) +(defun geiser-con--comint-buffer-form (con) + (with-current-buffer (geiser-con--connection-reply-buffer con) (goto-char (point-max)) - (if (geiser-con--has-entered-debugger) + (if (geiser-con--has-entered-debugger con) `((error (key . geiser-debugger)) (output . ,(buffer-substring (point-min) (point)))) (condition-case nil @@ -207,32 +213,28 @@ geiser-con--debugging-preamble-regexp)) (req (geiser-con--connection-pop-request con)) (str (and req (geiser-con--request-string req))) - (cbuf (geiser-con--comint-buffer))) - (if (not (buffer-live-p buffer)) - (geiser-con--connection-cancel-timer con) - (when (and buffer req str) - (with-current-buffer cbuf - (setq comint-redirect-echo-input nil) - (setq geiser-con--debugging-prompt-regexp debug-prompt) - (setq geiser-con--debugging-preamble-regexp debug-preamble) - (delete-region (point-min) (point-max))) - (set-buffer buffer) - (if (geiser-con--is-debugging) - (geiser-con--request-deactivate req) - (geiser-log--info "<%s>: %s" (geiser-con--request-id req) str) - (comint-redirect-send-command (format "%s" str) cbuf nil t))))))) + (rbuffer (geiser-con--connection-reply-buffer con))) + (when (and buffer (buffer-live-p buffer) req str) + (with-current-buffer rbuffer + (delete-region (point-min) (point-max))) + (set-buffer buffer) + (if (geiser-con--is-debugging) + (geiser-con--request-deactivate req) + (geiser-log--info "<%s>: %s" (geiser-con--request-id req) str) + (comint-redirect-send-command (format "%s" str) rbuffer nil t)))))) (defun geiser-con--process-completed-request (req) (let ((cont (geiser-con--request-continuation req)) (id (geiser-con--request-id req)) (rstr (geiser-con--request-string req)) - (buffer (geiser-con--request-buffer req))) + (buffer (geiser-con--request-buffer req)) + (con (geiser-con--request-connection req))) (if (not cont) (geiser-log--warn "<%s> Droping result for request %S (%s)" id rstr req) (condition-case cerr (with-current-buffer (or buffer (current-buffer)) - (funcall cont (geiser-con--comint-buffer-form)) + (funcall cont (geiser-con--comint-buffer-form con)) (geiser-log--info "<%s>: processed" id)) (error (geiser-log--error "<%s>: continuation failed %S \n\t%s" id rstr cerr)))))) @@ -263,7 +265,7 @@ (save-current-buffer (let ((con (geiser-con--get-connection buffer/proc))) (unless con (error geiser-con--error-message)) - (let ((req (geiser-con--make-request str cont sender-buffer))) + (let ((req (geiser-con--make-request con str cont sender-buffer))) (geiser-con--connection-add-request con req) (geiser-con--process-next con) req)))) diff --git a/elisp/geiser-repl.el b/elisp/geiser-repl.el index 13b655e..f6fc12b 100644 --- a/elisp/geiser-repl.el +++ b/elisp/geiser-repl.el @@ -247,7 +247,8 @@ module command as a string") deb-preamble-rx) (add-to-list 'geiser-repl--repls (current-buffer)) (geiser-repl--set-this-buffer-repl (current-buffer)) - (geiser-repl--startup impl))) + (geiser-repl--startup impl) + (message "Geiser REPL up and running!"))) (defun geiser-repl--process () (let ((buffer (geiser-repl--set-up-repl geiser-impl--implementation))) -- cgit v1.2.3 From a1974c8ce4b38e472b961b6a256c4da67f6dcfaf Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 7 Nov 2010 18:29:25 +0100 Subject: Better connection logs --- elisp/geiser-connection.el | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index e24511b..066d1a3 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -224,17 +224,18 @@ (comint-redirect-send-command (format "%s" str) rbuffer nil t)))))) (defun geiser-con--process-completed-request (req) - (let ((cont (geiser-con--request-continuation req)) - (id (geiser-con--request-id req)) - (rstr (geiser-con--request-string req)) - (buffer (geiser-con--request-buffer req)) - (con (geiser-con--request-connection req))) + (let* ((cont (geiser-con--request-continuation req)) + (id (geiser-con--request-id req)) + (rstr (geiser-con--request-string req)) + (buffer (geiser-con--request-buffer req)) + (con (geiser-con--request-connection req)) + (form (geiser-con--comint-buffer-form con))) (if (not cont) - (geiser-log--warn "<%s> Droping result for request %S (%s)" - id rstr req) + (geiser-log--warn "<%s> Droping result for request %S: %s" + id rstr form) (condition-case cerr (with-current-buffer (or buffer (current-buffer)) - (funcall cont (geiser-con--comint-buffer-form con)) + (funcall cont form) (geiser-log--info "<%s>: processed" id)) (error (geiser-log--error "<%s>: continuation failed %S \n\t%s" id rstr cerr)))))) -- cgit v1.2.3 From 688762b5310211f8522979d61332aa54dea2b7d6 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 7 Nov 2010 18:41:32 +0100 Subject: Interruptible connection waiting --- elisp/geiser-connection.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index 066d1a3..c45a37a 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -294,7 +294,7 @@ (while (and (> time 0) (geiser-con--connection-process con) (not (geiser-con--connection-completed-p con id))) - (unless (accept-process-output nil waitsecs) + (unless (sit-for waitsecs) (setq time (- time step)))) (error (setq time 0))) (or (> time 0) -- cgit v1.2.3 From 7c2913d2b6287b4a29c8e56b58902f33d3c5868c Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 03:38:44 +0100 Subject: Connection plumbing: ability to specify EOT token added --- elisp/geiser-connection.el | 91 +++++++++++++++++++++++++--------------------- elisp/geiser-eval.el | 6 --- 2 files changed, 49 insertions(+), 48 deletions(-) diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index c45a37a..5305cd8 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -17,6 +17,7 @@ (require 'geiser-log) (require 'geiser-syntax) (require 'geiser-base) +(require 'geiser-impl) (require 'comint) (require 'advice) @@ -77,13 +78,20 @@ (cons :count 0) (cons :completed (make-hash-table :weakness 'value)) (cons :buffer buffer) - (cons :timer nil) - (cons :reply (geiser-con--make-reply-buffer (buffer-name buffer))))) + (cons :reply (geiser-con--make-reply-buffer buffer)))) -(defun geiser-con--make-reply-buffer (n) - (let ((rb (generate-new-buffer (concat " geiser-con-reply: " n)))) - (buffer-disable-undo rb) - rb)) +(defvar geiser-con--eot-regexp nil) +(geiser-impl--register-local-variable + 'geiser-con--eot-regexp 'eot-regexp nil + "A regular expression used to detect end of transmissions. +By default, Geiser uses the prompt regexp.") + +(defun geiser-con--make-reply-buffer (buffer) + (let ((name (concat " geiser-con-reply: " (buffer-name buffer))) + (eot (with-current-buffer buffer geiser-con--eot-regexp))) + (with-current-buffer (get-buffer-create name) + (setq geiser-con--eot-regexp eot) + (current-buffer)))) (defsubst geiser-con--connection-p (c) (and (listp c) (eq (car c) :geiser-connection))) @@ -103,11 +111,15 @@ (defsubst geiser-con--connection-reply-buffer (c) (cdr (assoc :reply c))) +(defsubst geiser-con--connection-completed (c r) + (geiser-con--request-deactivate req) + (puthash (geiser-con--request-id r) r (cdr (assoc :completed c)))) + (defun geiser-con--connection-clean-current-request (c) (let* ((cell (assoc :current c)) (req (cdr cell))) (when req - (puthash (geiser-con--request-id req) req (cdr (assoc :completed c))) + (geiser-con--connection-completed c req) (setcdr cell nil)))) (defun geiser-con--connection-add-request (c r) @@ -118,13 +130,17 @@ (gethash id (cdr (assoc :completed c)))) (defun geiser-con--connection-pop-request (c) - (let ((reqs (assoc :requests c)) - (current (assoc :current c))) - (setcdr current (prog1 (cadr reqs) (setcdr reqs (cddr reqs)))) - (if (and (cdr current) - (geiser-con--request-deactivated-p (cdr current))) + (let* ((reqs (assoc :requests c)) + (current (assoc :current c)) + (old-current (cdr current)) + (new-current (cadr reqs)) + (new-reqs (cddr reqs))) + (when old-current (geiser-con--connection-completed c old-current)) + (setcdr reqs new-reqs) + (if (and new-current + (geiser-con--request-deactivated-p new-current)) (geiser-con--connection-pop-request c) - (cdr current)))) + (setcdr current new-current)))) (defun geiser-con--connection-inc-count (c) (let* ((cnt (assoc :count c)) @@ -176,13 +192,11 @@ (setq geiser-con--debugging-prompt-regexp debug-prompt-regexp) (setq geiser-con--debugging-preamble-regexp debug-preamble-regexp) (setq geiser-con--connection (geiser-con--make-connection buffer)) - (set (make-local-variable 'comint-redirect-insert-matching-regexp) - (not (null debug-prompt-regexp))) - (set (make-local-variable 'comint-redirect-finished-regexp) - (if debug-prompt-regexp - (format "\\(%s\\)\\|\\(%s\\)" prompt-regexp debug-prompt-regexp) - prompt-regexp)) - (setq comint-prompt-regexp comint-redirect-finished-regexp) + (set (make-local-variable 'comint-redirect-insert-matching-regexp) t) + (setq comint-prompt-regexp + (if debug-prompt-regexp + (format "\\(%s\\)\\|\\(%s\\)" prompt-regexp debug-prompt-regexp) + prompt-regexp)) (add-hook 'comint-redirect-hook 'geiser-con--comint-redirect-hook nil t))) @@ -207,10 +221,6 @@ (defun geiser-con--process-next (con) (when (not (geiser-con--connection-current-request con)) (let* ((buffer (geiser-con--connection-buffer con)) - (debug-prompt (with-current-buffer buffer - geiser-con--debugging-prompt-regexp)) - (debug-preamble (with-current-buffer buffer - geiser-con--debugging-preamble-regexp)) (req (geiser-con--connection-pop-request con)) (str (and req (geiser-con--request-string req))) (rbuffer (geiser-con--connection-reply-buffer con))) @@ -219,7 +229,7 @@ (delete-region (point-min) (point-max))) (set-buffer buffer) (if (geiser-con--is-debugging) - (geiser-con--request-deactivate req) + (geiser-con--connection-completed con req) (geiser-log--info "<%s>: %s" (geiser-con--request-id req) str) (comint-redirect-send-command (format "%s" str) rbuffer nil t)))))) @@ -236,24 +246,27 @@ (condition-case cerr (with-current-buffer (or buffer (current-buffer)) (funcall cont form) + (geiser-con--request-deactivate req) (geiser-log--info "<%s>: processed" id)) (error (geiser-log--error - "<%s>: continuation failed %S \n\t%s" id rstr cerr)))))) + "<%s>: continuation failed %S \n\t%s" id rstr cerr)))) + (geiser-con--connection-clean-current-request con))) (defun geiser-con--comint-redirect-hook () (if (not geiser-con--connection) (geiser-log--error "No connection in buffer") (let ((req (geiser-con--connection-current-request geiser-con--connection))) - (if (not req) (geiser-log--error "No current request") - (geiser-con--process-completed-request req) - (geiser-con--connection-clean-current-request - geiser-con--connection))))) + (if (not req) + (geiser-log--error "No current request") + (geiser-con--process-completed-request req))))) (defadvice comint-redirect-setup (after geiser-con--advice (output-buffer comint-buffer finished-regexp &optional echo)) (with-current-buffer comint-buffer + (when geiser-con--eot-regexp + (setq comint-redirect-finished-regexp geiser-con--eot-regexp)) (when geiser-con--connection (setq mode-line-process nil)))) (ad-activate 'comint-redirect-setup) @@ -262,20 +275,11 @@ (defconst geiser-con--error-message "Geiser connection not active") -(defun geiser-con--send-string (buffer/proc str cont &optional sender-buffer) - (save-current-buffer - (let ((con (geiser-con--get-connection buffer/proc))) - (unless con (error geiser-con--error-message)) - (let ((req (geiser-con--make-request con str cont sender-buffer))) - (geiser-con--connection-add-request con req) - (geiser-con--process-next con) - req)))) - (defvar geiser-connection-timeout 30000 "Time limit, in msecs, blocking on synchronous evaluation requests") (defun geiser-con--send-string/wait (buffer/proc str cont - &optional timeout sbuf) + &optional timeout sbuf) (save-current-buffer (let* ((con (geiser-con--get-connection buffer/proc)) (proc (and con (geiser-con--connection-process con)))) @@ -284,17 +288,20 @@ (with-current-buffer (geiser-con--connection-buffer con) (when (geiser-con--is-debugging) (error "Geiser REPL is in debug mode"))) - (let* ((req (geiser-con--send-string buffer/proc str cont sbuf)) + (let* ((req (geiser-con--make-request con str cont sbuf)) (id (and req (geiser-con--request-id req))) (time (or timeout geiser-connection-timeout)) (step 100) (waitsecs (/ step 1000.0))) (when id + (geiser-con--connection-add-request con req) + (geiser-con--process-next con) (condition-case nil (while (and (> time 0) (geiser-con--connection-process con) (not (geiser-con--connection-completed-p con id))) - (unless (sit-for waitsecs) + (unless (accept-process-output nil waitsecs nil nil) + (geiser-con--process-next con) (setq time (- time step)))) (error (setq time 0))) (or (> time 0) diff --git a/elisp/geiser-eval.el b/elisp/geiser-eval.el index ffe3306..3534312 100644 --- a/elisp/geiser-eval.el +++ b/elisp/geiser-eval.el @@ -136,12 +136,6 @@ module-exports, autodoc, callers, callees and generic-methods.") (defun geiser-eval--set-sync-retort (s) (setq geiser-eval--sync-retort (geiser-eval--log s))) -(defsubst geiser-eval--send (code cont &optional buffer) - (geiser-con--send-string (geiser-eval--proc) - (geiser-eval--code-str code) - `(lambda (s) (,cont (geiser-eval--log s))) - buffer)) - (defun geiser-eval--send/wait (code &optional timeout buffer) (setq geiser-eval--sync-retort nil) (geiser-con--send-string/wait (geiser-eval--proc) -- cgit v1.2.3 From 2f41f60f97936d139a5e533736f4d1d606ca46f9 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 04:05:31 +0100 Subject: Better handling of REPL's header line --- elisp/geiser-repl.el | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/elisp/geiser-repl.el b/elisp/geiser-repl.el index f6fc12b..ee88005 100644 --- a/elisp/geiser-repl.el +++ b/elisp/geiser-repl.el @@ -214,10 +214,10 @@ module command as a string") (defun geiser-repl--save-remote-data (remote address) (setq geiser-repl--address (and remote address)) - (when remote - (setq header-line-format (format "Host: %s Port: %s" - (geiser-repl--host) - (geiser-repl--port))))) + (setq header-line-format (and remote + (format "Host: %s Port: %s" + (geiser-repl--host) + (geiser-repl--port))))) (defun geiser-repl--start-repl (impl &optional remote) (message "Starting Geiser REPL for %s ..." impl) -- cgit v1.2.3 From 6c59e10f0e0bba91f08fbd7b5972940aae9b0cc6 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 04:39:39 +0100 Subject: Tweakings in switch-to-geiser (multiple REPLs) --- elisp/geiser-repl.el | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/elisp/geiser-repl.el b/elisp/geiser-repl.el index ee88005..b50f1d1 100644 --- a/elisp/geiser-repl.el +++ b/elisp/geiser-repl.el @@ -308,14 +308,21 @@ With prefix argument, ask for which one if more than one is running. If no REPL is running, execute `run-geiser' to start a fresh one." (interactive "P") (let* ((impl (or impl geiser-impl--implementation)) - (repl (cond ((and (not ask) (not impl) + (in-repl (eq major-mode 'geiser-repl-mode)) + (in-live-repl (and in-repl (get-buffer-process (current-buffer)))) + (repl (cond ((and (not ask) + (not impl) + (not in-repl) (or geiser-repl--repl (car geiser-repl--repls)))) - ((and (not ask) impl (geiser-repl--repl/impl impl))))) + ((and (not ask) + (not in-repl) + impl + (geiser-repl--repl/impl impl))))) (pop-up-windows geiser-repl-window-allow-split)) - (cond ((and (eq (current-buffer) repl) - (not (eq repl buffer)) - (buffer-live-p geiser-repl--last-scm-buffer)) - (pop-to-buffer geiser-repl--last-scm-buffer)) + (cond ((or in-live-repl + (and (eq (current-buffer) repl) (not (eq repl buffer)))) + (when (buffer-live-p geiser-repl--last-scm-buffer) + (pop-to-buffer geiser-repl--last-scm-buffer))) (repl (pop-to-buffer repl)) ((geiser-repl--remote-p) (geiser-connect impl)) (t (run-geiser impl))) -- cgit v1.2.3 From 92066980e04a39a65cca1966b56b11ed78362744 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 05:43:58 +0100 Subject: Let geiser-connect take optional host and port args --- elisp/geiser-repl.el | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/elisp/geiser-repl.el b/elisp/geiser-repl.el index b50f1d1..a05346c 100644 --- a/elisp/geiser-repl.el +++ b/elisp/geiser-repl.el @@ -206,11 +206,13 @@ module command as a string") (defsubst geiser-repl--port () (cdr geiser-repl--address)) (defsubst geiser-repl--remote-p () geiser-repl--address) -(defun geiser-repl--get-address () +(defun geiser-repl--get-address (&optional host port) (let ((defhost (or (geiser-repl--host) geiser-repl-default-host)) (defport (or (geiser-repl--port) geiser-repl-default-port))) - (cons (read-string (format "Host (default %s): " defhost) nil nil defhost) - (read-number "Port: " defport)))) + (cons (or host + (read-string (format "Host (default %s): " defhost) + nil nil defhost)) + (or port (read-number "Port: " defport))))) (defun geiser-repl--save-remote-data (remote address) (setq geiser-repl--address (and remote address)) @@ -219,10 +221,10 @@ module command as a string") (geiser-repl--host) (geiser-repl--port))))) -(defun geiser-repl--start-repl (impl &optional remote) +(defun geiser-repl--start-repl (impl &optional remote host port) (message "Starting Geiser REPL for %s ..." impl) (geiser-repl--to-repl-buffer impl) - (let ((program (if remote (geiser-repl--get-address) + (let ((program (if remote (geiser-repl--get-address host port) (geiser-repl--binary impl))) (args (geiser-repl--arglist impl)) (prompt-rx (geiser-repl--prompt-regexp impl)) @@ -289,7 +291,7 @@ module command as a string") "Start Geiser for scheme implementation: ")))) (geiser-repl--start-repl impl)) -(defun geiser-connect (impl) +(defun geiser-connect (impl &optional host port) "Start a new Geiser REPL connected to a remote Scheme process." (interactive (list (or (geiser-repl--only-impl-p) @@ -297,7 +299,7 @@ module command as a string") geiser-impl--implementation) (geiser-repl--read-impl "Scheme implementation: ")))) - (geiser-repl--start-repl impl t)) + (geiser-repl--start-repl impl t host port)) (make-variable-buffer-local (defvar geiser-repl--last-scm-buffer nil)) @@ -343,7 +345,8 @@ If no REPL is running, execute `run-geiser' to start a fresh one." "Switch to running Geiser REPL and try to enter a given module." (interactive) (let* ((module (or module - (geiser-completion--read-module "Switch to module: "))) + (geiser-completion--read-module + "Switch to module (default top-level): "))) (cmd (and module (geiser-repl--enter-cmd geiser-impl--implementation module)))) -- cgit v1.2.3 From 06ade45ac52d5597dc04655f4668b02f9b3ebdf2 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 05:44:18 +0100 Subject: geiser-squarify to toggle between () and [] --- README | 1 + doc/cheat.texi | 3 +++ doc/parens.texi | 4 ++++ elisp/geiser-mode.el | 19 +++++++++++++++++++ 4 files changed, 27 insertions(+) diff --git a/README b/README index 8134f97..b10af2a 100644 --- a/README +++ b/README @@ -111,6 +111,7 @@ | M-. | Go to definition of identifier at point | | M-, | Go back to where M-. was last invoked | | C-c C-e m | Ask for a module and open its file | + | C-c C-e [ | Toggle between () and [] for current form | |---------------------+-------------------------------------------------| | C-M-x | Eval definition around point | | C-c M-e | Eval definition around point and switch to REPL | diff --git a/doc/cheat.texi b/doc/cheat.texi index adcc4d8..4e81b92 100644 --- a/doc/cheat.texi +++ b/doc/cheat.texi @@ -31,6 +31,9 @@ @item C-c C-e C-m @tab geiser-edit-module @tab Ask for a module and open its file +@item C-c C-e C-[ +@tab geiser-squarify +@tab Toggle between () and [] for current form @item @tab @tab @item C-M-x @tab geiser-eval-definition diff --git a/doc/parens.texi b/doc/parens.texi index 9ce0d05..9839892 100644 --- a/doc/parens.texi +++ b/doc/parens.texi @@ -482,6 +482,10 @@ try to find a module name that matches it. You can also request explicitly completion only over module names using @kbd{M-`} (that's a backtick). +There's also this little command, @code{geiser-squarify}, which will +toggle the delimiters of the innermost list around point between round +and square brackets. It is bound to @key{C-c C-e [}. + @c Local Variables: @c mode: texinfo @c TeX-master: "geiser" diff --git a/elisp/geiser-mode.el b/elisp/geiser-mode.el index e9e5563..3575474 100644 --- a/elisp/geiser-mode.el +++ b/elisp/geiser-mode.el @@ -176,6 +176,24 @@ With prefix, try to enter the current's buffer module." (goto-char (point-max)) (pop-to-buffer b))) +(defun geiser-squarify () + "Toggle between () and [] for current form." + (interactive) + (let ((pared (and (boundp 'paredit-mode) paredit-mode))) + (when pared (paredit-mode -1)) + (unwind-protect + (save-excursion + (unless (looking-at-p "\\s(") (backward-up-list)) + (let ((p (point)) + (round (looking-at-p "("))) + (forward-sexp) + (backward-delete-char 1) + (insert (if round "]" ")")) + (goto-char p) + (delete-char 1) + (insert (if round "[" "(")))) + (when pared (paredit-mode 1))))) + ;;; Geiser mode: @@ -258,6 +276,7 @@ interacting with the Geiser REPL is at your disposal. ("Complete module name" ((kbd "M-`") (kbd "C-.")) geiser-completion--complete-module) ("Edit module" ("\C-c\C-e\C-m" "\C-c\C-em") geiser-edit-module) + ("Toggle ()/[]" ("\C-c\C-e\C-[" "\C-c\C-e[") geiser-squarify) -- ("Callers" ((kbd "C-c <")) geiser-xref-callers :enable (and (geiser-eval--supported-p 'callers) (symbol-at-point))) -- cgit v1.2.3 From a3743f25313498e96563e3622422bc62d9b80178 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 06:07:12 +0100 Subject: squarify again, now with numeric prefix --- doc/parens.texi | 4 +++- elisp/geiser-mode.el | 35 +++++++++++++++++++++++------------ 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/doc/parens.texi b/doc/parens.texi index 9839892..101ece5 100644 --- a/doc/parens.texi +++ b/doc/parens.texi @@ -484,7 +484,9 @@ backtick). There's also this little command, @code{geiser-squarify}, which will toggle the delimiters of the innermost list around point between round -and square brackets. It is bound to @key{C-c C-e [}. +and square brackets. It is bound to @kbd{C-c C-e [}. With numeric a +prefix (as in, say @kbd{M-2 C-c C-e [}), it will perform that many +toggles, forward for positive values and backward for negative ones. @c Local Variables: @c mode: texinfo diff --git a/elisp/geiser-mode.el b/elisp/geiser-mode.el index 3575474..1645ba2 100644 --- a/elisp/geiser-mode.el +++ b/elisp/geiser-mode.el @@ -176,22 +176,33 @@ With prefix, try to enter the current's buffer module." (goto-char (point-max)) (pop-to-buffer b))) -(defun geiser-squarify () - "Toggle between () and [] for current form." - (interactive) - (let ((pared (and (boundp 'paredit-mode) paredit-mode))) +(defun geiser-squarify (n) + "Toggle between () and [] for current form. +With numeric prefix, perform that many toggles, forward for +positive values and backward for negative." + (interactive "p") + (let ((pared (and (boundp 'paredit-mode) paredit-mode)) + (fwd (> n 0)) + (steps (abs n))) (when pared (paredit-mode -1)) (unwind-protect (save-excursion (unless (looking-at-p "\\s(") (backward-up-list)) - (let ((p (point)) - (round (looking-at-p "("))) - (forward-sexp) - (backward-delete-char 1) - (insert (if round "]" ")")) - (goto-char p) - (delete-char 1) - (insert (if round "[" "(")))) + (while (> steps 0) + (let ((p (point)) + (round (looking-at-p "("))) + (forward-sexp) + (backward-delete-char 1) + (insert (if round "]" ")")) + (goto-char p) + (delete-char 1) + (insert (if round "[" "(")) + (setq steps (1- steps)) + (backward-char) + (condition-case nil + (progn (when fwd (forward-sexp 2)) + (backward-sexp)) + (error (setq steps 0)))))) (when pared (paredit-mode 1))))) -- cgit v1.2.3 From 9863645f5fad1974b24b5e6bab0941d3ed9d8cde Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 06:11:15 +0100 Subject: Documentation typos --- doc/parens.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/parens.texi b/doc/parens.texi index 101ece5..78149e5 100644 --- a/doc/parens.texi +++ b/doc/parens.texi @@ -484,8 +484,8 @@ backtick). There's also this little command, @code{geiser-squarify}, which will toggle the delimiters of the innermost list around point between round -and square brackets. It is bound to @kbd{C-c C-e [}. With numeric a -prefix (as in, say @kbd{M-2 C-c C-e [}), it will perform that many +and square brackets. It is bound to @kbd{C-c C-e [}. With a numeric +prefix (as in, say, @kbd{M-2 C-c C-e [}), it will perform that many toggles, forward for positive values and backward for negative ones. @c Local Variables: -- cgit v1.2.3 From 9b9419690de2edb3f259d5f456d1a4bc03752762 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Mon, 8 Nov 2010 06:15:51 +0100 Subject: README nit --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index b10af2a..8d7ec09 100644 --- a/README +++ b/README @@ -97,7 +97,7 @@ Geiser's completion will use it. Just require company-mode and, from then on, any new scheme buffer or REPL will use it. If you didn't know about Nikolaj Schumacher's awesome mode, check this - screencast: . + screencast: http://goo.gl/yxLQ. * Quick key reference -- cgit v1.2.3 From 6cf1ce0e924fc231b1f51a3ce4eb23e35e9eaf25 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Tue, 9 Nov 2010 02:38:49 +0100 Subject: Elisp buggettes and warnings --- elisp/geiser-connection.el | 2 +- elisp/geiser-mode.el | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index 5305cd8..f146563 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -112,7 +112,7 @@ By default, Geiser uses the prompt regexp.") (cdr (assoc :reply c))) (defsubst geiser-con--connection-completed (c r) - (geiser-con--request-deactivate req) + (geiser-con--request-deactivate r) (puthash (geiser-con--request-id r) r (cdr (assoc :completed c)))) (defun geiser-con--connection-clean-current-request (c) diff --git a/elisp/geiser-mode.el b/elisp/geiser-mode.el index 1645ba2..719176d 100644 --- a/elisp/geiser-mode.el +++ b/elisp/geiser-mode.el @@ -184,7 +184,7 @@ positive values and backward for negative." (let ((pared (and (boundp 'paredit-mode) paredit-mode)) (fwd (> n 0)) (steps (abs n))) - (when pared (paredit-mode -1)) + (when (and pared (fboundp 'paredit-mode)) (paredit-mode -1)) (unwind-protect (save-excursion (unless (looking-at-p "\\s(") (backward-up-list)) @@ -203,7 +203,7 @@ positive values and backward for negative." (progn (when fwd (forward-sexp 2)) (backward-sexp)) (error (setq steps 0)))))) - (when pared (paredit-mode 1))))) + (when (and pared (fboundp 'paredit-mode)) (paredit-mode 1))))) ;;; Geiser mode: -- cgit v1.2.3 From a7ad5704722b7fab966ac8fb4e6b62fe2e424756 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Tue, 9 Nov 2010 21:35:50 +0100 Subject: Racket: remote REPLs --- .gitignore | 1 + Makefile.am | 2 +- bin/Makefile.am | 15 ++++++++++++ bin/geiser-racket.sh | 19 +++++++++++++++ configure.ac | 1 + doc/repl.texi | 60 +++++++++++++++++++++++++++++++--------------- elisp/geiser-connection.el | 57 +++++++++++++++++++------------------------ 7 files changed, 102 insertions(+), 53 deletions(-) create mode 100644 bin/Makefile.am create mode 100755 bin/geiser-racket.sh diff --git a/.gitignore b/.gitignore index 15ac980..444b523 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,4 @@ /doc/geiser.info /doc/texinfo.tex /autom4te.cache/ +/bin/Makefile.in diff --git a/Makefile.am b/Makefile.am index 0ef180e..4f5a16b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = . elisp scheme doc +SUBDIRS = . elisp scheme bin doc EXTRA_DIST = THANKS diff --git a/bin/Makefile.am b/bin/Makefile.am new file mode 100644 index 0000000..9f6ee2b --- /dev/null +++ b/bin/Makefile.am @@ -0,0 +1,15 @@ +EXTRA_DIST = geiser-racket.sh +dist_bin_SCRIPTS = geiser-racket +noinst_SCRIPTS = geiser-racket-noinst + +CLEANFILES = $(dist_bin_SCRIPTS) $(noinst_SCRIPTS) + +geiser-racket: $(srcdir)/geiser-racket.sh + @sed -e "s|top=\".*\"|top=$(datarootdir)/geiser|" \ + $(srcdir)/geiser-racket.sh >$@ + @chmod +x $@ + +geiser-racket-noinst: $(srcdir)/geiser-racket.sh + @sed -e "s|top=\".*\"|top=$(abs_top_srcdir)/scheme|" \ + $(srcdir)/geiser-racket.sh >$@ + @chmod +x $@ diff --git a/bin/geiser-racket.sh b/bin/geiser-racket.sh new file mode 100755 index 0000000..4f16383 --- /dev/null +++ b/bin/geiser-racket.sh @@ -0,0 +1,19 @@ +#!/bin/bash +#| +top="$(dirname $0)/../scheme" +exec racket -i -S "$top/racket" -l errortrace -cu "$0" ${1+"$@"} +|# + +#lang racket/base + +(require (lib "cmdline.rkt")) + +(define port (make-parameter 1969)) + +(command-line + "run-racket.sh" (current-command-line-arguments) + (once-each + (("-p" "--port") p "Geiser server port" (port (string->number p))))) + +(and ((dynamic-require 'geiser/server 'start-geiser) (port)) + (printf "Geiser server running at port ~a~%" (port))) diff --git a/configure.ac b/configure.ac index 1a70214..ddeec3f 100644 --- a/configure.ac +++ b/configure.ac @@ -25,6 +25,7 @@ elisp/Makefile elisp/geiser-version.el elisp/geiser-load.el scheme/Makefile +bin/Makefile doc/Makefile ]) diff --git a/doc/repl.texi b/doc/repl.texi index e707e61..03fb42a 100644 --- a/doc/repl.texi +++ b/doc/repl.texi @@ -45,27 +45,49 @@ 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. +@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{/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 diff --git a/elisp/geiser-connection.el b/elisp/geiser-connection.el index f146563..dc669aa 100644 --- a/elisp/geiser-connection.el +++ b/elisp/geiser-connection.el @@ -159,15 +159,17 @@ By default, Geiser uses the prompt regexp.") (make-variable-buffer-local (defvar geiser-con--debugging-preamble-regexp nil)) -(defun geiser-con--is-debugging () - (and geiser-con--debugging-prompt-regexp - geiser-con--debugging-inhibits-eval - comint-last-prompt-overlay - (string-match-p geiser-con--debugging-prompt-regexp - (buffer-substring (overlay-start - comint-last-prompt-overlay) - (overlay-end - comint-last-prompt-overlay))))) +(defun geiser-con--is-debugging (&optional con) + (with-current-buffer (or (and con (geiser-con--connection-buffer con)) + (current-buffer)) + (and geiser-con--debugging-prompt-regexp + geiser-con--debugging-inhibits-eval + comint-last-prompt-overlay + (string-match-p geiser-con--debugging-prompt-regexp + (buffer-substring (overlay-start + comint-last-prompt-overlay) + (overlay-end + comint-last-prompt-overlay)))))) (defsubst geiser-con--has-entered-debugger (con) (with-current-buffer (geiser-con--connection-buffer con) @@ -278,35 +280,24 @@ By default, Geiser uses the prompt regexp.") (defvar geiser-connection-timeout 30000 "Time limit, in msecs, blocking on synchronous evaluation requests") -(defun geiser-con--send-string/wait (buffer/proc str cont - &optional timeout sbuf) +(defun geiser-con--send-string/wait (b/p str cont &optional timeout sbuf) (save-current-buffer - (let* ((con (geiser-con--get-connection buffer/proc)) + (let* ((con (geiser-con--get-connection b/p)) (proc (and con (geiser-con--connection-process con)))) - (unless proc - (error geiser-con--error-message)) - (with-current-buffer (geiser-con--connection-buffer con) - (when (geiser-con--is-debugging) - (error "Geiser REPL is in debug mode"))) + (unless proc (error geiser-con--error-message)) + (when (geiser-con--is-debugging con) (error "REPL is in debug mode")) (let* ((req (geiser-con--make-request con str cont sbuf)) - (id (and req (geiser-con--request-id req))) - (time (or timeout geiser-connection-timeout)) - (step 100) - (waitsecs (/ step 1000.0))) - (when id - (geiser-con--connection-add-request con req) - (geiser-con--process-next con) + (id (geiser-con--request-id req)) + (timeout (/ (or timeout geiser-connection-timeout) 1000.0)) + (waitsecs 0.1)) + (geiser-con--connection-add-request con req) + (with-timeout (timeout (geiser-con--request-deactivate req)) (condition-case nil - (while (and (> time 0) - (geiser-con--connection-process con) + (while (and (geiser-con--connection-process con) (not (geiser-con--connection-completed-p con id))) - (unless (accept-process-output nil waitsecs nil nil) - (geiser-con--process-next con) - (setq time (- time step)))) - (error (setq time 0))) - (or (> time 0) - (geiser-con--request-deactivate req) - nil)))))) + (geiser-con--process-next con) + (accept-process-output proc waitsecs nil t)) + (error (geiser-con--request-deactivate req)))))))) (provide 'geiser-connection) -- cgit v1.2.3