fmt: an extensible code formatter for Racket
| (require fmt) | package: fmt |
This package provides a tool raco fmt to reformat Racket code.
The package uses pprint-compact, a very expressive pretty printer library, to compute the most optimal layout of the output code, and uses syntax-color/module-lexer to lex the input program.
The interface to allow users to extend formatting style is extremely unstable and is still a work in progress. For now, the only thing that is stable is the command raco fmt.
1 Requirements and Installation
Make sure Racket 8.0 or later is installed. Run raco pkg install fmt to install the formatter.
2 Running raco fmt
raco fmt ‹file.rkt› ... reads ‹file.rkt›s and displays the formatted programs to the standard output. If ‹file.rkt›s are not given, it accepts an input program from the standard input.
The raco fmt command accepts the following flags:
--width ‹width› —
set the page width limit to ‹width›, which must be either a natural number or +inf.0. The default value is 80. --max-blank-lines ‹n› —
set the maximum consecutive blank lines limit to ‹n›, which must be either a natural number or +inf.0. The default value is 1. --indent ‹n› —
set the indentation level for subsequent lines to ‹n›, which must be a natural number. The default value is 0. -i —
modify the input files in-place instead of outputting to standard output. This flag has no effect if raco fmt accepts the input from the standard input.
3 Examples
Given the file "example.rkt" shown on the left, running raco fmt --width 40 example.rkt would output the program on the right:
|
|
4 Unstable concepts
A formatter is a function that accepts a code fragment and returns a doc?. In principle, you can create your own formatter, but you need to understand many structures that are currently undocumented and unstable. (If you want to implement one, perhaps take a look at this file.)
A formatter map is a function that accepts either a string or #f, and returns either a formatter or #f. Conceptually, when the input is a string s, a formatter map should return a formatter that will format a form named s, and When the input is #f, the formatter map should return a formatter that will format function application. An exception is that the formatter map can also return #f, which means the formatter map wants to let other fallback formatter maps to handle formatting instead.
5 Unstable API
procedure
(program-format s [ #:formatter-map formatter-map #:width width #:max-blank-lines max-blank-lines #:indent indent]) → string? s : string? formatter-map : formatter-map/c = empty-formatter-map width : (or/c natural-number/c +inf.0) = (current-width)
max-blank-lines : (or/c natural-number/c +inf.0) = (current-max-blank-lines) indent : natural-number/c = (current-indent)
> (define s "(define (foo) (bar baz) food) (define-like (foo) (bar baz) food)") > (display (program-format s))
(define (foo)
(bar baz)
food)
(define-like (foo) (bar baz) food)
> (define (lib-define-formatter-map s) (cond [(and (string? s) (string-prefix? s "define-")) (standard-formatter-map "define")] [else #f]))
> (define (lib-bar-formatter-map s) (case s [("bar") (standard-formatter-map "cond")] [else #f])) > (display (program-format s #:formatter-map lib-define-formatter-map))
(define (foo)
(bar baz)
food)
(define-like (foo)
(bar baz)
food)
> (display (program-format s #:formatter-map lib-bar-formatter-map))
(define (foo)
(bar
baz)
food)
(define-like (foo)
(bar
baz)
food)
> (display (program-format s #:formatter-map (compose-formatter-map lib-define-formatter-map lib-bar-formatter-map)))
(define (foo)
(bar
baz)
food)
(define-like (foo)
(bar
baz)
food)
augment augment-final augride begin begin-for-syntax begin0 |
case case-lambda class cond define define-for-syntax |
define-match-expander define-simple-macro define-struct |
define-syntax define-syntax-class define-syntax-parameter |
define-syntax-parse-rule define-syntax-parser define-syntax-rule |
define-syntaxes define-values define-values-for-syntax |
define/augment define/augment-final define/augride |
define/overment define/override define/override-final |
define/private define/public define/public-final define/pubment |
export field for for* for*/and for*/async for*/first for*/fold |
for*/hash for*/hasheq for*/hasheqv for*/last for*/list |
for*/list/concurrent for*/or for*/vector for/and for/async |
for/first for/fold for/hash for/hasheq for/hasheqv for/last |
for/list for/list/concurrent for/or for/vector if import inherit |
init instantiate lambda let let* let*-values let-syntax |
let-syntaxes let-values letrec letrec-syntax letrec-syntaxes |
letrec-syntaxes+values letrec-values link match match* |
match-define match-define-values match-lambda match-lambda* |
match-lambda** match-let match-let* match-let*-values |
match-let-values match-letrec match-letrec-values mixin module |
module* module+ overment override override-final parameterize |
parameterize* pattern private provide public public-final |
pubment quasisyntax/loc rename require shared splicing-let |
splicing-let-syntax splicing-let-syntaxes splicing-let-values |
splicing-letrec splicing-letrec-syntax splicing-letrec-syntaxes |
splicing-letrec-syntaxes+values splicing-letrec-values |
splicing-parameterize splicing-syntax-parameterize struct |
syntax-case syntax-parameterize syntax-parse syntax-parser |
syntax-rules syntax/loc unless when with-handlers with-handlers* |
with-syntax with-syntax* λ |
For other forms, it uses the function application style.
procedure
(compose-formatter-map f ...) → formatter-map/c
f : formatter-map/c
6 Parameters
parameter
(current-width) → (or/c +inf.0 natural-number/c)
(current-width width) → void? width : (or/c +inf.0 natural-number/c)
= 102
parameter
(current-max-blank-lines) → (or/c +inf.0 natural-number/c)
(current-max-blank-lines max-blank-lines) → void? max-blank-lines : (or/c +inf.0 natural-number/c)
= 1
parameter
(current-indent indent) → void? indent : natural-number/c
= 0
7 Related work
DrRacket (by the Racket team) is a Racket editor. It has an indenter which can re-indent code, but cannot in general re-format code. Users can add custom keywords to the four predefined keyword categories, but cannot define a new category (without a plug-in).
raco-format (by Dan Anderson) is a command-line tool that invokes DrRacket’s indenter.
Racket Mode (by Greg Hendershott) is a mode in Emacs for editing Racket code. Similar to DrRacket, it has an indenter. Compared to DrRacket, Racket Mode is more customizable on one axis (more keyword categories) but less customizable on another axis (must map each keyword one-by-one)
racket/pretty (by the Racket team) is a library for pretty printing an S-expression value. It does not support comments, is less expressive and less optimal than fmt.
pprint (by Dave Herman and Asumu Takikawa) is a library for pretty printing an arbitrary document. It is based on Wadler’s pretty printer, which is less expressive and less optimal than pprint-compact (but has better performance).
racket-pretty-printer (by 为世人降下祝福) is a Racket formatter written in Haskell. It uses Wadler’s pretty printer, so it has the limitations as described in the above item.
racket-formatting (by Alex Owens and Shu-Hung You) is a Racket formatter that attaches formatting information to syntax object properties. It does not attempt to pick the most optimal layout to stay within the column limit, and does not support comments.
racket-format (by Russell Wallace) is a Racket formatter written manually. It uses a greedy algorithm to decide which layout to pick, which is not optimal. It supports line-comments and the normalization features (such as sorting the list of provided elements), but doesn’t preserve parenthesis shape.