Removed rate limit setting.
[geiser.git] / doc / intro.texi
blob0e92513a771a127354d4471d46a9f5735efbb499
1 @node Introduction, Installation, Top, Top
2 @chapter Introduction
4 Geiser is an Emacs environment to hack and have fun in Scheme.  If that's
5 enough for you, see @ref{Installation} to get it running and
6 @ref{The REPL} for the fun part.
8 @menu
9 * Modus operandi::
10 * Showing off::
11 @end menu
13 @node Modus operandi, Showing off, Introduction, Introduction
14 @section Modus operandi
16 @cindex modus operandi
17 As already mentioned, Geiser relies on a running Scheme process to
18 obtain the information it makes accessible to the programmer.  There's
19 little effort, on the Elisp side, to understand, say, the module system
20 used by the Scheme implementation at hand; instead, a generic interface
21 between the two worlds is defined, and each supported Scheme includes a
22 library implementing that API, together with some wee shims in Elisp
23 allowing the reuse of the Emacs-side framework, which constitutes the
24 bulk of the code.
26 @cindex current module
27 @anchor{current-module} While being as generic as possible, the
28 Scheme-Elisp interface makes some assumptions about the capabilities and
29 interaction mode of the corresponding REPL.  In particular, Geiser
30 expects the latter to support namespaces in the form of a module system,
31 and to provide a well-defined way to establish the REPL's current
32 namespace (or module), as well as the current file's module (or
33 namespace).  Thus, all evaluations performed by Geiser either in the
34 REPL or in a source code buffer happen in the context of the current
35 namespace.  Every time you switch to a different file, you're switching
36 namespaces automatically; at the REPL, you must request the switch
37 explicitly (usually just using means provided by the Scheme
38 implementation itself).
40 If your favourite Scheme supports the above modus operandi, it has all
41 that's needed for a bare-bones Geiser mode.  But Geiser can, and will,
42 use any metadata available: procedure arities and argument lists to
43 display interactive help, documentation strings, location information
44 to jump to definitions, export lists to provide completion, and so on
45 and so forth.  Although this is not an all-or-none proposition (Geiser
46 can operate with just part of that functionality available), i
47 initially concentrated in supporting those Schemes with the richest
48 (to my knowledge) introspection capabilities, namely, Guile and
49 Racket.  Later on, Dan Leslie added support for Chicken, and there's
50 active work to add support for scsh.
52 @node Showing off,  , Modus operandi, Introduction
53 @section Showing off
54 @cindex swanking
55 When working with a fully conniving Scheme, Geiser can offer the
56 following functionality:
58 @itemize @bullet
59 @item
60 Form evaluation in the context of the current file's module.
61 @item
62 Macro expansion.
63 @item
64 File/module loading and/or compilation.
65 @item
66 Namespace-aware identifier completion (including local bindings, names
67 visible in the current module, and module names).
68 @item
69 Autodoc: the echo area shows information about the signature of the
70 procedure/macro around point automatically.
71 @item
72 Jump to definition of identifier at point.
73 @item
74 Access to documentation (including docstrings when the implementation
75 provides it).
76 @item
77 Listings of identifiers exported by a given module.
78 @item
79 Listings of callers/callees of procedures.
80 @item
81 Rudimentary support for debugging (when the REPL provides a
82 debugger) and error navigation.
83 @item
84 Support for multiple, simultaneous REPLs.
85 @item
86 Support for image display in those Schemes that treat them as first
87 class values.
88 @end itemize
90 In the following pages, i'll try to explain what these features
91 actually are (i'm just swanking here), and how to use them for your
92 profit.  But, before that, let's see how to install Geiser.
94 @c Local Variables:
95 @c mode: texinfo
96 @c TeX-master: "geiser"
97 @c End: