diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 185 |
1 files changed, 185 insertions, 0 deletions
@@ -0,0 +1,185 @@ + -*- org -*- +* Overview + + Geiser is a generic Emacs/Scheme interaction mode, featuring an + enhanced REPL and a set of minor modes improving Emacs' basic scheme + major mode. The main functionalities provided are: + + - Evaluation of forms in the namespace of the current module. + - Macro expansion. + - File/module loading. + - Namespace-aware identifier completion (including local bindings, + names visible in the current module, and module names). + - Autodoc: the echo area shows information about the signature of + the procedure/macro around point automatically. + - Jump to definition of identifier at point. + - Access to documentation (including docstrings when the + implementation provides it). + - Listings of identifiers exported by a given module. + - Listings of callers/callees of procedures. + - Rudimentary support for debugging (list of + evaluation/compilation error in an Emacs' compilation-mode + buffer). + + NOTE: if you're not in a hurry, [[http://www.nongnu.org/geiser/][Geiser's website]] contains a nicer + manual, also included in Geiser tarballs as a texinfo file + (doc/geiser.info). + +* Supported scheme implementations + + - Guile 2.0 (not released yet: use the latest git master branch). + - PLT Racket 5.0.1 or better. + +* Installation + Geiser can be used either directly from its uninstalled source tree + or byte-compiled and installed after perfoming the standard + configure/make/make install dance. + +*** In place + - Extract the tarball or clone the git repository anywhere in your + file system. Let's call that place <path-to-geiser>. + - In your .emacs: + + #+BEGIN_SRC emacs-lisp + (load-file "<path-to-geiser>/elisp/geiser.el") + #+END_SRC + +*** Byte-compiled + - Create a build directory, `build', say: + #+BEGIN_SRC shell + $ cd <path-to-geiser> + $ mkdir build; cd build + #+END_SRC + - Configure and make: + #+BEGIN_SRC shell + $ ../configure && make + #+END_SRC + + Now, you can use the byte-compiled Geiser in place by adding to + your .emacs: + + #+BEGIN_SRC emacs-lisp + (load "<path-to-geiser>/build/elisp/geiser-load") + #+END_SRC + + or, alternatively, install it with: + + #+BEGIN_SRC shell + $ make install + #+END_SRC + + (you might need to get root access, depending on your installation + directory) and, instead of the above load forms, require + 'geiser-install (not 'geiser, mind you) in your emacs + initialization file: + + #+BEGIN_SRC emacs-lisp + (require 'geiser-install) + #+END_SRC + + You're ready to go! + +* Basic configuration + The loading invocations above install all supported Scheme + implementations. You can list explicitly the ones that you want by + setting the variable `geiser-impl-installed-implementations' *before* + loading geiser.el. For instance: + + #+BEGIN_SRC emacs-lisp + (setq geiser-impl-installed-implementations '(racket guile)) + #+END_SRC + + On opening a scheme file, Geiser will try to guess its Scheme, + defaulting to the first in the list. Use `C-c C-s' to select the + implementation by hand (on a per file basis). + + Check the geiser customization group for some options with: + + M-x customize-group RET geiser RET + + In particular, customize `geiser-<impl>-binary', which should point + to an executable in your path. + + To start a REPL, M-x geiser. + +*** Completion with company-mode + Geiser offers identifier and module name completion, bound to + M-TAB and M-` respectively. Only names visible in the current + module are offered. + + While that is cool and all, things are even better: if you have + [[http://nschum.de/src/emacs/company-mode/][company-mode]] installed, 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 [[http://www.screentoaster.com/watch/stU0lSRERIR1pYRFVdXVlRVFFV/company_mode_for_gnu_emacs][this screencast]]. + +* Quick key reference + +*** In Scheme buffers: + + |---------------------+-------------------------------------------------| + | C-c C-z | Switch to REPL | + | C-u C-c C-z | Switch to REPL and current module | + | C-c C-s | Specify Scheme implementation for buffer | + | 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-M-x | Eval definition around point | + | C-c M-e | Eval definition around point and switch to REPL | + | C-x C-e | Eval sexp before point | + | C-c C-r | Eval region | + | C-c M-r | Eval region and switch to REPL | + | C-c C-m x | Macro-expand definition around point | + | C-c C-m e | Macro-expand sexp before point | + | C-c C-m r | Marcro-expand region | + | C-u C-c C-m [x,e,r] | (With prefix, macro expansions are recursive) | + | C-c C-k | Compile and load current file | + | C-c C-l | Load current file | + | C-c C-d d | See documentation for identifier at point | + | C-c C-d m | See a list of a module's exported identifiers | + | C-c C-d a | Toggle autodoc mode | + | C-c< | Show callers of procedure at point | + | C-c> | Show callees of procedure at point | + | C-c C-x f | See a generic's methods signatures | + | M-TAB | Complete identifier at point | + | M-`, C-. | Complete module name at point | + | TAB | Complete identifier at point or indent | + | | (If `geiser-mode-smart-tab-p' is t) | + |---------------------+-------------------------------------------------| + +*** In the REPL + + |-------------+----------------------------------------------------| + | C-c C-z | Start Scheme REPL, or jump to previous buffer | + | C-c C-q | Kill Scheme process | + | M-. | Edit identifier at point | + | TAB, M-TAB | Complete identifier at point | + | M-`, C-. | Complete module name at point | + | M-p, M-n | Prompt history, matching current prefix | + | C-c C-k | Nuke REPL: use it if the REPL becomes unresponsive | + | C-c C-m | Set current module | + | C-c C-i | Import module into current namespace | + | C-c C-l | Load scheme file | + | C-c C-d C-d | See documentation for symbol at point | + | C-c C-d C-m | See documentation for module | + | C-c C-d C-a | Toggle autodoc mode | + |-------------+----------------------------------------------------| + +*** In the documentation browser: + + |------------+----------------------------------------------| + | n, f | Next page | + | p, b | Previous page | + | TAB, S-TAB | Next/previous link | + | k | Kill current page and go to previous or next | + | g, r | Refresh page | + | c | Clear browsing history | + | ., M-. | Edit identifier at point | + | z | Switch to REPL | + | q | Bury buffer | + |------------+----------------------------------------------| + +*** In backtrace (evaluation/compile result) buffers: + + - TAB, M-TAB for error navigation. + - q to bury buffer. |