# fix-getters-rules

This package contains rules definitions for the `fix-getters` tools.

See the [workspace documentation](https://github.com/fengalin/fix-getters/blob/0.3.2/README.md)
for more details on `fix-getters`.

## Rules

The `rules` apply to:

* file system directory entries to decide if a file should be processed or
  if a directory branch should be skipped. This requires `feature` **`dir-entry`**
  (enabled by default).
* functions name.

## Feature

* **`dir-entry`** — directory entry filtering rules. This features is enabled by
  default. Use `default-features = false` if your use case differs.

## Function name rules

The initial intent is to comply with Rust [naming conventions for getter methods](https://doc.rust-lang.org/1.0.0/style/style/naming/README.html#getter/setter-methods-%5Brfc-344%5D):

> A method `foo(&self) -> &T` for getting the current value of the field.

### General rules

These rules are based on the function name and knowledge of the return type.
See next chapter for `get` functions returning exactly one `bool`.

A `get` function is considered eligible for `get` prefix removal if:

* The function starts with `get_`.
* The suffix is not a Rust keyword, which would result in invalid code.

  E.g.: `get_as`, `get_false`, ... are kept as is.

* The method would result inconsistent with other similar methods.

  E.g.: a `struct` `Value` with a `get_mut` method to get the underlying value
  as a mutable reference, `get_optional` to get the underlying value of a type
  in the form `Option<T>` and `get_some` to get the underlying value of a type
  for which the value is always defined.

  See `RESERVED` in [`function.rs`](https://github.com/fengalin/fix-getters/blob/0.3.2/rules/src/function.rs).

* The suffix is not part of a subsitution list. This includes some Rust keywords.

  E.g.: `get_type` is replaced with `type_`.

  See `EXACT_SUFFIX_SUBSTITUTES` in [`function.rs`](https://github.com/fengalin/fix-getters/blob/0.3.2/rules/src/function.rs).

Another rule is applied to homogenize functions names in the form
`get_something_mut`. This rule renames both `get_something_mut` and
`get_mut_something` as `something_mut`.

The `fix-getters` tools also apply selective rules based on on the function
signature. See the dedicated chapter in [this `README`](https://github.com/fengalin/fix-getters/blob/0.3.2/README.md#get-functions-selection).

### Functions returning exactly one `bool`

Get functions returning `bool` should usually use the form `is_suffix`, which
reads natural when used in a condition. E.g.:

```rust
if event.is_serialized() {
  ...
}
```

The following additional rules are implemented.

#### First token substitutions

When the suffix starts with a verb, it's common to conjugate. E.g.

* `get_emit_eos` -> `if element.emits_eos()`.

`BOOL_FIRST_TOKEN_SUBSTITUTES` in [`function.rs`](https://github.com/fengalin/fix-getters/blob/0.3.2/rules/src/function.rs)
lists a set of verbs and the matching substitutions and also includes other
cases such as:

* `get_always_...` -> `must_always_...`.
* `get_focus` -> `gets_focus`.

#### Special first tokens

Modal verbs should be kept unchanged and no `is` prefix should be used. E.g.:

* `get_can_focus` -> `can_focus`.
* `get_must_...` -> `must_...`.

This is also the case for already conjugated verbs. E.g.:

* `get_has_...` -> `has_...`.

See `BOOL_FIRST_TOKEN_NO_PREFIX` in [`function.rs`](https://github.com/fengalin/fix-getters/blob/0.3.2/rules/src/function.rs).

#### Exact suffix substitutions

In some cases, the semantic requires substitutions only if the whole suffix
matches a value. E.g.:

* `get_result` -> `result`. Neither `if a.is_result()` nor `if a.results()`
  would be suitable.
* `get_visibility` -> `is_visible` Neither `if a.is_visibility()` nor
  `if a.visibility()`) would be suitable.

See `BOOL_EXACT_SUBSTITUTES` in [`function.rs`](https://github.com/fengalin/fix-getters/blob/0.3.2/rules/src/function.rs).

#### get_is prefix

Finally, the `is` prefix shouldn't be repeated when already present:

* `get_is_active` -> `is_active`.

### Detecting functions returning exactly one `bool`

The return type of Rust functions is usually not explicit. When renaming the
`get` functions call sites (see [`fix-getters-calls`](https://github.com/fengalin/fix-getters/tree/0.3.2/fix-calls)),
the returned type must be inferred. The rules described in previous chapter are
reversed when possible and an additional heuristic is used: when the first token
of the `get` function suffix ends in `able`, the function is considered to be
returning a `bool`. E.g.:

* `get_seekable` -> `is_seekable`.

## LICENSE

This crate is licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
   http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
   http://opensource.org/licenses/MIT)

at your option.