hooks (hooks v3.0.0)
View SourceGeneric hooks system for Erlang applications.
Overview
The hooks
module provides a flexible and efficient hooks system that allows you to create
extension points in your application. Hooks enable you to register multiple functions that
will be called at specific points in your code, similar to events or callbacks but with
more flexibility.
Features
- Priority-based execution order
- Multiple execution strategies (run, fold, all, all_till_ok, only)
- Plugin system with automatic hook registration
- Efficient storage using persistent_term
- Support for deferred initialization
Examples
Basic Hook Registration
%% Register a hook function
ok = hooks:reg(on_user_login, my_module, log_login, 2, 10).
%% Run the hook
ok = hooks:run(on_user_login, [UserId, Timestamp]).
%% Unregister the hook
ok = hooks:unreg(on_user_login, my_module, log_login, 2).
Using Plugins
%% Enable a plugin that registers its own hooks
ok = hooks:enable_plugin(my_plugin).
%% Disable the plugin and unregister its hooks
ok = hooks:disable_plugin(my_plugin).
Different Execution Strategies
%% Run all hooks until one returns 'stop'
ok = hooks:run(before_save, [Data]).
%% Fold over hooks with an accumulator
Result = hooks:run_fold(transform_data, [Input], InitialAcc).
%% Get all results from all hooks
Results = hooks:all(validate_data, [Data]).
%% Run until one returns ok or {ok, Value}
case hooks:all_till_ok(authenticate, [User, Pass]) of
ok -> authenticated;
{ok, UserInfo} -> {authenticated, UserInfo};
{error, Reasons} -> {failed, Reasons}
end.
Configuration
The hooks application supports the following configuration options:
{wait_for_proc, atom()}
- Wait for a registered process before becoming ready
Since
1.0.0
Summary
Functions
Register a function for a specific hook name.
Types
-type hook() :: {atom(), atom(), non_neg_integer()} | {atom(), atom(), non_neg_integer(), integer()}.
-type hookname() :: any().
Functions
-spec disable_plugin(Application :: atom()) -> ok.
-spec munreg(Hooks :: hooks()) -> ok.
-spec reg(Module :: atom(), Fun :: atom(), Arity :: non_neg_integer()) -> ok | {error, term()}.
-spec reg(HookName :: hookname(), Module :: atom(), Fun :: atom(), Arity :: non_neg_integer()) -> ok | {error, term()}.
Register a function for a specific hook name.
Parameters
HookName
- The hook identifierModule
- The module containing the hook functionFun
- The function nameArity
- The function arity
Returns
ok
- Registration successful{error, term()}
- Registration failed
Examples
%% Register a function for the 'before_save' hook
ok = hooks:reg(before_save, validator, check_data, 1).
Since
1.0.0
-spec unreg(Module :: atom(), Function :: atom(), Arity :: non_neg_integer()) -> ok.
-spec unreg(HookName :: hookname(), Module :: atom(), Fun :: atom(), Arity :: non_neg_integer()) -> ok.
-spec unreg(HookName :: hookname(), Module :: atom(), Fun :: atom(), Arity :: non_neg_integer(), Priority :: integer()) -> ok.