diff options
Diffstat (limited to 'doc/fun.texi')
| -rw-r--r-- | doc/fun.texi | 488 |
1 files changed, 0 insertions, 488 deletions
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: |