Permalink
Browse files

Readme improvements.

  • Loading branch information...
1 parent b37f186 commit 8ce162640175bb434ca17fa8beec0da174b9c82e @technomancy committed Nov 12, 2010
Showing with 39 additions and 2 deletions.
  1. +39 −2 README.md
View
@@ -16,6 +16,16 @@ loaded on startup. Then users can place files that call add-hook under
a specific namespace prefix (my.program.hooks.*) which they can rely
on getting loaded at startup.
+Hooks can change the behaviour of the functions they wrap in many
+ways:
+
+* binding
+* conditional execution (may decide not to continue or decide to call
+ a different function in some circumstances)
+* modify arguments
+* add side effects
+* return different value
+
Hooke is inspired by Emacs Lisp's defadvice and clojure.test fixtures.
## Usage
@@ -55,8 +65,35 @@ sorts of other stuff.
Technically the first argument to a hook function is not always the
target function; if there is more than one hook then the first hook
will receive a function that is a composition of the remaining
-hooks. But when you're writing hooks, you should act as if it is the
-target function.
+hooks. (Dare I say a continuation?) But when you're writing hooks, you
+should act as if it is the target function.
+
+Adding hooks to a defmulti is discouraged as it will make it
+impossible to add further methods. Hooks are meant to extend functions
+you don't control; if you own the target function there are obviously
+better ways to change its behaviour.
+
+## Bonus Features
+
+Most of the time you'll never need more than just add-hook. But
+there's more!
+
+If you are using Hooke just to add side-effects to a function, it may
+be simpler to use the append or prepend macros:
+
+ (prepend print-name
+ (print "The following person is awesome:"))
+
+ (print-name "Gilbert K. Chesterton")
+ > The following person is awesome:
+ > Gilbert K. Chesterton
+
+You may also run a block of code with the hooks for a given var
+stripped out:
+
+ (with-hooks-disabled print-name
+ (print-name "Alan Moore"))
+ > Alan Moore
## License

0 comments on commit 8ce1626

Please sign in to comment.