thegeorge / power_shell

Erlang shell with advanced features: evaluating non-exported functions and shortcuts for frequently used functions.

power_shell

Advanced system-wide Erlang shell capabilities. Evaluates Erlang code loaded from the module debug information, or source file.

Erlang/OTP versions supported: tested with 21, 22, 23, 24, and 25.

License

power_shell license is available in the LICENSE.md file in the root directory of this source tree.

Installation

For Elixir, the package can be installed by adding power_shell to your list of dependencies in mix.exs:

def deps do
  [
    {:power_shell, "~> 1.2.0"}
  ]
end

For Erlang, the package can be installed by adding power_shell to your list of dependencies in rebar.config:

{deps, [
    {power_shell, "1.2.0"}
]}.

Documentation can be found at hexdocs.pm/power_shell.

Usage

power_shell can be used as an application, and in form of a library.

When started as application, power_shell examines shell_integration configuration parameter. It can be set to shell_default, or user_default.

Depending on the parameter, power_shell can load itself as user_default module (if none was loaded before), or add proxy calls to already loaded user_default module.

Evaluating non-exported functions

Enter the following in the shell to evaluate function Fun in module Mod. The function does not need to be exported.

power_shell:eval(Mod, Fun, [Arg1, Arg2, Arg3]).

If module Mod is currently loaded, power_shell will try to locate corresponding *.beam file, load debug info chunk, and evaluate function Fun with supplied arguments.

If module is not loaded, but *.beam file can be found, power_shell does not attempt to load it.

However, if there is a remote (fully qualified) call, Erlang VM (BEAM) will load the file automatically.

When shell integration (injection) is enabled, evaluating non-exported functions is simplified to just:

eval(Mod, Fun, [Args]).

Debugging shortcuts

Available with shell integration.

Coverage Analysis Tool for Erlang

Modules that were patched by cover application are also supported.

If a module was cover_compiled, and it is being evaluated with power_shell:eval, coverage analysis works as expected.

-on_load() attribute support

To preserve compatibility with earlier versions, power_shell does not execute -on_load() by default.

To change this behaviour, set skip_on_load application variable to false:

ok = application:load(power_shell),
ok = application:set_env(power_shell, skip_on_load, false).

Recompiling and hot-loading modules with extra functions exported

Starting with version 1.2.0, power_shell can recompile an existing module exporting all or selected functions.

Use power_shell:export(Mod) to export all functions.

This may be used in conjunction with Common Test suites, allowing for white-box testing of functions that should not be exported in production code. Example:

my_case(Config) when is_list(Config) ->
    Old = power_shell:export(prod_module),
    WhiteBoxRet = prod_module:not_exported_fun(123),
    power_shell:revert(Old).

For reliable Common Test execution export/1,2,3 start a linked process that will reload the original code upon termination.

This allows to avoid failing other test cases that do not expect extra exports available.

Configuration

During application startup, power_shell examines following application environment variables:

• cache_code :: boolean() (default false) - start code cache process. This process keeps decompiled beam files in memory, speeding up execution if code does not change.
• shell_integration :: shell_default | user_default (default user_default) - apply shell integration, making power_shell:eval(Mod, Fun, Args) available in shell, via eval(Mod, Fun, Args).
• skip_on_load :: boolean() (default true) - skip -on_load() execution when decompiling beam (or loading source).

It is possible to supply values using sys.config file, or via command line when starting BEAM:

erl -power_shell cache_code true