Restructure

1 files changed, 193 insertions, 229 deletions

diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md
index 4ad74f5..1380cd3 100644
--- a/DESIGN/01-main.md
+++ b/DESIGN/01-main.md
@@ -1,38 +1,3 @@
-# TABLE OF CONTENTS
-- [PURPOSE](#purpose)
-- [GOALS](#goals)
-    - [Ease of Use](#ease-of-use)
-    - [Client-Generated Events](#client-generated-events)
-    - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code)
-- [DESIGN](#design)
-    - [Core](#core)
-        - [Client Object](#client-object)
-        - [Message Delivery](#message-delivery)
-    - [Supported Named Events](#supported-named-events)
-        - [`irc-nick`](#irc-nick)
-        - [`irc-quit`](#irc-quit)
-        - [`irc-join`](#irc-join)
-        - [`irc-part`](#irc-part)
-        - [`irc-mode`](#irc-mode)
-        - [`irc-topic`](#irc-topic)
-        - [`irc-invite`](#irc-invite)
-        - [`irc-kick`](#irc-kick)
-        - [`irc-privmsg`](#irc-privmsg)
-        - [`irc-notice`](#irc-notice)
-        - [Convenience Events](#convenience-events)
-            - [`irc-mode-channel`](#irc-mode-channel)
-            - [`irc-mode-user`](#irc-mode-user)
-            - [`irc-to-me`](#irc-to-me)
-            - [`irc-addressed`](#irc-addressed)
-            - [`irc-mentioned`](#irc-mentioned)
-            - [`irc-privmsg-channel`](#irc-privmsg-channel)
-            - [`irc-privmsg-me`](#irc-privmsg-me)
-            - [`irc-notice-channel`](#irc-notice-channel)
-            - [`irc-privmsg-me`](#irc-privmsg-me-1)
-            - [`irc-started`](#irc-started)
-            - [`irc-connected`](#irc-connected)
-        - [Numeric Events](#numeric-events)
-
 # PURPOSE
 
 The purpose of IRC::Client is to provide serve as a fully-functional IRC
@@ -87,9 +52,9 @@ The implementation distribution may also include several plugins that may
 be commonly needed by users. Such plugins are not enabled by default and
 the user must request their inclusion with code.
 
-## Core
+# Core
 
-### Client Object
+## Client Object
 
 Client Object represents a connected IRC client and is aware of and can
 manipulate its state, such as disconnecting, joining or parting a channel,
@@ -102,7 +67,7 @@ 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
@@ -172,191 +137,13 @@ A plugin can send messages and emit events at will:
         }
     }
 ```
-
-## Supported Named Events
-
-### `irc-nick`
-
-```perl6
-    # :zoffix!zoffix@127.0.0.1 NICK not-zoffix
-
-    method irc-nick ($msg) {
-        printf "%s changed nickname to %s\n", .nick, .new-nick given $msg;
-    }
-```
-
-[RFC 2812, 3.1.2](https://tools.ietf.org/html/rfc2812#section-3.1.2).
-Emitted when a user changes their nickname.
-
-### `irc-quit`
-
-```perl6
-    # :zoffix!zoffix@127.0.0.1 QUIT :Quit: Leaving
-
-    method irc-quit ($msg) {
-        printf "%s has quit (%s)\n", .nick, .reason given $msg;
-    }
-```
-
-[RFC 2812, 3.1.7](https://tools.ietf.org/html/rfc2812#section-3.1.7).
-Emitted when a user quits the server.
-
-### `irc-join`
-
-```perl6
-    # :zoffix!zoffix@127.0.0.1 JOIN :#perl6
-
-    method irc-join ($msg) {
-        printf "%s joined channel %s\n", .nick, .channel given $msg;
-    }
-```
-
-[RFC 2812, 3.2.1](https://tools.ietf.org/html/rfc2812#section-3.2.1).
-Emitted when a user joins a channel.
-
-### `irc-part`
-
-```perl6
-    # :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 2812, 3.2.2](https://tools.ietf.org/html/rfc2812#section-3.2.2).
-Emitted when a user leaves a channel.
-
-### `irc-mode`
-
-```perl6
-    # :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 "%s set mode(s) %s on user %s\n",
-                .nick, .modes, .who given $msg;
-        }
-    }
-```
-
-[RFC 2812, 3.1.5](https://tools.ietf.org/html/rfc2812#section-3.1.5)/[RFC 2812, 3.2.3](https://tools.ietf.org/html/rfc2812#section-3.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`
-
-```perl6
-    # :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 2812, 3.2.4](https://tools.ietf.org/html/rfc2812#section-3.2.4).
-Emitted when a user changes the topic of a channel.
-
-### `irc-invite`
-
-```perl6
-    # :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 2812, 3.2.7](https://tools.ietf.org/html/rfc2812#section-3.2.7).
-Emitted when a user invites us to a channel.
-
-### `irc-kick`
-
-```perl6
-    # :zoffix!zoffix@127.0.0.1 KICK #perl6 zoffix2 :go away
-
-    method irc-kick ($msg) {
-        printf "%s kicked %s out of %s (%s)\n",
-            .nick, .who, .channel, .reason given $msg;
-    }
-```
-
-[RFC 2812, 3.2.8](https://tools.ietf.org/html/rfc2812#section-3.2.8).
-Emitted when someone kicks a user out of a channel.
-
-### `irc-privmsg`
-
-```perl6
-    # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello
-    # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh
-
-    method irc-privmsg ($msg) {
-        if $msg?.channel {
-            # message sent to a channel
-            printf "%s said `%s` to channel %s\n",
-                .nick, .what, .channel given $msg;
-        }
-        else {
-            # private message
-            printf "%s messaged us: %s\n", .nick, .what given $msg;
-        }
-    }
-```
-
-[RFC 2812, 3.3.1](https://tools.ietf.org/html/rfc2812#section-3.3.1).
-Emitted when a user sends a message either to a channel
-or a private message to us. See *Convenience Events* section for a number
-of more convenient ways to listen to messages.
-
-### `irc-notice`
-
-```perl6
-    # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me!
-    # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me?
-
-    method irc-notice ($msg) {
-        if $msg?.channel {
-            # notice sent to a channel
-            printf "%s sent a notice `%s` to channel %s\n",
-                .nick, .what, .channel given $msg;
-        }
-        else {
-            # private notice
-            printf "%s sent us a notice: %s\n", .nick, .what given $msg;
-        }
-    }
-```
-
-[RFC 2812, 3.3.2](https://tools.ietf.org/html/rfc2812#section-3.3.2).
-Emitted when a user sends a notice either to a channel
-or a private notice to us. See *Convenience Events* section for a number
-of more convenient ways to listen to notices and messages.
-
-### Convenience Events
+# 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`
+## `irc-mode-channel`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2
@@ -371,7 +158,7 @@ of events easier.
 Emitted when IRC `MODE` command is received and it's being operated on a
 channel, see `irc-mode` event for details.
 
-#### `irc-mode-user`
+## `irc-mode-user`
 
 ```perl6
     # :zoffix2!f@127.0.0.1 MODE zoffix2 +w
@@ -385,7 +172,7 @@ channel, see `irc-mode` event for details.
 Emitted when IRC `MODE` command is received and it's being operated on a
 user, see `irc-mode` event for details.
 
-#### `irc-to-me`
+## `irc-to-me`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hello
@@ -406,7 +193,7 @@ The `.how` method returns a `Pair` where the key is the message type used
 (`PRIVMSG` or `NOTICE`) and the value is the addressee of that message
 (a channel or us).
 
-#### `irc-addressed`
+## `irc-addressed`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :zoffix2, hello
@@ -421,7 +208,7 @@ Emitted when a user addresses us in a channel. Specifically, this means
 their message starts with our nickname, followed by optional comma or colon,
 followed by whitespace. That prefix will be stripped from the message.
 
-#### `irc-mentioned`
+## `irc-mentioned`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :Is zoffix2 a robot?
@@ -435,7 +222,7 @@ followed by whitespace. That prefix will be stripped from the message.
 Emitted when a user mentions us in a channel. Specifically, this means
 their message contains our nickname separated by a word boundary on each side.
 
-#### `irc-privmsg-channel`
+## `irc-privmsg-channel`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello
@@ -448,7 +235,7 @@ their message contains our nickname separated by a word boundary on each side.
 
 Emitted when a user sends a message to a channel.
 
-#### `irc-privmsg-me`
+## `irc-privmsg-me`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh
@@ -460,7 +247,7 @@ Emitted when a user sends a message to a channel.
 
 Emitted when a user sends us a private message.
 
-#### `irc-notice-channel`
+## `irc-notice-channel`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me!
@@ -473,7 +260,7 @@ Emitted when a user sends us a private message.
 
 Emitted when a user sends a notice to a channel.
 
-#### `irc-privmsg-me`
+## `irc-privmsg-me`
 
 ```perl6
     # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me?
@@ -485,7 +272,7 @@ Emitted when a user sends a notice to a channel.
 
 Emitted when a user sends us a private notice.
 
-#### `irc-started`
+## `irc-started`
 
 ```perl6
     method irc-started {
@@ -499,7 +286,7 @@ even if the client reconnects to the server numerous times. *IMPORTANT:*
 when this event fires, there's no guarantee we event started a connection to
 the server, let alone connected successfully.
 
-#### `irc-connected`
+## `irc-connected`
 
 ```perl6
     method irc-connected {
@@ -512,7 +299,7 @@ Similar to `irc-started`, except will be emitted every time a
 of the requested channels. That is, we'll wait to either receive the
 full user list or error message for each of the channels we're joining.
 
-### Numeric Events
+# Numeric Events
 
 Numeric IRC events can be subscribed to by defining a method with name
 `irc-` followed by the numeric code of the event (e.g. `irc-001`). The
@@ -530,3 +317,180 @@ See [this reference](https://www.alien.net.au/irc/irc2numerics.html) for
 a detailed list of numerics and their arguments available in the wild. Note:
 the client will emit an event for any received numeric with a 3-digit
 code, regardless of whether it is listed in that reference.
+
+# Named Events
+
+## `irc-nick`
+
+```perl6
+    # :zoffix!zoffix@127.0.0.1 NICK not-zoffix
+
+    method irc-nick ($msg) {
+        printf "%s changed nickname to %s\n", .nick, .new-nick given $msg;
+    }
+```
+
+[RFC 2812, 3.1.2](https://tools.ietf.org/html/rfc2812#section-3.1.2).
+Emitted when a user changes their nickname.
+
+## `irc-quit`
+
+```perl6
+    # :zoffix!zoffix@127.0.0.1 QUIT :Quit: Leaving
+
+    method irc-quit ($msg) {
+        printf "%s has quit (%s)\n", .nick, .reason given $msg;
+    }
+```
+
+[RFC 2812, 3.1.7](https://tools.ietf.org/html/rfc2812#section-3.1.7).
+Emitted when a user quits the server.
+
+## `irc-join`
+
+```perl6
+    # :zoffix!zoffix@127.0.0.1 JOIN :#perl6
+
+    method irc-join ($msg) {
+        printf "%s joined channel %s\n", .nick, .channel given $msg;
+    }
+```
+
+[RFC 2812, 3.2.1](https://tools.ietf.org/html/rfc2812#section-3.2.1).
+Emitted when a user joins a channel.
+
+## `irc-part`
+
+```perl6
+    # :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 2812, 3.2.2](https://tools.ietf.org/html/rfc2812#section-3.2.2).
+Emitted when a user leaves a channel.
+
+## `irc-mode`
+
+```perl6
+    # :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 "%s set mode(s) %s on user %s\n",
+                .nick, .modes, .who given $msg;
+        }
+    }
+```
+
+[RFC 2812, 3.1.5](https://tools.ietf.org/html/rfc2812#section-3.1.5)/[RFC 2812, 3.2.3](https://tools.ietf.org/html/rfc2812#section-3.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`
+
+```perl6
+    # :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 2812, 3.2.4](https://tools.ietf.org/html/rfc2812#section-3.2.4).
+Emitted when a user changes the topic of a channel.
+
+## `irc-invite`
+
+```perl6
+    # :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 2812, 3.2.7](https://tools.ietf.org/html/rfc2812#section-3.2.7).
+Emitted when a user invites us to a channel.
+
+## `irc-kick`
+
+```perl6
+    # :zoffix!zoffix@127.0.0.1 KICK #perl6 zoffix2 :go away
+
+    method irc-kick ($msg) {
+        printf "%s kicked %s out of %s (%s)\n",
+            .nick, .who, .channel, .reason given $msg;
+    }
+```
+
+[RFC 2812, 3.2.8](https://tools.ietf.org/html/rfc2812#section-3.2.8).
+Emitted when someone kicks a user out of a channel.
+
+## `irc-privmsg`
+
+```perl6
+    # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello
+    # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh
+
+    method irc-privmsg ($msg) {
+        if $msg?.channel {
+            # message sent to a channel
+            printf "%s said `%s` to channel %s\n",
+                .nick, .what, .channel given $msg;
+        }
+        else {
+            # private message
+            printf "%s messaged us: %s\n", .nick, .what given $msg;
+        }
+    }
+```
+
+[RFC 2812, 3.3.1](https://tools.ietf.org/html/rfc2812#section-3.3.1).
+Emitted when a user sends a message either to a channel
+or a private message to us. See *Convenience Events* section for a number
+of more convenient ways to listen to messages.
+
+## `irc-notice`
+
+```perl6
+    # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me!
+    # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me?
+
+    method irc-notice ($msg) {
+        if $msg?.channel {
+            # notice sent to a channel
+            printf "%s sent a notice `%s` to channel %s\n",
+                .nick, .what, .channel given $msg;
+        }
+        else {
+            # private notice
+            printf "%s sent us a notice: %s\n", .nick, .what given $msg;
+        }
+    }
+```
+
+[RFC 2812, 3.3.2](https://tools.ietf.org/html/rfc2812#section-3.3.2).
+Emitted when a user sends a notice either to a channel
+or a private notice to us. See *Convenience Events* section for a number
+of more convenient ways to listen to notices and messages.