Rhombulary🔗

Tero Hasu

Rhombulary is primarily an Emacs Lisp package, but it does contain and rely on Racket code for determining what scribblings have been installed as documentation for the Racket that is running the code, and then also for extracting parts of that documentation in a textual “blue boxes” style, and writing out that data as Lisp for use within Emacs.

1 Command-Line Interface🔗

The rhombulary/rhombulary-cli module does not expose any Racket API, but rather it implements a command-line interface for the dictionary generator tool. It gets installed as the rhombulary program if the project is raco pkg installed, but doing that is entirely optional for the functioning of the Emacs package.

The rhombulary Emacs Lisp feature runs the "rhombulary-cli.rkt" file directly, and it therefore does not rely on the rhombulary program being installed. Furthermore the Emacs Lisp functionality only uses the --input-eval option when it calls "rhombulary-cli.rkt", with the other options existing for testing purposes only. In essence the Emacs Lisp feature just uses "rhombulary-cli.rkt" for evaluating its instructions against the rhombulary/rhombulary-api interface, and it expresses those instructions in Racket rather than encoding them as command-line arguments.

The path of the racket executable that is used for running "rhombulary-cli.rkt" from Emacs Lisp is determined by the rhombulary-racket-program variable of the rhombulary feature, which can be configured using the standard Emacs customization facility if the default setting does not correctly point to the desired Racket installation’s racket.

2 Application Programming Interface🔗

(require rhombulary/rhombulary-api)

package: rhombulary

The dictionary generation API consists of a number of parameters for configuring the generator and functions for running the generator to emit Emacs Lisp code.

parameter
(configuration-name) → string?
(configuration-name name) → void?
name : string?
= "generic"

A parameter that names the current generator configuration. Used in the naming of generated constants so that different name tables get different definitions. This parameter corresponds to the customizable Emacs variable rhombulary-configuration-name.

parameter
(ranked-language-families) → (listof string?)
(ranked-language-families lst) → void?
lst : (listof string?)
= '("*")

A parameter of specifying language families in decreasing order of priority when ranking directionary entries. As a special case the string "*" matches any language family name. Dictionary entries are generated only for words of the specified language families. This parameter corresponds to the customizable Emacs variable rhombulary-ranked-language-families.

parameter
(ranked-modules) → (listof string?)
(ranked-modules lst) → void?
lst : (listof string?)
= null

A parameter of module path prefix patterns to rank documentation for an identifier so that the most frequently referenced definition would come first. This parameter corresponds to the customizable Emacs variable rhombulary-ranked-modules.

parameter
(included-modules) → (listof string?)
(included-modules lst) → void?
lst : (listof string?)
= null

A parameter of module path prefix patterns for choosing the definitions to be included in the generated dictionary. This can be useful if one for example wants to have a dictionary for looking up Zuo definitions only, which are far fewer than those of Racket proper. This parameter corresponds to the customizable Emacs variable rhombulary-included-modules.

parameter
(excluded-modules) → (listof string?)
(excluded-modules lst) → void?
lst : (listof string?)
= null

A parameter of module path prefix patterns for choosing the definitions to be excluded from the generated dictionary. This parameter corresponds to the customizable Emacs variable rhombulary-excluded-modules.

parameter
(ranked-as-included-modules) → boolean?
(ranked-as-included-modules flag) → void?
flag : boolean?
= #f

A parameter indicating whether ranked-modules should also be included-modules. If this flag is true then only definitions from ranked-modules and any included-modules will be included in the generated dictionary. This parameter corresponds to the customizable Emacs variable rhombulary-ranked-as-included-modules.

parameter
(additional-words) → (listof (list/c string? string? string?))
(additional-words lst) → void?
lst : (listof (list/c string? string? string?))
= null

A parameter listing additional entries to include in the generator dictionary for words that are not otherwise documented. Each entry is represented as a tuple of three strings: (1) the word itself, (2) a description of its origin (e.g., a module path), and (3) a help text. The first line of the help text is the most significant, and some common strings for that line are "procedure" and "syntax". This parameter corresponds to the customizable Emacs variable rhombulary-additional-words.

parameter
(feature-name) → string?
(feature-name name) → void?
name : string?
= #f

A parameter for specifying the name of the Emacs Lisp feature name. There is no corresponding parameter on the Emacs Lisp side, and the value need not be specified. By default the feature name is derived from the path argument of any call to write-elisp-tables-to-file, and for display-elisp-tables no feature name is set by default.

parameter
(provide-feature?) → boolean?
(provide-feature? flag) → void?
flag : boolean?
= #f

A parameter for choosing whether to include a provide form for the generated Emacs Lisp feature (see feature-name). There is no corresponding parameter on the Emacs side, and the feature is generally not provided from the Lisp source files that Rhombulary generates and uses.

procedure
(display-elisp-tables [out]) → any
out : output-port? = (current-output-port)

Runs the generator to emit Emacs Lisp to the specified output port.

procedure
(write-elisp-tables-to-file path) → any
path : path-string?

Runs the generator to emit Emacs Lisp into a file of the specified path.