util v1.1.5

View Source smerl (util v1.1.5)

Simple Metaprogramming for Erlang

Link to this section Summary

Types

args/0
error_t/1
export/0
exports/0
A list of export()s.
func_form/0
The abstract form for the function, as described in the ERTS Users' manual.
func_forms/0
A list of func_form()s.
meta_mod/0
A data structure holding the abstract representation for a module.
ok_t/1
result/1
result/2

Functions

add_func(MetaMod, Form)

Equivalent to add_func(MetaMod, Form, true).

add_func(MetaMod, Func, Export)
Add Function to MetaMod and return the new meta_mod(). If Export is true, add Function to MetaMod's exports.
compile(MetaMod)

Equivalent to compile(MetaMod, []).

compile(MetaMod, Options)

Equivalent to compile(MetaMod, [report_errprs, report_warnings, return_errors]).

curry(Form, Args)
Get the curried form for Form with Args. Here, "currying" involves replacing one or more of the function's leading arguments with predefined values.
curry(Module, Function, Arity, Args)
Curry Module:Function/Arity with the given Args.
curry(Module, Function, Arity, Args, NewName)
Curry Module:Function/Aritywith the given Args, renaming it to NewName and return the renamed form.
curry_add(MetaMod, Form, Args)
Add Form curried with Args to MetaMod.
curry_add(MetaMod, Function, Arity, Args)
Add Function/Arity curried with Args to MetaMod.
curry_add(MetaMod, Function, Arity, Args, NewName)
Curry MetaMod:Function/Arity and add it to MetaMod as NewName.
curry_add(MetaMod, Module, Function, Arity, Args, NewName)
Curry Module:Function/Arity and add it to MetaMod as NewName.
curry_replace(MetaMod, Form, Args)
Replace the function represented by Form in MetaMod with its curried form.
curry_replace(MetaMod, Function, Arity, Args)
Replace Function/Arity in MetaMod with its curried form.
embed_all(MetaMod, Values)
Apply embed_args/2 with Values to all forms in MetaMod. exports for functions whose arities change are preserved.
embed_args(Form, Vals)
Replace the arguments of the function represented by Form, where the argument's Name matches an element from Vals with the corresponding Value.
embed_args(MetaMod, Function, Arity, Values)

Equivalent to embed_args(MetaMod, Name, Arity, Values, Name).

embed_args(MetaMod, Function, Arity, Values, NewName)
Apply embed_args/2 to MetaMod:Function/Arity and add the resulting function to MetMod, after renaming it to NewName.

See also: rename/2.

extend(Parent, Child)
Add aliases for Parent's functions missing from Child to Child. The new functions in Child are shallow, i.e. they have the name and arity of the corresponding functions in Parent, but instead of implementing their logic they call the Parent functions.
extend(Parent, Child, ArityDiff)
Similar to extend/2, with the addition of ArityDiff, which indicates the difference in arities Smerl should use when figuring out which functions to generate based on the modules' exports. This is sometimes useful when calling extend/3 followed by embed_all/2.
extend(Parent, Child, ArityDiff, Options)
for_file(SrcFilePath)

Equivalent to for_file(SrcFilePath, []).

for_file(SrcFilePath, IncludePaths)

Equivalent to for_file(SrcFilePath, IncludePaths, []).

for_file(SrcFilePath, IncludePaths, Macros)
Create a meta_mod for a module from its source file.
for_module(ModuleName)

Equivalent to for_module(ModuleName, []).

for_module(ModuleName, IncludePaths)

Equivalent to for_module(ModuleName, IncludePaths, []).

for_module(ModuleName, IncludePaths, Macros)

Create a meta_mod tuple for an existing module. If ModuleName is a string, it is interpreted as a file name (this is the same as calling for_file/3). If ModuleName is an atom, Smerl attempts to find its abstract represtation either from its source file or from its .beam file directly (if it has been compiled with debug_info). If the abstract representation can't be found, this function returns an error.

