readme.org (11151B)
1 * Overview 2 3 Geiser is a generic Emacs/Scheme interaction mode, featuring an 4 enhanced REPL and a set of minor modes improving Emacs' basic scheme 5 major mode. The main functionalities provided are: 6 7 - Evaluation of forms in the namespace of the current module. 8 - Macro expansion. 9 - File/module loading. 10 - Namespace-aware identifier completion (including local bindings, 11 names visible in the current module, and module names). 12 - Autodoc: the echo area shows information about the signature of 13 the procedure/macro around point automatically. 14 - Jump to definition of identifier at point. 15 - Access to documentation (including docstrings when the 16 implementation provides it). 17 - Listings of identifiers exported by a given module. 18 - Listings of callers/callees of procedures. 19 - Rudimentary support for debugging (list of 20 evaluation/compilation error in an Emacs' compilation-mode 21 buffer). 22 - Support for inline images in schemes, such as Racket, that treat 23 them as first order values. 24 25 If you're not in a hurry, [[http://www.nongnu.org/geiser/][Geiser's website]] contains a much nicer 26 manual. 27 28 * Supported schemes 29 30 Geiser needs Emacs 24 or better, and installing also at least one 31 of the supported scheme implementations. 32 33 The following schemes are supported via an independent package, 34 installable from either NonGNU ELPA or MELPA: 35 36 - Chez 9.4 or better, via [[https://gitlab.com/emacs-geiser/chez][geiser-chez]] 37 - Chibi 0.7.3 or better, via [[https://gitlab.com/emacs-geiser/chibi][geiser-chibi]] 38 - Chicken 4.8.0 or better, via [[https://gitlab.com/emacs-geiser/chicken][geiser-chicken]] 39 - Gambit 4.9.3 or better, via [[https://gitlab.com/emacs-geiser/gambit][geiser-gambit]] 40 - Gauche 0.9.6 or better, via [[https://gitlab.com/emacs-geiser/gauche][geiser-gauche]] 41 - Guile 2.2 or better, via [[https://gitlab.com/emacs-geiser/guile][geiser-guile]] 42 - Kawa 3.1, via [[https://gitlab.com/emacs-geiser/kawa][geiser-kawa]] 43 - MIT/GNU Scheme, via [[https://gitlab.com/emacs-geiser/mit][geiser-mit]] 44 - Racket 6.0 or better, via [[https://gitlab.com/emacs-geiser/racket][geiser-racket]] 45 - Stklos 1.50, via [[https://gitlab.com/emacs-geiser/stklos][geiser-stklos]] 46 47 * Installation 48 *** Using ELPA 49 50 Geiser is available in the ELPA repositories [[https://elpa.nongnu.org/nongnu/geiser.html][NonGNU ELPA]] 51 (pre-configured by default as a source starting in Emacs 28) and 52 MELPA. So the easiest way is to use the ELPA package, and just 53 type 54 55 =M-x package-install RET geiser-<implementation>= 56 57 inside emacs, or the corresponding =use-package= stanza, for, say 58 59 #+begin_src emacs-lisp 60 (use-package geiser-mit :ensure t) 61 #+end_src 62 63 All the concrete implementation packages depend on the base =geiser= 64 package, so it'll be installed for you. 65 66 *** From a repository checkout 67 68 If you are not using MELPA, just put this repository's ~elisp~ 69 directory and the target's scheme directory in your load path and 70 require the latter: 71 72 #+begin_src emacs-lisp 73 (add-to-list 'load-path "<geiser checkout dir>/elisp") 74 (add-to-list 'load-path "<geiser-mit checkout dir>") 75 (require 'geiser-mit) 76 #+end_src 77 78 Some scheme implementations need additional installation steps to 79 fully support all geiser operations, so please do check their 80 corresponding web pages. 81 82 * Basic configuration 83 84 When opening a scheme file, Geiser will try to guess its Scheme, 85 defaulting to the first in the list 86 =geiser-active-implementations=. If you've installed more than one 87 geiser package, you can also use =C-c C-s= to select the 88 implementation by hand (on a per file basis). 89 90 Check the geiser customization group for some other options with: 91 92 #+begin_example 93 M-x customize-group RET geiser RET 94 #+end_example 95 96 In particular, customize =geiser-<impl>-binary=, which should point 97 to an executable in your path. 98 99 To start a REPL, run =M-x geiser=. 100 101 ** Completion at point 102 103 Geiser offers identifier and module name completion, bound to 104 =M-TAB= and =M-`= respectively. Only names visible in the current 105 module are offered. 106 107 While that is cool and all, things are even better: if you have [[http://company-mode.github.io/][Company]] or 108 [[https://github.com/minad/corfu][Corfu]] installed, Geiser's completion will integrate with it. Just enable 109 global-company-mode/corfu-global-mode and, from then on, any new scheme 110 buffer or REPL will use it. Alternatively you can activate company-mode or 111 corfu-mode individually only in some buffers. 112 113 ** Macro expansion with macrostep-geiser 114 115 Geiser offers basic macro expansion in a dedicated buffer. If you 116 prefer in-buffer, step by step expansion, please take a look at 117 Nikita Bloshchanevich's [[https://github.com/nbfalcon/macrostep-geiser][macrostep-geiser]]. 118 119 * Quick key reference 120 121 (See also [[http://geiser.nongnu.org/geiser_5.html#Cheat-sheet][the user's manual cheat sheet]]') 122 123 ** In Scheme buffers: 124 125 | C-c C-s | Specify Scheme implementation for buffer | 126 | C-c C-z | Switch to REPL | 127 | C-c C-a | Switch to REPL and current module | 128 | M-. | Go to definition of identifier at point | 129 | M-, | Go back to where M-. was last invoked | 130 | C-c C-e m | Ask for a module and open its file | 131 | C-c C-e C-l | Add a given directory to Scheme's load path | 132 | C-c C-e [ | Toggle between () and [] for current form | 133 | c-c C-e \ | Insert λ | 134 | C-c C-i | Interrupt on-going evaluation | 135 | C-M-x | Eval definition around point | 136 | C-c C-c | Eval definition around point | 137 | C-c M-e | Eval definition around point and switch to REPL | 138 | C-x C-e | Eval sexp before point | 139 | C-c C-r | Eval region | 140 | C-c M-r | Eval region and switch to REPL | 141 | C-c C-b | Eval buffer | 142 | C-c M-b | Eval buffer and switch to REPL | 143 | C-c C-m x | Macro-expand definition around point | 144 | C-c C-m e | Macro-expand sexp before point | 145 | C-c C-m r | Macro-expand region | 146 | C-c C-k | Compile and load current buffer | 147 | C-c C-l | Load scheme file | 148 | C-u C-c C-k | Compile and load current buffer, restarting REPL | 149 | C-c C-d d | See documentation for identifier at point | 150 | C-c C-d s | See short documentation for identifier at point | 151 | C-c C-d i | Look up manual for identifier at point | 152 | C-c C-d m | See a list of a module's exported identifiers | 153 | C-c C-d a | Toggle autodoc mode | 154 | C-c < | Show callers of procedure at point | 155 | C-c > | Show callees of procedure at point | 156 | M-TAB | Complete identifier at point | 157 | M-`, C-. | Complete module name at point | 158 | TAB | Complete identifier at point or indent | 159 | | (If geiser-mode-smart-tab-p is t) | 160 161 ** In the REPL 162 163 | C-c C-z | Start Scheme REPL, or jump to previous buffer | 164 | C-c M-o | Clear scheme output | 165 | C-c C-q | Kill Scheme process | 166 | C-c C-l | Load scheme file | 167 | C-c C-k | Nuke REPL: use it if the REPL becomes unresponsive | 168 | M-. | Edit identifier at point | 169 | TAB, M-TAB | Complete identifier at point | 170 | M-`, C-. | Complete module name at point | 171 | M-p, M-n | Prompt history, matching current prefix | 172 | C-c \ | Insert λ | 173 | C-c [ | Toggle between () and [] for current form | 174 | C-c C-m | Set current module | 175 | C-c C-i | Import module into current namespace | 176 | C-c C-r | Add a given directory to scheme's load path | 177 | C-c C-d C-d | See documentation for symbol at point | 178 | C-c C-d C-m | See documentation for module | 179 | C-c C-d C-a | Toggle autodoc mode | 180 181 ** In the documentation browser: 182 183 | f | Next page | 184 | b | Previous page | 185 | TAB, n | Next link | 186 | S-TAB, p | Previous link | 187 | N | Next section | 188 | P | Previous section | 189 | k | Kill current page and go to previous or next | 190 | g, r | Refresh page | 191 | c | Clear browsing history | 192 | ., M-. | Edit identifier at point | 193 | z | Switch to REPL | 194 | q | Bury buffer | 195 196 ** In backtrace (evaluation/compile result) buffers: 197 198 - =M-g n=, =M-g p=, =C-x `= for error location navigation. 199 - =n=, =p= for moving among errors in the buffer. 200 - =,= to pop-up the debugger actions menu. 201 - =q= to bury buffer. 202 203 * How to support a new scheme implementation 204 Geiser works by running an instance of a REPL, or remotely 205 connecting to one, and evaluating the scheme code it sees 206 there. Then, every time it needs to perform some operation (like, 207 say, printing autodoc, jumping to a source location or expanding a 208 macro), it asks the running scheme instance for that information. 209 210 So supporting a new scheme usually means writing a small scheme 211 library that provides that information on demand, and then some 212 standard elisp functions that invoke the procedures in that library. 213 214 To see what elisp functions one needs to implement, just execute the 215 command `M-x geiser-implementation-help` inside emacs with a recent 216 version of geiser installed. And then take a look at, say, 217 [[https://gitlab.com/emacs-geiser/guile/-/blob/master/geiser-guile.el][geiser-guile.el]] for examples of how those functions are implemented 218 for concrete schemes. 219 220 Not all schemes can provide introspective information to implement all 221 the functionality that geiser tries to offer. That is okay: you can 222 leave as many functions unimplemented as you see fit (there is even an 223 explicit list of unsupported features), and geiser will still know how 224 to use the ones that are implemented.