Write some design

1 files changed, 155 insertions, 13 deletions

diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md
index 2b4d419..15f5ae1 100644
--- a/DESIGN/01-main.md
+++ b/DESIGN/01-main.md
@@ -67,26 +67,39 @@ A relevant Client Object must be easily accessible to the user of the
 implementation. This includes user's plugins responsible for handling
 events.
 
-###
+### Message Delivery
 
-## Message Delivery
+An event listener is defined by a method in a plugin class. The name
+of the method starts with `irc-` and followed by the lowercase name of the
+event. User-defined events follow the same pattern, except they start with
+`irc-custom-`:
+
+    use IRC::Client::Plugin;
+    unit Plugin::Foo is IRC::Client::Plugin;
+
+    # Listen to PRIVMSG IRC events:
+    method irc-privmsg ($msg) {
+        return IRC_NEXT unless $msg.channel eq '#perl6';
+        $msg.reply: 'Nice to meet you!';
+    }
+
+    method irc-custom-my-event ($some, $random, :$args) {
+        return IRC_NEXT unless $random > 5;
+        $.irc.send: where => '#perl6', what => 'Custom event triggered!';
+    }
 
 An event listener receives the event message in the form of an object.
 The object must provide all the relevant information about the source
 and content of the message.
 
 The message object's attributes must be mutable, and where appropriate,
-it must provide the means to send the message back to the originator
+it must provide a means to send the message back to the originator
 of the message. For example, here's a potential implementation of
 `PRIVMSG` handler that receives the message object:
 
-    use IRC::Client::Plugin;
-    unit Plugin::Foo is IRC::Client::Plugin;
-
     method irc-privmsg ($msg) {
-        return IRC_NOT_HANDLED unless $msg.channel eq '#perl6';
-        $msg.what = "Nice to meet you, $msg.who()";
-        $msg.send;
+        return IRC_NEXT unless $msg.channel eq '#perl6';
+        $msg.reply: 'Nice to meet you!';
     }
 
 The message object should include a means to access the Client Object to
@@ -95,10 +108,139 @@ a possible implementation to re-emit a `NOTICE` message sent to channel
 `#perl6` as a `PRIVMSG` message.
 
     method irc-notice ($msg) {
-        if $msg.channel eq '#perl6' {
-            $msg.how = 'PRIVMSG';
-            $msg.irc.emit: 'PRIVMSG', $msg;
+        $.irc.emit: 'PRIVMSG', $msg
+            if $msg.channel eq '#perl6';
+
+        IRC_NEXT;
+    }
+
+A plugin can send messages and emit events at will:
+
+    method irc-connected {
+        Supply.interval(60).tap: {
+            $.irc.send: where => '#perl6', what  => 'One minute passed!!';
+        };
+        Promise.in(60*60).then: {
+            $.irc.send:
+                where => 'Zoffix',
+                what => 'I lived for one hour already!",
+                :notice;
+
+            $.irc.emit: 'CUSTOM-MY-EVENT', 'One hour passed!';
         }
+    }
+
+## Supported Events
+
+### Channel Operations
 
-        return IRC_NOT_HANDLED;
+[RFC 1459, 4.2](https://tools.ietf.org/html/rfc1459#section-4.2)
+
+#### `irc-join`
+
+    # :zoffix!zoffix@127.0.0.1 JOIN :#perl6
+
+    method irc-join ($msg) {
+        printf "%s joined channel %s\n", .nick, .channel given $msg;
     }
+
+[RFC 1459, 4.2.1](https://tools.ietf.org/html/rfc1459#section-4.2.1).
+Emitted when user joins a channel.
+
+#### `irc-part`
+
+    # :zoffix!zoffix@127.0.0.1 PART #perl6 :Leaving
+
+    method irc-part ($msg) {
+        printf "%s left channel %s (%s)\n", .nick, .channel, .reason given $msg;
+    }
+
+[RFC 1459, 4.2.2](https://tools.ietf.org/html/rfc1459#section-4.2.2).
+Emitted when user leaves a channel.
+
+#### `irc-mode`
+
+    # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2
+    # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@*
+    # :zoffix2!f@127.0.0.1 MODE zoffix2 +w
+
+    method irc-mode ($msg) {
+        if $msg?.channel {
+            # channel mode change
+            printf "%s set mode(s) %s in channel %s\n",
+                .nick, .modes, .channel given $msg;
+        }
+        else {
+            # user mode change
+            printf "Nick %s set mode(s) %s on user %s\n",
+                .nick, .modes, .who given $msg;
+        }
+    }
+
+[RFC 1459, 4.2.3](https://tools.ietf.org/html/rfc1459#section-4.2.3).
+Emitted when IRC `MODE` command is received. As the command is dual-purpose,
+the message object will have either `.channel` method available
+(for channel mode changes) or `.who` method (for user mode changes). See
+also `irc-mode-channel` and `irc-mode-user` convenience events.
+
+For channel modes, the `.modes` method returns a list of `Pair` where key
+is the mode set and the value is the argument for that mode (i.e. "limit",
+"user", or "banmask") or an empty string if the mode takes no arguments.
+
+For user modes, the `.modes` method returns a list of `Str` of the modes
+set.
+
+#### `irc-topic`
+
+    # :zoffix!zoffix@127.0.0.1 TOPIC #perl6 :meow
+
+    method irc-topic ($msg) {
+        printf "%s set topic of channel %s to %s\n",
+            .nick, .channel, .topic given $msg;
+    }
+
+[RFC 1459, 4.2.4](https://tools.ietf.org/html/rfc1459#section-4.2.4).
+Emitted when a user changes topic of a channel.
+
+#### `irc-invite`
+
+    # :zoffix!zoffix@127.0.0.1 INVITE zoffix2 :#perl6
+
+    method irc-invite ($msg) {
+        printf "%s invited us to channel %s\n",
+            .nick, .channel given $msg;
+    }
+
+[RFC 1459, 4.2.7](https://tools.ietf.org/html/rfc1459#section-4.2.7).
+Emitted when a user invites us to a channel.
+
+### Convenience Events
+
+These sets of events do not have a corresponding IRC command defined by the
+protocol and instead are offered to make listening for a specific kind
+of events easier.
+
+#### `irc-mode-channel`
+
+    # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2
+    # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@*
+
+    method irc-mode-channel ($msg) {
+        printf "Nick %s with usermask %s set mode(s) %s in channel %s\n",
+            .nick, .usermask, .modes, .channel given $msg;
+    }
+
+Emitted when IRC `MODE` command is received and it's being operated on a
+channel, see `irc-mode` event for details.
+
+#### `irc-mode-user`
+
+    # :zoffix2!f@127.0.0.1 MODE zoffix2 +w
+
+    method irc-mode-user ($msg) {
+        printf "Nick %s with usermask %s set mode(s) %s on user %s\n",
+            .nick, .usermask, .modes, .who given $msg;
+    }
+
+Emitted when IRC `MODE` command is received and it's being operated on a
+user, see `irc-mode` event for details.