Tested with Nyxt 2 Pre-release 3
Below, we share what we've learned about hook design, extensibility, and how we've improved upon legacy hook systems in Nyxt.
Note: For an introduction to hooks in Nyxt, see our other article on hooks.
Hook: a place in the code where we can add code dynamically.
Hook handler: a piece of code that can be evaluated by a hook.
During the development of Nyxt we quickly felt dissatisfied with our initial hook implementation (based on Emacs, built with cl-hooks (https://github.com/scymtym/architecture.hooks)). Hooks are an important extension feature. They need to be powerful, reliable, and easy to use.
No existing implementations satisfied our needs, so we decided to write our own with the following enhancements/concepts:
Hooks are first-class objects – not just any list – so that we can tell if something evaluates to a hook.
disablehook handlers without deleting them, so that they can be toggled on and off.
In Emacs, handlers can be any function, including lambdas which make hooks hard to manipulate (e.g. you can't remove a lambda by its name since it has no name).
Lambdas are effectively blackboxes once added to the hook.
Lambdas don't compare, so adding the same lambda twice will unintentionally stack it.
To overcome this limitation while still allowing the use of lambdas, we created a
handlertype with a
nameslot. This allows us to fix both issues: The handler can be associated to a lambda and handlers can be compared.
In Emacs, hook handlers are always run sequentially and do not return anything. There is no way to customize how they are run and what return value we expect. In particular, they do now allow for composing handlers – which would in effect turn the hook into a pipeline!
Our hook class has a
combinationslot which accepts a function that schedules the handler execution and collects the return value(s).
In Emacs, hooks cannot be typed which leads to "hard to catch" errors. E.g., when the user tries to add a function of the wrong type to a hook. Therefore, we've added macros to help define typed hooks.
Emacs hooks are simple lists, they can't be attached to a given object. In our hook system we've added support for globally-accessible hooks, as well as object-bound hooks.
Our work has now been merged in Serapeum and can be accessed from the
Let's have a look at the implementation details!
Declaring new hook types
We provide a
define-hook-type macro. For instance
add-hookmethod specialized over
Say we've got a
#'my-downcase function of type
(function (string) string). Now we can create a hook and add
#'my-downcase to it.
The library comes with the following predefined hook types:
voidhook type is for handlers that don't return anything. This is useful when we want to use handlers for their side effects.
anyhook type accepts any handler type.
Lambdas as handlers
You don't always want to declare top-level functions before adding a handler to a hook. So the above example could be replaced with the following:
enable-hook methods which accept multiple handler names as argument.
Not passing any handler name is equivalent to selecting all handlers.
Disabling a handler and re-enabling it moves it to the front of the handler list, which may change the handler order. Keep this in mind if execution order matters!
A hook can be configured in how it runs its handlers. Example:
In the above the result of the first handler is passed as the input to the second and so on. The final result is the output of the last handler.
The library provides a few default combination functions:
default-combine-hook: Return the list of the results of the HOOK handlers applied to the arguments.
combine-hook-until-failure: As above but stop the list at the first handler that returns nil.
combine-hook-until-success: As above but return the first non-nil result.
combine-composed-hook: This is the handler from the above example.
A common pitfall that keeps tripping Emacs users is when a handler is added to a hook that takes an argument of an unexpected type. This kind of error is usually only caught at runtime.
This is why we've introduced typing in our library. In the [[Declaring new hook types]] section we saw that defining a hook type generates a new
add-hook method that's specialized over the specified types. Since there is only one such method, it's only possible to call
add-hook over the right handler object, which is created by the associated typed handler constructor (e.g.
Common Lisp compilers like SBCL perform function type-checking at compile time, which allows us to catch errors early when the user tries to create a handler over a function of the wrong type.
Global hooks and object-bound hooks
define-hook function allows for registering hooks globally without binding them to global variables.
With just a type and a name, it defines a global hook which can then be accessed with the
You can also bind a hook over an object. This hook is unique to the object.
We've been using our novel hook system in Nyxt for a while now and it's proven both robust and flexible. It has removed a whole class of errors from user configurations!
We hope these design decisions will be met with success. It'd be great to see this kind of sophistication in Emacs and other extensible programs!
Thanks for reading :-)