Ractionary is a set of tools for generating dictionaries for Racket language aware tool support. The generation is done based on information available through Racket’s own facilities, including: scribble/xref provided documentation cross-reference information; and DrRacket “blue boxes” data (see scribble/contract-render).
Currently the focus is on Emacs support. One of the generated dictionary file formats is just a plain list of words, whereas the others contain Emacs Lisp definitions.
The Ractionary source code repository is at
https://github.com/bldl/ractionary
The following files may currently be generated as shown in the included “Makefile”:
- “racket-mode” is suitable for use as a drop-in Emacs Auto Complete Mode dictionary, for example, without any specific Emacs configuration required. It is just a list of bare symbols (one per line) without any additional information, and could potentially be used for auto completion in other editors as well.
- “ractionary-words.el” is like the above, but it declares an Emacs Lisp variable
ractionary-dictionarywhose value is the list of strings constituting a Racket vocabulary. - “ractionary-words-help.el” is like the above, but its
ractionary-dictionary-with-helpvariable also includes a “Help” text for each symbol. For a given symbol there may be multiple possible definitions; these are ranked according to the “importance” of the Racket module providing it (as defined by “ranking.rkt”), and the highest ranked one is picked. For example,carinr5rsorsrfi/1probably should not be considered as important as thecarin Racket proper. - “ractionary-urls.el” associates API documentation URLs (for a local Racket installation) with symbols. Where the same symbol has multiple documented definitions, each of them will get its own URL. The generated URL table can hence be used either to implement an “I’m feeling lucky” search for the symbols in Racket, or a set of choices can be presented to the user.
The “emacs” directory contains an Emacs library for accessing Ractionary-generated data. Its contents include:
- ractionary-ivy: An Ivy-based command for incremental narrowing and selection of a Racket symbol for which to open documentation in a web browser. Also allows for searching for other topics in the Racket documentation index.
- ractionary-helm: A Helm-based command for incremental narrowing and selection of a Racket symbol for which to open documentation in a web browser.
To use any of the above features, add the “emacs” directory to your load-path, so that the features become loadable with require or other Emacs Lisp functions. The generated dictionaries must also be on your load-path to allow the features to load them.
The “examples” directory contains additional examples of using Ractionary-generated data in Emacs. The examples are not being actively maintained, and so they may require adjustments to work with the current version of Ractionary and other Emacs libraries. The contents of the directory include:
- ./examples/emacs-company-vanilla/company-ractionary.el: A basic Company mode backend that does nothing but offer completions from among symbols an a Ractionary-generated dictionary.
- ./examples/emacs-company-quickhelp/company-ractionary.el: A backend similar to the above, but adds help strings for possible display with Company quickhelp.
- ./examples/emacs-company-racket-mode/company-ractionary.el: Complements the above Company backend with another one, which wraps the symbol completion functionality of racket-mode, whose
racket-complete-at-pointfunction does completion in a dynamic and context sensitive manner. - ./examples/emacs-company-scribble/company-ractionary.el: This example adapts the earlier emacs-company-quickhelp backend for completion of @-expressions’ initial symbols. While scribble-mode comes built in with completion for common Scribble symbols, a more extensive dictionary might be worth having when editing Scribble documents that make heavy use of additional abstractions, or particularly in languages such as
at-expracket.
The emacs-company-racket-mode example is notable in that it illustrates it being possible to combine both a static dictionary for readily available context-insensitive completion, and more delicate and processing-intensive dynamic and contextual completion. That combination can further be complemented with Company’s own company-dabbrev-code backend, which provides generic-yet-contextual completion of non-comment symbols (e.g., those in the current buffer, or in same-mode buffers).
- “Dictionary-Enabled Racket Support for Emacs”: A blog post describing one way to set up Emacs to use the generated dictionary files for Auto Complete mode based symbol completion, and for quick opening of documentation for a symbol. This example is somewhat out of date with respect to the current version of Ractionary.