aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZoffix Znet <cpan@zoffix.com>2016-07-29 11:39:53 -0400
committerZoffix Znet <cpan@zoffix.com>2016-07-29 11:39:53 -0400
commit8d73a96993aca6decc024641313ea240c27e4eed (patch)
tree5b10030f12b94eb8e4459688164c2b4f080a9174
parentfba0bb9ed6774b666fa4002fa4a052ae3964bb8e (diff)
Add events reference
-rw-r--r--docs/02-event-reference.md246
1 files changed, 241 insertions, 5 deletions
diff --git a/docs/02-event-reference.md b/docs/02-event-reference.md
index b1ec2ba..6233b24 100644
--- a/docs/02-event-reference.md
+++ b/docs/02-event-reference.md
@@ -49,8 +49,12 @@ irc-addressed â–¶ irc-to-me â–¶ irc-notice-channel â–¶ irc-notice â
irc-mode-channel â–¶ irc-mode â–¶ irc-all
irc-mode-me â–¶ irc-mode â–¶ irc-all
- irc-connected â–¶ irc-numeric â–¶ irc-XXX â–¶ irc-all
- irc-numeric â–¶ irc-XXX â–¶ irc-all
+ irc-connected â–¶ irc-XXX â–¶ irc-numeric â–¶ irc-all
+ irc-XXX â–¶ irc-numeric â–¶ irc-all
+ irc-join â–¶ irc-all
+ irc-part â–¶ irc-all
+ irc-quit â–¶ irc-all
+ irc-unknown â–¶ irc-all
irc-started
```
@@ -72,11 +76,11 @@ the plugins
### `irc-addressed`
```
-irc-addressed â–¶ irc-to-me â–¶ irc-privmsg-channel â–¶ irc-privmsg â–¶ irc-all
-irc-addressed â–¶ irc-to-me â–¶ irc-notice-channel â–¶ irc-notice â–¶ irc-all
+irc-addressed â–¶ irc-to-me â–¶ irc-privmsg-channel â–¶ irc-privmsg â–¶ irc-all
+irc-addressed â–¶ irc-to-me â–¶ irc-notice-channel â–¶ irc-notice â–¶ irc-all
```
-This event chain is triggered when the client is addressed in channel either
+This event chain is triggered when the client is addressed in a channel either
via a `PRIVMSG` or `NOTICE` IRC message. 'Addressed' means the message line
starts with the current nickname of the client, followed by single whitespace character, `;`, or `,` characters, followed by any number of whitespace; or
in regex terms, matches `/^ $nick <[,:\s]> \s* /`. This prefix portion will be
@@ -87,6 +91,44 @@ Possible message objects received by event handler:
* `IRC::Client::Message::Privmsg::Channel`
* `IRC::Client::Message::Notice::Channel`
+### `irc-all`
+
+```
+irc-all
+```
+
+Triggered on all events, except for the special `irc-started` event.
+
+Possible message objects received by event handler:
+* `IRC::Client::Message::Notice::Channel`
+* `IRC::Client::Message::Notice::Me`
+
+### `irc-connected`
+
+```
+irc-connected â–¶ irc-001 â–¶ irc-numeric â–¶ irc-all
+```
+
+Triggered on `001` numeric IRC command that indicates we successfully
+connected to the IRC server and obtained a nickname. *Note:* it's not
+guaranteed that we already joined all the channels when this event is triggered;
+in fact, it's more likely that we haven't yet. *Also note:* that in long
+running programs this event will be triggered more than once, because the
+client automatically reconnects when connection drops, so the event will
+be triggered on each reconnect. See also `irc-started`
+
+Receives `IRC::Client::Message::Numeric` message object.
+
+### `irc-join`
+
+```
+irc-join â–¶ irc-all
+```
+
+Triggered when someone joins a channel we are in. *Note:* typically the
+server will generate this event when *we* join a channel too.
+Receives `IRC::Client::Message::Join` message object.
+
### `irc-mentioned`
```
@@ -94,9 +136,203 @@ irc-mentioned â–¶ irc-privmsg-channel â–¶ irc-privmsg â–¶ irc-all
irc-mentioned â–¶ irc-notice-channel â–¶ irc-notice â–¶ irc-all
```
+This event chain is triggered when the client is mentioned in a channel either
+via a `PRIVMSG` or `NOTICE` IRC message. Being mentioned means the message
+contains our nick delimited by word boundaries on both sides; or in regex
+terms, matches `/ << $nick >> /`.
+
+Possible message objects received by event handler:
+* `IRC::Client::Message::Privmsg::Channel`
+* `IRC::Client::Message::Notice::Channel`
+
+### `irc-mode`
+
+```
+irc-mode â–¶ irc-all
+```
+
+Triggered when `MODE` commands are performed on the client or on the channel
+we are in.
+
+Possible message objects received by event handler:
+* `IRC::Client::Message::Mode::Channel`
+* `IRC::Client::Message::Mode::Me`
+
+### `irc-mode-channel`
+
+```
+irc-mode-channel â–¶ irc-mode â–¶ irc-all
+```
+
+Triggered when `MODE` commands are performed on a channel the client is in
+Receives `IRC::Client::Message::Mode::Channel` message object.
+
+### `irc-mode-me`
+
+```
+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-notice`
+
+```
+irc-notice â–¶ irc-all
+```
+
+Triggered on `NOTICE` messages sent to a channel the client is in or to
+the client directly.
+
+Possible message objects received by event handler:
+* `IRC::Client::Message::Notice::Channel`
+* `IRC::Client::Message::Notice::Me`
+
+### `irc-notice-channel`
+
+```
+irc-notice-channel â–¶ irc-notice â–¶ irc-all
+```
+
+Triggered on `NOTICE` messages sent to a channel the client is in.
+Receives `IRC::Client::Message::Notice::Channel` message object.
+
+### `irc-notice-me`
+
+```
+irc-notice-me â–¶ irc-notice â–¶ irc-all
+```
+
+Triggered on `NOTICE` messages sent directly to the client.
+Receives `IRC::Client::Message::Notice::Me` message object.
+
+### `irc-numeric`
+
+```
+irc-numeric â–¶ irc-XXX â–¶ irc-all
+```
+
+Triggered on numeric IRC commands.
+Receives `IRC::Client::Message::Numeric` message object.
+
+### `irc-part`
+
+```
+irc-part â–¶ irc-all
+```
+
+Triggered when someone parts (leaves without quitting IRC entirely) a channel
+we are in. Receives `IRC::Client::Message::Part` message object.
+
+### `irc-privmsg`
+
+```
+irc-privmsg â–¶ irc-all
+```
+
+Triggered on `PRIVMSG` messages sent to a channel the client is in or to
+the client directly.
+
+Possible message objects received by event handler:
+* `IRC::Client::Message::Privmsg::Channel`
+* `IRC::Client::Message::Privmsg::Me`
+
+### `irc-privmsg-channel`
+
+```
+irc-privmsg-channel â–¶ irc-privmsg â–¶ irc-all
+```
+
+Triggered on `PRIVMSG` messages sent to a channel the client is in.
+Receives `IRC::Client::Message::Privmsg::Channel` message object.
+
+
+### `irc-privmsg-me`
+
+```
+irc-privmsg-me â–¶ irc-privmsg â–¶ irc-all
+```
+
+Triggered on `PRIVMSG` messages sent directly to the client.
+Receives `IRC::Client::Message::Privmsg::Me` message object.
+
+### `irc-quit`
+
+```
+irc-quit â–¶ irc-all
+```
+
+Triggered when someone in a channel we are in quits IRC.
+Receives `IRC::Client::Message::Quit` message object.
+
+### `irc-started`
+
+```
+irc-started
+```
+
+The event is different from all others (see end of `Event Map` section). It's
+triggered just once per call of `.run` method on `IRC::Client` object,
+regardless of how many times the client reconnects, and it's
+called on all of the plugins, regardless of the return value of the
+event handler.
+
+Does not receive any arguments.
+
+### `irc-to-me`
+
+```
+irc-addressed â–¶ irc-to-me â–¶ irc-privmsg-channel â–¶ irc-privmsg â–¶ irc-all
+ irc-to-me â–¶ irc-privmsg-me â–¶ irc-privmsg â–¶ irc-all
+
+irc-addressed â–¶ irc-to-me â–¶ irc-notice-channel â–¶ irc-notice â–¶ irc-all
+ irc-to-me â–¶ irc-notice-me â–¶ irc-notice â–¶ irc-all
+```
+
+This event chain is triggered when the client is addressed in a channel via
+a `PRIVMSG` or `NOTICE` IRC message or receives a private or notice
+message directly. In cases where the trigger happened due to being addressed
+in channel, the prefix used for addressing (nick + `,` or `.` + whitespace)
+will be stripped from the message.
+
Possible message objects received by event handler:
* `IRC::Client::Message::Privmsg::Channel`
+* `IRC::Client::Message::Privmsg::Me`
* `IRC::Client::Message::Notice::Channel`
+* `IRC::Client::Message::Notice::Me`
+
+*Note irrelevant to common users:* to avoid spurious triggers during
+IRC server connection negotiation, this event does *not* fire until the server
+deems the client connected; that is, sends the IRC `001` command.
+
+### `irc-unknown`
+
+```
+irc-unknown â–¶ irc-all
+```
+
+Triggered when an unknown event is generated. You're not supposed to receive
+any of these and receiving one likely indicates a problem with `IRC::Client`.
+Please report this [on the Issue
+tracker](https://github.com/zoffixznet/perl6-IRC-Client/issues/new),
+indicating what server generated such a message and include your code too,
+if possible.
+
+Receives `IRC::Client::Message::Unknown` message object.
+
+### `irc-XXX`
+
+**Note:*** `XXX` stands for a three-digit numeric code of the command that
+triggered the event, for example `irc-001`. See `irc-numeric` for event trigger
+that responds to all numerics.
+
+```
+irc-XXX â–¶ irc-numeric â–¶ irc-all
+```
+
+Triggered on numeric IRC commands.
+Receives `IRC::Client::Message::Numeric` message object.
## Up Next