A low-friction linter for Lisp that finally allows your team members to use Parinfer.
Unlike full pretty-printers, it preserves as much of the original source as possible, only fixing confusing indentation and dangling close-parens. But it's still flexible, allowing any-space indentation within thresholds.
Adopt Parlinter to make your project Parinfer friendly!
- See concrete examples of Common Lint Results in Clojure.
- See the only Two Rules it follows.
- Try it out on your project then check
git diff -wto verify the minor changes.
Parlinter performs minimal source transformation in order to satisfy two rules:
Close-parens at the beginning of a line are moved to the end of its previous token:
;; bad
(foo (bar
) baz
) ^
^
;; fixed
(foo (bar)
baz) ^
^Conventional Formatters comply with Rule #1 for all cases except to allow close-parens after a comment. Parlinter does NOT make this exception.
Newlines must be indented to the right of their parent open-paren:
(foo (bar)
|
|
>
bar) ;; must be indented to the right of the point above: ✔️
^But they cannot extend too far right into another open-paren:
(foo (bar)
|
|
<
bar) ;; must be indented to the left of the point above: ✔️
^To fix, indentation is clamped to these points:
;; bad
(foo (bar)
baz)
;; fixed
(foo (bar)
baz) ;; <-- nudged to the right;; bad
(foo (bar)
baz)
;; fixed
(foo (bar)
baz) ;; <-- nudged to the leftConventional formatters comply with Rule #2 for all cases, except clojure.pprint and older versions of clojure-mode, which cause extra indentation of multi-arity function bodies.
npm install -g parlinter
or
yarn global add parlinter
Want to use as a plugin in your build environment instead? (e.g. lein, boot) Help wanted! Please create an issue.
$ parlinter
Usage: parlinter [opts] [filename|glob ...]
Available options:
--write Edit the file in-place. (Beware!)
--trim Remove lines that become empty after linting.
--list-different or -l Print filenames of files that are different from Parlinter formatting.
--stdin Read input from stdin.
--version or -v Print Parlinter version.
Glob patterns must be quoted.
Format all clojure files:
parlinter --trim --write "**/*.{clj,cljs,cljc,edn}"
Verify non-whitespace changes below for peace-of-mind: (AST not changed)
git diff -w
Check if all clojure files are properly formatted (non-zero exit code if not):
$ parlinter -l "**/*.{clj,cljs,cljc,edn}"
It takes ~0.5s to run against ~40k lines. (tested on the Clojure and ClojureScript project repos)
It was heavily optimized to allow Parinfer to run at 60hz on a ~3k line file while typing.
Syntactically compatible with Clojure, Racket, Scheme, and other Lisps that follow this syntax:
- delimiters
(,{,[ - strings
" - characters
\ - comments
;
Culturally compatible with standard Lisp styles*:
* some allow close-parens on their own line, but still allow them to be removed as Parlinter does
A collection of common changes performed by Parlinter on Clojure code—the Lisp I am most familiar with.
Sometimes function bodies for multi-arity functions are indented past the function params.
;; bad
(defn foo
"I have two arities."
([x]
(foo x 1))
([x y]
(+ x y)))
;; fixed
(defn foo
"I have two arities."
([x]
(foo x 1))
([x y]
(+ x y)))Since close-parens cannot be at the beginning of a line, they cannot come after comments.
;; bad
(-> 10
(foo 20)
(bar 30)
;; my comment
)
;; fixed
(-> 10
(foo 20)
(bar 30))
;; my commentIndentation of lines inside multi-line strings is significant, so it is not modified:
;; bad
(foo (bar
"Hello
world"))
;; fixed
(foo (bar
"Hello
world")) ;; <-- not nudgedFunction bodies are sometimes indented to its grandparent form rather than its parent:
;; bad
(foo bar (fn [a]
(println a)))
;; fixed
(foo bar (fn [a]
(println a))) ;; <-- nudged to be inside "(fn"It is sometimes common to use JSON-style indentation in a top-level EDN config:
;; bad
:cljsbuild {
:builds [...]
}
;; fixed
:cljsbuild {
:builds [...]} ;; <-- nudged to be inside "{"
;; fine (but not automated)
:cljsbuild {:builds [...]}
;; fine (but not automated)
:cljsbuild
{:builds [...]}Comment and ignore forms are commonly added retroactively without adjusting indentation:
;; bad
#_(defn foo []
(bar baz))
;; fixed
#_(defn foo []
(bar baz));; bad
(comment
(defn foo []
(bar baz))
)
;; fixed
(comment
(defn foo []
(bar baz)))Linting may throw off the alignment of comments, due to paren movement:
;; bad
(let [foo 1 ; this is number one
bar 2 ; this is number two
]
(+ foo bar))
;; fixed
(let [foo 1 ; this is number one
bar 2] ; this is number two
(+ foo bar))Though Parinfer was designed to lower the barrier for newcomers, it faced a problem of practicality by not allowing them to collaborate smoothly with people who didn't use it. This friction was not part of the intended experience.
Parlinter was designed as an answer to this problem, since there now seems to be a growing acceptance of linters and even full-formatters like Prettier, refmt, and gofmt from other language communities.
Thus, I hope that Parlinter at least spurs some thoughts on what is an acceptable amount of process around linting in Lisp, whether or not Parinfer is worth linting for, and how else we can help newcomers get into Lisp easier.
(It may also open the door for some exciting next-gen things I'm not yet ready to talk about.)
Written for Lisp with <3