View Source merlin_lib (merlin v2.0.1)

Helpers for working with erl_syntax:syntaxTree/0. Similar to erl_syntax_lib, but with a different set of helpers, and a preference for returning maps over proplists.

Link to this section Summary

Types

Represents the three types of bindings.
env
Bindings from the surrounding scope, i.e. a fun's closure.
bound
Bindings with value.
free
Bindings without a value. It's a compile time error to try to access them.
Represents the current bindings for a form
Reprensent a single builtin annotation property.
The different types of builtin annotations.

Represents a list of annotations.

Copied from erl_syntax
A bit dirty to know about the internal structure like this, but erl_syntax:syntaxTree/0 also includes the vanilla AST and dialyser doesn't always approve of that.
Represents a set() of variables.
Represents either of the two builtin set data structures in OTP.

Functions

Adds the given binding to the existing ones.

See also: add_bindings/2.

Adds the given bindings to the existing ones. Accepts the same input as get_bindings/1.

Same as add_new_variable/3 with default prefix and suffix.

See also: new_variable/3.

Same as add_new_variable/3 with the given prefix and default suffix.

See also: new_variable/3.

Creates a new variable using new_variable/3 and adds it to the given form or bindings.

See also: new_variable/3.

Same as new_variables/3 with default prefix and suffix.

See also: new_variable/3.

Same as new_variable/3 with the given prefix and default suffix.

See also: new_variable/3.

Creates Total number of new variables using new_variables/4 and adds it to the given form or bindings.

See also: new_variable/3.

Annotates the given form or forms using erl_syntax_lib:annotate_bindings/2.

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

Returns the filename for the first -file attribute in Forms, or "" if not found.
Returns the path to the source for the given module, or undefined if it can't be found.
Callback for formatting error messages from this module

See also: erl_parse:format_error/1.

Callback for formatting error messages from this module.

Returns the annotation for the given form, or raises {badkey, Annotation} if not found.
Returns the annotation for the given form, or Default if not found.
Returns all annotations associated with the given Form as a map.
Returns the argument to the first module attribute with the given name, or Default if not found.
Returns all attributes with the given name in the given list of forms or subtrees of the given form.

Returns the arguments to all attributes with the given name in the given list of forms or subtrees of the given form.

Get the type of the given binding in the given form. Preferring bound over env over free.

See also: erl_syntax_lib:annotate_bindings/2.

Get all bindings for the given value. Can be a set of annotations, see get_annotations/1, or merlin:ast() form from which those annotations are taken.
Returns the bindings associated of the given Type

Get all bindings associated with the given Form.

Returns a error info with the given reason and location taken from the second argument. If it is a stacktrace, the latter is taken from the first frame. Otherwise it is assumed to be a syntax node and its location is used.
Returns the module name for the first -module attribute in Forms, or '' if not found.
Returns the form for the first -module attribute in Forms, or undefined if not found.
Same as new_variable/3 with default prefix and suffix.
Same as new_variable/3 with the given prefix and default suffix.

Returns a new variable guaranteed not to be in the given bindings, or the bindings associated with the given form.

Same as new_variables/4 with default prefix and suffix.
Same as new_variables/4 with the given prefix and default suffix.
Same as new_variables/4 with the given prefix and suffix.

Returns the given form without the given annotation.

Returns the given form with the given annotation set to the given value. When given an erl_anno annotation and erl_parse form, it returns a erl_parse form, otherwise an erl_syntax form.

Returns the given form with the given annotations.

Returns the given form with the given annotations merged in. It separates erl_anno annotations from user once, which means if you set line or file, you update the position/location of the form, else you are setting an erl_syntax user annotation.

See also: erl_anno, erl_syntax:get_ann/1, erl_syntax:get_pos/1.

Updates the given form using the given groups or subtrees of another form.

Returns the value of the given literal node as an Erlang term.

Link to this section Types

-type binding_type() :: env | bound | free.
Represents the three types of bindings.
env
Bindings from the surrounding scope, i.e. a fun's closure.
bound
Bindings with value.
free
Bindings without a value. It's a compile time error to try to access them.
-type bindings() ::
    #{env := ordsets:ordset(variable()),
      bound := ordsets:ordset(variable()),
      free := ordsets:ordset(variable())}.