get_attribute(MetaMod, Key)
Get the value of MetaMod's Key attribute.
get_export_all(MetaMod)
Get the export_all value for MetaMod.
get_exports(MetaMod)
Return the list of exports in the meta_mod.
get_forms(MetaMod)
Return the list of function forms in the meta_mod.
get_func(MetaMod, Function, Arity)
Attempt to get the func_form() for MetaMod:Function/Arity.
get_module(MetaMod)
Return the module name for the meta_mod.
has_func(MetaMod, Function, Arity)
Check whether MetaMod has a function Function/Arity.
new(Module)
Create a new meta_mod for a module with the given name.
remove_export(MetaMod, Function, Arity)
Remove an export {Function, Arity} from the list of exports in MetaMod.
remove_func(MetaMod, Function, Arity)
Try to remove Function from MetaMod. If the function exists, return the new meta_mod(). Otherwise, return MetaMod.
rename(Form, NewName)
Change the name of the function represented by Form to NewName.
replace_func(MetaMod, Function)
Replace an existing function with a new one. If a matching function doesn't exist, add Function to MetaMod. This is tantamount to calling remove_func/3 followed by add_func/2.
set_export_all(MetaMod, Value)
Set the export_all value for MetaMod.
set_exports(MetaMod, Exports)
Set the MetaMod's export list to Exports.
set_forms(MetaMod, Forms)
set_module(MetaMod, NewName)
Set the meta_mod's module name.
to_src(MetaMod)
Return the pretty-printed source code for MetaMod.
to_src(MetaMod, Filename)

Equivalent to file:write_file(Filename, to_src(MetaMod)).

Link to this section Types

Link to this type

args/0

View Source 
-type args() :: term() | [term()].
Link to this type

error_t/1

View Source 
-type error_t(Error) :: ok | {error, Error}.
Link to this type

export/0

View Source 
-type export() :: {Function :: atom(), Arity :: arity()}.
Link to this type

exports/0

View Source 
-type exports() :: [export()].
A list of export()s.
Link to this type

func_form/0

View Source 
-type func_form() :: erl_parse:abstract_form().
The abstract form for the function, as described in the ERTS Users' manual.
Link to this type

func_forms/0

View Source 
-type func_forms() :: [func_form()].
A list of func_form()s.
Link to this type

meta_mod/0

View Source 
-type meta_mod() :: #meta_mod{}.
A data structure holding the abstract representation for a module.
Link to this type

ok_t/1

View Source 
-type ok_t(Value) :: {ok, Value} | error.
Link to this type

result/1

View Source 
-type result(Value) :: result(Value, term()).
Link to this type

result/2

View Source 
-type result(Value, Error) :: {ok, Value} | {error, Error}.

Link to this section Functions

Link to this function

add_func(MetaMod, Form)

View Source 
-spec add_func(MetaMod, Form) -> result(meta_mod(), parse_error)
            when MetaMod :: meta_mod(), Form :: func_form() | string().

Equivalent to add_func(MetaMod, Form, true).

Add a new exported function to MetaMod.
Link to this function

add_func(MetaMod, Func, Export)

View Source 
-spec add_func(MetaMod, Func, Export) -> result(meta_mod(), parse_error)
            when MetaMod :: meta_mod(), Func :: func_form() | string(), Export :: boolean().
Add Function to MetaMod and return the new meta_mod(). If Export is true, add Function to MetaMod's exports.
Link to this function

compile(MetaMod)

View Source 
-spec compile(MetaMod :: meta_mod()) -> error_t(term()).

Equivalent to compile(MetaMod, []).

Compile MetaMod and load the resulting BEAM into the emulator.
Link to this function

compile(MetaMod, Options)

View Source 
-spec compile(MetaMod, Options) -> error_t(term())
           when MetaMod :: meta_mod(), Options :: [proplists:property()].

Equivalent to compile(MetaMod, [report_errprs, report_warnings, return_errors]).

Compile MetaMod and load the resulting BEAM into the emulator. Options is a list of options as described in the compile module in the Erlang documentation. If an outdir is provided, write the .beam file to it.
Link to this function

