From 55e5d664753471d6a07a198c590c5102ea66cbfb Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 29 Jul 2016 12:45:35 -0400 Subject: Document stuff --- docs/02-event-reference.md | 12 ++ docs/03-method-reference.md | 279 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 291 insertions(+) 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; +``` + +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; + $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; +``` + +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; + $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 -- cgit v1.1