[project @ 2002-08-02 04:31:30 by unknown_lamer]

[clinton/bobotpp.git] / bobot++.texinfo

diff --git a/bobot++.texinfo b/bobot++.texinfo
index cdcfe01..56bbf55 100644 (file)
--- a/bobot++.texinfo
+++ b/bobot++.texinfo
@@ -206,7 +206,7 @@ processing of hooks stops.
 @findex addhook
 To add a new hook you use the function
 @code{bot:addhook}. @code{bot:addhook} is prototyped as
-@code{(bot:addhook type regex function pri fall)}. @code{type}
+@code{(bot:addhook type regex function pri fall name)}. @code{type}
 specifies the type of hook (the types of hooks are listed in @ref{Hook
 Types}). @code{regex} is a standard regular expression. If
 @code{regex} is matched, @code{function} will be
@@ -215,7 +215,13 @@ on the hook type. @code{pri} specifies the priority of the
 hook---higher priority hooks are executed first. This argument is
 optional and defaults to @code{0}. @code{fall} is @code{#t} if the
 hook is a fallthrough hook and @code{#f} is the hook is not a
-fallthrough hook. This arg is also optional and default to @code{#t}. 
+fallthrough hook. This arg is also optional and default to
+@code{#t}. @code{name} is the optional name of the hook that defaults
+to ``DEFAULT''. If you set the name then you can have more than one
+hook that matches the same regexp, as long as they have the same
+name. E.g. in a log script you could have the regexps for the log
+function all be @code{".*"} and set their names to @code{"log"} to
+avoid a conflict with other hooks.
 
 @node Hook Types,  , Creating a Hook, Hooks
 @subsection Hook Types
@@ -594,6 +600,36 @@ If you want to execute code when the bot exits, just do
 argumentless procedure (a thunk). When the bot exits your thunk will
 be called.
 
+Since a bot calls hooks on things it says, you have to be careful
+about hooks that output text that might match itself. E.g. if you have
+a hook that matches @code{"foo"} and the hook displays @code{"foo to
+the whatsit?"}, then the hook will call itself over and over until the
+stack overflows! To protect against this I wrote the macro
+@code{not-from-me}. You call it like this: @code{(not-from-me from
+(stmts if not from bot) (stmts if from bot))}. E.g. 
+
+@example
+(bot:addhook hooks/public "foo"
+             (lambda (f t p)
+               (not-from-me f ((bot:say t "foo to the what!")))))
+@end example
+
+This say ``foo to the what!'' to the channel that ``foo'' was said in
+and do nothing otherwise. You can optionally specify an action to be
+executed if the message is from the bot:
+
+@example
+(bot:addhook hooks/public "foo"
+             (lambda (f t p)
+               (not-from-me f ((bot:say t "foo to the what!"))
+                              ((bot:say t "moof")))))
+@end example
+
+That will do the same thing as the first example, but the bot will
+say ``moof'' if it said ``foo'' before. That probably isn't a very
+nice thing to do, but it works as an example. You can have as many
+staments as you want in the clauses.
+
 @node Concept Index, Function Index, Scripting, Top
 @unnumbered Concept Index
 @printindex cp