diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/01-basics.md | 148 | ||||
| -rw-r--r-- | docs/02-event-reference.md | 385 | ||||
| -rw-r--r-- | docs/03-method-reference.md | 758 | ||||
| -rw-r--r-- | docs/04-big-picture-behaviour.md | 44 | ||||
| -rw-r--r-- | docs/README.md | 10 |
5 files changed, 0 insertions, 1345 deletions
diff --git a/docs/01-basics.md b/docs/01-basics.md deleted file mode 100644 index 281c745..0000000 --- a/docs/01-basics.md +++ /dev/null @@ -1,148 +0,0 @@ -[[back to doc map]](README.md) - -# Basics Tutorial - -## Table of Contents - -- [Blog Tutorial](#blog-tutorial) -- [Subscribing to Events](#subscribing-to-events) - - [Event Handler Input](#event-handler-input) -- [Responding to Events](#responding-to-events) - - [Example: Echo Bot](#example-echo-bot) -- [Generating Messages](#generating-messages) -- [Up Next](#up-next) - ----- - -This tutorial covers basic usage of `IRC::Client`, without going into -[all of the supported events](02-event-reference.md) or describing -[all of the methods](03-method-reference.md) or [available Message -Objects](04-message-objects.md). This should be enough -if you're just bringing some functionality using IRC as your interface, rather -than making, say, a full-featured IRC client. - -## Blog Tutorial - -There exists a blog post describing this bot and showcasing some of the -more advanced features. You can find it at [*yet to be published*](#). - -## Subscribing to Events - -All of the functionality is implemented as "plugins", which are passed to -the `:plugins` attribute. Plugins are just regular classes, altough they can -do the `IRC::Client::Plugin` role to obtain extra functionality. - -To subscribe to one of [the events](02-event-reference.md), simply create a -method with the event's name in your class. The tutorial will use the -`irc-to-me` event, which is a convenience event fired when the bot is addressed -in-channel or someone sends it a notice or a private message. - -### Event Handler Input - -The event handlers receive one positional argument, which is an object that -does the `IRC::Client::Message` role. The actual object received depends on the -event that triggered the handler. For example, the `irc-to-me` can receive -these message objects: - -```perl6 - IRC::Client::Message::Privmsg::Me - IRC::Client::Message::Privmsg::Channel - IRC::Client::Message::Notice::Me - IRC::Client::Message::Notice::Channel -``` - -While message objects differ in methods they offer, all of the above do have -a `.text` attribute and stringify to its value. This means we can add a type -constraint on it without having to explicitly call it: - -```perl6 - method irc-to-me ($e where /'bot command'/) { 'Do things here!'; } -``` - -## Responding to Events - -Channel messages, private messages, and notices can be replied to. Their -message objects have a `.reply` method you can call to send a reply to the -message's sender. However, it's easier to just return a value from your method -handler, which will automatically call `.reply` on the message object for you. - -Returning a value from your event handler signals to the Client Object that -it handled the event and no other plugins or event handlers should be tried. -Your plugin can do the `IRC::Client::Plugin` role (automatically exported -when you `use IRC::Client`), which provides `$.NEXT` attribute. The value -of that attribute is special and returning it signals the Client Object -that your event handler did **not** handle the event and other plugins and -event handlers should be tried. - -Here are the things your event handler can return: - -* Value of `$.NEXT`: pass the event to the next plugin or event handler than can -handle it -* `Nil` (and a select few other items that don't make sense as replies, such as -`IRC::Client` object): do not reply to the message, but do not pass the event to -any other event handler; we handled it -* `Promise`: when the Promise is `.kept`, use its value for the .reply, unless -it's a `Nil`. **Note:** you cannot return `$.NEXT` here. -* *Any other value*: mark the event as handled and don't pass it further. The -returned value will be given to message object's `.reply` method if -it has one, or ignored if it doesn't. For `irc-to-me` message objects, this -means the value will be sent back to the sender of the original message - -### Example: Echo Bot - -In this example, we subscribe to the `irc-to-me` event and respond by returning -the original message, prefixed with `You said `. - -```perl6 - use IRC::Client; - - .run with IRC::Client.new: - :host<irc.freenode.net> - :channels('#perl6bot', '#zofbot', '#myown' => 's3cret') - :debug - :plugins( - class { method irc-to-me ($e) { "You said $e.text()"} } - ) -``` - -## Generating Messages - -If your plugin needs to generate messages instead of merely responding to -commands, you can use the Client Object's `.send` method. Your plugin needs -to do the `IRC::Client::Plugin` role to get access to the Client Object via -the `$.irc` attribute: - -```perl6 -use IRC::Client; - -class AlarmBot does IRC::Client::Plugin { - method irc-connected ($) { - react { - whenever Supply.interval(3) { - $.irc.send: :where<#perl6> :text<Three seconds passed!>; - } - } - } -} - -.run with IRC::Client.new: - :nick<MahBot> - :host<irc.freenode.net> - :channels<#perl6> - :debug - :plugins(AlarmBot.new) -``` - -Here, we subscribe to the `irc-connected` event (using an anonymous parameter -for its message object, since we don't need it). It fires whenever we -successfully connect to a server. In the event handler we setup a -`react`/`whenever` loop, with a `Supply` generating an event every three -seconds. In the `whenever` block, we use the `$.irc` attribute provided -by the `IRC::Client::Plugin` role to call method `.send` on the Client Object. -In the `:where` parameter, we specify we want to send the message to -channel `#perl6` and the `:text` parameter contains the text we want to send. -The bot will send that text every 3 seconds. - -## Up Next - -Read [the event reference](02-event-reference.md) next. diff --git a/docs/02-event-reference.md b/docs/02-event-reference.md deleted file mode 100644 index fdf9d0a..0000000 --- a/docs/02-event-reference.md +++ /dev/null @@ -1,385 +0,0 @@ -[[back to doc map]](README.md) - -# Event Reference - -## Table of Contents - -- [Responding to Events](#responding-to-events) -- [Event Map](#event-map) -- [Event Triggers](#event-triggers) - - [`irc-addressed`](#irc-addressed) - - [`irc-all`](#irc-all) - - [`irc-connected`](#irc-connected) - - [`irc-join`](#irc-join) - - [`irc-mentioned`](#irc-mentioned) - - [`irc-mode`](#irc-mode) - - [`irc-mode-channel`](#irc-mode-channel) - - [`irc-mode-me`](#irc-mode-me) - - [`irc-nick`](#irc-nick) - - [`irc-notice`](#irc-notice) - - [`irc-notice-channel`](#irc-notice-channel) - - [`irc-notice-me`](#irc-notice-me) - - [`irc-numeric`](#irc-numeric) - - [`irc-part`](#irc-part) - - [`irc-privmsg`](#irc-privmsg) - - [`irc-privmsg-channel`](#irc-privmsg-channel) - - [`irc-privmsg-me`](#irc-privmsg-me) - - [`irc-quit`](#irc-quit) - - [`irc-started`](#irc-started) - - [`irc-to-me`](#irc-to-me) - - [`irc-unknown`](#irc-unknown) - - [`irc-nXXX`](#irc-nXXX) -- [Up Next](#up-next) - ---- - -The module offers named, numeric, and convenience events. The named and -numeric events correspond to IRC protocol events, while convenience events -are an extra layer provided to make using the module easier. This means one -IRC event can trigger several events of the module. For example, if someone -addresses our bot in a channel, the following chain of events will be fired: - - irc-addressed ▶ irc-to-me ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all - -The events are ordered from "narrowest" to "widest": `irc-addressed` can be -triggered only in-channel, when our bot is addressed; `irc-to-me` can also -be triggered via notice and private message, so it's wider; -`irc-privmsg-channel` includes all channel messages, so it's wider still; -and `irc-privmsg` also includes private messages to our bot. The chain ends -by the widest event of them all: `irc-all`. - -## Responding to Events - -See [section in Basic Tutorial](01-basics.md#responding-to-events) for -responding by returning a value from the event handler. - -The Message Objects received by the event handlers for the `irc-privmsg` and -`irc-notice` event chains also provide a `.reply` method using which you -can reply to the event. When this method is called `.is-replied` attribute -of the Message Object is set to `True`, which signals to the Client Object -that the returned value from the event handler should be discarded. - -## Event Map - -In the chart below, `irc-nXXX` stands for numeric events where `XXX` is a -three-digit number. See [this numerics -table](https://www.alien.net.au/irc/irc2numerics.html) for meaning of codes, -depending on the server used. - -``` -irc-addressed ▶ irc-to-me ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all - irc-mentioned ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all - 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-mentioned ▶ irc-notice-channel ▶ irc-notice ▶ irc-all - irc-notice-channel ▶ irc-notice ▶ irc-all - irc-to-me ▶ irc-notice-me ▶ irc-notice ▶ irc-all - - irc-mode-channel ▶ irc-mode ▶ irc-all - irc-mode-me ▶ irc-mode ▶ irc-all - - irc-connected ▶ irc-nXXX ▶ irc-numeric ▶ irc-all - irc-nXXX ▶ irc-numeric ▶ irc-all - irc-join ▶ irc-all - irc-nick ▶ irc-all - irc-part ▶ irc-all - irc-quit ▶ irc-all - irc-unknown ▶ irc-all - - irc-started -``` - -**Note:** `irc-started` is a special event that's exempt from the rules -applicable to all other events and their event handlers: - -* It's called just once per call of `IRC::Client`'s `.run` method, regardless -of how many times the client reconnects -* When it's called, there's no guarantee the connections to servers have -been fully established yet or channels joined yet. -* Unless all other event handlers, this one does not take any arguments -* Return values from handlers are ignored and the event is propagated to all of -the plugins -* This event does not trigger `irc-all` event - -## Event Triggers - -### `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 -``` - -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 or one of its aliases, -followed by `;` or `,` -characters, followed by any number of whitespace; or -in regex terms, matches `/^ [$nick | @aliases] <[,:]> \s* /`. -This prefix portion will be -**stripped** from the actual message. - -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-n001 ▶ 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` - -``` -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 or one of the aliases delimited by word boundaries on both -sides; or in regex terms, matches `/ << [$nick | @aliases] >> /`. - -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-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` - -``` -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-nXXX ▶ 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|aliases + `,` 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-nXXX` - -**Note:*** `XXX` stands for a three-digit numeric code of the command that -triggered the event, for example `irc-n001`. See `irc-numeric` for event trigger -that responds to all numerics. - -``` -irc-nXXX ▶ irc-numeric ▶ irc-all -``` - -Triggered on numeric IRC commands. -Receives `IRC::Client::Message::Numeric` message object. - -## Up Next - -Read [the method reference](03-method-reference.md) next. diff --git a/docs/03-method-reference.md b/docs/03-method-reference.md deleted file mode 100644 index 2e19e9e..0000000 --- a/docs/03-method-reference.md +++ /dev/null @@ -1,758 +0,0 @@ -[[back to doc map]](README.md) - -# Method Reference - -This document describes events available on various objects in use when working -with `IRC::Client`. - -## Table of Contents - -- [Message Objects (`IRC::Client::Message` and subclasses)](#message-objects-ircclientmessage-and-subclasses) - - [Message Object Hierarchy](#message-object-hierarchy) - - [Methods and Attributes](#methods-and-attributes) - - [`IRC::Client::Message`](#ircclientmessage) - - [`.irc`](#irc) - - [`.nick`](#nick) - - [`.username`](#username) - - [`.host`](#host) - - [`.usermask`](#usermask) - - [`.command`](#command) - - [`.server`](#server) - - [`.args`](#args) - - [`.Str`](#str) - - [`IRC::Client::Message::Join`](#ircclientmessagejoin) - - [`.channel`](#channel) - - [`IRC::Client::Message::Nick`](#ircclientmessagenick) - - [`.new-nick`](#new-nick) - - [`IRC::Client::Message::Numeric`](#ircclientmessagenumeric) - - [`IRC::Client::Message::Part`](#ircclientmessagepart) - - [`.channel`](#channel-1) - - [`IRC::Client::Message::Ping`](#ircclientmessageping) - - [`.reply`](#reply) - - [`IRC::Client::Message::Quit`](#ircclientmessagequit) - - [`IRC::Client::Message::Unknown`](#ircclientmessageunknown) - - [`.Str`](#str-1) - - [`IRC::Client::Message::Mode`](#ircclientmessagemode) - - [`.modes`](#modes) - - [`IRC::Client::Message::Mode::Channel`](#ircclientmessagemodechannel) - - [`.channel`](#channel-2) - - [`IRC::Client::Message::Mode::Me`](#ircclientmessagemodeme) - - [`IRC::Client::Message::Notice`](#ircclientmessagenotice) - - [`.text`](#text) - - [`.replied`](#replied) - - [`.Str`](#str-2) - - [`IRC::Client::Message::Notice::Channel`](#ircclientmessagenoticechannel) - - [`.channel`](#channel-3) - - [`.reply`](#reply-1) - - [`IRC::Client::Message::Notice::Me`](#ircclientmessagenoticeme) - - [`.reply`](#reply-2) - - [`IRC::Client::Message::Privmsg`](#ircclientmessageprivmsg) - - [`.text`](#text-1) - - [`.replied`](#replied-1) - - [`.Str`](#str-3) - - [`IRC::Client::Message::Privmsg::Channel`](#ircclientmessageprivmsgchannel) - - [`.channel`](#channel-4) - - [`.reply`](#reply-3) - - [`IRC::Client::Message::Privmsg::Me`](#ircclientmessageprivmsgme) - - [`.reply`](#reply-4) -- [Server Object (`IRC::Client::Server`)](#server-object-ircclientserver) - - [Labels](#labels) - - [Methods and Attributes](#methods-and-attributes-1) - - [`.label`](#label) - - [`.channels`](#channels) - - [`.nick`](#nick-1) - - [`.alias`](#alias) - - [`.host`](#host-1) - - [`.port`](#port) - - [`.password`](#password) - - [`.username`](#username-1) - - [`.userhost`](#userhost) - - [`.userreal`](#userreal) - - [`.Str`](#str-4) - - [Writable Non-Writable Attributes](#writable-non-writable-attributes) - - [`.current-nick`](#current-nick) - - [`.is-connected`](#is-connected) - - [`.has-quit`](#has-quit) - - [`.has-quit`](#has-quit-1) -- [Client Object (`IRC::Client`)](#client-object-ircclient) - - [Methods and Attributes](#methods-and-attributes-2) - - [`.join`](#join) - - [`.new`](#new) - - [`:channels`](#channels-1) - - [`:debug`](#debug) - - [`:filters`](#filters) - - [`:host`](#host-2) - - [`:nick`](#nick-2) - - [`:alias`](#alias-1) - - [`:password`](#password-1) - - [`:plugins`](#plugins) - - [`:port`](#port-1) - - [`:servers`](#servers) - - [`:username`](#username-2) - - [`:userhost`](#userhost-1) - - [`:userreal`](#userreal-1) - - [`.nick`](#nick-3) - - [`.part`](#part) - - [`.quit`](#quit) - - [`.run`](#run) - - [`.send`](#send) -- [Up Next](#up-next) - ---- - -## Message Objects (`IRC::Client::Message` and subclasses) - -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` - -Object is never sent to event handlers and merely provides commonality to -its subclasses. - -##### `.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. For addressed commands, -the nick will be stripped. Use `.args` method to get full, original text, -which will be the second value in the list. - -##### `.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. For addressed commands, -the nick will be stripped. Use `.args` method to get full, original text, -which will be the second value in the list. - -##### `.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. - ---- - -## Server Object (`IRC::Client::Server`) - -The Server Object represents one of the IRC servers the client is connected -to. It's returned by the `.server` attribute of the Message Object and -can be passed to various Client Object methods to indicate to which server -a command should be sent to. - -Client Object's `%.servers` attribute contains all of the `IRC::Client::Server` -objects with their keys as labels and values as objects themselves. - -### Labels - -Each `IRC::Client::Server` object has a label that was given to it during -the creation of `IRC::Client` object. `IRC::Client::Server` objects stringify -to the value of their labels and methods that can take an -`IRC::Client::Server` object can also take a `Str` with the label of that server -instead. - -### Methods and Attributes - -#### `.label` - -The label of this server. - -#### `.channels` - -A list of `Str` or `Pair` containing all the channels the client is in on this -server. Pairs represent channels with channel passwords, where the key is -the channel and the value is its password. - -#### `.nick` - -A list of nicks the client uses on this server. If one nick is -taken, next one in the list will be attempted to be used. - -#### `.alias` - -A list of aliases on this server. - -#### `.host` - -The host of the server. - -#### `.port` - -The port of the server. - -#### `.password` - -The password of the server. - -#### `.username` - -Our username on this server. - -#### `.userhost` - -Our hostname on this server. - -#### `.userreal` - -The "real name" of our client. - -#### `.Str` - -Affects stringification of the object and makes it stringify to the value -of `.label` attribute. - -#### Writable Non-Writable Attributes - -The following attributes are writable, however, they are written to by -the internals and the behaviour when writing to them directly is undefined. - -##### `.current-nick` - -Writable attribute. Our currently-used nick. Will be one of the nicks returned -by `.nicks`. - -##### `.is-connected` - -Writable `Bool` attribute. Indicates whether we're currently in a state -where the server considers us connected. This defaults to `False`, then is set -to `True` when the server sends us `001` IRC command and set back to `False` -when the socket connection breaks. - -##### `.has-quit` - -Writable `Bool` attribute. Set to `True` when `.quit` method is called -on the Client Object and is used by the socket herder to determine whether -or not the socket connection was cut intentionally. - -##### `.has-quit` - -Writable `IO::Socket::Async` attribute. Contains an object representing -the socket connected to the server, although it may already be closed. - ---- - -## Client Object (`IRC::Client`) - -The Client Object is the heart of this module. The `IRC::Client` you instantiate -and `.run`. The running Client Object is available to your plugins via -`.irc` attribute that you can obtain by doing the `IRC::Client::Plugin` role -or via `.irc` attribute on Message Objects your event handler receives. - -The client object's method let you control the client: e.g. joining or parting -channels, changing nicks, banning users, or sending text messages. - -### Methods and Attributes - -#### `.join` - -```perl6 - $.irc.join: <#foo #bar #ber>, :$server; -``` - -Causes the client join the provided channels. -If `:server` named argument is given, will operate only on that server; -otherwise operates on all connected servers. - -#### `.new` - -```perl6 -my $irc = IRC::Client.new: - :debug - :host<irc.freenode.net> - :6667port - :password<s3cret> - :channels<#perl #perl6 #rust-lang> - :nick<MahBot> - :alias('foo', /b.r/) - :username<MahBot> - :userhost<localhost> - :userreal('Mah awesome bot!') - :servers( - freenode => %(), - local => %( :host<localhost> ), - ) - :plugins( - class { method irc-to-me ($ where /42/) { 'The answer to universe!' } } - ) - :filters( - -> $text where .lines > 5 or .chars > 300 { "Text is too big!!!" } - ) -``` - -Instantiates a new `IRC::Client` object. Takes the following named arguments: - -##### `:channels` - -```perl6 - :channels('#perl6bot', '#zofbot', '#myown' => 's3cret') -``` - -A list of `Str` or `Pair` containing the channels to join. -Pairs represent channels with channel passwords, where the key is -the channel and the value is its password. -**Defaults to:** `#perl6` - -##### `:debug` - -Takes an `Int`. When set to a positive number, causes debug output to be -generated. Install optional -[Terminal::ANSIColor]https://modules.perl6.org/repo/Terminal::ANSIColor] to -make output colourful. Debug levels: - -* `0`—no debug output -* `1`—basic debug output -* `2`—also include list of emitted events -* `3`—also include `irc-all` in the list of emitted events - -**Defaults to:** `0` - -##### `:filters` - -Takes a list of `Callable`s. Will attempt to call them for replies to -`PRIVMSG` and `NOTICE` events if the signatures accept `($text)` or -`($text, :$where)` calls, where `$text` is the reply text and `:$where` is -a named argument of the destination of the reply (either a user or a channel -name). - -Callables with `:$where` in the signature must return two values: the new -text to reply with and the location. Otherwise, just one value needs to -be returned: the new text to reply with. - -**By default** not specified. - -##### `:host` - -The hostname of the IRC server to connect to. -**Defaults to:** `localhost` - -##### `:nick` - -A list of nicknames to use. If set to just one value will automatically -generate three additional nicknames that have underscores appended -(e.g. `P6Bot`, `P6Bot_`, `P6Bot__`, `P6Bot___`). - -If one of the given nicks is in use, the client will attempt to use the -next one in the list. - -##### `:alias` - -**Defaults to:** `P6Bot` - -```perl6 - :alias('foo', /b.r/) -``` - -A list of `Str` or `Regex` objects that in the context of -`irc-addressed`, `irc-to-me`, and `irc-mentioned` events will be used -as alternative nicks. In other words, specifying `'bot'` as alias will allow -you to address the bot using `bot` nick, regardless of the actual nick the -bot is currently using. - -**Defaults to:** empty list - -##### `:password` - -The server password to use. On some networks (like Freenode), the server -password also functions as NickServ's password. -**By default** not specified. - -##### `:plugins` - -Takes a list of instantiated objects or type objects that implement the -functionality of the system. See [basics tutorial](01-basics.md) and -[event reference](02-event-reference.md) for more information on how -to implement plugin classes. - -**By default** not specified. - -##### `:port` - -The port of the IRC server to connect to. Takes an `Int` between 0 and 65535. -**Defaults to:** `6667` - -##### `:servers` - -Takes an `Assosiative` with keys as labels of servers and values with -server-specific configuration. Valid keys in the configuration are -`:host`, `:port`, `:password`, `:channels`, `:nick`, `:username`, -`:userhost`, and `:userreal`. They take the same values as same-named arguments -of the `IRC::Client.new` method and if any key is omitted, the value -of the `.new`'s argument will be used. - -If `:servers` is not specified, then a server will be created with the -label `_` (underscore). - -**By default** not specified. - -##### `:username` - -The IRC username to use. **Defaults to:** `Perl6IRC` - -##### `:userhost` - -The hostname of your client. **Defaults to:** `localhost` and can probably -be left as is, unless you're having issues connecting. - -##### `:userreal` - -The "real name" of your client. **Defaults to:** `Perl6 IRC Client` - ----- - -#### `.nick` - -```perl6 - $.irc.nick: 'MahBot', :$server; - $.irc.nick: <MahBot MahBot2 MahBot3 MahBot4 MahBot5>, :$server; -``` - -Causes the client to change its nick to the one provided and uses this -as new value of `.current-nick` and `.nick` attributes of the appropriate -`IRC::Client::Server` object. If only one nick -is given, another 3 nicks will be automatically generated by appending -a number of underscores. Will automatically retry nicks further in the list -if the currently attempted one is already in use. - -If `:server` named argument is given, will operate only on that server; - otherwise operates on all connected servers. - -#### `.part` - -```perl6 - $.irc.part: <#foo #bar #ber>, :$server; -``` - -Causes the client part the provided channels. -If `:server` named argument is given, will operate only on that server; -otherwise operates on all connected servers. - -#### `.quit` - -```perl6 - $.irc.quit; - $.irc.quit: :$server; -``` - -Causes the client to quit the IRC server. -If `:server` named argument is given, will operate only on that server; -otherwise operates on all connected servers. - -#### `.run` - -Takes no arguments. Runs the IRC client, causing it to connect to servers -and do all of its stuff. Returns only if all of the servers the client connects -to have been explicitly `.quit` from. - -#### `.send` - -```perl6 - $.irc.send: :where<Zoffix> :text<Hello!>; - $.irc.send: :where<#perl6> :text('I ♥ Perl 6!'); - $.irc.send: :where<Senpai> :text('Notice me!') :notice :$server; -``` - -Sends a `:text` message to `:where`, using either a `PRIVMSG` or `NOTICE`. -The `:where` can be either a user's nick or a channel name. If `:notice` -argument is set to a `True` value will use `NOTICE` otherwise will use -`PRIVMSG` (if you just want to send text to channel like you'd normally -do when talking with regular IRC clients, that'd be the `PRIVMSG` messages). - -If `:server` named argument is given, will operate only on that server; -otherwise operates on all connected servers. - -**NOTE:** calls to `.send` when server is not connected yet will be -**semi-silently ignored** (only debug output will mention that they were -ignored). This is done on purpose, to prevent `.send` calls from interfering -with the connection negotiation during server reconnects. Although not -free from race conditions, you can mitigate this issue by checking the -`.is-connected` attribute on the appropriate `IRC::Client::Server` object -before attempting the `.send` - -## Up Next - -Read [Big Picture behaviour](04-big-picture-behaviour.md) next. diff --git a/docs/04-big-picture-behaviour.md b/docs/04-big-picture-behaviour.md deleted file mode 100644 index 1f67b84..0000000 --- a/docs/04-big-picture-behaviour.md +++ /dev/null @@ -1,44 +0,0 @@ -[[back to doc map]](README.md) - -# Big-Picture Behaviour - -This document describes the general behaviour of the `IRC::Client` clients. - -## Table of Contents - -- [Connection Maintenance](#connection-maintenance) -- [Nickname Maintenance](#nickname-maintenance) - ---- - -## Connection Maintenance - -The client is designed with the goal of being run indefinitely. As such, it -will restart server connections if they close. - -If a connection fails or a disconnect happens, the client will wait -10 seconds (non-blockingly) and attempt to reconnect, repeating the process -if the reconnect fails too. This loop will continue indefinitely until either -the connection is established or the client explicitly quits the server -using the `.quit` method on the Client Object. - -The described process applies to individual servers, regardless of how many -servers the client is asked to connect to. Thus, it's possible that one -server will be in the reconnect loop, while others will be connected and -functioning like normal. It's also possible for the user to `.quit` some -servers, while maintaining connection to others. The client object's -`.run` method will return only when *all* servers have been `.quit` - -## Nickname Maintenance - -If the first nickname assigned to the bot at the start (or one set -using `.nick` method) is in use, the bot will automatically use the next one -in the list. If *all* of the nicks are in use, it will wait a short period -of time, before retrying all nicks again. - -Note: the same system will be applied if the proposed nick is an erroneous -one that cannot be used on the server—for example, it can contain invalid -characters or be too long. This means the bot will never succeed -in connecting to the server or changing a nick if the entire list of nicks it -possesses are invalid ones. Be sure to turn the debug output on and inspect -output for any suspect messages if you're having issues connecting. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 3a6f153..0000000 --- a/docs/README.md +++ /dev/null @@ -1,10 +0,0 @@ -[[back to main docs]](../README.md) - -# Documentation Map - -* [Blog Post](http://perl6.party/post/IRC-Client-Perl-6-Multi-Server-IRC-Module) -* [Basics Tutorial](01-basics.md) -* [Event Reference](02-event-reference.md) -* [Method Reference](03-method-reference.md) -* [Big-Picture Behaviour](04-big-picture-behaviour.md) -* [Examples](../examples/) |