Zedex

Version: 0.0.1-prerelease

Warning

This is VERY early days of this project. I would not recommend using this for anything serious at this time.

Table of Contents

1. About The Project
   • Built With
2. Getting Started
3. Usage
4. License

About the Project

This library allows patching and replacing functions in existing modules with your own, effectively turning them into zombies (or zeds) 🧟. This is useful if you need to hook into some existing code that has no other way to be modified.

Caution

You don't want to use this library in live production code. Its original intent is to help hook into low-level Erlang operations for testing and experimentation purposes.

Built With

(back to top)

Getting Started

Add add Zedex to your mix.exs dependencies:

def deps do
  [
    {:zedex, git: "[email protected]:chriskdon/zedex.git", branch: "main"}
  ]
end

Note

Eventually this will be published to Hex once there is a minimal feature set.

Run mix deps.get.

(back to top)

Usage

# replace :random.uniform/1 and :random with MyRandom.uniform/1
:ok = Zedex.replace([
  {{:random, :uniform, 1}, {MyRandom, :constant_uniform, 1}},
  {{:rand, :uniform, 1}, {MyRandom, :constant_uniform, 1}},
])

:ok = Zedex.replace_with({:random, :uniform, 1}, {MyRandom, :constant_uniform, 1})

# replace :erlang.uniform/1 with anonymous function
:ok = Zedex.replace_with({:random, :uniform, 1}, fn n ->
  1
end)

# reset all modules back to their original versions
:ok = Zedex.reset()

# Replace function calls instead of the function implementation.
#
# ⚠ Replacing calls is generally not recommended as any changes to the underlying
# code being replaced could break the intended behaviour. It mainly exists to
# replace NIFs and BIFs (e.g. send) that can't normally be hooked into by
# replacing the function directly.

# Replace calls in GenServer.call/3 to :gen.call/4
# with ReplacementModule.capture_call/4.
:ok = Zedex.Danger.replace_calls(
  {GenServer, :call, 3},
  {:gen, :call, 4},
  {ReplacementModule, :capture_call, 4}
)

# or use an anonymous function
:ok = Zedex.Danger.replace_calls(
  {GenServer, :call, 3},
  {:gen, :call, 4},
  fn server, label, msg, timeout  ->
    Logger.info("#{inspect(self())} sent #{inspect(msg)} to #{inspect(server)}")

    # Perform the real call
    :gen.call(server, label, msg, timeout)
  end
)

Run mix docs --open for the complete documentation.

(back to top)

License

Distributed under the MIT license. See LICENSE.txt for more information.

(back to top)