Skip to content

Commit

Permalink
Merge pull request #117 from inaka/425-rename-application-update-readme
Browse files Browse the repository at this point in the history 
[inaka/elvis#425] Update README after renaming the application
  • Loading branch information
@elbrujohalcon
elbrujohalcon authored Dec 18, 2019
2 parents 59043b5 + e671e73 commit 5fd30f5
Showing 1 changed file with 126 additions and 85 deletions.
211 changes: 126 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,57 +5,62 @@ Erlang style reviewer core library.
This library includes the mechanism to apply rules to your code and their
implementation.

## Contact Us
## Contributing & Reporting Bugs

If you find any **bugs** or have a **problem** while using this library, please
[open an issue](https://github.com/inaka/elvis/issues/new) in this repo
(or a pull request :)).

## Contributing & Reporting Bugs

If you find a bug or want to contribute to this project please create an issue through
the [elvis](https://github.com/inaka/elvis) repository. This is where all elvis related
work is coordinated.
The [elvis](https://github.com/inaka/elvis) repository is where all elvis_core
related work is coordinated.

## Usage

### As a library

This library implements all the core functionality for the
[`elvis`](https://github.com/inaka/elvis) command-line tool. For an example on
how to use it please check that project.
This library implements all the core functionality for analyzing files and
applying the styles rules defined here or custom ones defined by its users.

The [`elvis`](https://github.com/inaka/elvis) command-line tool uses it
extensively, so please check that project for a concrete example on how
you could use for your own purposes.

### Erlang Shell

After adding `elvis_core` as a dependency to your project and setting up its
[configuration](#configuration), you can run it from an Erlang shell in the
following two ways.
After adding `elvis_core` as a dependency to your project and starting a
shell, you will need to make sure the application is started:

```erlang
elvis_core:rock().
{ok, _} = application:ensure_all_started(elvis_core).
%%= {ok,[ zipper, katana_code, elvis_core]}
```

Once this is done you can run the style rules in the following ways.

#### Load configuration from a file

```erlang
ElvisConfig = elvis_core:from_file("elvis.config").
elvis_core:rock(ElvisConfig).
%%+ # src/elvis_core.erl [OK]
%%+ # src/elvis_result.erl [OK]
%%+ # src/elvis_style.erl [OK]
%%+ # src/elvis_utils.erl [OK]
%%= ok
```

This will try to load the configuration for `elvis_core` specified in an
`elvis.config` located in the current directory. If no configuration is
found `invalid_config` will be thrown.
This will try to load the [configuration](#configuration) specified in an
`elvis.config` located in the current directory. If no configuration is found
`invalid_config` will be thrown.

To start the application in the shell enter the following command:

```erlang
application:start(elvis).
%%= ok
```
#### Provide configuration as a value

Another option for using `elvis_core` from the shell is explicitly providing a
configuration as an argument to `rock/1`:

```erlang
Config = [#{dirs => ["src"], filter => "*.erl", rules => []}],
elvis_core:rock(Config).
ElvisConfig = [#{dirs => ["src"], filter => "*.erl", rules => []}],
elvis_core:rock(ElvisConfig).
%%+ # src/elvis_core.erl [OK]
%%+ # src/elvis_result.erl [OK]
%%+ # src/elvis_style.erl [OK]
Expand All @@ -68,6 +73,8 @@ under development the definition for *valid format* is still a work in progress.
If the configuration format changes though, the example configuration files and
the documentation in this README will be updated.

#### Output for failing rules

We have only presented results where all files were well-behaved (respect all
the rules), so here's an example of how it looks when files break some of the
rules:
Expand All @@ -86,67 +93,60 @@ rules:

## Configuration

To provide a default configuration you should create an `elvis.config` file located
in the root directory:
An `elvis.config` configuration file should look like this:

```erlang
[
{
elvis,
[
{config,
[#{dirs => ["src"],
include_dirs => ["include"],
filter => "*.erl",
ruleset => erl_files
},
#{dirs => ["."],
filter => "Makefile",
ruleset => makefiles
},
#{dirs => ["."],
filter => "rebar.config",
ruleset => rebar_config
},
#{dirs => ["."],
filter => "elvis.config",
ruleset => elvis_config
}
]
},
%% Optional to select the output format, the default is colors
{output_format, plain},
%% Only necessary for the 'webhook' functionality
{github_user, "user"},
{github_password, "password"}
]
}
[ { elvis
, [ { config
, [ #{ dirs => ["src"]
, filter => "*.erl"
, ruleset => erl_files
}
, #{ dirs => ["."]
, filter => "Makefile"
, ruleset => makefiles
}
, #{ dirs => ["."]
, filter => "rebar.config"
, ruleset => rebar_config
}
, #{ dirs => ["."]
, filter => "elvis.config"
, ruleset => elvis_config
}
]
}
%% output_format (optional): how to format the output.
%% Possible values are 'plain', 'colors' or 'parsable' (default='colors').
, {output_format, colors},
%% verbose (optional): when 'true' more information will
%% be printed (default=false).
, {verbose, true}
%% no_output (optional): when 'true' nothing will be printed
%% (default=false).
, {no_output, false}
%% parallel: determine how many files in parallel will be
%% analyzed (default=1).
, {parallel, 1}
]
}
].
```

The `include_dirs` key is just a list of folders (`[string()]`) where to search for
header files.
### Files, Rules & Rulesets

The `dirs` key is a list that indicates where `elvis` should look for the
files that match `filter`, which will be run through each of the default rules
in the specified `ruleset`, which is an *atom*. If you want to override the
[default rules](https://github.com/inaka/elvis_core/blob/master/src/elvis_rulesets.erl)
for a given ruleset you need to specify them in a `rules` key which is a
list of items with the following structure `{Module, Function, RuleConfig}` or
`{Module, Function}` if the rule takes no configuration values. You can also
`disable` certain rules if you want to just by specifying the rule in the `rules`
key and passing `disable` as its third parameter.
in the specified `ruleset`, which is an *atom*.

`output_format` is used to configure the output format. Possible values are `colors`,
`plain` and `parsable`. The latter could be use for the automated parsing and has a
format very close to dialyzer in a form `FILE:LINE:RULE:MESSAGE`:
If you want to override the [default rules][default-rules] for a given ruleset
you need to specify them in a `rules` key which is a list of items with the
following structure `{Module, Function, RuleConfig}` or `{Module, Function}`
if the rule takes no configuration values. You can also `disable` certain rules
if you want to just by specifying the rule in the `rules` key and passing
`disable` as its third parameter.

```
src/example.erl:1:god_modules:This module has too many functions (56). Consider breaking it into a number of modules.
src/example_a.erl:341:no_debug_call:Remove the debug call to io:format/2 on line 341.
src/example_a.erl:511:used_ignored_variable:Ignored variable is being used on line 511 and column 54.
src/example_a.erl:1252:used_ignored_variable:Ignored variable is being used on line 1252 and column 21.
```
#### Disabling Rules

**IMPORTANT:** `disable` will only work if you also provided a `ruleset` as shown above.

Expand All @@ -163,6 +163,8 @@ also you like to use tabs instead of spaces, so you need to override `erl_files`
},
```

