aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorZoffix Znet <cpan@zoffix.com>2016-07-29 12:45:35 -0400
committerZoffix Znet <cpan@zoffix.com>2016-07-29 12:45:35 -0400
commit55e5d664753471d6a07a198c590c5102ea66cbfb (patch)
tree9053d9098eb0796915ffd3d0b4e6039947c11ab4 /docs
parent8d73a96993aca6decc024641313ea240c27e4eed (diff)
Document stuff
Diffstat (limited to 'docs')
-rw-r--r--docs/02-event-reference.md12
-rw-r--r--docs/03-method-reference.md279
2 files changed, 291 insertions, 0 deletions
diff --git a/docs/02-event-reference.md b/docs/02-event-reference.md
index 6233b24..20aa870 100644
--- a/docs/02-event-reference.md
+++ b/docs/02-event-reference.md
@@ -52,6 +52,7 @@ irc-addressed ▶ irc-to-me ▶ irc-notice-channel ▶ irc-notice â
irc-connected ▶ irc-XXX ▶ irc-numeric ▶ irc-all
irc-XXX ▶ irc-numeric ▶ irc-all
irc-join ▶ irc-all
+ irc-nick ▶ irc-all
irc-part ▶ irc-all
irc-quit ▶ irc-all
irc-unknown ▶ irc-all
@@ -176,6 +177,17 @@ irc-mode-me ▶ irc-mode ▶ irc-all
Triggered when `MODE` commands are performed on the client.
Receives `IRC::Client::Message::Mode::Me` message object.
+### `irc-nick`
+
+```
+irc-nick ▶ irc-all
+```
+
+Triggered when someone in a channel we are in changes nick.
+*Note:* typically the server will generate this event when *we* change
+a nick too.
+Receives `IRC::Client::Message::Nick` message object.
+
### `irc-notice`
```
diff --git a/docs/03-method-reference.md b/docs/03-method-reference.md
index bf4810c..92773c2 100644
--- a/docs/03-method-reference.md
+++ b/docs/03-method-reference.md
@@ -1,5 +1,284 @@
[[back to main docs]](../README.md#documentation-map)
+# Method Reference
+
+This document describes events available on various objects in use when working
+with `IRC::Client`.
+
+## Message Objects
+
+All event handlers (except for special `irc-started`) receive one positional
+argument that does `IRC::Client::Message` role and is refered to as
+the Message Object throughout the documentation. The actual received
+message object depends on the event the event handler is subscribed to.
+See [event reference](02-event-reference.md) to learn which message objects
+an event can receive.
+
+### Message Object Hierarchy
+
+All message objects reside in the `IRC::Client::Message` package and
+follow the following hierarchy, with children having all the methods
+and attributes of their parents.
+
+```
+IRC::Client::Message
+│
+├───IRC::Client::Message::Join
+├───IRC::Client::Message::Nick
+├───IRC::Client::Message::Numeric
+├───IRC::Client::Message::Part
+├───IRC::Client::Message::Ping
+├───IRC::Client::Message::Quit
+├───IRC::Client::Message::Unknown
+│
+├───IRC::Client::Message::Mode
+│  ├───IRC::Client::Message::Mode::Channel
+│  └───IRC::Client::Message::Mode::Me
+│
+├───IRC::Client::Message::Notice
+│  ├───IRC::Client::Message::Notice::Channel
+│  └───IRC::Client::Message::Notice::Me
+│
+└───IRC::Client::Message::Privmsg
+   ├───IRC::Client::Message::Privmsg::Channel
+  └───IRC::Client::Message::Privmsg::Me
+```
+
+### Methods and Attributes
+
+Subclasses inherit all the methods and attributes of their parents (see
+hierarchy chart above). Some event handlers can receive more than one
+type of a message object. In many cases, the type can be differentiated
+with a safe-method-call operator (`.?`):
+
+```perl6
+ method irc-privmsg ($e) {
+ if $e.?channel {
+ say '$e is a IRC::Client::Message::Privmsg::Channel';
+ }
+ else {
+ say '$e is a IRC::Client::Message::Privmsg::Me';
+ }
+ }
+```
+
+#### `IRC::Client::Message`
+
+##### `.irc`
+
+Contains the `IRC::Client` object.
+
+##### `.nick`
+
+Contains the nick of the sender of the message.
+
+##### `.username`
+
+Contains the username of the sender of the message.
+
+##### `.host`
+
+Contains the host of the sender of the message.
+
+##### `.usermask`
+
+Contains the usermask of the sender of the message. That is
+string constructed as `nick!username@host`
+
+##### `.command`
+
+The IRC command responsible for this event, such as `PRIVMSG` or `001`.
+
+##### `.server`
+
+The `IRC::Client::Server` object from which the event originates.
+
+##### `.args`
+
+A possibly-empty list of arguments, received for the IRC command that triggered
+the event.
+
+##### `.Str`
+
+(affects stringification of message objects). Returns a string
+constructed from `":$!usermask $!command $!args[]"`, but is overriden to
+a different value by some message objects.
+
+#### `IRC::Client::Message::Join`
+
+##### `.channel`
+
+Contains the channel name of the channel that was joined
+
+#### `IRC::Client::Message::Nick`
+
+##### `.new-nick`
+
+Contains the new nick switched to (`.nick` attribute contains the old one).
+
+#### `IRC::Client::Message::Numeric`
+
+Does not offer any object-specific methods. Use the `.command` attribute
+to find out the actual 3-digit IRC command that triggered the event.
+
+#### `IRC::Client::Message::Part`
+
+##### `.channel`
+
+Contains the channel name of the channel that was parted. Use `.args`
+attribute to get any potential parting messages.
+
+#### `IRC::Client::Message::Ping`
+
+**Included in the docs for completeness only.** Used internally. Not sent
+to any event handlers and `irc-ping` is not a valid event.
+
+##### `.reply`
+
+Takes no arguments. Replies to the server with appropriate `PONG` IRC command.
+
+#### `IRC::Client::Message::Quit`
+
+Does not offer any object-specific methods. Use `.args`
+attribute to get any potential quit messages.
+
+#### `IRC::Client::Message::Unknown`
+
+##### `.Str`
+
+Overrides the default stringification string to
+`"❚⚠❚ :$.usermask $.command $.args[]"`
+
+#### `IRC::Client::Message::Mode`
+
+Object is never sent to event handlers and merely provides commonality to
+its subclasses.
+
+##### `.modes`
+
+Contains the modes set by the IRC command that triggered the event. When
+modes are set on the channel, contains a list of `Pair`s where the key
+is the sign of the mode (`+` or `-`) and the value if the mode letter itself.
+When modes are set on the client, contains just a list of modes as strings,
+without any signs.
+
+#### `IRC::Client::Message::Mode::Channel`
+
+##### `.channel`
+
+Contains the channel on which the modes were set.
+
+#### `IRC::Client::Message::Mode::Me`
+
+Does not offer any object-specific methods.
+
+#### `IRC::Client::Message::Notice`
+
+Object is never sent to event handlers and merely provides commonality to
+its subclasses.
+
+##### `.text`
+
+Writable attribute. Contains the text of the message.
+
+##### `.replied`
+
+Writable `Bool` attribute. Automatically gets set to `True` by the
+`.reply` method. If set to `True`, indicates to the Client Object that
+the event handler's value must not be used as a reply to the message.
+
+##### `.Str`
+
+Overrides stringification of the message object to be the value of the
+`.text` attribute.
+
+#### `IRC::Client::Message::Notice::Channel`
+
+##### `.channel`
+
+Contains the channel to which the message was sent.
+
+##### `.reply`
+
+```perl6
+ $e.reply: "Hello, World!";
+ $e.reply: "Hello, World!", :where<#perl6>;
+ $e.reply: "Hello, World!", :where<Zoffix>;
+```
+
+Replies to the sender of the message using the `NOTICE` IRC command. The
+optional `:where` argument specifies a channel or nick
+where to send the message and defaults to the channel in which the message
+originated.
+
+#### `IRC::Client::Message::Notice::Me`
+
+##### `.reply`
+
+```perl6
+ $e.reply: "Hello, World!";
+ $e.reply: "Hello, World!", :where<Zoffix>;
+ $e.reply: "Hello, World!", :where<#perl6>;
+```
+
+Replies to the sender of the message using the `NOTICE` IRC command. The
+optional `:where` argument specifies a nick or channel
+where to send the message and defaults to the nick from which the message
+originated.
+
+#### `IRC::Client::Message::Privmsg`
+
+Object is never sent to event handlers and merely provides commonality to
+its subclasses.
+
+##### `.text`
+
+Writable attribute. Contains the text of the message.
+
+##### `.replied`
+
+Writable `Bool` attribute. Automatically gets set to `True` by the
+`.reply` method. If set to `True`, indicates to the Client Object that
+the event handler's value must not be used as a reply to the message.
+
+##### `.Str`
+
+Overrides stringification of the message object to be the value of the
+`.text` attribute.
+
+#### `IRC::Client::Message::Privmsg::Channel`
+
+##### `.channel`
+
+Contains the channel to which the message was sent.
+
+##### `.reply`
+
+```perl6
+ $e.reply: "Hello, World!";
+ $e.reply: "Hello, World!", :where<#perl6>;
+ $e.reply: "Hello, World!", :where<Zoffix>;
+```
+
+Replies to the sender of the message using the `PRIVMSG` IRC command. The
+optional `:where` argument specifies a channel or nick
+where to send the message and defaults to the channel in which the message
+originated.
+
+#### `IRC::Client::Message::Privmsg::Me`
+
+##### `.reply`
+
+```perl6
+ $e.reply: "Hello, World!";
+ $e.reply: "Hello, World!", :where<Zoffix>;
+ $e.reply: "Hello, World!", :where<#perl6>;
+```
+
+Replies to the sender of the message using the `PRIVMSG` IRC command. The
+optional `:where` argument specifies a nick or channel
+where to send the message and defaults to the nick from which the message
+originated.
## Up Next