Racket Dictionary Generator
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
emacs
examples
.gitignore
LICENSE
Makefile
README.org
elisp.rkt
info.rkt
module-path.rkt
racket-blueboxes.rkt
ractionary-make-dict.rkt
ractionary-make-urls.rkt
ractionary.scrbl
ranking.rkt
root-modules.rkt
util.rkt
xref.rkt

README.org

Ractionary

Introduction

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.

Source Code

The Ractionary source code repository is at
https://github.com/bldl/ractionary

Generated Dictionaries

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-dictionary whose value is the list of strings constituting a Racket vocabulary.
  • “ractionary-words-help.el” is like the above, but its ractionary-dictionary-with-help variable 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, car in r5rs or srfi/1 probably should not be considered as important as the car in 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.

Emacs Library

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.

Examples of Dictionary Data Use in Emacs

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:

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).

See Also

  • “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.

Related Software