View Source Quokka

Hex.pm Hexdocs.pm Github.com

Quokka

A happy quokka with style

Quokka is an Elixir formatter plugin that's combination of mix format and mix credo, except instead of telling you what's wrong, it just rewrites the code for you. Quokka is a fork of Styler that checks the Credo config to determine which rules to rewrite. Many common, non-controversial Credo style rules are rewritten automatically, while the controversial Credo style rules are rewritten based on your Credo configuration so you can customize your style.

WARNING

Quokka can change the behavior of your program!

In some cases, this can introduce bugs. It goes without saying, but look over your changes before committing to main :)

We recommend making changes in small chunks until all of the more dangerous changes has been safely committed to the codebase

Installation

Add :quokka as a dependency to your project's mix.exs:

def deps do
  [
    {:quokka, "~> 2.4.0", only: [:dev, :test], runtime: false},
  ]
end

Then add Quokka as a plugin to your .formatter.exs file

[
  plugins: [Quokka]
]

And that's it! Now when you run mix format you'll also get the benefits of Quokka's Stylish Stylings.

First Run

You may want to initially run Quokka in "newline fixes only" mode. This will only fix spacing issues, making future PRs much smaller and easier to digest. See the example in the configuration section if you wish to do this.

Speed: Expect the first run to take some time as Quokka rewrites violations of styles and bottlenecks on disk I/O. Subsequent formats will take noticeably less time.

Configuration

Quokka primarily relies on the configurations of .formatter.exs and Credo (if available). However, there are some Quokka specific options that can also be specified in .formatter.exs to fine tune your setup:

[
  plugins: [Quokka],
  quokka: [
    autosort: [:map, :defstruct],
    inefficient_function_rewrites: true | false,
    files: %{
      included: ["lib/", ...],
      excluded: ["lib/example.ex", ...]
    },
    only: [
      # Changes to blocks of code
      :blocks
      # Comment directives such as # quokka:sort
      | :comment_directives
      # Sorting config files
      | :configs
      # Minimizes function heads
      | :defs
      # Converts deprecations
      | :deprecations
      # SPECIAL CASE: excludes all modules and only does newline fixups
      | :line_length
      # Fixes for imports, aliases, etc.
      | :module_directives
      # Various fixes for pipes
      | :pipes
      # Inefficient function rewrites, large numbers get underscores, etc.
      # Basically anything that doesn't fit into the categories above
      | :single_node
    ],
    exclude: [
      :blocks
      | :comment_directives
      | :configs
      | :defs
      | :deprecations
      | :module_directives
      | :pipes
      | :single_node
    ],
    piped_function_exclusions: [:subquery, :"Repo.update", ...]
  ]
]
OptionDescriptionDefault
:autosortSort all maps and/or defstructs in your codebase. Quokka will skip sorting maps that have comments inside them, though sorting can still be forced with # quokka:sort.[]
:filesQuokka gets files from .formatter.exs[:inputs]. However, in some cases you may need to selectively exclude/include files you wish to still run in mix format, but have different behavior with Quokka.%{included: [], excluded: []} (all files included, none excluded)
:onlyOnly include the given modules. The special :line_length option excludes all changes except line length fixups.[] (all modules included)
:excludeExclude the given modules. This is just a convenience function that filters from the :only list.[] (all modules included)
:inefficient_function_rewritesRewrite inefficient functions to more efficient formtrue
:piped_function_exclusionsAllows you to specify certain functions that won't be rewritten into a pipe. Particularly good for things like Ecto's subquery macro.[]

Credo inspired rewrites

The power of Quokka comes from utilizing the opinions you've already made with Credo and going one step further to attempt rewriting them for you.

Below is a general overall of many Credo checks Quokka attempts to handle and some additional useful details such as links to detailed documentation and if the check can be configured further for fine tuning.

:controversial Credo checks

Quokka allows all :controversial Credo checks to be configurable. In many cases, a Credo check can also be disabled to prevent rewriting.

Credo CheckRewrite DescriptionDocumentationConfigurable
.MultiAliasImportRequireUseExpands multi-alias/import statementsDirective Expansion
.ParameterPatternMatchingEnforces consistent parameter pattern matchingParameter Pattern Matching

License

Quokka is licensed under the Apache 2.0 license. See the LICENSE file for more details.