363 lines
10 KiB
Elixir
363 lines
10 KiB
Elixir
# We cannot use to_char_list because it depends on inspect,
|
|
# which depends on protocol, which depends on this module.
|
|
import Elixir::Builtin, except: [to_char_list: 1]
|
|
|
|
defmodule Module do
|
|
require Erlang.ets, as: ETS
|
|
|
|
@moduledoc """
|
|
This module provides many functions to deal with modules during
|
|
compilation time. It allows a developer to dynamically attach
|
|
documentation, merge data, register attributes and so forth.
|
|
|
|
After the module is compiled, using many of the functions in
|
|
this module will raise errors, since it is out of their purpose
|
|
to inspect runtime data. Most of the runtime data can be inspected
|
|
via the `__info__(attr)` function attached to each compiled module.
|
|
"""
|
|
|
|
@doc """
|
|
Evalutes the quotes contents in the given module context.
|
|
Raises an error if the module was already compiled.
|
|
|
|
## Examples
|
|
|
|
defmodule Foo do
|
|
contents = quote do: (def sum(a, b), do: a + b)
|
|
Module.eval_quoted __MODULE__, contents, [], __FILE__, __LINE__
|
|
end
|
|
|
|
Foo.sum(1, 2) #=> 3
|
|
"""
|
|
def eval_quoted(module, quoted, binding, filename, line) do
|
|
assert_not_compiled!(:eval_quoted, module)
|
|
{ binding, scope } = Erlang.elixir_module.binding_and_scope_for_eval(line, to_char_list(filename), module, binding)
|
|
Erlang.elixir_def.reset_last(module)
|
|
Erlang.elixir.eval_quoted([quoted], binding, line, scope)
|
|
end
|
|
|
|
@doc """
|
|
Checks if the module is compiled or not.
|
|
|
|
## Examples
|
|
|
|
defmodule Foo do
|
|
Module.compiled?(__MODULE__) #=> false
|
|
end
|
|
|
|
Module.compiled?(Foo) #=> true
|
|
|
|
"""
|
|
def compiled?(module) do
|
|
table = data_table_for(module)
|
|
table == ETS.info(table, :name)
|
|
end
|
|
|
|
@doc """
|
|
Reads the data for the given module. This is used
|
|
to read data of uncompiled modules. If the module
|
|
was already compiled, you shoul access the data
|
|
directly by invoking `__info__(:data)` in that module.
|
|
|
|
## Examples
|
|
|
|
defmodule Foo do
|
|
Module.merge_data __MODULE__, value: 1
|
|
Module.read_data __MODULE__ #=> [value: 1]
|
|
end
|
|
|
|
"""
|
|
def read_data(module) do
|
|
assert_not_compiled!(:read_data, module)
|
|
ETS.lookup_element(data_table_for(module), :data, 2)
|
|
end
|
|
|
|
@doc """
|
|
Reads the data from `module` at the given key `at`.
|
|
|
|
## Examples
|
|
|
|
defmodule Foo do
|
|
Module.merge_data __MODULE__, value: 1
|
|
Module.read_data __MODULE__, :value #=> 1
|
|
end
|
|
|
|
"""
|
|
def read_data(module, at) do
|
|
Orddict.get read_data(module), at
|
|
end
|
|
|
|
@doc """
|
|
Merge the given data into the module, overriding any
|
|
previous one.
|
|
|
|
If any of the given data is a registered attribute, it is
|
|
automatically added to the attribute set, instead of marking
|
|
it as data. See register_attribute/2 and add_attribute/3 for
|
|
more info.
|
|
|
|
## Examples
|
|
|
|
defmodule Foo do
|
|
Module.merge_data __MODULE__, value: 1
|
|
end
|
|
|
|
Foo.__info__(:data) #=> [value: 1]
|
|
|
|
"""
|
|
def merge_data(module, data) do
|
|
assert_not_compiled!(:merge_data, module)
|
|
|
|
table = data_table_for(module)
|
|
old = ETS.lookup_element(table, :data, 2)
|
|
registered = ETS.lookup_element(table, :registered_attributes, 2)
|
|
|
|
{ attrs, new } = Enum.partition data, fn({k,_}) -> List.member?(registered, k) end
|
|
Enum.each attrs, fn({k,v}) -> add_attribute(module, k, v) end
|
|
ETS.insert(table, { :data, Orddict.merge(old, new) })
|
|
end
|
|
|
|
@doc """
|
|
Attaches documentation to a given function. It expects
|
|
the module the function belongs to, the line (a non negative
|
|
integer), the kind (def or defmacro), a tuple representing
|
|
the function and its arity and the documentation, which should
|
|
be either a binary or a boolean.
|
|
|
|
## Examples
|
|
|
|
defmodule MyModule do
|
|
Module.add_doc(__MODULE__, __LINE__ + 1, :def, { :version, 0 }, "Manually added docs")
|
|
def version, do: 1
|
|
end
|
|
|
|
"""
|
|
def add_doc(module, line, kind, tuple, doc) when
|
|
is_binary(doc) or is_boolean(doc) do
|
|
assert_not_compiled!(:add_doc, module)
|
|
case kind do
|
|
match: :defp
|
|
:warn
|
|
else:
|
|
table = docs_table_for(module)
|
|
ETS.insert(table, { tuple, line, kind, doc })
|
|
:ok
|
|
end
|
|
end
|
|
|
|
@doc """
|
|
Checks if a function was defined, regardless if it is
|
|
a macro or a private function. Use function_defined?/3
|
|
to assert for an specific type.
|
|
|
|
## Examples
|
|
|
|
defmodule Example do
|
|
Module.function_defined? __MODULE__, { :version, 0 } #=> false
|
|
def version, do: 1
|
|
Module.function_defined? __MODULE__, { :version, 0 } #=> true
|
|
end
|
|
|
|
"""
|
|
def function_defined?(module, tuple) when is_tuple(tuple) do
|
|
assert_not_compiled!(:function_defined?, module)
|
|
table = function_table_for(module)
|
|
ETS.lookup(table, tuple) != []
|
|
end
|
|
|
|
@doc """
|
|
Checks if a function was defined and also for its `kind`.
|
|
`kind` can be either :def, :defp or :defmacro.
|
|
|
|
## Examples
|
|
|
|
defmodule Example do
|
|
Module.function_defined? __MODULE__, { :version, 0 }, :defp #=> false
|
|
def version, do: 1
|
|
Module.function_defined? __MODULE__, { :version, 0 }, :defp #=> false
|
|
end
|
|
|
|
"""
|
|
def function_defined?(module, tuple, kind) do
|
|
List.member? defined_functions(module, kind), tuple
|
|
end
|
|
|
|
@doc """
|
|
Return all functions defined in the given module.
|
|
|
|
## Examples
|
|
|
|
defmodule Example do
|
|
def version, do: 1
|
|
Module.defined_functions __MODULE__ #=> [{:version,1}]
|
|
end
|
|
|
|
"""
|
|
def defined_functions(module) do
|
|
assert_not_compiled!(:defined_functions, module)
|
|
table = function_table_for(module)
|
|
lc { tuple, _, _ } in ETS.tab2list(table), do: tuple
|
|
end
|
|
|
|
@doc """
|
|
Returns all functions defined in te given module according
|
|
to its kind.
|
|
|
|
## Examples
|
|
|
|
defmodule Example do
|
|
def version, do: 1
|
|
Module.defined_functions __MODULE__, :def #=> [{:version,1}]
|
|
Module.defined_functions __MODULE__, :defp #=> []
|
|
end
|
|
|
|
"""
|
|
def defined_functions(module, kind) do
|
|
assert_not_compiled!(:defined_functions, module)
|
|
table = function_table_for(module)
|
|
entry = kind_to_entry(kind)
|
|
ETS.lookup_element(table, entry, 2)
|
|
end
|
|
|
|
@doc """
|
|
Adds a compilation callback hook that is invoked
|
|
exactly before the module is compiled.
|
|
|
|
This callback is useful when used with `use` as a mechanism
|
|
to clean up any internal data in the module before it is compiled.
|
|
|
|
## Examples
|
|
|
|
Imagine you are creating a module/library that is meant for
|
|
external usage called `MyLib`. It could be defined as:
|
|
|
|
defmodule MyLib do
|
|
def __using__(target) do
|
|
Module.merge_data target, some_data: true
|
|
Module.add_compile_callback(target, __MODULE__, :__callback__)
|
|
end
|
|
|
|
defmacro __callback__(target) do
|
|
value = Orddict.get(Module.read_data(target), :some_data, [])
|
|
quote do: (def my_lib_value, do: unquote(value))
|
|
end
|
|
end
|
|
|
|
And a module could use `MyLib` with:
|
|
|
|
defmodule App do
|
|
use ModuleTest::ToBeUsed
|
|
end
|
|
|
|
In the example above, `MyLib` defines a data to the target. This data
|
|
can be updated throughout the module definition and therefore, the final
|
|
value of the data can only be compiled using a compiation callback,
|
|
which will read the final value of :some_data and compile to a function.
|
|
"""
|
|
def add_compile_callback(module, target, fun // :__compiling__) do
|
|
assert_not_compiled!(:add_compile_callback, module)
|
|
new = { target, fun }
|
|
table = data_table_for(module)
|
|
old = ETS.lookup_element(table, :compile_callbacks, 2)
|
|
ETS.insert(table, { :compile_callbacks, [new|old] })
|
|
end
|
|
|
|
@doc """
|
|
Adds an Erlang attribute to the given module with the given
|
|
key and value. The same attribute can be added more than once.
|
|
|
|
## Examples
|
|
|
|
defmodule MyModule do
|
|
Module.add_attribute __MODULE__, :custom_threshold_for_lib, 10
|
|
end
|
|
|
|
"""
|
|
def add_attribute(module, key, value) when is_atom(key) do
|
|
assert_not_compiled!(:add_attribute, module)
|
|
table = data_table_for(module)
|
|
attrs = ETS.lookup_element(table, :attributes, 2)
|
|
ETS.insert(table, { :attributes, [{key, value}|attrs] })
|
|
end
|
|
|
|
@doc """
|
|
Deletes all attributes that matches the given key.
|
|
|
|
## Examples
|
|
|
|
defmodule MyModule do
|
|
Module.add_attribute __MODULE__, :custom_threshold_for_lib, 10
|
|
Module.delete_attribute __MODULE__, :custom_threshold_for_lib
|
|
end
|
|
|
|
"""
|
|
def delete_attribute(module, key) when is_atom(key) do
|
|
assert_not_compiled!(:delete_attribute, module)
|
|
table = data_table_for(module)
|
|
attrs = ETS.lookup_element(table, :attributes, 2)
|
|
final = lc {k,v} in attrs, k != key, do: {k,v}
|
|
ETS.insert(table, { :attributes, final })
|
|
end
|
|
|
|
@doc """
|
|
Registers an attribute. This allows a developer to use the data API
|
|
but Elixir will register the data as an attribute automatically.
|
|
By default, `vsn`, `behavior` and other Erlang attributes are
|
|
automatically registered.
|
|
|
|
## Examples
|
|
|
|
defmodule MyModule do
|
|
Module.register_attribute __MODULE__, :custom_threshold_for_lib
|
|
@custom_threshold_for_lib 10
|
|
end
|
|
|
|
"""
|
|
def register_attribute(module, new) do
|
|
assert_not_compiled!(:register_attribute, module)
|
|
table = data_table_for(module)
|
|
old = ETS.lookup_element(table, :registered_attributes, 2)
|
|
ETS.insert(table, { :registered_attributes, [new|old] })
|
|
end
|
|
|
|
@doc false
|
|
# Used internally to compile documentation. This function
|
|
# is private and must be used only internally.
|
|
def compile_doc(module, line, kind, pair) do
|
|
case read_data(module, :doc) do
|
|
match: nil
|
|
# We simply discard nil
|
|
match: doc
|
|
result = add_doc(module, line, kind, pair, doc)
|
|
merge_data(module, doc: nil)
|
|
result
|
|
end
|
|
end
|
|
|
|
## Helpers
|
|
|
|
defp kind_to_entry(:def), do: :public
|
|
defp kind_to_entry(:defp), do: :private
|
|
defp kind_to_entry(:defmacro), do: :macros
|
|
|
|
defp to_char_list(list) when is_list(list), do: list
|
|
defp to_char_list(bin) when is_binary(bin), do: binary_to_list(bin)
|
|
|
|
defp data_table_for(module) do
|
|
list_to_atom Erlang.lists.concat([:d, module])
|
|
end
|
|
|
|
defp function_table_for(module) do
|
|
list_to_atom Erlang.lists.concat([:f, module])
|
|
end
|
|
|
|
defp docs_table_for(module) do
|
|
list_to_atom Erlang.lists.concat([:o, module])
|
|
end
|
|
|
|
defp assert_not_compiled!(fun, module) do
|
|
compiled?(module) ||
|
|
raise ArgumentError, message:
|
|
"could not call #{fun} on module #{module} because it was already compiled"
|
|
end
|
|
end |