More docs

2 files changed, 56 insertions, 8 deletions

diff --git a/docs/01-basics.md b/docs/01-basics.md
index ddc69da..10a0f60 100644
--- a/docs/01-basics.md
+++ b/docs/01-basics.md
@@ -66,8 +66,9 @@ Here are the things your event handler can return:
 
 * Value of `$.NEXT`: pass the event to the next plugin or event handler than can
 handle it
-* `Nil`: do not reply to the message, but do not pass the event to any other
-event handler; we handled it
+* `Nil` (and a select few other items that don't make sense as replies, such as
+`IRC::Client` object): do not reply to the message, but do not pass the event to
+any other event handler; we handled it
 * `Promise`: when the Promise is `.kept`, use its value for the .reply, unless
 it's a `Nil`. **Note:** you cannot return `$.NEXT` here.
 * *Any other value*: mark the event as handled and don't pass it further. The
@@ -95,4 +96,37 @@ the original message, prefixed with `You said `.
 ## Generating Messages
 
 If your plugin needs to generate messages instead of merely responding to
-commands, you can use the Client Object's `.send` method.
+commands, you can use the Client Object's `.send` method. Your plugin needs
+to do the `IRC::Client::Plugin` role to get access to the Client Object via
+the `$.irc` attribute:
+
+```perl6
+use IRC::Client;
+
+class AlarmBot does IRC::Client::Plugin {
+    method irc-connected ($) {
+        react {
+            whenever Supply.interval(3) {
+                $.irc.send: :where<#perl6> :text<Three seconds passed!>;
+            }
+        }
+    }
+}
+
+.run with IRC::Client.new:
+    :nick<MahBot>
+    :host<irc.freenode.net>
+    :channels<#perl6>
+    :debug
+    :plugins(AlarmBot.new)
+```
+
+Here, we subscribe to `irc-connected` event (using an anonymous parameter
+for its message object, since we don't need it). It fires whenever we
+successfully connect to a server. In the event handler we setup a
+`react`/`whenever` loop, with a `Supply` generating an event every three
+seconds. In the `whenever` block, we use the `$.irc` attribute provided
+by the `IRC::Client::Plugin` role to call method `.send` on the Client Object.
+In the `:where` parameter, we specify we want to send the message to
+channel `#perl6` and the `:text` parameter contains the text we want to send.
+The bot will send that text every 3 seconds.
diff --git a/lib/IRC/Client.pm6 b/lib/IRC/Client.pm6
index 91690e7..aa1d132 100644
--- a/lib/IRC/Client.pm6
+++ b/lib/IRC/Client.pm6
@@ -32,6 +32,12 @@ my &colored = try {
     = GLOBAL::Terminal::ANSIColor::EXPORT::DEFAULT::<&colored>;
 } // sub (Str $s, $) { $s };
 
+method join (*@channels, :$server) {
+    self.send-cmd: 'JOIN', $_, :$server for @channels;
+
+    self;
+}
+
 method run {
     self!prep-servers;
     .irc = self for @.plugins.grep: { .DEFINITE and .^can: 'irc' };
@@ -82,18 +88,20 @@ method run {
     await Promise.allof: %!servers.values».<promise>;
 }
 
-method emit-custom (|c) {
-    $!event-pipe.send: c;
-}
+# method emit-custom (|c) {
+#     $!event-pipe.send: c;
+# }
 
 method send (:$where!, :$text!, :$server, :$notice) {
     for $server || |%!servers.keys.sort {
         self.send-cmd: $notice ?? 'NOTICE' !! 'PRIVMSG', $where, $text,
             :server($_);
     }
+
+    self;
 }
 
-method send-cmd ($cmd, *@args is copy, :$server, :$prefix = '') {
+method send-cmd ($cmd, *@args is copy, :$prefix = '', :$server) {
     if $cmd eq 'NOTICE'|'PRIVMSG' and @!filters
         and my @f = @!filters.grep({
                .signature.ACCEPTS: \(@args[1])
@@ -187,6 +195,11 @@ method !handle-event ($e) {
         for self!plugs-that-can($event, $e) {
             my $res = ."$event"($e);
             next if $res ~~ IRC_FLAG_NEXT;
+
+            # Bail out on bogus return values
+            # dd [ $res, $res ~~ IRC::Client, $res ~~ IRC::Client | Supply | Channel];
+            last EVENT if $res ~~ IRC::Client | Supply | Channel;
+
             if $res ~~ Promise {
                 $res.then: { $e.?reply: $^r unless $^r ~~ Nil or $e.?replied; }
             } else {
@@ -208,7 +221,8 @@ method !plugs-that-can ($method, $e) {
     }
 }
 
-method !ssay (Str:D $msg, :$server = '*') {
+method !ssay (Str:D $msg, :$server is copy) {
+    $server //= '*';
     $!debug and debug-print $msg, :out, :$server;
     %!servers{ $server }<sock>.print("$msg\n");
     self;