{"id":13561972,"url":"https://github.com/benoitc/hooks","last_synced_at":"2025-03-22T08:31:05.446Z","repository":{"id":57505340,"uuid":"45421509","full_name":"benoitc/hooks","owner":"benoitc","description":"generic plugin \u0026 hook system for Erlang applications","archived":false,"fork":false,"pushed_at":"2020-03-05T12:25:05.000Z","size":56,"stargazers_count":71,"open_issues_count":2,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-17T11:52:33.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benoitc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-02T20:55:33.000Z","updated_at":"2024-09-12T12:37:44.000Z","dependencies_parsed_at":"2022-09-26T17:51:25.137Z","dependency_job_id":null,"html_url":"https://github.com/benoitc/hooks","commit_stats":null,"previous_names":["barrel-db/hooks"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fhooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fhooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fhooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fhooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benoitc","download_url":"https://codeload.github.com/benoitc/hooks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244931480,"owners_count":20534007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:03.188Z","updated_at":"2025-03-22T08:31:05.168Z","avatar_url":"https://github.com/benoitc.png","language":"Erlang","readme":"\n\n# hooks - Generic Hooks system for Erlang and Elixir pplications #\n\nCopyright (c) 2015-2017 Benoit Chesneau.\n\n__Version:__ 2.1.0\n\n# hooks\n\n`hooks` is a generic Hooks system for **Erlang** applications. It allows you to\naugment your application by adding hooks to your application aka\n[Hooking](https://en.wikipedia.org/wiki/Hooking). Hooks can also be [used easily\nwith Elixir applications](#usage-in-elixir-applications).\n\n[![Build Status](https://travis-ci.org/barrel-db/hooks.png?branch=master)](https://travis-ci.org/barrel-db/hooks)\n[![Hex pm](http://img.shields.io/hexpm/v/hooks.svg?style=flat)](https://hex.pm/packages/hooks)\n\nMain Features are:\n\n- Handle module hooks\n- Basic plugin system\n- Registered hooks are exported as functions in a dynamically compiled erlang module . It allows us to share the list of registered hooks between every process of your application without message passing. It is also memory efficient and minimize locking.\n\n## Usage in Erlang Applications\n\nFull application API is available in [`hooks`](http://github.com/barrel-db/hooks/blob/master/doc/hooks.md) .\n\n### adding hooks manually\n\nYour application can add hooks using the following methods\n\n- `hooks:reg/{3, 4, 5}` to register a hook from a module\n- `hook:unreg/{3, 5, 5}` to unregister a hook.\n\n```\nok = hooks:reg(a, ?MODULE, hook_add, 1, 10),\nok = hooks:reg(a, ?MODULE, hook_add2, 1, 0),\n```\n\n### add multiple hooks\n\n- `hook:mreg/1`: to register multiple hooks\n- `hooks:munreg/1`: to register multiple hooks\n\nEx:\n\n```\nHooks = [{a, [{?MODULE, hook1, 0},\n              {?MODULE, hook2, 0}]},\n         {b, [{?MODULE, hook1, 2},\n              {?MODULE, hook2, 2}]},\n         {c, [{?MODULE, hook_add, 1},\n              {?MODULE, hook_add1, 1}]}],\n%% register multiple hooks\nok = hooks:mreg(Hooks),\n%% unregister multiple hooks\nok = hooks:munreg(Hooks)\n```\n\n### Enable/Disable Plugins\n\nPlugins are simple Erlang applications that exposes hooks. A plugin can be enabled to your application using `hooks:enable_plugin/{1,2}` and disabled using `hooks:disable_plugin/1` . When enabled the application and its dependencies are started (if not already stared) and exposed hooks are registered.\n\nTo expose the hooks,  just add them to application environment settings. Example:\n\n```\n{application, 'myapp',\n [{description, \"\"},\n  {vsn, \"1.0.0\"},\n\n  ...\n\n  {env,[\n    {hooks, [{a, [{?MODULE, hook1, 0},\n                  {?MODULE, hook2, 0}]},\n             {b, [{?MODULE, hook1, 2},\n                  {?MODULE, hook2, 2}]}]},\n    ...\n  ]},\n\n  ...\n\n ]}.\n```\n\n\u003e You can specify a patch where to load the application and its dependencies.\n\n### run hooks\n\nYou can use the following command to execute hooks\n\n- `hooks:run/2` :run all hooks registered for the HookName.\n- `hooks:run_fold/3`: fold over all hooks registered for HookName, and return Acc.\n- `hooks:all/2`: execute all hooks for this HookName and return all results\n- `hooks:all_till_ok/2`: execute all hooks for the HookName until one return ok or {ok, Val}.\n- `hooks:only/2`: call the top priority hook for the HookName and return the result.\n\n### advanced features\n\n#### Internal  hooks\n\n2 internal hooks are exposed\n\n- `init_hooks`: the hook is executed when hooks is started, a function of arity 0 is expected.\n- `build_hooks`: the hooks is executed when the list of hooks has changed. A function of arity 1, receiving the list of hooks is expected.\n\nWhen added to the hooks application environnement, the hooks are immediately available and won't wait for any registered process.\n\n#### wait_for_proc application setting\n\nThe `wait_for_proc` application environment settings in the `hooks` application allows you to wait for a specific registered process (example your main application process) to be started before making the hooks available. It means that until the process isn`t registered the beam containing the list of hooks won't be compiled with the list of added hooks.\n\n#### custom start/stop functions\n\nWhen enabling a plugin the application is generally started like any OTP application. In some cases however you may want to use your own start/stop functions.\n\nTo do it create an `Application` module and add to it the functions `start/0` and `stop/0`. `Application:start/0` should return ok or an error if it can't be started.\n\n## Usage in Elixir applications\n\nAdd hooks to your mix app by adding hooks to your list of dependencies,\n\n```\n[{:hooks, \"~\u003e 2.0.0\"}]\n\n## [{:hooks, git: \"https://github.com/barrel-db/hooks\"}]\n```\n\nSample code usage is as follows:\n\n```\ndefmodule DemoMReg do\n    def run do\n        Application.ensure_all_started(:hooks)\n        hooks = [\n                    {:a, [{__MODULE__, :hook1, 1}, {__MODULE__, :hook1, 1}]},\n                    {:b, [{__MODULE__, :hook1, 1}, {__MODULE__, :hook1, 1}]}\n                ]\n\n        IO.inspect Hooks.mreg(hooks)\n        IO.inspect Hooks.find(:b)\n        IO.inspect Hooks.all(:b, [1])\n    end\n\n    def hook1(args) do\n        [ok: args]\n    end\nend\n\ndefmodule DemoReg do\n    def run do\n        Application.ensure_all_started(:hooks)\n        IO.inspect Hooks.reg(:c, __MODULE__, :hook1, 1)\n        IO.inspect Hooks.find(:c)\n        IO.inspect Hooks.all(:c, [1])\n    end\n\n    def hook1(args) do\n        [ok: args]\n    end\nend\n```\n","funding_links":[],"categories":["Erlang"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenoitc%2Fhooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenoitc%2Fhooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenoitc%2Fhooks/lists"}