Represents the current bindings for a form
-type bindings_or_form() :: bindings() | merlin:ast().
-type erl_annotation() ::
    {line, erl_anno:line()} |
    {column, erl_anno:column()} |
    {file, file:filename_all()} |
    {generated, boolean()} |
    {location, erl_anno:location()} |
    {record, boolean()} |
    {text, string()}.
Reprensent a single builtin annotation property.
-type erl_annotation_key() :: line | column | file | generated | location | record | text.
The different types of builtin annotations.
-type erl_annotations() :: [erl_annotation()].

Represents a list of annotations.

This is also the internal format of erl_anno once more then erl_anno:line() and/or erl_anno:line() has been set.
Copied from erl_syntax
-type erl_syntax_ast() :: {tree, any(), any(), any()} | {wrapper, any(), any(), any()}.
A bit dirty to know about the internal structure like this, but erl_syntax:syntaxTree/0 also includes the vanilla AST and dialyser doesn't always approve of that.
-type set() :: set(variable()).
Represents a set() of variables.
-type set(T) :: sets:set(T) | ordsets:ordset(T).
Represents either of the two builtin set data structures in OTP.
-type variable() :: atom() | merlin:ast().

Link to this section Functions

Link to this function

add_binding(BindingsOrForm, NewBinding)

View Source
-spec add_binding(bindings(), variable()) -> bindings();
           (merlin:ast(), variable()) -> erl_syntax_ast().
Adds the given binding to the existing ones.

See also: add_bindings/2.

Link to this function

add_bindings(Bindings, NewBindings)

View Source
-spec add_bindings(bindings(), set()) -> bindings();
            (merlin:ast(), set()) -> erl_syntax_ast().

Adds the given bindings to the existing ones. Accepts the same input as get_bindings/1.

When given a form, it updates the bindings on that form, see merlin:annotate/2 for more info.

When given a map of bindings as returned by get_bindings_with_type/1, it updates the free and bound fields as appropriate.
Link to this function

add_new_variable(BindingsOrForm)

View Source
-spec add_new_variable(BindingsOrForm) -> {variable(), BindingsOrForm}
                    when BindingsOrForm :: bindings_or_form().
Same as add_new_variable/3 with default prefix and suffix.

See also: new_variable/3.

Link to this function

add_new_variable(BindingsOrForm, Prefix)

View Source
-spec add_new_variable(BindingsOrForm, string()) -> {variable(), BindingsOrForm}
                    when BindingsOrForm :: bindings_or_form().
Same as add_new_variable/3 with the given prefix and default suffix.

See also: new_variable/3.

Link to this function

add_new_variable(BindingsOrForm, Prefix, Suffix)

View Source
-spec add_new_variable(BindingsOrForm, string(), string()) -> {variable(), BindingsOrForm}
                    when BindingsOrForm :: bindings_or_form().
Creates a new variable using new_variable/3 and adds it to the given form or bindings.

See also: new_variable/3.

Link to this function

add_new_variables(BindingsOrForm, Total)

View Source
-spec add_new_variables(BindingsOrForm, pos_integer()) -> {[variable()], BindingsOrForm}
                     when BindingsOrForm :: bindings_or_form().
Same as new_variables/3 with default prefix and suffix.

See also: new_variable/3.

Link to this function

add_new_variables(BindingsOrForm, Total, Prefix)

View Source
-spec add_new_variables(BindingsOrForm, pos_integer(), string()) -> {[variable()], BindingsOrForm}
                     when BindingsOrForm :: bindings_or_form().
Same as new_variable/3 with the given prefix and default suffix.

See also: new_variable/3.

Link to this function

add_new_variables(BindingsOrForm, Total, Prefix, Suffix)

View Source
-spec add_new_variables(BindingsOrForm, pos_integer(), string(), string()) ->
                     {[variable()], BindingsOrForm}
                     when BindingsOrForm :: bindings_or_form().
