Geiser User Manual - download.savannah.gnu.org
Contents
1. see the script bin geiser racket sh in the source distri bution or if you ve compiled Geiser bin geiser racket noinst in the build directory or if you ve installed Geiser geiser racket in lt installation prefix gt bin These scripts start a new interactive Racket that is also running a REPL server they also load the errortrace library to provide better diagnostics but that s not strictly needed With your external Scheme process running and serving come back to Emacs and exe cute M x geiser connect M x connect to guile or M x connect to racket You ll be Chapter 3 The REPL 6 asked for a host and a port and voila you ll have a Geiser REPL that is served by the remote Scheme process in a dedicated thread meaning that your external program can go on doing whatever it was doing while you tinker with it from Emacs Note however that all Scheme threads share the heap so that you ll be able to interact with those other threads in the running Scheme from Emacs in a variety of ways For starters all your re definitions will be visible everywhere That s dangerous but will come in handy when you need to debug your running web server The connection between Emacs and the Scheme process goes over TCP so it can be as remote as you need perhaps with the intervention of an SSH tunnel 3 2 First aids A quick way of seeing what else Geiser s REPL can do for you is to display the corresponding entry up2. Key C c C z C c C a C c C s M M C c C e C m C c C e C 1 C c C e C C M x C c M e C x C e C c C r C c M r C c C m C x C c C m C e C c C m C r C c C k M g n C x M g p C c C d C d Command geiser mode switch to repl geiser mode switch to repl and enter geiser set scheme geiser edit symbol at point geiser pop symbol stack geiser edit module geiser add to load path geiser squarify geiser eval definition geiser eval definition and go geiser eval last sexp geiser eval region geiser eval region and go geiser expand definition geiser expand last sexp geiser expand region geiser compile current buffer next error previous error geiser doc symbol at point Description Switch to REPL Switch to REPL and current mod ule also C u C c C z Specify Scheme implementation for buffer Go to definition of identifier at point Go back to where M was last invoked Ask for a module and open its file Ask for a directory and add to Scheme load path Toggle between and for cur rent form Eval definition around point Eval definition around point and switch to REPL Eval sexp before point Eval region Eval region and switch to REPL Macro expand definition around point Macro expand sexp before point Macro expand region Compile and load current file Jump to the location of next error Jump to the location of previous error See documentation for identifier
3. PDF format here What You still here I promise the above is all that s needed to start using Geiser But in case you are missing your configure make all install routine by all means you can go through those motions to byte compile and install Geiser too That is you enter the source directory and since we grabbed the development tree run the customary autogen Script Chapter 2 Installation 4 cd lisp geiser autogen sh I recommend that you compile Geiser in a separate directory mkdir build amp amp cd build configure some drivel here gt make all lt more of the above gt Now you have two options loading the byte compiled Geiser from the elisp subdirec tory or installing it system wide To load the byte code from here add this line to your initialisation file load lisp geiser build elisp geiser load and eval that form and you re done you could also restart Emacs but killing your friends is widely considered bad form Yes that s load and geiser load instead of load file and geiser el If you prefer a system wide installation just type sudo make install With the above spell Geiser will be compiled and installed in a safe place inside Emacs load path To load it into Emacs you ll need instead of the load file form above the following line in your initialisation file require geiser install Please note that we re requiring geiser install and not geis
4. at point Chapter 5 Cheat sheet C c C d C s C c C d C m C c C d C i C c C d C a C c lt C c gt M TAB M CS 5 2 REPL Key C c C z C c C q M TAB S TAB backtab M TAB M C C c C r M p M n C c M p C c M n C c C m C c C i C c C d C d C c C d C m C c C d C a geiser autodoc show geiser doc module geiser doc look up manual geiser autodoc mode geiser xref callers geiser xref callees completion at point geiser completion complete module Command switch to geiser geiser repl exit geiser edit symbol at point geiser repl tab dwim geiser repl previous error completion at point geiser completion complete module geiser add to load path comint commands comint commands switch to geiser module geiser repl import module geiser doc symbol at point geiser repl doc module geiser autodoc mode 5 3 Documentation browser Key Command 19 Show signature or value for iden tifier at point in echo area See a list of a module s exported identifiers Look up manual for symbol at point Toggle autodoc mode Show callers of procedure at point Show callees of procedure at point Complete identifier at point Complete module name at point Description Start Scheme REPL or jump to previous buffer Kill Scheme process Edit identifier at point Complete indent or go to next error Go to previous error in the REPL buffer Complete indentifier at point Comp
5. autodoc in scheme buffers 00 t2 autodoc in the REPL 0005 B DacktTaces icc scchawecaness PORPDSLDREEPDERI bases 15 bug trackers be oe rer bin adh CR Gad 21 byte compilation i 0 0008 ce ee de 3 C COMPANY s c6hacc ond obser dents nce EEEE EREE Rees 4 completion for module names 16 completion in scheme buffers 16 completion at the REPL 0 7 CONNECE to SeEVer eser ve ke Rae eer mere riisi 5 current module 4n beie eme Re ndn e guis 1 current module change 000 6 current module in REPL usse 6 D disabling autodoc liess 13 docstrings maybe ssssessseeeeeeeeees 14 documentation for symbol 14 E error b lfer i2lssliilssscacc teertele EuehiRniqel LS evaliation nineideeskLrvEGR 4d deeds 15 G Peiser MOdE sess estas rias be pit wed iawenss 10 geiser mode commands 005 10 BEID ngeisenssnneiUencieeweelten8S ER IG IP 21 Guile s REPL server ooeccecererisererceri teres 5 GUILE LOAD PATH 00005 8 H help on identifier cece eee ee eee eee if host defatiltinc sce oiereiee dete reple RIEF 9 22 I incremental development 00005 14 incremental development evil 14 incremental development not evil 15 TRC channel Dee robe i ainiai DR da
6. eee e 8 4 Between the parens 10 4 1 Activating Geiser sssssssssssesssese eene 10 4 2 The source and the REPL 0 cece eee eee eee 11 4 3 Documentation helpers 0 0c cece eee eee eee ens 12 4 4 To eval or not to eval 0 0 6 ccc cece cece eee nen eees 14 4 5 To err perchance to debug ccc cece cece e eee rn 15 4 6 Jumping around 0 cee emn 16 4 7 Geiser writes for you ssesesssssseee en 16 5 Cheat sheet i oooo ooo oor v eR ERVAS REX 18 5 L Scheme butergs iu i iiia xe REL kbpesie Re ae RR ed 18 5 2 REPL iR RE ERU RR ERA EDO RSEREE ERR A RR URN 19 5 3 Documentation browser esses 19 6 No hacker is an island 21 Chapter 1 Introduction 1 1 Introduction Geiser is an Emacs environment to hack and have fun in Scheme If that s enough for you see Chapter 2 Installation page 3 to get it running and Chapter 3 The REPL page 5 for the fun part 1 1 Modus operandi As already mentioned Geiser relies on a running Scheme process to obtain the information it makes accessible to the programmer There s little effort on the Elisp side to understand say the module system used by the Scheme implementation at hand instead a generic interface between the two worlds is defined and each supported Scheme includes a library implementing that API together with some wee shims in Elisp allowing the reuse of the Emacs
7. implementation for you according to the algorithm described below How Geiser associates a REPL to your Scheme buffer To determine what Scheme implementation corresponds to a given source file Geiser uses the following algorithm 1 If the file local variable geiser scheme implementation is defined its value is used A common way of setting buffer local variables is to put them in a comment near the beginning of the file surrounded by marks as in geiser scheme implementation guile 2 f you ve customized geiser active implementations so that it s a single element list that element is used as the chosen implementation 3 The contents of the file is scanned for hints on its associated implementation For instance files that contain a lang directive will be considered Racket source code while those with a define module form in them will be assigned to a Guile REPL 4 The current buffers file name is checked against the rules given in geiser implementations alist and the first match is applied You can provide your own rules by customizing this variable as explained below 5 If we haven t been lucky this far and you have customized geiser default implementation to the name of a supported implementation we ll follow your lead 6 See That s the problem of being a smart aleck one s always outsmarted by people around At this point geiser mode will humbly give up and ask you to explicitly choose the Sc
8. rule will take precedence over the default ones Switching between source files and the REPL Once you have a working geiser mode you can switch from Scheme source buffers to the REPL or C c C z Those shortcuts map to the interactive command switch to geiser If you use a numeric prefix as in C u C c C z besides being teleported to the REPL the latter will switch to the namespace of the Scheme source file as if you had used C c C m in the REPL with the source file s module as argument cf discussion in Section 3 3 Switching context page 6 This command is also bound to C c C a Once you re in the REPL the same C c C z shortcut will bring you back to the buffer you jumped from provided you don t kill the Scheme process in between This is why the command is called switch to geiser instead of switch to repl and what makes it really handy if you ask me If for some reason you re not happy with the Scheme implementation that Geiser has assigned to your file you can change it with C c C s and you probably should take a look at the previous subsection to make sure that Geiser doesn t get confused again A note about context As explained before see Section 1 1 Modus operandi page 1 all Geiser activities take place in the context of the current namespace which for Scheme buffers corresponds to the module that the Scheme implementation associates to the source file at hand for instance in Racket there s a one to one corre
9. side framework which constitutes the bulk of the code While being as generic as possible the Scheme Elisp interface makes some assumptions about the capabilities and interaction mode of the corresponding REPL In particular Geiser expects the latter to support namespaces in the form of a module system and to provide a well defined way to establish the REPL s current namespace or module as well as the current file s module or namespace Thus all evaluations performed by Geiser either in the REPL or in a source code buffer happen in the context of the current namespace Every time you switch to a different file you re switching namespaces automatically at the REPL you must request the switch explicitly usually just using means provided by the Scheme implementation itself If your favourite Scheme supports the above modus operandi it has all that s needed for a bare bones Geiser mode But Geiser can and will use any metadata available proce dure arities and argument lists to display interactive help documentation strings location information to jump to definitions export lists to provide completion and so on and so forth Although this is not an all or none proposition Geiser can operate with just part of that functionality available i ve initially concentrated in supporting those Schemes with the richest to my knowledge introspection capabilities namely Guile and Racket 1 2 Showing off When working with a ful
10. there in your menu bar No i don t normally use menus either but they can come in handy until you ve memorized Geiser s commands as a learning device And yes i usually run Emacs inside a terminal but one can always use La Carte to access the menus in a convenient enough fashion Or just press C h m and be done with that Among the commands at your disposal we find the familiar input navigation keys with a couple twists By default M p and M n are bound to matching items in your input history That is they ll find the previous or next sexp that starts with the current input prefix defined as the text between the end of the prompt and your current position a k a point in the buffer For going up and down the list unconditionally just use C c M p and C c M n In addition navigation is sexp based rather than line based There are also a few commands to twiddle with the Scheme process C c C q will gently ask it to quit while C u C c C q will mercilessly kill the process but not before stowing your history in the file system Unless you re using a remote REPL that is in which case both commands will just sever the connection and leave the remote process alone If worse comes to worst and the process is dead C c C z will restart it However the same shortcut issued when the REPL is alive will bring you back to the buffer you came from as explained in Section 4 2 The source and the REPL page 11 The remaining commands are mea
11. will notice their presence and react accordingly Chapter 3 The REPL 5 3 The REPL If you ve followed the instructions in Section 2 2 Setting it up page 3 your Emacs is now ready to start playing Otherwise i ll wait for you when you re ready just come back here and proceed to the following sections 3 1 Starting the REPL To start a Scheme REPL meaning a Scheme process offering you a Read Eval Print Loop Geiser provides the generic interactive command run geiser If you invoke it via as is customary in Emacs M x run geiser you l be saluted by a prompt asking which one of the supported implementations you want to launch yes you can stop the asking see Section 3 6 Customization and tips page 8 Tabbing for completion will offer you as of this writing guile and racket Just choose your poison and a new REPL buffer will pop up by default the REPL will appear in a new window if that annoys you just set geiser repl use other window to nil and the current window will be used If all went according to plan you ll be facing an implementation dependent banner followed by an interactive prompt Going according to plan includes having the executable of the Scheme you chose in your path If that s not the case you can tell Emacs where it is as described in Section 3 6 Customization and tips page 8 Returning to our REPL the first thing to notice is that the funny prompt is telling you your current module its name
12. Geiser User Manual Emacs and Scheme talk to each other Jose Antonio Ortega Ruiz This manual documents Geiser an Emacs environment to hack in Scheme Copyright c 2010 2011 Jose Antonio Ortega Ruiz Permission is granted to copy distribute and or modify this document under the terms of the GNU Free Documentation License Version 1 3 or any later version published by the Free Software Foundation with no Invariant Sections no Front Cover Texts and no Back Cover Texts A copy of the license is available from the Free Software Foundation Web site at http www gnu org licenses fdl html The document was typeset with GNU Texinfo Table of Contents 1 Introduction tape e ORE Kn o dra bd aca 1 Ll Modusoperandi erre RH ERR PREISE need 1 1 2 Showing Off rtesus eepbreentqpE REED beer e RR RR s 1 2 InstallabTOD cun Cerca oon ra dr coe 3 2 Mustneeds iioc epo ud db dU ekRER AG dara E REC HN ERR 3 2 2 Setting it Up ads cese Vestae eere Lace De a ea toa P de dn 3 2 9 Friends sso sers Sidney eho SEX NCMO wee nae CR prd 4 S HO6IEDLD xsue 202m EUR EDELSM NU dd 5 3 1 Starting the REPL sssseseseseeess re 5 9 2 First 8ldSucesske e monere beeebEE EE ERE qda ausser nee a eee 6 3 3 Switching context ssssesseeseseeese emen 6 3 4 Completion and error handling ssseeeeeeeeeeeeese Yi 3 5 Autodoc and friends lssssssssssesssssssses sese di 3 6 Customization and tips 0 cece
13. a Scheme buffer Geiser also instructs Emacs to consider files with the extension rkt part of the family so that in principle there s nothing you need to do to ensure that Geiser s extensions will be available out of the box when you start editing Scheme code Indications that everything is working according to plan include the Geiser minor mode indicator in your mode line and the appearance of a new entry for Geiser in the menu bar If moreover the mode line indicator is the name of a Scheme implementation you re indeed in a perfect world otherwise don t despair and keep on reading i ll tell you how to fix that in a moment The menu provides a good synopsis of everything Geiser brings to the party including those keyboard shortcuts we Emacsers love If you re seeing the name of your favourite Scheme implementation in the mode line have a running REPL and are comfortable with Emacs you can stop reading now and instead discover Geiser s joys by yourself I ve tried to make Geiser as self documenting as any self respecting Emacs package should be If you follow this route make sure to take a look at Geiser s customization buffers M x customize group RET geiser there s lot of fine tuning available there You might also want to take a glance at the tables in see Chapter 5 Cheat sheet page 18 Since geiser mode is a minor mode you can toggle it with M x geiser mode and control its activation in hooks with the functions
14. ame and that value When the argument is a keyword argument its name has as a prefix Chapter 3 The REPL 8 If that s not enough documentation for you C c C d d will open a separate documen tation buffer with help on the symbol at point This buffer will contain implementation specific information about the identifier e g its docstring for Guile or its contract if any for Racket and a handy button to open the corresponding manual entry for the symbol which will open an HTML page for Racket or the texinfo manual for Guile Geiser can also produce for you a list classified by kind of the identifiers exported by a given module all you need to do is press C c C d m and type or complete the desired module s name The list of exported bindings is shown again in a buffer belonging to Geiser s documen tation browser where you have at your disposal a bunch of navigation commands listed in Section 5 3 Documentation browser page 19 We ll have a bit more to say about the documentation browser in Section 4 3 Documen tation helpers page 12 If that s still not enough Geiser can jump via M to the symbol s definition A buffer with the corresponding file will pop up with its point resting upon the identifier s defining form When you re done inspecting M will bring you back to where you were As we will see these commands are also available in Scheme buffers M also works for modules if your point is on an una
15. ardo Cavazos contagious enthusiasm has helped in many ways to keep Geiser alive and he s become its best evangelist in R6RS circles Eli Barzilay took the time to play with an early alpha and made many valuable sugges tions besides answering all my how do you in PLT questions Matthew Flatt Robby Findler and the rest of the PLT team did not only answer my inquiries but provided almost instant fixes to the few issues i found Thanks also to the PLT and Guile communities for showing me that Geiser was not only possible but a pleasure to hack on And to the Slime hackers who led the way Joining the fun e For questions praise critique and anything else Geiser do not hesitate to drop an email to our list 0 geiser users nongnu org no subscription required Check the list page for more information or browse the archives The list is also accessible via Gmane as gmane lisp scheme geiser e You can submit bug reports either to the mailing list or to our bug tracker over at Savannah e If you only need to hear about Geiser on new releases the News page and its Atom feed are probably what you re looking for e The Freenode IRC channel geiser is the Geiserati s meeting point in cyberspace Index Index A autodoc customized 0 cece eee eee eee 13 autodoc explained 0 0 e eee eee eee 13 autodoc for variables sssssseeessse 13 autodoc disabling 00 008 9
16. defining it That s not a limitation imposed by Geiser but a consequence of how macros work in Scheme and other Lisps There s also the risk that you lose track of what s actually defined and what s not during a given session But in my opinion those Chapter 4 Between the parens 15 are limitations we lispers are aware of and they don t force us to throw the baby with the bathwater and ditch incremental evaluation Some people disagree if you happen to find their arguments convincing you don t have to throw away Geiser together with the baby M x geiser restart repl will let you restart the REPL as many times as you see fit For all of you bearded old lispers still with me here are some of the commands performing incremental evaluation in Geiser geiser eval last sexp bound to C x C e will eval the s expression just before point geiser eval definition bound to C M x finds the topmost definition containing point and sends it for evaluation The variant geiser eval definition and go C c M e works in the same way but it also teleports you to REPL after the evaluation geiser eval region bound to C c C r evals the current region Again there s an and go version available geiser eval region and go bound to C c M r For all the commands above the result of the evaluation is displayed in the minibuffer unless it causes a Scheme side error see Section 4 5 To err perchance to debug page 15 At the risk of repeating mys
17. doc s noise geiser repl autodoc p is the customization variable for you set it to nil and autodoc will be disabled by default in new REPLs You can always bring the fairies back on a per REPL basis using C c C d C a Remote connections When using connect to guile connect to racket or geiser connect you ll be prompted for a host and a port defaulting to localhost and 37146 You can change those defaults customizing geiser repl default host and geiser repl default port respectively Chapter 4 Between the parens 10 4 Between the parens A good REPL is a must but just about half the story of a good Scheme hacking environment Well perhaps a bit more than a half but at any rate one surely needs also a pleasant way of editing source code Don t pay attention to naysayers Emacs comes with an excellent editor included for about any language on Earth and just the best one when that language is sexpy especially if you use Paredit Geiser s support for writing Scheme code adds to Emacs scheme mode rather than supplanting it and it does so by means of a minor mode unimaginatively dubbed geiser mode that defines a bunch of new commands to try and with the help of the same Scheme process giving you the REPL make those Scheme buffers come to life 4 1 Activating Geiser With Geiser installed following any of the procedures described in Section 2 2 Setting it up page 3 Emacs will automatically activate geiser mode when opening
18. elf i ll remind you that all these evaluations will take place in the namespace of the module corresponding to the Scheme file from which you re sending your code which in general will be different from the REPL s current module And if all goes according to plan re defined variables and procedures should be immediately visible inside and if exported outside their module Besides evaluating expressions definitions and regions you can also macro expand them The corresponding key bindings start with the prefix C c C m and end respectively with C e C x and C r The result of the macro expansion always appears in a pop up buffer 4 5 To err perchance to debug When an error occurs during evaluation it will be reported according to the capabilities of the underlying Scheme REPL In Racket you ll be presented with a backtrace in a new buffer where file paths locating the origin of the error are click able you can navigate them using the TAB key and use RET or the mouse to jump to the offending spot or invoke Emacs stock commands next error and previous error bound to M g n and M g p by default The Racket backtrace also highlights the exception type making it click able Following the link will open the documentation corresponding to said exception type Both the error and exception link faces are customizable geiser font lock error link and geiser font lock doc link On the other hand Guile s reaction to evaluation erro
19. er and that there s no load file to be seen this time There are some ways of fine tuning this process mainly by providing additional arguments in the call to configure you ll find those gory details in the file called INSTALL right at the root of the source tree The installation will also take care of placing this manual in Info format where Emacs can find it so you can continue to learn about Geiser inside its natural habitat See you there and into the next chapter 2 3 Friends Although Geiser does not need them it plays well with and is enhanced by the following Emacs packages e Paredit Regardless of whether you use Geiser or not you shouldn t be coding in any Lisp dialect without the aid of Taylor Campbell s structured editing mode e Company Nikolaj Schumacher s company mode provides a generic front end for com pletion engines such as Geiser s Very nice if you like that kind of thing judge by yourself with the help of this screencast e Quack You can still use the many goodies provided by Neil van Dyke s quack mode since most of them are not yet available in Geiser The only caveat might be a conflict between Quack s and Geiser s default key bindings which i m sure you ll man age to tackle just fine It s also probably a good idea to require quack after loading geiser el or requiring a compiled version You just need to install and setup them as usual for every package s definition of usual Geiser
20. f buttons giving you access to further documentation First you ll see a button named source pressing it you ll jump to the symbol s definition The second button dubbed manual will open the Scheme implementation s manual page for the symbol at hand For Racket that will open your web browser displaying the corresponding reference s page using Emacs browser url command while in Guile a lookup will be performed in the texinfo manual You can also jump directly to the manual page for the symbol at point with the command geiser doc look up manual bound to C c C d i A list of all navigation commands in the documentation browser is available in Section 5 3 Documentation browser page 19 4 4 To eval or not to eval One of Geiser s main goals is to facilitate incremental development You might have noticed that i ve made a big fuss of Geiser s ability to recognize context by being aware of the namespace where its operations happen That awareness is especially important when evaluating code in your scheme buffers using the commands described below They allow you to send code to the running Scheme with a granularity ranging from whole files to single s expressions That code will be evaluated in the module associated with the file you re editing allowing you to redefine values and procedures to your heart s and other modules content Macros are of course another kettle of fish one needs to re evaluate uses of a macro after re
21. heme implementation As you can see in the list above there are several ways to influence Geiser s guess ing by means of customizable variables The most direct and most impoverishing is probably limiting the active implementations to a single one while customizing geiser implementations alist is the most flexible and unsurprisingly also the most complex Here s the default value for the latter variable C Gregexp scm guile regexp ss racket regexp rkt racket which describes the simple heuristic that files with scm as extension are by default as sociated to a Guile REPL while those ending in ss or rkt correspond to Racket s implementation with the caveat that these rules are applied only if the previous heuristics Chapter 4 Between the parens 12 have failed to detect the correct implementation and that they ll match only if the corre sponding implementation is active You can add rules to geiser implementations alist or replace all of them by customizing it Besides regular expressions you can also use a directory name for instance the following snippet eval after load geiser impl add to list geiser implementations alist dir home jao prj frob guile will add a new rule that says that any file inside my home jao prj frob directory or recursively any of its children is to be assigned to Guile Since rules are first matched first served this new
22. is the part just after the sign in Guile that means guile user while Racket s top namespace doesn t have a name cf discussion in Section 3 3 Switching context page 6 Other than that this is pretty much equivalent to having a command line interpreter in a terminal with a bunch of add ons that we ll be reviewing below You can start typing sexps right there Geiser will only dispatch them for evaluation when they re complete and will indent new lines properly until then It will also keep track of your input maintaining a history file that will be reloaded whenever you restart the REPL Connecting to an external Scheme There s an alternative way of starting a Geiser REPL you can connect to an external Scheme process provided it s running a REPL server at some known port How to make that happen depends on the Scheme implementation If you use Guile you just need to start your Guile process possibly outside Emacs passing to it the flag listen This flag accepts an optional port as argument as in listen 1969 if you don t want to use the default In Racket you have to use the REPL server that comes with Geiser To that end put Geiser s Racket scheme directory in Racket s collection search path and invoke start geiser a procedure in the module geiser server somewhere in your program passing it the desired port This procedure will start the REPL server in a separate thread For an example of how to do that
23. l completion won t work if you have disabled it globally in your Emacs configuration if you don t know what i m talking about never mind Geiser s partial completion will work for you out of the box If you find the M modifier annoying you always have the option to activate geiser smart tab mode which will make the TAB key double duty as the regular Emacs indentation command when the cursor is not near a symbol and Geiser s completion function If you want this smarty pants mode always on in Scheme buffers customize geiser mode smart tab p to t Geiser also knows how to complete module names if no completion for the prefix at point is found among the currently visible bindings it will try to find a module name that matches it You can also request explicitly completion only over module names using M that s a backtick Chapter 4 Between the parens 17 Besides completion there s also this little command geiser squarify which will toggle the delimiters of the innermost list around point between round and square brackets It is bound to C c C e With a numeric prefix as in say M 2 C c C e it will perform that many toggles forward for positive values and backward for negative ones Chapter 5 Cheat sheet 5 Cheat sheet 18 In the tables below triple chords always accept a variant with the third key not modified by Control e g geiser autodoc show is bound both to C c C d C s and C c C d s 5 1 Scheme buffers
24. lete module name at point Ask for a directory and add to Scheme load path Prompt history matching current prefix Previous next prompt inputs Set current module Import module into current namespace See documentation for symbol at point See documentation for module Toggle autodoc mode Description Chapter 5 Cheat sheet TAB n S TAB p For Ds ON forward button backward button geiser doc next section geiser doc previous section geiser doc next geiser doc previous geiser doc kill page geiser doc refresh geiser doc clean history geiser doc edit symbol at point geiser doc switch to repl View quit 20 Next link Previous link Next section Previous section Next page Previous page Kill current page and go to previ ous or next Refresh page Clear browsing history Edit identifier at point Switch to REPL Bury buffer Chapter 6 No hacker is an island 21 6 No hacker is an island Andy Wingo Geiser s first user has been a continuous source of encouragement and sug gestions and keeps improving Guile and heeding my feature requests The nice thing about collaborating with Andreas Rottmann over all these years is that he will not only make your project better with insightful comments and prodding he ll send you patches galore too Ludovic Courts geiser s citizen no 1 joined the fun after a while and has since then been a continuous source of encouragement ideas and bug reports Edu
25. ly conniving Scheme Geiser can offer the following functionality e Form evaluation in the context of the current file s module e Macro expansion e File module loading and or compilation e Namespace aware identifier completion including local bindings names visible in the current module and module names e Autodoc the echo area shows information about the signature of the procedure macro around point automatically e Jump to definition of identifier at point e Access to documentation including docstrings when the implementation provides it e Listings of identifiers exported by a given module e Listings of callers callees of procedures Chapter 1 Introduction 2 e Rudimentary support for debugging when the REPL provides a debugger and error navigation e Support for multiple simultaneous REPLs In the following pages il try to explain what these features actually are i m just swanking here and how to use them for your profit But before that let s see how to install Geiser Chapter 2 Installation 3 2 Installation 2 1 Must needs If Geiser came with any guarantees you d break all of them by not using GNU Emacs 23 2 or better i regularly use it with a recent Emacs snapshot and at least one of the supported Schemes namely e Racket 5 0 1 or better e Guile 2 0 or better Since Geiser supports multiple REPLs having both of them will just add to the fun Downloading Geiser You ll also need Gei
26. mbiguous module name the file where it s defined will be opened for you 3 6 Customization and tips The looks and ways of the REPL can be fine tuned via a bunch of customization variables You can see and modify them all in the corresponding customization group by using the menu entry or the good old M x customize group geiser repl or by setting them in your Emacs initialisation files as a rule all knobs in Geiser are tunable this way you don t need to use customization buffers if you don t like them I m documenting below a proper subset of those settings together with some related tips Choosing a Scheme implementation Instead of using the generic run geiser command you can start directly your Scheme of choice via run racket or run guile In addition the variable geiser active implementations contains a list of those Schemes Geiser should be aware of T hus if you happen to be say a racketeer not to be beguiled by other schemes you can tell Geiser to forget about the richness of the Scheme ecosystem with something like setq geiser active implementations racket in your initialisation files When starting a new REPL Geiser assumes by default that the corresponding Scheme binary is in your path If that s not the case the variables to tweak are geiser guile binary and geiser racket binary which should be set to a string with the full path to the requisite binary You can also specify a couple more initialisation pa
27. nctions defined using case lambda or some syntax rules macros for which Geiser has often the black magic necessary to retrieve their actual arities In those cases autodoc shows all known signatures using the above rules for each one separated by a vertical bar 1 As you have already noticed the whole autodoc message is enclosed in parentheses After all we re talking about Scheme here Finally life is much easier when your cursor is on a symbol corresponding to a plain variable you ll see in the echo area its name preceded by the module where it s defined and followed by its value with an intervening arrow for greater effect This time there are no enclosing parentheses i hope you see the logic in my madness You can change the way Geiser displays the module identifier combo by customizing geiser autodoc identifier format For example if you wanted a tilde surrounded by spaces instead of a colon as a separator you would write something like setq geiser autodoc identifier format 4s 4s in your Emacs initialisation files There s also a face geiser font lock autodoc identifier that you can customize for instance with M x customize face to change the appearance of the text And another one geiser font lock autodoc current arg that controls how the current argument position is highlighted Chapter 4 Between the parens 14 Other documentation commands Sometimes autodoc won t provide enough information for
28. nke 21 jump at the REPL eeeeesesesese 8 jumping customized 0008 16 jumping in scheme buffers 16 M mailing IiSt ane ore ectese teens vesan aslin 21 manual autodoc eee eee eee eee 13 module Exports nce seca meme rene 8 modus operandi eee e eee eee eee eee il N news feed cie wince Bat IU came PUN E PES 21 opening manual pages 2 000 14 P PALER cee osc sel enger me rcm n EAR Hare anes 4 partial completion eee eee eee 16 peace and quiet essere sea mph rend 9 plulosophiy aceusseesechbenubDreseve gut naD a 14 PLTCOLLECTS sees 8 port default seco seagieesdecg E Rp RR PERAE 9 GUIK peas S E nE ieee vad ene Raster asd oe baat agian 4 Racket s REPL server eee eee eee 5 POCUTSION ue ied esctelc ent htneee heehee 22 remote connections 0 eee eee eee eee ee 6 remote REPL 00 cee eee eee eee ee eee 5 REPDeecrospererrann ettan rak EATE enses 5 REPL commands 0 0 eee eee eee eee 6 REPL customization 02 cece eee eee 8 Index scheme executable path 00 eee ee 8 scheme file extensions 0 0 eee ee ee 10 scheme implementation choosing S dd scheme init file 0 0 eee eee ee eee eee 8 scheme load path 00 eee eee eee eee 8 Smart tabs oue ue s neat n EA meses PUES 16 supported versio
29. ns esee 3 SWOMKING ceeueehtes ti keea ienai Ue aas 1 switching schemes 0 0000000 12 switching to module 00028 5 12 switching to REPL cesse 12 switching to source 12 23 T Dial 21 to err is schemey eee e eee ee eee 15 U use the source Luke 0 eee eee eee 3 useless wretch 0 00 ee cece eee teen ee ee 10 V versions supported 00 cece eee eee eee 3
30. nt and if that fails a module with that name if the latter succeeds the file where the module is defined will pop up Sometimes the underlying Scheme will tell Geiser only the file where the symbol is defined but Geiser will use some heuristics read regular expressions to locate the exact line and bring you there Thus if you find Geiser systematically missing your definitions send a message to the mailing list and we ll try to make the algorithm smarter You can control how the destination buffer pops up by setting geiser edit symbol method to either nil to open the file in the current window window other window in the same frame or frame in a new frame 4 7 Geiser writes for you No self respecting programming mode would be complete without completion In geiser mode identifier completion is bound to M TAB and will offer all visible identifiers starting with the prefix before point Visible here means all symbols imported or defined in the current namespace plus locally bound ones E g if you re at the end of the following partial expression let default 42 frob def and press M TAB one of the possible completions will be default After obtaining the list of completions from the running Scheme Geiser uses the standard Emacs completion machinery to display them That means among other things that partial completion is available just try to complete d s or w o t s to see why this is a good thing Partia
31. ou prefer that it be inactive by default e g because you re connecting to a really remote scheme and want to minimize network exchanges just set geiser mode autodoc p to nil in your customization files Even when autodoc mode is off you can use geiser autodoc show bound by default to C c C d s to show the autodoc string for the symbol at point The way autodoc displays information deserves some explanation It will first show the name of the module where the identifier at hand is defined followed by a colon and the identifier itself If the latter corresponds to a procedure or macro it will be followed by a list of argument names starting with the ones that are required Then there comes a list of optional arguments if any enclosed in parentheses When an optional argument has a default value or a form defining its default value autodoc will display it after the argument name When the optional arguments are keywords their names are prefixed with ie their names are keywords An ellipsis serves as a marker of an indeterminate number of parameters as is the case with rest arguments or when autodoc cannot fathom the exact number of arguments this is often the case with macros defined using syntax case Another way in which autodoc displays its ignorance is by using an underscore to display parameters whose name is beyond its powers It can also be the case that a function or macro has more than one signature e g fu
32. rameters For Guile geiser guile load path is a list of paths to add to its load path when it s started while geiser guile init file is the path to an initialisation file to be loaded on start up The equivalent variables for Racket are geiser racket collects and geiser racket init file Chapter 3 The REPL 9 Note however that specifying geiser guile init file is not equivalent to changing Guile s init file guile because the former is loaded using the 1 flag together with q to disable loading the second But there are subtle differences in the way Guile loads the init file vs how it loads a file specifed via the 1 flag If what you want is just loading guile leave geiser guile init file alone and set geiser guile load init file p to t instead History By default Geiser won t record duplicates in your input history If you prefer it did just set geiser repl history no dups p to nil History entries are persistent across REPL sessions they re saved in implementation specific files whose location is controlled by the variable geiser repl history filename For example my Geiser configuration includes the following line setq geiser repl history filename emacs d geiser history which makes the files geiser history guile and geiser history racket to live inside my home s emacs d directory Autodoc If you happen to love peace and quiet and prefer to keep your REPL s echo area free from auto
33. rs is different it enters the de bugger in its REPL Accordingly the REPL buffer will pop up if your evaluation fails in a Guile file and the error message and backtrace will be displayed in there again click able and all But there you have the debugger at your disposal with the REPL s current module set to that of the offender and a host of special debugging commands that are described in Guile s fine documentation In addition Guile will sometimes report warnings for otherwise successful evaluations In those cases it won t enter the debugger and Geiser will report the warnings in a debug buffer as it does for Racket You can control how picky Guile is reporting warnings by customizing the variable geiser guile warning level whose detailed docstring which Chapter 4 Between the parens 16 see using e g C h v allows me to offer no further explanation here The customization group geiser guile is also worth a glance for a couple of options to fine tune how Geiser interacts with Guile s debugger and more Same thing for racketeers and geiser racket 4 6 Jumping around This one feature is as sweet as it is easy to explain M geiser edit symbol at point will open the file where the identifier around point is defined and land your point on its definition To return to where you were press M geiser pop symbol stack This command works also for module names Geiser first tries to locate a definition for the identifier at poi
34. ser itself The latest release tarball can be found here while older versions are here Just download geiser 0 1 2 tar gz and untar it in a directory of your choice If you feel like living on the bleeding edge just grab Geiser from its Git repository over at Savannah either with the following incantation git clone git git sv gnu org geiser git or if you happen to live behind a firewall with the alternative git clone http git sv gnu org r geiser git You can also follow Geiser s development in one or three mirrors that are kept synchronized with the one at Savannah Either way you ll now be in possession of a copy of Geiser s libre code Pll follow you into its directory and the next section 2 2 Setting it up Geiser is ready to be used out of the box without much more ado For the sake of concrete ness let s assume you put its source in the directory lisp geiser All you need to do is to add the following line to your Emacs initialisation file be it emacs or any of its moral equivalents load file lisp geiser elisp geiser el or simply evaluate that form inside Emacs you wouldn t kill a friend just to start using Geiser would you That s it you re ready to go see Chapter 3 The REPL page 5 If you obtained the Geiser source tree from a release tarball you can even continue to read this fine manual inside Emacs by opening doc geiser info using C u C h i The manual is also available in
35. spondence between paths and modules while Guile relies on explicit define module forms in the source file Now that we have geiser mode happily alive in our Scheme buffers and communicating with the right REPL instance let us see what it can do for us besides jumping to and fro 4 3 Documentation helpers Autodoc redux The first thing you will notice by moving around Scheme source is that every now and then the echo area lights up with the same autodoc messages we know and love from our REPL forays This happens every time the Scheme process is able to recognise an identifier in the buffer and provide information either on its value for variables or on its arity and the name of its formal arguments for procedures and macros That information will only be available if the module the identifier belongs to has been loaded in the running Scheme image So it can be the case that at first no autodoc is shown for identifiers defined in Chapter 4 Between the parens 13 the file you re editing But as soon as you evaluate them either individually or collectively using any of the devices described in Section 4 4 To eval or not to eval page 14 their signatures will start appearing in the echo area Autodoc activation is controlled by a minor mode geiser autodoc which you can toggle with M x geiser autodoc mode or its associated keyboard shortcut C c C d a That A indicator in the mode line is telling you that autodoc is active If y
36. t as t you can always jump to an old error by moving to its line at the REPL and pressing RET When your cursor is away from the last prompt TAB will move to the next error in the buffer and you can use BACKTAB everywhere to go to the previous one 3 5 Autodoc and friends Oftentimes there s more you ll want to know about an identifier besides its name What module does it belong to Is it a procedure and if so what arguments does it take Geiser tries to help you answering those questions too Actually if you ve been playing with the REPL as you read you might have notice some frantic activity taking place in the echo area every now and then That was Geiser trying to be helpful while hopefully not being clippy or more concretely what i call for want of a better name its autodoc mode Whenever it s active did you notice that A in the mode line Geiser s gerbils will be scanning what you type and showing unless you silence them with C c C d C a information about the identifier nearest to point If that identifier corresponds to a variable visible in the current namespace you ll see the module it belongs to and its value For procedures and macros autodoc will display instead of their value the argument names or an underscore if Geiser cannot determine the name used in the definition Optional arguments are surrounded by parentheses When the optional argument has a default value it s represented by a list made up of its n
37. tier and deserve sections of their own 3 3 Switching context In tune with Geiser s modus operandi evaluations in the REPL take place in the namespace of the current module As noted above the REPL s prompt tells you the name of the current module To switch to a different one you can use the command switch to geiser module bound to C c C m You ll notice that Geiser simply uses a couple of meta commands provided by the Scheme REPL the stock m in Guile and the geiser defined enter in Racket and that it doesn t even try to hide that fact That means that you can freely use said native ways directly at the REPL and Geiser will be happy to oblige In Racket enter works like Racket s standard enter form but you can also provide a path string as its argument e g enter tmp foo rkt is equivalent to enter file tmp foo rkt Like enter enter accepts also module names as in say enter geiser main As mentioned Guile s m is used as is Chapter 3 The REPL n Once you enter a new module only those bindings visible in its namespace will be available to your evaluations All Schemes supported by Geiser provide a way to import new modules in the current namespace Again there s a Geiser command geiser repl import module to invoke such functionality bound this time to C c C i And again you ll see Geiser just introducing the native incantation for you and you re free to use such incantations by hand whenever yo
38. turn on geiser mode and turn off geiser mode If for some reason i cannot fathom you prefer geiser mode not to be active by default customizing geiser mode auto p to nil will do the trick And if you happen to use a funky extension for your Scheme files that is not recognised as such by Emacs just tell her about it with add to list auto mode alist funky extension scheme mode y Now geiser mode is just a useless wretch unless there s a running Scheme process backing it up Meaning that virtually all the commands it provides require a REPL up and running preferably corresponding to the correct Scheme implementation In the following section we ll see how to make sure that that s actually the case Chapter 4 Between the parens 11 4 2 The source and the REPL As i ve already mentioned a couple of times geiser mode needs a running REPL to be operative Thus a common usage pattern will be for you to first call run geiser or one of its variants e g run guile and then open some Scheme files but there s nothing wrong in first opening a couple Scheme buffers and then starting the REPL you can even find it more convenient since pressing C c C z in a Scheme buffer will start the REPL for you Since Geiser supports more than one Scheme implementation though there s the problem of knowing which of them is to be associated with each Scheme source file Serviceable as it is geiser mode will try to guess the correct
39. u want One convenience provided by these two Geiser commands is that completion is available when introducing the new module name using the TAB key Pressing it at the command s prompt will offer you a prefix aware list of available module names Which brings me to the next group of REPL commands 3 4 Completion and error handling We ve already seen Geiser completion of module names in action at the minibuffer You won t be surprised to know that it s also available at the REPL buffer itself There you can use either C or M to complete module names and TAB or M TAB to complete identifiers Geiser will know what identifiers are bound in the current module and show you a list of those starting with the prefix at point Needless to say this is not a static list and it will grow as you define or import new bindings in the namespace at hand If no completion is found TAB will try to complete the prefix after point as a module name REPL buffers use Emacs compilation mode to highlight errors reported by the Scheme interpreter and you can use the next error command M g n to jump to their location By default every time you enter a new expression for evaluation old error messages are forgotten so that M g n will always jump to errors related to the last evaluation request if any If you prefer a not so forgetful REPL set the customization variable geiser repl forget old errors p to nil Note however that even when that variable is lef
40. you to understand what a func tion does In those cases you can ask Geiser to ask the running Scheme for further infor mation on a given identifier or module For symbols the incantation is M x geiser doc symbol at point or C c C d C d for short If the associated Scheme supports docstrings as for instance Guile does you ll be teleported to a new Emacs buffer displaying Geiser s documentation browser filled with information about the identifier including its docstring if any unfortunately that an implementation supports docstrings doesn t mean that they re used everywhere Pressing q in the documentation buffer will bring you back enlightened to where you were There s also a handful of other navigation commands available in that buffer which you can discover by means of its menu or via the good old C h m command And feel free to use the navigation buttons and hyperlinks that justify my calling this buffer a documentation browser For Racket which does not support docstrings out of the box this command will provide less information but the documentation browser will display the corresponding contract when it s available as well as some other tidbits for re exported identifiers You can also ask Geiser to display information about a module in the form of a list of its exported identifiers using C c C d C m exactly as you would do in Chapter 3 The REPL page 5 In both cases the documentation browser will show a couple o
Download Pdf Manuals
Related Search