curry(Form, Args)

View Source 
-spec curry(Form :: func_form(), Args :: args()) -> result(func_form()).
Get the curried form for Form with Args. Here, "currying" involves replacing one or more of the function's leading arguments with predefined values.
Link to this function

curry(Module, Function, Arity, Args)

View Source 
-spec curry(Module, Function, Arity, Args) -> result(func_form())
         when
             Module :: module() | meta_mod(), Function :: atom(), Arity :: arity(), Args :: args().
Curry Module:Function/Arity with the given Args.
Link to this function

curry(Module, Function, Arity, Args, NewName)

View Source 
-spec curry(Module, Function, Arity, Args, NewName) -> result(func_form())
         when
             Module :: module() | meta_mod(),
             Function :: atom(),
             Arity :: arity(),
             Args :: args(),
             NewName :: atom().
Curry Module:Function/Aritywith the given Args, renaming it to NewName and return the renamed form.
Link to this function

curry_add(MetaMod, Form, Args)

View Source 
-spec curry_add(MetaMod, Form, Args) -> result(meta_mod())
             when MetaMod :: meta_mod(), Form :: func_form(), Args :: args().
Add Form curried with Args to MetaMod.
Link to this function

curry_add(MetaMod, Function, Arity, Args)

View Source 
-spec curry_add(MetaMod, Function, Arity, Args) -> result(meta_mod())
             when MetaMod :: meta_mod(), Function :: atom(), Arity :: arity(), Args :: args().
Add Function/Arity curried with Args to MetaMod.
Link to this function

curry_add(MetaMod, Function, Arity, Args, NewName)

View Source 
-spec curry_add(MetaMod, Function, Arity, Args, NewName) -> Result
             when
                 MetaMod :: meta_mod(),
                 Function :: atom(),
                 Arity :: arity(),
                 Args :: args(),
                 NewName :: atom(),
                 Result :: result(meta_mod(), parse_error).
Curry MetaMod:Function/Arity and add it to MetaMod as NewName.
Link to this function

curry_add(MetaMod, Module, Function, Arity, Args, NewName)

View Source 
-spec curry_add(MetaMod, Module, Function, Arity, Args, NewName) -> Result
             when
                 MetaMod :: meta_mod(),
                 Module :: module() | meta_mod(),
                 Function :: atom(),
                 Arity :: arity(),
                 Args :: args(),
                 NewName :: atom(),
                 Result :: result(meta_mod()).
Curry Module:Function/Arity and add it to MetaMod as NewName.
Link to this function

curry_replace(MetaMod, Form, Args)

View Source 
-spec curry_replace(MetaMod, Form, Args) -> result(meta_mod())
                 when MetaMod :: meta_mod(), Form :: func_form(), Args :: args().
Replace the function represented by Form in MetaMod with its curried form.
Link to this function

curry_replace(MetaMod, Function, Arity, Args)

View Source 
-spec curry_replace(MetaMod, Function, Arity, Args) -> result(meta_mod())
                 when MetaMod :: meta_mod(), Function :: atom(), Arity :: arity(), Args :: args().
Replace Function/Arity in MetaMod with its curried form.
Link to this function

embed_all(MetaMod, Values)

View Source 
-spec embed_all(MetaMod, Values) -> NewMod
             when
                 MetaMod :: meta_mod(),
                 Values :: [{Name :: atom(), Value :: term()}],
                 NewMod :: meta_mod().
Apply embed_args/2 with Values to all forms in MetaMod. exports for functions whose arities change are preserved.
Link to this function

embed_args(Form, Vals)

View Source 
-spec embed_args(Form, Vals) -> NewForm
              when
                  Form :: func_form(),
                  Vals :: [{Name :: atom(), Value :: term()}],
                  NewForm :: func_form().
Replace the arguments of the function represented by Form, where the argument's Name matches an element from Vals with the corresponding Value.
Link to this function

embed_args(MetaMod, Function, Arity, Values)

