Uses the given module in the current context.

When calling:

use MyModule, some: :options

the __using__/1 macro from the MyModule module is invoked with the second argument passed to use as its argument. Since __using__/1 is a macro, all the usual macro rules apply, and its return value should be quoted code that is then inserted where use/2 is called.

Examples

For example, to write test cases using the ExUnit framework provided with Elixir, a developer should use the ExUnit.Case module:

defmodule AssertionTest do
  use ExUnit.Case, async: true

  test "always pass" do
    assert true
  end
end

In this example, Elixir will call the __using__/1 macro in the ExUnit.Case module with the keyword list [async: true] as its argument.

In other words, use/2 translates to:

defmodule AssertionTest do
  require ExUnit.Case
  ExUnit.Case.__using__(async: true)

  test "always pass" do
    assert true
  end
end

where ExUnit.Case defines the __using__/1 macro:

defmodule ExUnit.Case do
  defmacro __using__(opts) do
    # do something with opts
    quote do
      # return some code to inject in the caller
    end
  end
end

Best practices

__using__/1 is typically used when there is a need to set some state (via module attributes) or callbacks (like @before_compile, see the documentation for Module for more information) into the caller.

__using__/1 may also be used to alias, require, or import functionality from different modules:

defmodule MyModule do
  defmacro __using__(_opts) do
    quote do
      import MyModule.Foo
      import MyModule.Bar
      import MyModule.Baz

      alias MyModule.Repo
    end
  end
end

However, do not provide __using__/1 if all it does is to import, alias or require the module itself. For example, avoid this:

defmodule MyModule do
  defmacro __using__(_opts) do
    quote do
      import MyModule
    end
  end
end

In such cases, developers should instead import or alias the module directly, so that they can customize those as they wish, without the indirection behind use/2.

Finally, developers should also avoid defining functions inside the __using__/1 callback, unless those functions are the default implementation of a previously defined @callback or are functions meant to be overridden (see defoverridable/1). Even in these cases, defining functions should be seen as a "last resort".

In case you want to provide some existing functionality to the user module, please define it in a module which will be imported accordingly; for example, ExUnit.Case doesn't define the test/3 macro in the module that calls use ExUnit.Case, but it defines ExUnit.Case.test/3 and just imports that into the caller when used.