#### Ignoring Modules

You can also `ignore` modules at a _check level_ or at a _ruleset (group of checks) level_:
- at check level by setting the ignore parameter in the rule you want to skip, e.g:
```erlang
Expand All @@ -180,25 +182,64 @@ You can also `ignore` modules at a _check level_ or at a _ruleset (group of chec
```
With this configuration, none of the checks for [erl_files](https://github.com/inaka/elvis_core/blob/master/src/elvis_rulesets.erl#L6-L34) would be applied to `module1.erl` and `module4.erl` files.

The implementation of a rule is just a function that takes 3 arguments: `elvis`'s
`config` entry from its [configuration](#configuration); the file to be
analyzed; and a configuration map specified for the rule. This means you can
define rules of your own as long as the functions that implement them respect
this arity.
### Formating

`output_format` is used to configure the output format. Possible values are `colors`,
`plain` and `parsable`. The latter could be use for the automated parsing and has a
format very close to dialyzer in a form `FILE:LINE:RULE:MESSAGE`:

```
src/example.erl:1:god_modules:This module has too many functions (56). Consider breaking it into a number of modules.
src/example_a.erl:341:no_debug_call:Remove the debug call to io:format/2 on line 341.
src/example_a.erl:511:used_ignored_variable:Ignored variable is being used on line 511 and column 54.
src/example_a.erl:1252:used_ignored_variable:Ignored variable is being used on line 1252 and column 21.
```

### Verbosity

It is possible to indicate elvis_core to produce more information in its output
with the `verbose` option. The value provided should be a boolean, either `true`
or `false`.

You can find the default `elvis` configuration file at `config/elvis.config`.
The default value for `verbose` is `false`.

The GitHub configuration parameters `github_user` and `github_password` are
required only when `elvis` is used as a [webhook](#webhook).
On the other hand if no output is desired then the value for the `no_output`
option should be `true`.

The default value for `no_output` is `false`.

### Parallelization

In order to speed up the analysis of files, the `parallel` option can be used.

Its value indicates how many processes to use at the same time to apply the
style rules to all the files gathered. The number provided should be less than
or equal to the available CPUs, since any value higher than that won't report
any speedup benefits.

The default value for `parallel` is `1`.

## Configuration Examples

You can find examples for configuration files in this project's `config` directory.

## Implemented Rules

A reference of all rules implemented in Elvis can be found in this wiki page:
[Rules](https://github.com/inaka/elvis/wiki/Rules).

### Custom Rules

The implementation of a rule is just a function that takes 3 arguments: `elvis`'s
`config` entry from its [configuration](#configuration); the file to be
analyzed; and a configuration map specified for the rule. This means you can
define rules of your own as long as the functions that implement them respect
this arity.

## References

Inspired by [HoundCI][houndci]

[houndci]: https://houndci.com/
[config]: http://www.erlang.org/doc/man/config.html
[default-rules]: (https://github.com/inaka/elvis_core/blob/master/src/elvis_rulesets.erl)
[houndci]: https://houndci.com/
[config]: http://www.erlang.org/doc/man/config.html

0 comments on commit 5fd30f5

Please sign in to comment.