Creates Total number of new variables using new_variables/4 and adds it to the given form or bindings.

See also: new_variable/3.

Link to this function

annotate_bindings(Forms0)

View Source
-spec annotate_bindings(merlin:ast() | [merlin:ast()]) -> merlin:ast().

Annotates the given form or forms using erl_syntax_lib:annotate_bindings/2.

If given a form, it returns the same with the annotated bindings. If given a list of forms, a form list is returned instead.

It tries to find the env variables from the given form, or first form if given a list of forms. If none can be found it assumes there's no env variables.
Link to this function

export(Forms, FunctionsToExport)

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

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

If the -module attribute is missing, the -export is prepended to the given forms.

If it's available, the -export is inserted just after the -module. In addition, if the -module attribute form as an analysis annotation, i.e. from merlin:annotate/2, then it is used to avoid re-exporting any functions already exported.

See also: annotate_bindings/1, get_bindings/1.

-spec file([merlin:ast()]) -> string().
Returns the filename for the first -file attribute in Forms, or "" if not 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 format_error(term()) -> string().
Callback for formatting error messages from this module

See also: erl_parse:format_error/1.

-spec format_error(Reason, erlang:stacktrace()) -> ErrorInfo
                when
                    Reason :: term(), ErrorInfo :: #{pos_integer() | general | reason => string()}.

Callback for formatting error messages from this module.

See EEP 54
Link to this function

get_annotation(Form, Annotation)

View Source
-spec get_annotation(merlin:ast(), atom()) -> term().
Returns the annotation for the given form, or raises {badkey, Annotation} if not found.
Link to this function

get_annotation(Form, Annotation, Default)

View Source
-spec get_annotation(merlin:ast(), atom(), Default) -> Default.
Returns the annotation for the given form, or Default if not found.
-spec get_annotations(merlin:ast()) -> #{atom() := term()}.
Returns all annotations associated with the given Form as a map.
Link to this function

get_attribute(Tree, Name, Default)

View Source
-spec get_attribute(merlin:ast() | [merlin:ast()], atom(), term()) -> term().
Returns the argument to the first module attribute with the given name, or Default if not found.
Link to this function

get_attribute_forms(Tree, Name)

View Source
-spec get_attribute_forms(merlin:ast() | [merlin:ast()], atom()) -> merlin:ast().
Returns all attributes with the given name in the given list of forms or subtrees of the given form.
Link to this function

get_attributes(Tree, Name)

View Source
-spec get_attributes(merlin:ast() | [merlin:ast()], atom()) -> term().

Returns the arguments to all attributes with the given name in the given list of forms or subtrees of the given form.

Returns the empty list if no such attributes are found.
Link to this function

get_binding_type(Form, Name)

View Source
-spec get_binding_type(bindings_or_form(), atom()) -> bound | env | free | unknown.
Get the type of the given binding in the given form. Preferring bound over env over free.

See also: erl_syntax_lib:annotate_bindings/2.

-spec get_bindings(bindings_or_form()) -> ordsets:ordset(atom()).
Get all bindings for the given value. Can be a set of annotations, see get_annotations/1, or merlin:ast() form from which those annotations are taken.
Link to this function

get_bindings_by_type(Bindings, Type)

View Source
-spec get_bindings_by_type(bindings_or_form(), binding_type()) -> ordsets:ordset(atom()).
Returns the bindings associated of the given Type
Link to this function

get_bindings_with_type(Form)

View Source
-spec get_bindings_with_type(bindings_or_form()) -> #{variable() := binding_type()}.

Get all bindings associated with the given Form.

Returns a map from binding name to kind, preferring bound over env over free.

See also: erl_syntax_lib:annotate_bindings/2.

Link to this function

into_error_marker(Reason, Node)

View Source
-spec into_error_marker(Reason, Stacktrace | Node) -> merlin:error_marker()
                     when
                         Reason :: term(),
                         Stacktrace :: [{module(), atom(), arity(), [{atom(), term()}]}],
                         Node :: merlin:ast().
