Formatters for Pragtical

List of formatters (Keep alphabetical)

• autoflake python formatter
• black python formatter
• clang-format
• cljfmt
• cmake-format
• csharpier
• crystal
• css-beautify
• dartformat
• dfmt
• elixir
• elm-format
• esformatter
• gdformat
• google-java-format
• goimports
• html-beautify
• isort python formatter
• js-beautify
• juliaformat
• luaformatter
• ocp-indent
• ormolu
• perltidy
• phpcbf
• prettier
• qmlformat
• rubocop
• ruff
• rustfmt
• shformat
• sql-formatter
• styluaformat
• tidy
• tsformat
• vfmt
• zigfmt

Installation instructions

1. Clone this repository into the pragtical plugins/formatter folder

2. Make sure you have the command that formatter uses installed, or it won't work.

3. Extra configuration: If you want to customize a formatter, you can do this from your init.lua script. Example:

local formatter = require("plugins.formatter")

formatter.config("jsbeautify", {
    -- Optionally disable this formmater
    enabled = false,
    -- Optionally set path of executable
    path = "/path/to/js-beautify",
    -- Set jsBeautify arguments to indent with spaces.
    args = "-r -s 4 -p -b end-expand"
})

4. You can also enable/disable and configure all available formatters from the settings graphical interface on Plugins -> Formatter.

Formatter plugin public API

local formatter = require("plugins.formatter")

---Represents a registered formatter.
---@class plugins.formatter.formatter
---@field name string
---@field label string
---@field enabled boolean?
---@field file_patterns string[]
---@field command string[]
---@field args? string

---Register a new formatter.
---@param f plugins.formatter.formatter
function formatter.add_formatter(f)

---Modify a registered formatter configuration.
---@param name string
---@param options plugins.formatter.formatter
---@return boolean modified
function formatter.config(name, options)

---Get a formatter by its name.
---@param name string
---@return plugins.formatter.formatter?
function formatter.get(name)

---Get the first formatter that matches the given filename and is enabled.
---@param filename string
---@return plugins.formatter.formatter?
function formatter.get_by_filename(filename)

Using the formatter

the default keymap to format the current doc is alt+shift+f the command is formatter:format-doc

to format a document at each save add the following config to your user init.lua as shown:

config.plugins.formatter.format_on_save = true

Contributing a formatter

Example from jsbeautify.lua:

-- for JS Beautify fortmatter

return {
  label = "JS Beautifier",
  file_patterns = {"%.js$"},
  command = {"js-beautify", "$ARGS", "$FILENAME"},
  -- make sure to keep -r arg if you change this
  args = "-r -q -s 1 -t -p -b end-expand"
}

A few things to keep in mind

• choose a unique file name
• make sure to set a label
• make sure to add it to the list in readme.md (and keep it alphabetical)

Then, submit a pull request