This macro allows an Ecto.Schema to leverage rummage's features with ease. This macro defines a function rummage/2 which can be called on the Module using this which delegates to Rummage.Ecto.rummage/3, but before doing that it resolves the options with default values for repo, search hook, sort hook and paginate hook. If rummage/2 is called with those options in form of keys given to the last argument opts, then it sets those keys to what's given else it delegates it to the defaults specficied by __using__ macro. If no defaults are specified, then it further delegates it to configurations.

The function rummage/2 takes in rummage params and opts and calls Rummage.Ecto.rummage/3 with whatever schema is calling it as the queryable.

This macro also defines a function rummageq/3 where q implies queryable. Therefore this function can take a queryable as the first argument.

In this way this macro makes it very easy to use Rummage.Ecto.

Usage:

Basic Usage where a default repo is specified as options to the macro.

defmodule MyApp.MySchema do
  use Ecto.Schema
  use Rummage.Ecto, repo: MyApp.Repo, per_page: 10
end

Advanced Usage where search and sort hooks are overrident for this module.

defmodule MyApp.MySchema do
  use Ecto.Schema
  use Rummage.Ecto, repo: MyApp.Repo, per_page: 10,
                    search: CustomSearchModule,
                    sort: CustomSortModule
end

This allows you do just do `MyApp.Schema.rummage(rummage_params)` with specific
`rummage_params` and add `Rummage.Ecto`'s power to your schema.

Specs

rummage(Ecto.Query.t(), map(), Keyword.t()) :: {Ecto.Query.t(), map()}

This is the function which calls to the Rummage hooks. It is the entry-point to Rummage.Ecto.

This function takes in a queryable, a rummage map and an opts keyword. Recognized opts keys are:

• repo: If you haven't set up a repo at the config level or __using__

      level, this a way of passing `repo` to `rummage`. If you have
      already configured your app to use a default `repo` and/or
      specified the `repo` at `__using__` level, this is a way of
      overriding those defaults.

• per_page: If you haven't set up a per_page at the config level or __using__

          level, this a way of passing `per_page` to `rummage`. If you have
          already configured your app to use a default `per_page` and/or
          specified the `per_page` at `__using__` level, this is a way of
          overriding those defaults.

• search: If you haven't set up a search at the config level or __using__

        level, this a way of passing `search` to `rummage`. If you have
        already configured your app to use a default `search` and/or
        specified the `search` at `__using__` level, this is a way of
        overriding those defaults. This can be used to override native
        `Rummage.Ecto.Hook.Search` to a custom hook.

• sort: If you haven't set up a sort at the config level or __using__

      level, this a way of passing `sort` to `rummage`. If you have
      already configured your app to use a default `sort` and/or
      specified the `sort` at `__using__` level, this is a way of
      overriding those defaults. This can be used to override native
      `Rummage.Ecto.Hook.Sort` to a custom hook.

• paginate: If you haven't set up a paginate at the config level or __using__

          level, this a way of passing `paginate` to `rummage`. If you have
          already configured your app to use a default `paginate` and/or
          specified the `paginate` at `__using__` level, this is a way of
          overriding those defaults. This can be used to override native
          `Rummage.Ecto.Hook.Paginate` to a custom hook.

Examples

When no hook params are given, it just returns the queryable and the params:

iex> import Rummage.Ecto
iex> alias Rummage.Ecto.Product
iex> rummage = %{}
iex> {queryable, rummage} = rummage(Product, rummage)
iex> rummage
%{}
iex> queryable
Rummage.Ecto.Product

When nil hook module is given, it just returns the queryable and the params:

iex> import Rummage.Ecto
iex> alias Rummage.Ecto.Product
iex> rummage = %{paginate: %{page: 1}}
iex> {queryable, rummage} = rummage(Product, rummage, paginate: nil)
iex> rummage
%{paginate: %{page: 1}}
iex> queryable
Rummage.Ecto.Product

When a hook param is given, with hook module it just returns the queryable and the params:

iex> import Rummage.Ecto
iex> alias Rummage.Ecto.Product
iex> rummage = %{paginate: %{page: 1}}
iex> repo = Rummage.Ecto.Repo
iex> Ecto.Adapters.SQL.Sandbox.checkout(repo)
iex> opts = [paginate: Rummage.Ecto.Hook.Paginate, repo: repo]
iex> {queryable, rummage} = rummage(Product, rummage, opts)
iex> rummage
%{paginate: %{max_page: 0, page: 1, per_page: 10, total_count: 0}}
iex> queryable
#Ecto.Query<from p0 in Rummage.Ecto.Product, limit: ^10, offset: ^0>

When a hook is given, with correspondng params, it updates and returns the queryable and the params accordingly:

iex> import Rummage.Ecto
iex> alias Rummage.Ecto.Product
iex> rummage = %{paginate: %{per_page: 1, page: 1}}
iex> repo = Rummage.Ecto.Repo
iex> Ecto.Adapters.SQL.Sandbox.checkout(repo)
iex> repo.insert!(%Product{name: "name", internal_code: "100"})
iex> repo.insert!(%Product{name: "name2", internal_code: "101"})
iex> opts = [paginate: Rummage.Ecto.Hook.Paginate,
...>  repo: repo]
iex> {queryable, rummage} = rummage(Product, rummage, opts)
iex> rummage
%{paginate: %{max_page: 2, page: 1, per_page: 1, total_count: 2}}
iex> queryable
#Ecto.Query<from p0 in Rummage.Ecto.Product, limit: ^1, offset: ^0>