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