From 24c3b1d0b52ec0ee6881d1598250fd592fa70f09 Mon Sep 17 00:00:00 2001
From: Zoffix Znet <cpan@zoffix.com>
Date: Fri, 27 May 2016 20:27:22 -0400
Subject: Describe Message Object

---
 DESIGN/01-main.md              | 75 ++++++++++++++++++++++++++++++++++++++++++
 DESIGN/specs-and-references.md |  1 +
 2 files changed, 76 insertions(+)

diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md
index 9758fb6..af4e47b 100644
--- a/DESIGN/01-main.md
+++ b/DESIGN/01-main.md
@@ -172,6 +172,81 @@ A plugin can send messages and emit events at will:
         }
     }
 ```
+
+# Message Object Interface
+
+The message object received by all non-custom events is an event-specific
+subclass of `IRC::Client::Message`. The subclass is named
+`IRC::Client::Message::$NAME`, where `$NAME` is:
+
+* Named and Convenience events use their names without `irc-` part, with any `-`
+changed to `::` and with each word written in `Title Case`. e.g.
+message object for `irc-privmsg-me` is `IRC::Client::Message::Privmsg::Me`
+* Numeric events always receive `IRC::Client::Message::Numeric` message
+object, regardless of the actual number of the event.
+
+Along with event-specific methods
+described under each event, the `IRC::Client::Message` offers the following
+methods:
+
+## `.nick`
+
+```perl6
+    say $msg.nick ~ " says hello";
+```
+
+Contains the nickname of the sender of the message.
+
+## `.username`
+
+```perl6
+    say $msg.nick ~ " has username " ~ $msg.username;
+```
+
+Contains the username of the sender of the message.
+
+## `.host`
+
+```perl6
+    say $msg.nick ~ " is connected from " ~ $msg.host;
+```
+
+Hostname of sender of the message.
+
+## `.usermask`
+
+```perl6
+    say $msg.usermask;
+```
+
+Nick, username, and host combined into a full usermask, e.g.
+`Zoffix!zoffix@zoffix.com`
+
+## `.reply`
+
+```perl6
+    $msg.reply: 'I love you too'
+        if $msg.what ~~ /'I love you'/;
+```
+
+Replies back to a message. For example, if we received the message as a
+private message to us, the reply will be a private message back to the
+user. Same for notices. For in-channel messages, `irc-addressed`
+and `irc-to-me` will address the sender in return, while all other in-channel
+events will not.
+
+**NOTE:** this method is only available for these events:
+
+* `irc-privmsg`
+* `irc-notice`
+* `irc-to-me`
+* `irc-addressed`
+* `irc-mentioned`
+* `irc-privmsg-channel`
+* `irc-privmsg-me`
+* `irc-notice-channel`
+* `irc-privmsg-me`
+
 # Convenience Events
 
 These sets of events do not have a corresponding IRC command defined by the
diff --git a/DESIGN/specs-and-references.md b/DESIGN/specs-and-references.md
index ec0bc93..917e606 100644
--- a/DESIGN/specs-and-references.md
+++ b/DESIGN/specs-and-references.md
@@ -10,6 +10,7 @@
 * [WebIRC](https://irc.wiki/WebIRC)
 * [CTCP SPEC](http://cpansearch.perl.org/src/HINRIK/POE-Component-IRC-6.78/docs/ctcpspec.html)
 * [DCC Description](http://www.irchelp.org/irchelp/rfc/dccspec.html)
+* [DCC2](https://tools.ietf.org/id/draft-smith-irc-dcc2-negotiation-00.txt)
 
 # Future
 
-- 
cgit v1.1