1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
|
* 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).
- Support for inline images in schemes, such as Racket, that treat
them as first order values.
NOTE: if you're not in a hurry, [[http://www.nongnu.org/geiser/][Geiser's website]] contains a much
nicer manual.
* Requirements
Geiser needs Emacs 24 or better, and at least one of the supported
scheme implementations:
- Guile 2.2 or better.
- Chicken 4.8.0 or better.
- MIT/GNU Scheme 9.1.1 or better.
- Chibi 0.7.3 or better.
- Gambit 4.9.3 or better.
- Racket 6.0 or better.
- Chez 9.4 or better.
* Installation
The easiest way is to use MELPA, and just type
=M-x package-install RET geiser= inside emacs.
Geiser can be used either directly from its uninstalled source tree
or byte-compiled and installed after performing the standard
configure/make/make install dance. See the INSTALL file for more details.
** Chicken 5 Addendum
These steps are necessary to fully support Chicken Scheme, but are
not required for any other scheme.
- Install the necessary support eggs:
#+BEGIN_EXAMPLE
$ chicken-install -s apropos chicken-doc srfi-18 srfi-1
#+END_EXAMPLE
- Update the Chicken documentation database:
#+BEGIN_EXAMPLE
$ cd `csi -R chicken.platform -p '(chicken-home)'`
$ curl https://3e8.org/pub/chicken-doc/chicken-doc-repo-5.tgz | sudo tar zx
#+END_EXAMPLE
** Chicken 4 Addendum
These steps are necessary to fully support Chicken Scheme, but are
not required for any other scheme.
- Install the necessary support eggs:
#+BEGIN_EXAMPLE
$ chicken-install -s apropos chicken-doc
#+END_EXAMPLE
- Update the Chicken documentation database:
#+BEGIN_EXAMPLE
$ cd `csi -p '(chicken-home)'`
$ curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx
#+END_EXAMPLE
** Gambit Addendum
These steps are necessary to fully support Gambit Scheme.
1 - clone the last version of gambit
2 - configure gambit using --enable-rtlib-debug-source to activate autodoc
#+BEGIN_EXAMPLE
$ cd ~/
$ git clone "the gambit repo address"
$ cd gambit
$ ./configure --enable-single-host --enable-debug --enable-rtlib-debug-source
$ make bootstrap
$ make bootclean
$ make -j
$ make install
#+END_EXAMPLE
* 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-active-implementations= *before* loading
geiser.el. For instance:
#+BEGIN_SRC elisp
(setq geiser-active-implementations '(chicken 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:
#+BEGIN_EXAMPLE
M-x customize-group RET geiser RET
#+END_EXAMPLE
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://company-mode.github.io/][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.
* Quick key reference
(See also [[file:///home/jao/usr/jao/geiser/web/geiser_5.html#Cheat-sheet][the manual]]'s cheat sheet)
** In Scheme buffers:
|-------------+--------------------------------------------------|
| C-c C-s | Specify Scheme implementation for buffer |
| C-c C-z | Switch to REPL |
| C-c C-a | Switch to REPL and current module |
| | |
|-------------+--------------------------------------------------|
| 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 C-l | Add a given directory to Scheme's load path |
| C-c C-e [ | Toggle between () and [] for current form |
| c-c C-e \ | Insert λ |
| | |
|-------------+--------------------------------------------------|
| C-M-x | Eval definition around point |
| C-c C-c | 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-b | Eval buffer |
| C-c M-b | Eval buffer 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 | Macro-expand region |
| | |
|-------------+--------------------------------------------------|
| C-c C-k | Compile and load current buffer |
| C-c C-l | Load scheme file |
| C-u C-c C-k | Compile and load current buffer, restarting REPL |
| | |
|-------------+--------------------------------------------------|
| C-c C-d d | See documentation for identifier at point |
| C-c C-d s | See short documentation for identifier at point |
| C-c C-d i | Look up manual 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 |
| | |
|-------------+--------------------------------------------------|
| 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 M-o | Clear scheme output |
| C-c C-q | Kill Scheme process |
| C-c C-l | Load scheme file |
| C-c C-k | Nuke REPL: use it if the REPL becomes unresponsive |
| | |
|-------------+----------------------------------------------------|
| 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 \ | Insert λ |
| C-c [ | Toggle between () and [] for current form |
| | |
|-------------+----------------------------------------------------|
| C-c C-m | Set current module |
| C-c C-i | Import module into current namespace |
| C-c C-r | Add a given directory to scheme's load path |
| | |
|-------------+----------------------------------------------------|
| 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:
|----------+----------------------------------------------|
| f | Next page |
| b | Previous page |
| | |
|----------+----------------------------------------------|
| TAB, n | Next link |
| S-TAB, p | Previous link |
| N | Next section |
| P | Previous section |
| | |
|----------+----------------------------------------------|
| 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:
- =M-g n=, =M-g p=, =C-x `= for error navigation.
- =q= to bury buffer.
* How to support a new scheme implementation
Geiser works by running an instance of a REPL, or remotely connecting
to one, and evaluating the scheme code it sees there. Then, every time
it needs to perform some operation (like, say, printing autodoc,
jumping to a source location or expanding a macro), it asks the
running scheme instance for that information.
So supporting a new scheme usually means writing a small scheme
library that provides that information on demand, and then some
standard elisp functions that invoke the procedures in that
library.
To see what elisp functions one needs to implement, just execute the
command `M-x geiser-implementation-help` inside emacs with a recent
version of geiser installed. And then take a look at, say,
geiser-guile.el or geiser-racket.el for examples of how those
functions are implemented for concrete schemes (those are the most
featureful implementations we have, so perhaps it's easier to begin
with something like geiser-chicken.el or geiser-chibi.el).
Not all schemes can provide introspective information to implement all
the functionality that geiser tries to offer. That is okay: you can
leave as many functions unimplemented as you see fit (there is even an
explicit list of unsupported features), and geiser will still know how
to use the ones that are implemented.
|
