Skip to content

Latest commit

 

History

History
176 lines (143 loc) · 15.4 KB

README.md

File metadata and controls

176 lines (143 loc) · 15.4 KB

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 {: .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, "~> 0.1", 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: [
    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", ...]
  ]
]
Option Description Default
:autosort Sort all maps and/or defstructs in your codebase. Quokka will skip sort maps that have comments inside them, though sorting can still be forced with # quokka:sort. []
:files Quokka 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)
:only Only include the given modules. The special :line_length option excludes all changes except line length fixups. [] (all modules included)
:exclude Exclude the given modules. This is just a convenience function that filters from the :only list. [] (all modules included)
:inefficient_function_rewrites Rewrite inefficient functions to more efficient form true
:piped_function_exclusions Allows 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 {: .tip}

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

Credo.Check.Consistency

Credo Check Rewrite Description Documentation Configurable
.MultiAliasImportRequireUse Expands multi-alias/import statements Directive Expansion
.ParameterPatternMatching Enforces consistent parameter pattern matching Parameter Pattern Matching

Credo.Check.Design

Credo Check Rewrite Description Documentation Configurable
.AliasUsage Extracts repeated aliases Alias Lifting ✓

Credo.Check.Readability

Credo Check Rewrite Description Documentation Configurable
.AliasOrder Alphabetizes module directives Module Directives ✓
.BlockPipe (En|dis)ables piping into blocks Pipe Chains ✓
.LargeNumbers Formats large numbers with underscores Number Formatting ✓
.MaxLineLength Enforces maximum line length Line Length ✓
.MultiAlias Expands multi-alias statements Module Directives ✓
.OneArityFunctionInPipe Optimizes pipe chains with single arity functions Pipe Chains
.ParenthesesOnZeroArityDefs Enforces consistent function call parentheses Function Calls ✓
.PipeIntoAnonymousFunctions Optimizes pipes with anonymous functions Pipe Chains
.PreferImplicitTry Simplifies try expressions Control Flow Macros
.SinglePipe Optimizes pipe chains Pipe Chains ✓
.StringSigils Replaces strings with sigils Strings to Sigils
.StrictModuleLayout Enforces strict module layout Module Directives ✓
.UnnecessaryAliasExpansion Removes unnecessary alias expansions Module Directives
.WithSingleClause Simplifies with statements Control Flow Macros

Credo.Check.Refactor

Credo Check Rewrite Description Documentation Configurable
.CondStatements Simplifies boolean expressions Control Flow Macros
.FilterCount Optimizes filter + count operations Styles
.MapInto Optimizes map + into operations Styles
.MapJoin Optimizes map + join operations Styles
.NegatedConditionsInUnless Simplifies negated conditions in unless Control Flow Macros
.NegatedConditionsWithElse Simplifies negated conditions with else Control Flow Macros
.PipeChainStart Optimizes pipe chain start Pipe Chains
.RedundantWithClauseResult Removes redundant with clause results Control Flow Macros
.UnlessWithElse Simplifies unless with else Control Flow Macros
.WithClauses Optimizes with clauses Control Flow Macros

License

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