Returns a error info with the given reason and location taken from the second argument. If it is a stacktrace, the latter is taken from the first frame. Otherwise it is assumed to be a syntax node and its location is used.
-spec module([merlin:ast()]) -> module() | ''.
Returns the module name for the first -module attribute in Forms, or '' if not found.
-spec module_form([merlin:ast()]) -> merlin:ast() | undefined.
Returns the form for the first -module attribute in Forms, or undefined if not found.
Link to this function

new_variable(BindingsOrForm)

View Source
-spec new_variable(bindings_or_form()) -> variable().
Same as new_variable/3 with default prefix and suffix.
Link to this function

new_variable(BindingsOrForm, Prefix)

View Source
-spec new_variable(bindings_or_form(), string()) -> variable().
Same as new_variable/3 with the given prefix and default suffix.
Link to this function

new_variable(BindingsOrForm, Prefix, Suffix)

View Source
-spec new_variable(bindings_or_form(), string(), string()) -> variable().

Returns a new variable guaranteed not to be in the given bindings, or the bindings associated with the given form.

If given a set of existing bindings, it will return an atom, if given a form it will return a new variable. That variable will have the generated flag set.

The resulting variable will be on the format Prefix<N>Suffix, where N is some small number. Prefix defaults to __Var, and suffix to __.

If TEST is set during compilation, the numbers will be deterministically increment from 1, otherwise they are random.

See also: erl_syntax_lib:new_variable_name/1.

-spec new_variables(pos_integer()) -> ordsets:ordset(variable()).
Same as new_variables/4 with default prefix and suffix.
Link to this function

new_variables(BindingsOrForm, Total)

View Source
-spec new_variables(bindings_or_form(), pos_integer()) -> ordsets:ordset(variable()).
Same as new_variables/4 with the given prefix and default suffix.
Link to this function

new_variables(BindingsOrForm, Total, Prefix)

View Source
-spec new_variables(bindings_or_form(), pos_integer(), string()) -> ordsets:ordset(variable()).
Same as new_variables/4 with the given prefix and suffix.
Link to this function

new_variables(BindingsOrForm, Total, Prefix, Suffix)

View Source
-spec new_variables(bindings_or_form(), pos_integer(), string(), string()) -> ordsets:ordset(variable()).
Returns Total number of new variables like new_variable/3.

See also: erl_syntax_lib:new_variable_names/3.

Link to this function

remove_annotation(Form, Annotation)

View Source
-spec remove_annotation(merlin:ast(), atom()) -> merlin:ast().

Returns the given form without the given annotation.

You may not remove the line, as it must always be present. You may remove annotations that are not present, if which case the original form is returned.
Link to this function

set_annotation(Form, Annotation, Value)

View Source
-spec set_annotation(merlin:ast(), atom(), term()) -> merlin:ast().
Returns the given form with the given annotation set to the given value. When given an erl_anno annotation and erl_parse form, it returns a erl_parse form, otherwise an erl_syntax form.
Link to this function

set_annotations(Form0, Annotations)

View Source
-spec set_annotations(merlin:ast(), #{atom() := term()}) -> merlin:ast().

Returns the given form with the given annotations.

These may be erl_parse annotations, user annotations, or a mix of both. The given annotations overwrite any already present. To preseve existing ones use update_annotations/2 instead.
Link to this function

update_annotations(Form0, NewAnnotations)

View Source
-spec update_annotations(merlin:ast(), #{atom() := term()}) -> erl_syntax_ast().
Returns the given form with the given annotations merged in. It separates erl_anno annotations from user once, which means if you set line or file, you update the position/location of the form, else you are setting an erl_syntax user annotation.

See also: erl_anno, erl_syntax:get_ann/1, erl_syntax:get_pos/1.

Link to this function

update_tree(Node, Groups)

View Source
-spec update_tree(merlin:ast(), [[merlin:ast()]] | merlin:ast()) -> merlin:ast().

Updates the given form using the given groups or subtrees of another form.

This is a generalisation of erl_syntax:update_tree/2.
-spec value(merlin:ast()) -> term().

Returns the value of the given literal node as an Erlang term.

Raises {badvalue, Node} if the given Node is not an literal node.