dotemacs

My Emacs configuration
git clone git://git.entf.net/dotemacs
Log | Files | Refs | LICENSE

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>