View Source merlin_module (merlin v3.0.0)

Helpers for working with forms representing a module.

They also work with lists of pretty much any node, but most makes only sense if you have a list of forms representing a module.

Summary

Types

Represents a function name as returned by erl_syntax_lib:analyze_forms/1.

Represents a list of forms.

Represents a FunctionName/Arity pair.

Functions

Similar to erl_syntax_lib:analyze_forms/1 with some differences noted below.

Same as analyze/1, but also extracts and appends any inline -compile options to the given one.

Annotate the given module forms according to the given options.

Returns the given Forms with an -export attribute for the given functions.

Returns the filename for the first -file attribute in Forms, or none if no such attribute is found.
Returns the path to the source for the given module, or undefined if it can't be found.
Returns the line number for the first -file attribute in Forms, or none if no such attribute is found.
Returns the module name for the first -module attribute in Forms, or '' if not found.

Types

-type analysis() ::
    #{attributes :=
          #{spec =>
                #{function_name() :=
                      {Arguments :: [merlin:ast()],
                       Guard :: none | merlin:ast(),
                       Return :: merlin:ast()}},
            type => #{function_name() := {TypeArguments :: [merlin:ast()], Type :: merlin:ast()}},
            opaque =>
                #{function_name() := {TypeArguments :: [merlin:ast()], Type :: merlin:ast()}},
            compile => [compile:option()],
            AttributeName :: atom() => AttributeArguments :: [term()]},
      exports := ordsets:ordset(extended_function_name()),
      export_types := ordsets:ordset(function_name()),
      file := string(),
      functions := ordsets:ordset(function_name()),
      imports := #{module() := ordsets:ordset(extended_function_name())},
      module_imports := ordsets:ordset(module()),
      records :=
          #{RecordTag :: atom() :=
                #{Field :: atom() := {Default :: none | merlin:ast(), Type :: none | merlin:ast()}}},
      module => module(),
      errors => [merlin:ast()],
      warnings => [merlin:ast()]}.
Link to this type

extended_function_name/0

View Source
-type extended_function_name() :: atom() | {atom(), arity()} | {module(), atom()}.
Represents a function name as returned by erl_syntax_lib:analyze_forms/1.
-type forms() :: [merlin:ast()].

Represents a list of forms.

That is, a list of nodes that represents top level constructs. For example an attribute (-module) or a function definition.

A good rule of thumb is to think top level stuff that ends with . (period).
-type function_name() :: {atom(), arity()}.
Represents a FunctionName/Arity pair.

Functions

-spec analyze([merlin:ast()]) -> analysis().

Similar to erl_syntax_lib:analyze_forms/1 with some differences noted below.

First off it returns maps instead of lists when possible, all fields except module are present. The latter is left alone to make it easy to determine if the module attribute is missing. There's a couple of extra fields, namely file with the value of the first -file attribute or "", and export_types as an analogue of exports but for -export_type.

The attributes are returned as a map from attribute name to a list of attribute nodes, except for spec, type and opaque. These are returned as map from {Function, Arity} to a simplified form of their attribute arguments.

Finally, unlike erl_syntax_lib:analyze_forms/1, this guarantees that most lists are sorted and contain no duplicates. This is accomplished by turning them into ordsets.

See also: analysis().

Link to this function

analyze(ModuleForms, Options)

View Source
-spec analyze([merlin:ast()], [compile:option()]) -> {analysis(), [compile:option()]}.
Same as analyze/1, but also extracts and appends any inline -compile options to the given one.
-spec annotate([merlin:ast()]) -> merlin:parse_transform_return().

Equivalent to annotate(ModuleForms, [bindings, file, resolve_calls, resolve_types]).

Link to this function

annotate(ModuleForms, Options)

View Source
-spec annotate(ModuleForms, Options) -> merlin:parse_transform_return(ModuleForms)
            when
                ModuleForms :: [merlin:ast()],
                Options :: [Option | {Option, boolean()}],
                Option :: bindings | file | resolve_calls | resolve_types.

Annotate the given module forms according to the given options.

It always annotates each function definition with a is_exportedannotation.

bindings
See erl_syntax_lib:annotate_bindings/2
compile
The analysis contains a compile key that merges then given compile options with all -compile attributes in ModuleForms. See analyze/2
file
Each node is annotated with the current file, as determined by the most recent -file attribute.
resolve_calls
Resolves local and remote calls according to the -import attributes, if any. For all successfully resolved calls, this sets both a module and is_exportedannotation on the application node.
resolve_types
Marks exported local types with is_exportedannotation on user_type_application nodes.
Link to this function

export(Forms, FunctionsToExport)

View Source
-spec export(forms(), [{atom(), arity()}]) -> forms().

Returns the given Forms with an -export attribute for the given functions.

If the -module attribute is present in the given Forms, then the -export is inserted just after the -module. In addition, if the -module attribute form has an analysis annotation, i.e. from annotate/2, then it is used to avoid re-exporting any functions already exported.

Otherwise the -export is prepended to the given forms.
-spec file([merlin:ast()]) -> file:filename().
Returns the filename for the first -file attribute in Forms, or none if no such attribute is found.
-spec find_source(module()) -> file:filename() | undefined.
Returns the path to the source for the given module, or undefined if it can't be found.
-spec line([merlin:ast()]) -> erl_anno:line().
Returns the line number for the first -file attribute in Forms, or none if no such attribute is found.
-spec name([merlin:ast()]) -> module() | ''.
Returns the module name for the first -module attribute in Forms, or '' if not found.