View Source 
-spec embed_args(MetaMod, Function, Arity, Values) -> result(meta_mod())
              when
                  MetaMod :: meta_mod(),
                  Function :: atom(),
                  Arity :: arity(),
                  Values :: proplists:proplist().

Equivalent to embed_args(MetaMod, Name, Arity, Values, Name).

Link to this function

embed_args(MetaMod, Function, Arity, Values, NewName)

View Source 
-spec embed_args(MetaMod, Function, Arity, Values, NewName) -> Result
              when
                  MetaMod :: meta_mod(),
                  Function :: atom(),
                  Arity :: arity(),
                  Values :: proplists:proplist(),
                  NewName :: atom(),
                  Result :: result(meta_mod()).
Apply embed_args/2 to MetaMod:Function/Arity and add the resulting function to MetMod, after renaming it to NewName.

See also: rename/2.

Link to this function

extend(Parent, Child)

View Source 
-spec extend(Parent, Child) -> NewChildMod
          when
              Parent :: module() | meta_mod(),
              Child :: module() | meta_mod(),
              NewChildMod :: meta_mod().
Add aliases for Parent's functions missing from Child to Child. The new functions in Child are shallow, i.e. they have the name and arity of the corresponding functions in Parent, but instead of implementing their logic they call the Parent functions.
Link to this function

extend(Parent, Child, ArityDiff)

View Source 
-spec extend(Parent, Child, ArityDiff) -> NewChildMod
          when
              Parent :: module() | meta_mod(),
              Child :: module() | meta_mod(),
              ArityDiff :: non_neg_integer(),
              NewChildMod :: meta_mod().
Similar to extend/2, with the addition of ArityDiff, which indicates the difference in arities Smerl should use when figuring out which functions to generate based on the modules' exports. This is sometimes useful when calling extend/3 followed by embed_all/2.
Link to this function

extend(Parent, Child, ArityDiff, Options)

View Source 
-spec extend(Parent, Child, ArityDiff, Options) -> NewChildMod
          when
              Parent :: module() | meta_mod(),
              Child :: module() | meta_mod(),
              ArityDiff :: non_neg_integer(),
              Options :: [proplists:property()],
              NewChildMod :: meta_mod().
Link to this function

for_file(SrcFilePath)

View Source

Equivalent to for_file(SrcFilePath, []).

Link to this function

for_file(SrcFilePath, IncludePaths)

View Source

Equivalent to for_file(SrcFilePath, IncludePaths, []).

Link to this function

for_file(SrcFilePath, IncludePaths, Macros)

View Source 
-spec for_file(SrcFilePath, IncludePaths, Macros) -> Result
            when
                SrcFilePath :: file:filename(),
                IncludePaths :: [file:filename()],
                Macros :: [{module(), atom()}],
                Result :: result(meta_mod(), invalid_module).
Create a meta_mod for a module from its source file.
Link to this function

for_module(ModuleName)

View Source

Equivalent to for_module(ModuleName, []).

Link to this function

for_module(ModuleName, IncludePaths)

View Source

Equivalent to for_module(ModuleName, IncludePaths, []).

Link to this function

for_module(ModuleName, IncludePaths, Macros)

View Source 
-spec for_module(ModuleName, IncludePaths, Macros) -> result(meta_mod)
              when
                  ModuleName :: atom() | string(),
                  IncludePaths :: [string()],
                  Macros :: [{atom(), term()}].

Create a meta_mod tuple for an existing module. If ModuleName is a string, it is interpreted as a file name (this is the same as calling for_file/3). If ModuleName is an atom, Smerl attempts to find its abstract represtation either from its source file or from its .beam file directly (if it has been compiled with debug_info). If the abstract representation can't be found, this function returns an error.

The IncludePaths argument is used when ModuleName is a file name.
Link to this function

get_attribute(MetaMod, Key)

View Source 
-spec get_attribute(MetaMod :: meta_mod(), Key :: atom()) -> result(term()).
Get the value of MetaMod's Key attribute.
Link to this function

get_export_all(MetaMod)

View Source 
-spec get_export_all(MetaMod :: meta_mod()) -> boolean().
Get the export_all value for MetaMod.
Link to this function

