Add examples; fix up docs

12 files changed, 204 insertions, 25 deletions

diff --git a/README.md b/README.md
index 8970dcc..69a6887 100644
--- a/README.md
+++ b/README.md
@@ -33,11 +33,12 @@ and output post-processing.
 
 # DOCUMENTATION MAP
 
-* [Blog Post](#not-published)
+* [Blog Post](http://perl6.party/post/IRC-Client-Perl-6-Multi-Server-IRC-Module)
 * [Basics Tutorial](docs/01-basics.md)
 * [Event Reference](docs/02-event-reference.md)
 * [Method Reference](docs/03-method-reference.md)
 * [Big-Picture Behaviour](docs/04-big-picture-behaviour.md)
+* [Examples](examples/README.md)
 
 ---
 
diff --git a/docs/03-method-reference.md b/docs/03-method-reference.md
index 1aafda2..7b6ddb6 100644
--- a/docs/03-method-reference.md
+++ b/docs/03-method-reference.md
@@ -538,6 +538,11 @@ server-specific configuration. Valid keys in the configuration are
 of the `IRC::Client.new` method and if any key is omitted, the value
 of the `.new`'s argument will be used.
 
+If `:servers` is not specified, then a server will be created with the
+label `_` (underscore).
+
+**By default** not specified.
+
 ##### `:username`
 
 The IRC username to use. **Defaults to:** `Perl6IRC`
diff --git a/docs/README.md b/docs/README.md
index ff476b2..227436f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,8 +2,9 @@
 
 # Documentation Map
 
-* [Blog Post](#not-published)
+* [Blog Post](http://perl6.party/post/IRC-Client-Perl-6-Multi-Server-IRC-Module)
 * [Basics Tutorial](01-basics.md)
 * [Event Reference](02-event-reference.md)
 * [Method Reference](03-method-reference.md)
 * [Big-Picture Behaviour](04-big-picture-behaviour.md)
+* [Examples](../examples/README.md)
diff --git a/examples/01-uppercase-bot.p6 b/examples/01-uppercase-bot.p6
new file mode 100644
index 0000000..d846538
--- /dev/null
+++ b/examples/01-uppercase-bot.p6
@@ -0,0 +1,8 @@
+use lib <lib>;
+use IRC::Client;
+.run with IRC::Client.new:
+    :nick<MahBot>
+    :host<irc.freenode.net>
+    :channels<#zofbot>
+    :debug
+    :plugins(class { method irc-to-me ($_) { .text.uc } })
diff --git a/examples/02-trickster-bot.p6 b/examples/02-trickster-bot.p6
new file mode 100644
index 0000000..178fcdd
--- /dev/null
+++ b/examples/02-trickster-bot.p6
@@ -0,0 +1,19 @@
+use lib <lib>;
+
+use IRC::Client;
+class Trickster {
+    multi method irc-to-me ($ where /time/) { DateTime.now }
+    multi method irc-to-me ($ where /temp \s+ $<temp>=\d+ $<unit>=[F|C]/) {
+        $<unit> eq 'F' ?? "That's {($<temp> - 32) × .5556}°C"
+                       !! "That's { $<temp> × 1.8 + 32   }°F"
+    }
+}
+
+class BFF { method irc-to-me ($ where /'♥'/) { 'I ♥ YOU!' } }
+
+.run with IRC::Client.new:
+    :nick<MahBot>
+    :host<irc.freenode.net>
+    :channels<#zofbot>
+    :debug
+    :plugins(Trickster, BFF)
diff --git a/examples/03-github-notifications.p6 b/examples/03-github-notifications.p6
new file mode 100644
index 0000000..8dec6d2
--- /dev/null
+++ b/examples/03-github-notifications.p6
@@ -0,0 +1,38 @@
+use lib <lib>;
+
+use IRC::Client;
+use HTTP::Tinyish;
+use JSON::Fast;
+
+class GitHub::Notifications does IRC::Client::Plugin {
+    has Str:D $.token  = %*ENV<GITHUB_TOKEN>;
+    has       $!ua     = HTTP::Tinyish.new;
+    constant  $API_URL = 'https://api.github.com/notifications';
+
+    method irc-connected ($) {
+        start react {
+            whenever self!notification.grep(* > 0) -> $num {
+                $.irc.send: :where<Zoffix>
+                            :text("You have $num unread notifications!")
+                            :notice;
+            }
+        }
+    }
+
+    method !notification {
+        supply {
+            loop {
+                my $res = $!ua.get: $API_URL, :headers{ :Authorization("token $!token") };
+                $res<success> and emit +grep *.<unread>, |from-json $res<content>;
+                sleep $res<headers><X-Poll-Interval> || 60;
+            }
+        }
+    }
+}
+
+.run with IRC::Client.new:
+    :nick<MahBot>
+    :host<irc.freenode.net>
+    :channels<#zofbot>
+    :debug
+    :plugins(GitHub::Notifications.new)
diff --git a/examples/04-bash-bot.p6 b/examples/04-bash-bot.p6
new file mode 100644
index 0000000..d3aaa4c
--- /dev/null
+++ b/examples/04-bash-bot.p6
@@ -0,0 +1,26 @@
+use lib <lib>;
+
+use IRC::Client;
+use Mojo::UserAgent:from<Perl5>;
+
+class Bash {
+    constant $BASH_URL = 'http://bash.org/?random1';
+    constant $cache    = Channel.new;
+    has        $!ua    = Mojo::UserAgent.new;
+
+    multi method irc-to-me ($ where /bash/) {
+        start $cache.poll or do { self!fetch-quotes; $cache.poll };
+    }
+
+    method !fetch-quotes {
+        $cache.send: $_
+            for $!ua.get($BASH_URL).res.dom.find('.qt').each».all_text.lines.join: ' ';
+    }
+}
+
+.run with IRC::Client.new:
+    :nick<MahBot>
+    :host<irc.freenode.net>
+    :channels<#zofbot>
+    :debug
+    :plugins(Bash.new);
diff --git a/examples/05-bash-bot-with-filter.p6 b/examples/05-bash-bot-with-filter.p6
new file mode 100644
index 0000000..f3f2c3b
--- /dev/null
+++ b/examples/05-bash-bot-with-filter.p6
@@ -0,0 +1,30 @@
+use lib <lib>;
+
+use IRC::Client;
+use Pastebin::Shadowcat;
+use Mojo::UserAgent:from<Perl5>;
+
+class Bash {
+    has      @!quotes;
+    has      $!ua      = Mojo::UserAgent.new;
+    constant $BASH_URL = 'http://bash.org/?random1';
+
+    method irc-to-me ($ where /bash/) {
+        start self!fetch-quotes and @!quotes.shift;
+    }
+    method !fetch-quotes {
+        @!quotes ||= $!ua.get($BASH_URL).res.dom.find('.qt').each».all_text;
+    }
+}
+
+.run with IRC::Client.new:
+    :nick<MahBot>
+    :host<localhost>
+    :channels<#zofbot>
+    :debug
+    :plugins(Bash.new)
+    :filters(
+        -> $text where .lines > 1 || .chars > 300 {
+            Pastebin::Shadowcat.new.paste: $text.lines.join: "\n";
+        }
+    )
diff --git a/examples/06-multi-server.p6 b/examples/06-multi-server.p6
new file mode 100644
index 0000000..3a5f5fc
--- /dev/null
+++ b/examples/06-multi-server.p6
@@ -0,0 +1,23 @@
+use lib <lib>;
+
+use IRC::Client;
+
+class BFF {
+    method irc-to-me ($ where /'♥'/) { 'I ♥ YOU!' }
+}
+
+.run with IRC::Client.new:
+    :debug
+    :plugins(BFF)
+    :nick<MahBot>
+    :channels<#zofbot>
+    :servers(
+        freenode => %(
+            :host<irc.freenode.net>,
+        ),
+        local => %(
+            :nick<P6Bot>,
+            :channels<#zofbot #perl6>,
+            :host<localhost>,
+        )
+    )
diff --git a/examples/07-multi-server-message-forwarder.p6 b/examples/07-multi-server-message-forwarder.p6
new file mode 100644
index 0000000..06d07ec
--- /dev/null
+++ b/examples/07-multi-server-message-forwarder.p6
@@ -0,0 +1,37 @@
+use lib <lib>;
+
+use IRC::Client;
+
+class Messenger does IRC::Client::Plugin {
+    method irc-privmsg-channel ($e) {
+        for $.irc.servers.values -> $server {
+            for $server.channels -> $channel {
+                next if $server eq $e.server and $channel eq $e.channel;
+
+                $.irc.send: :$server, :where($channel), :text(
+                    "$e.nick() over at $e.server.host()/$e.channel() says $e.text()"
+                );
+            }
+        }
+
+        $.irc.send: :where<Zoffix>
+                    :text('I spread the messages!')
+                    :server<local>;
+    }
+}
+
+.run with IRC::Client.new:
+    :debug
+    :plugins[Messenger.new]
+    :nick<MahBot>
+    :channels<#zofbot>
+    :servers{
+        freenode => %(
+            :host<irc.freenode.net>,
+        ),
+        local => %(
+            :nick<P6Bot>,
+            :channels<#zofbot #perl6>,
+            :host<localhost>,
+        )
+    }
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..49b9056
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,14 @@
+[[back to doc map]](../docs/README.md)
+
+# Examples
+
+These examples are covered in [the IRC::Client blog
+post](http://perl6.party/post/IRC-Client-Perl-6-Multi-Server-IRC-Module)
+
+* [Uppercasing bot](01-uppercase-bot.p6)
+* [Small bot with a couple of features](02-trickster-bot.p6)
+* [Bot to announce GitHub notifications](03-github-notifications.p6)
+* [Bash.org bot](04-bash-bot.p6)
+* [Bash.org bot with pastebin filter](05-bash-bot-with-filter.p6)
+* [Multi-server bot](06-multi-server.p6)
+* [Multi-server message forwarder bot](07-multi-server-message-forwarder.p6)
diff --git a/examples/bot.pl6 b/examples/bot.pl6
deleted file mode 100644
index e991a8e..0000000
--- a/examples/bot.pl6
+++ /dev/null
@@ -1,23 +0,0 @@
-use lib 'lib';
-use IRC::Client;
-
-class MyPlug does IRC::Client::Plugin {
-    method irc-privmsg-channel ($msg where .text ~~ /^'say' \s+ $<cmd>=(.+)/ ) {
-        $msg.reply: "How about: $<cmd>.uc()";
-    }
-}
-
-my $irc = IRC::Client.new(
-    :nick('IRCBot')
-    :debug<2>
-    :channels<#perl6 #perl7>
-    # :host<irc.freenode.net>
-    :port<6667>
-    # :servers(
-        # mine     => { :port<5667> },
-
-        # inspircd => {             },
-        # freenode => { :host<irc.freenode.net> },
-    # )
-    :plugins(MyPlug.new)
-).run;