Kernel.use
use
, go back to Kernel module for more information.
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.