cljfmt

cljfmt is a tool for detecting and fixing formatting errors in Clojure code.

Its defaults are based on the Clojure Style Guide, but it also has many customization options to suit a particular project or team.

It is not the goal of the project to provide a one-to-one mapping between a Clojure syntax tree and formatted text; rather the intent is to correct formatting errors with minimal changes to the existing structure of the text.

If you want format completely unstructured Clojure code, the zprint project may be more suitable.

Usage

cljfmt integrates with many existing build tools, or can be used as a library. As an end user, you have the choice of:

Clojure Tools

The official Clojure CLI supports installation of thirdparty tools. To install cljfmt as a tool, run:

clj -Ttools install io.github.weavejester/cljfmt '{:git/tag "0.10.1"}' :as cljfmt

To use the tool to check code for formatting errors, run:

clj -Tcljfmt check

And to fix those errors:

clj -Tcljfmt fix

Leiningen

Leiningen is a popular Clojure build tool. To use cljfmt with Leiningen, add the following plugin to your project.clj file:

:plugins [[dev.weavejester/lein-cljfmt "0.10.1"]]

To use the plugin to check code for formatting errors, run:

lein cljfmt check

And to fix those errors:

lein cljfmt fix

Babashka

Babashka is a native Clojure interpreter with a very fast startup. Running cljfmt via Babashka can be several times faster than running it as a tool or via Leiningen.

To use cljfmt with Babashka, add the following dependency and task to your bb.edn file:

{:deps
 {dev.weavejester/cljfmt {:mvn/version "0.10.1"}}
 :tasks
 {cljfmt {:doc "Run cljfmt"
          :requires ([cljfmt.main :as fmt])
          :task (binding [fmt/*command* "bb cljfmt"]
                  (apply fmt/-main *command-line-args*))}}}

To use the Babashka task to check code for formatting errors, run:

bb cljfmt check

And to fix those errors:

bb cljfmt fix

Standalone

cljfmt can also be run as a standalone -main application. Do do so, add the following dependency to your deps.edn file or the equivalent:

{:deps {dev.weavejester/cljfmt {:mvn/version "0.10.1"}}}

To use cljfmt to check for formatting errors, run:

clojure -M -m cljfmt.main check

And to fix those errors:

clojure -M -m cljfmt.main fix

Library

cljfmt can be run as a library that formats a string of Clojure code. First, add the dependency:

{:deps {dev.weavejester/cljfmt {:mvn/version "0.10.1"}}}

Then use the library:

(require '[cljfmt.core :as fmt])

(fmt/reformat-string "(defn sum [x y]\n(+ x y))")
;; => "(defn sum [x y]\n  (+ x y))"

To use load the configuration for the current directory:

(require '[cljfmt.config :as cfg])

(fmt/reformat-string "(+ x\ny)" (cfg/load-config))
;; => "(+ x\n   y)"

Editor Integration

You can also use cljfmt via your editor. Several Clojure editing environments have support for cljfmt baked in:

• Calva (Visual Studio Code)
• CIDER (Emacs)
• clojureVSCode (Visual Studio Code)
• vim-cljfmt (Vim)

Configuration

In most environments, cljfmt will look for the following configuration files in the current and parent directories:

• .cljfmt.edn
• .cljfmt.clj
• cljfmt.edn
• cljfmt.clj

The configuration file should contain a map of options.

In Leiningen, the configuration is found in on the :cljfmt key in the project map:

:cljfmt {}

Formatting Options

• :indentation? - true if cljfmt should correct the indentation of your code. Defaults to true.

• :indents - a map of var symbols to indentation rules, i.e. {symbol [& rules]}. See INDENTS.md for a complete explanation.

• :alias-map - a map of namespace alias strings to fully qualified namespace names. This option is unnecessary in most cases, because cljfmt will parse the ns declaration in each file. See INDENTS.md.

• :remove-surrounding-whitespace? - true if cljfmt should remove whitespace surrounding inner forms. This will convert (  foo  ) to (foo). Defaults to true.

• :remove-trailing-whitespace? - true if cljfmt should remove trailing whitespace in lines. This will convert (foo)   \n to (foo)\n. Defaults to true.

• :insert-missing-whitespace? - true if cljfmt should insert whitespace missing from between elements. This will convert (foo(bar)) to (foo (bar)). Defaults to true.

• :remove-consecutive-blank-lines? - true if cljfmt should collapse consecutive blank lines. This will convert (foo)\n\n\n(bar) to (foo)\n\n(bar). Defaults to true.

• :remove-multiple-non-indenting-spaces? - true if cljfmt should remove multiple non indenting spaces. For example, this will convert {:a 1     :b 2} to {:a 1 :b 2}. Defaults to false.

• :split-keypairs-over-multiple-lines? - true if cljfmt should break hashmaps onto multiple lines. This will convert {:a 1 :b 2} to {:a 1\n:b 2}. Defaults to false.

• :sort-ns-references? - true if cljfmt should alphanumerically sort the requires, imports and other references in the ns forms at the top of your namespaces. Defaults to false.

Runtime Options

• :file-pattern - a regular expression to decide which files to scan. Defaults to #”\.clj[csx]?$”.

• :parallel? - true if cljfmt should process files in parallel. Defaults to false.

• :paths - determines which files and directories to recursively search for Clojure files. Defaults to checking src and test, except in Leiningen where the :source-paths and :test-paths keys are used instead.

License

Copyright © 2023 James Reeves

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.