From 05647bd1f2312cc756f71152252a6349e86f43c5 Mon Sep 17 00:00:00 2001
From: Zoffix Znet <cpan@zoffix.com>
Date: Sun, 13 Dec 2015 19:14:23 -0500
Subject: update docs

---
 README.md                          | 45 ++++++++++++++++++++++++++++++++++++++
 lib/IRC/Client.pm6                 | 34 ++++++++++++++--------------
 lib/IRC/Client/Plugin.pm6          |  1 -
 lib/IRC/Client/Plugin/Debugger.pm6 |  4 ++--
 lib/IRC/Client/Plugin/PingPong.pm6 |  2 +-
 5 files changed, 65 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index b2bcad9..0568858 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,8 @@ IRC::Client - Extendable Internet Relay Chat client
 
 # SYNOPSIS
 
+## Client script
+
 ```perl6
     use IRC::Client;
     use IRC::Client::Plugin::Debugger;
@@ -17,6 +19,49 @@ IRC::Client - Extendable Internet Relay Chat client
     ).run;
 ```
 
+## Custom plugins
+
+### Basic response to an IRC command:
+
+The plugin chain handling the message will stop after this plugin.
+
+```
+unit class IRC::Client::Plugin::PingPong is IRC::Client::Plugin;
+method irc-ping ($irc, $msg) { $irc.ssay("PONG {$irc.nick} $msg<params>[0]") }
+```
+
+### More involved handling
+
+On startup, start sending message `I'm an annoying bot` to all channels
+every five seconds. We also subscribe to all events and print some debugging
+info. By returning a special constant, we tell other plugins to continue
+processing the data.
+
+```
+use IRC::Client::Plugin; # import constants
+unit class IRC::Client::Plugin::Debugger is IRC::Client::Plugin;
+
+method register($irc) {
+    Supply.interval( 5, 5 ).tap({
+        $irc.privmsg($_, "I'm an annoying bot!")
+            for $irc.channels;
+    })
+}
+
+method all-events ($irc, $e) {
+    say "We've got a private message"
+        if $e<command> eq 'PRIVMSG' and $e<params>[0] eq $irc.nick;
+
+    # Store arbitrary data in the `pipe` for other plugins to use
+    $e<pipe><respond-to-notice> = True
+        if $e<command> eq 'PRIVMSG';
+
+    say $e, :indent(4);
+    return IRC_NOT_HANDLED;
+}
+
+```
+
 # DESCRIPTION
 
 ***Note: this is a preview dev release. Things might change and new things
diff --git a/lib/IRC/Client.pm6 b/lib/IRC/Client.pm6
index c8e6ac4..2623dc2 100644
--- a/lib/IRC/Client.pm6
+++ b/lib/IRC/Client.pm6
@@ -30,37 +30,37 @@ class IRC::Client:ver<1.002001> {
             react {
                 whenever $!sock.Supply -> $str is copy {
                     $!debug and "[server {DateTime.now}] {$str}".put;
-                    my $messages = parse-irc $str;
-                    MESSAGES: for @$messages -> $message {
-                        $message<pipe>    = {};
+                    my $event = parse-irc $str;
+                    EVENTS: for @$events -> $e {
+                        $e<pipe>    = {};
 
-                        if ( $message<command> eq 'PRIVMSG'
-                            and $message<params>[0] eq $!nick
+                        if ( $e<command> eq 'PRIVMSG'
+                            and $e<params>[0] eq $!nick
                         ) {
                             for @!plugs.grep(*.^can: 'privmsg-me') -> $p {
-                                my $res = $p.privmsg-me(self, $message);
-                                next MESSAGES unless $res === IRC_NOT_HANDLED;
+                                my $res = $p.privmsg-me(self, $e);
+                                next EVENTS unless $res === IRC_NOT_HANDLED;
                             }
                         }
 
-                        if ( $message<command> eq 'NOTICE'
-                            and $message<params>[0] eq $!nick
+                        if ( $e<command> eq 'NOTICE'
+                            and $e<params>[0] eq $!nick
                         ) {
                             for @!plugs.grep(*.^can: 'notice-me') -> $p {
-                                my $res = $p.notice-me(self, $message);
-                                next MESSAGES unless $res === IRC_NOT_HANDLED;
+                                my $res = $p.notice-me(self, $e);
+                                next EVENTS unless $res === IRC_NOT_HANDLED;
                             }
                         }
 
-                        my $cmd = 'irc-' ~ $message<command>.lc;
+                        my $cmd = 'irc-' ~ $e<command>.lc;
                         for @!plugs.grep(*.^can: $cmd) -> $p {
-                            my $res = $p."$cmd"(self, $message);
-                            next MESSAGES unless $res === IRC_NOT_HANDLED;
+                            my $res = $p."$cmd"(self, $e);
+                            next EVENTS unless $res === IRC_NOT_HANDLED;
                         }
 
-                        for @!plugs.grep(*.^can: 'msg') -> $p {
-                            my $res = $p.msg(self, $message);
-                            next MESSAGES unless $res === IRC_NOT_HANDLED;
+                        for @!plugs.grep(*.^can: 'all-events') -> $p {
+                            my $res = $p.all-events(self, $e);
+                            next EVENTS unless $res === IRC_NOT_HANDLED;
                         }
                     }
                 }
diff --git a/lib/IRC/Client/Plugin.pm6 b/lib/IRC/Client/Plugin.pm6
index eda7a0a..55db82c 100644
--- a/lib/IRC/Client/Plugin.pm6
+++ b/lib/IRC/Client/Plugin.pm6
@@ -1,5 +1,4 @@
 constant IRC_HANDLED     = "irc plugin handled \x1";
 constant IRC_NOT_HANDLED = "irc plugin not-handled \x2";
 unit class IRC::Client::Plugin:ver<1.002002>;
-has $.irc;
 
diff --git a/lib/IRC/Client/Plugin/Debugger.pm6 b/lib/IRC/Client/Plugin/Debugger.pm6
index 4ded968..17cf697 100644
--- a/lib/IRC/Client/Plugin/Debugger.pm6
+++ b/lib/IRC/Client/Plugin/Debugger.pm6
@@ -2,7 +2,7 @@ use Data::Dump;
 use IRC::Client::Plugin;
 unit class IRC::Client::Plugin::Debugger:ver<1.002001> is IRC::Client::Plugin;
 
-method msg ($irc, $msg) {
-    say Dump $msg, :indent(4);
+method all-events ($irc, $e) {
+    say Dump $e, :indent(4);
     return IRC_NOT_HANDLED;
 }
diff --git a/lib/IRC/Client/Plugin/PingPong.pm6 b/lib/IRC/Client/Plugin/PingPong.pm6
index a85dc96..d6b8f28 100644
--- a/lib/IRC/Client/Plugin/PingPong.pm6
+++ b/lib/IRC/Client/Plugin/PingPong.pm6
@@ -1,2 +1,2 @@
 unit class IRC::Client::Plugin::PingPong:ver<1.002001>;
-method irc-ping ($irc, $msg) { $irc.ssay("PONG {$irc.nick} $msg<params>[0]") }
+method irc-ping ($irc, $e) { $irc.ssay("PONG {$irc.nick} $e<params>[0]") }
-- 
cgit v1.1