# `Machete.ListMatcher`
[🔗](https://github.com/mtrudel/machete/blob/main/lib/machete/matchers/list_matcher.ex#L1)

Defines a matcher that matches lists

# `opts`

```elixir
@type opts() :: [
  elements: Machete.Matchable.t(),
  match_mode: :all | :any | :none | non_neg_integer(),
  length: non_neg_integer(),
  min: non_neg_integer(),
  max: non_neg_integer()
]
```

Describes the arguments that can be passed to this matcher

# `t`

```elixir
@opaque t()
```

Describes an instance of this matcher

# `list`

```elixir
@spec list(opts()) :: t()
```

Matches lists. Useful for cases where you wish to match against the general shape / size of
a list, but cannot match against a literal list

Takes the following arguments:

* `elements`: A matcher to use against all elements in the list
* `match_mode`: How to apply the `elements` matcher to the elements in the list. `:all`, `:any`,
  and `:none` each match if all, any, or none of the list's elements match the `elements` matcher,
  respectively. A non-negative integer requires at least `n` of the elements in the list to match.
  Defaults to `:all`
* `length`: Requires the matched list to be exactly the specified length
* `min`: Requires the matched list to be greater than or equal to the specified length
* `max`: Requires the matched list to be less than or equal to the specified length

Examples:
    iex> assert [1] ~> list(elements: integer())
    true

    iex> assert [1, "a", :b] ~> list(elements: integer(), match_mode: :any)
    true

    iex> assert ["a", "b", :c] ~> list(elements: integer(), match_mode: :none)
    true

    iex> assert [1, 2, 3.0] ~> list(elements: integer(), match_mode: 2)
    true

    iex> assert [1] ~> list(length: 1)
    true

    iex> assert [1] ~> list(min: 1)
    true

    iex> assert [1] ~> list(max: 2)
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*