get_exports(MetaMod)

View Source 
-spec get_exports(MetaMod :: meta_mod()) -> exports().
Return the list of exports in the meta_mod.
Link to this function

get_forms(MetaMod)

View Source 
-spec get_forms(MetaMod :: meta_mod()) -> func_forms().
Return the list of function forms in the meta_mod.
Link to this function

get_func(MetaMod, Function, Arity)

View Source 
-spec get_func(MetaMod, Function, Arity) -> result(func_form())
            when MetaMod :: meta_mod() | module(), Function :: atom(), Arity :: arity().
Attempt to get the func_form() for MetaMod:Function/Arity.
Link to this function

get_module(MetaMod)

View Source 
-spec get_module(MetaMod :: meta_mod()) -> module().
Return the module name for the meta_mod.
Link to this function

has_func(MetaMod, Function, Arity)

View Source 
-spec has_func(MetaMod, Function, Arity) -> boolean()
            when MetaMod :: meta_mod(), Function :: atom(), Arity :: arity().
Check whether MetaMod has a function Function/Arity.
Link to this function

new(Module)

View Source 
-spec new(Module :: module()) -> meta_mod().
Create a new meta_mod for a module with the given name.
Link to this function

remove_export(MetaMod, Function, Arity)

View Source 
-spec remove_export(MetaMod, Function, Arity) -> NewMod
                 when
                     MetaMod :: meta_mod(),
                     Function :: atom(),
                     Arity :: arity(),
                     NewMod :: meta_mod().
Remove an export {Function, Arity} from the list of exports in MetaMod.
Link to this function

remove_func(MetaMod, Function, Arity)

View Source 
-spec remove_func(MetaMod, Function, Arity) -> NewMod
               when
                   MetaMod :: meta_mod(),
                   Function :: atom(),
                   Arity :: arity(),
                   NewMod :: meta_mod().
Try to remove Function from MetaMod. If the function exists, return the new meta_mod(). Otherwise, return MetaMod.
Link to this function

rename(Form, NewName)

View Source 
-spec rename(Form :: func_form(), NewName :: atom()) -> func_form().
Change the name of the function represented by Form to NewName.
Link to this function

replace_func(MetaMod, Function)

View Source 
-spec replace_func(MetaMod, Function) -> result(meta_mod())
                when MetaMod :: meta_mod(), Function :: string() | func_form().
Replace an existing function with a new one. If a matching function doesn't exist, add Function to MetaMod. This is tantamount to calling remove_func/3 followed by add_func/2.
Link to this function

set_export_all(MetaMod, Value)

View Source 
-spec set_export_all(MetaMod, Value) -> NewMod
                  when MetaMod :: meta_mod(), Value :: boolean(), NewMod :: meta_mod().
Set the export_all value for MetaMod.
Link to this function

set_exports(MetaMod, Exports)

View Source 
-spec set_exports(MetaMod, Exports) -> NewMod
               when MetaMod :: meta_mod(), Exports :: exports(), NewMod :: meta_mod().
Set the MetaMod's export list to Exports.
Link to this function

set_forms(MetaMod, Forms)

View Source 
-spec set_forms(MetaMod, Forms) -> NewMod
             when MetaMod :: meta_mod(), Forms :: func_forms(), NewMod :: meta_mod().
Link to this function

set_module(MetaMod, NewName)

View Source 
-spec set_module(MetaMod, NewName) -> NewMod
              when MetaMod :: meta_mod(), NewName :: module(), NewMod :: meta_mod().
Set the meta_mod's module name.
Link to this function

to_src(MetaMod)

View Source 
-spec to_src(MetaMod :: meta_mod()) -> Source :: string().
Return the pretty-printed source code for MetaMod.
Link to this function

to_src(MetaMod, Filename)

View Source 
-spec to_src(MetaMod, Filename) -> error_t(term())
          when MetaMod :: meta_mod(), Filename :: file:filename().

Equivalent to file:write_file(Filename, to_src(MetaMod)).