irc: Convert handle-line to a message handler.

[8sync.git] / doc / 8sync-new-manual.org

diff --git a/doc/8sync-new-manual.org b/doc/8sync-new-manual.org
index e1462f5e44c82cf60d2e67c5cd36822bf5dc673b..2545b1643e0f1323cc90accf2e5eaec58b790218 100644 (file)
--- a/doc/8sync-new-manual.org
+++ b/doc/8sync-new-manual.org
@@ -103,8 +103,8 @@ Now we need to add our bot.  Initially, it won't do much.
 #+BEGIN_SRC scheme
   (define-class <my-irc-bot> (<irc-bot>))
 
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     (if emote?
         (format #t "~a emoted ~s in channel ~a\n"
                 speaker line channel)
@@ -117,6 +117,11 @@ This is an 8sync actor.
 (8sync uses GOOPS to define actors.)
 We extended the handle-line generic method, so this is the code that
 will be called whenever the IRC bot "hears" anything.
+This method is itself an action handler, hence the second argument
+for =message=, which we can ignore for now.
+Pleasantly, the message's argument body is passed in as the rest of
+the arguments.
+
 For now the code is pretty basic: it just outputs whatever it "hears"
 from a user in a channel to the current output port.
 Pretty boring!
@@ -174,8 +179,8 @@ Let's get it to echo whatever we say back to us.
 Change handle-line to this:
 
 #+BEGIN_SRC scheme
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     (<- (actor-id irc-bot) 'send-line channel
         (format #f "Bawwwwk! ~a says: ~a" speaker line)))
 #+END_SRC
@@ -241,8 +246,8 @@ Indeed, we do have such a method, so we /could/ rewrite handle-line
 like so:
 
 #+BEGIN_SRC scheme
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     (irc-bot-send-line irc-bot channel
                        (format #f "Bawwwwk! ~a says: ~a" speaker line)))
 #+END_SRC
@@ -269,8 +274,8 @@ Whee, that looks like fun!
 To implement it, we're going to pull out Guile's pattern matcher.
 
 #+BEGIN_SRC scheme
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     (define my-name (irc-bot-username irc-bot))
     (define (looks-like-me? str)
       (or (equal? str my-name)
@@ -306,8 +311,8 @@ If you're getting the sense that we could make this a bit less wordy,
 you're right:
 
 #+BEGIN_SRC scheme
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     (define my-name (irc-bot-username irc-bot))
     (define (looks-like-me? str)
       (or (equal? str my-name)
@@ -595,6 +600,20 @@ Of course, we need to update our worker accordingly as well.
 everywhere as we are in this program... that's just to make the
 examples more illustrative.)
 
+"<-reply" is what actually returns the information to the actor
+waiting on the reply.
+It takes as an argument the actor sending the message, the message
+it is in reply to, and the rest of the arguments are the "body" of
+the message.
+(If an actor handles a message that is being "waited on" but does not
+explicitly reply to it, an auto-reply with an empty body will be
+triggered so that the waiting actor is not left waiting around.)
+
+The last thing to note is the call to "self-destruct".
+This does what you might expect: it removes the actor from the hive.
+No new messages will be sent to it.
+Ka-poof!
+
 Running it is the same as before:
 
 #+BEGIN_SRC scheme
@@ -627,20 +646,6 @@ manager> Oh!  I guess you can go home then.
 worker> Whew!  Free at last.
 #+END_SRC
 
-"<-reply" is what actually returns the information to the actor
-waiting on the reply.
-It takes as an argument the actor sending the message, the message
-it is in reply to, and the rest of the arguments are the "body" of
-the message.
-(If an actor handles a message that is being "waited on" but does not
-explicitly reply to it, an auto-reply with an empty body will be
-triggered so that the waiting actor is not left waiting around.)
-
-The last thing to note is the call to "self-destruct".
-This does what you might expect: it removes the actor from the hive.
-No new messages will be sent to it.
-Ka-poof!
-
 ** Writing our own network-enabled actor
 
 So, you want to write a networked actor!
@@ -929,8 +934,8 @@ Edit the respond section to see what channel it's really sending
 things to:
 
 #+BEGIN_SRC scheme
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     ;; [... snip ...]
     (define (respond respond-line)
       (<- (actor-id irc-bot) 'send-line (pk 'channel channel)
@@ -959,8 +964,8 @@ to looks like our own username that we respond back to the sender.
 (We can remove the pk now that we know what's going on.)
 
 #+BEGIN_SRC scheme
-  (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
-                              line emote?)
+  (define-method (handle-line (irc-bot <my-irc-bot>) message
+                              speaker channel line emote?)
     ;; [... snip ...]
     (define (respond respond-line)
       (<- (actor-id irc-bot) 'send-line