# `Filtrex`
[🔗](https://github.com/rcdilorenzo/filtrex/blob/main/lib/filtrex.ex#L1)

Filtrex consists of the following primary components:

  * `Filtrex` - handles the overall parsing of filters and delegates to
    `Filtrex.AST` to build an ecto query expression

  * `Filtrex.Condition` - an abstract module built to delegate to specific condition modules in the format of `Filtrex.Condition.Type` where the type is converted to CamelCase (See `Filtrex.Condition.Text.parse/2`)

  * `Filtrex.Params` - an abstract module for parsing plug-like params from a query string into a filter

  * `Filtrex.Fragment` - simple struct to hold generated expressions and values to be used when generating queries for ecto

  * `Filtrex.Type.Config` - struct to hold various configuration and validation options for creating a filter

# `t`

```elixir
@type t() :: t()
```

# `parse`

```elixir
@spec parse([Filtrex.Type.Config.t()], Map.t()) :: {:error, String.t()} | {:ok, t()}
```

Parses a filter expression and returns an error or the parsed filter with
the appropriate parsed sub-structures.

The `configs` option is a list of type configs (See `Filtrex.Type.Config`)
Example:
```
[%Filtrex.Type.Config{type: :text, keys: ~w(title comments)}]
```

# `parse_params`

This function converts Plug-decoded params like the example below into a filtrex struct based on options in the configs.
```
%{"comments_contains" => "love",
  "title" => "My Blog Post",
  "created_at_between" => %{"start" => "2014-01-01", "end" => "2016-01-01"}}
```

# `query`

```elixir
@spec query(Ecto.Queryable.t(), t(), Keyword.t()) :: Ecto.Query.t()
```

Converts a filter with the specified ecto module name into a valid ecto query
expression that is compiled when called.

If a `%Filtrex{empty: true}` struct is passed as the filter, the query will
not be modified. If you want the query to return no results when this happens,
set the `allow_empty` option to `true`:

```
Filtrex.query(query, filter, allow_empty: true)
```

# `safe_parse`

```elixir
@spec safe_parse([Filtrex.Type.Config.t()], Map.t()) :: t()
```

Parses a filter expression, like `parse/2`. If any exception is raised when
parsing the map, a `%Filtrex{empty: true}` struct will be returned.

# `safe_parse_params`

Converts Plug-decoded params into a Filtrex struct, like `parse_params/1`. If
an exception is raised while parsing the params, a `%Filtrex{empty: true}` struct
will be returned.

# `validate_structure`

Validates the rough filter params structure

---

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