From 3f65d48264430428a2165f6a9f5a4e16f823f6b8 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Thu, 19 May 2016 19:49:39 -0400 Subject: Start new design docs --- DESIGN/01-main.md | 70 ++++++++++++++++++++++++++++++++++++++++++ DESIGN/specs-and-references.md | 15 +++++++++ 2 files changed, 85 insertions(+) create mode 100644 DESIGN/01-main.md create mode 100644 DESIGN/specs-and-references.md (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md new file mode 100644 index 0000000..16ecf24 --- /dev/null +++ b/DESIGN/01-main.md @@ -0,0 +1,70 @@ +# PURPOSE + +The purpose of IRC::Client is to provide serve as a fully-functional IRC +client that--unlike programs like HexChat or mIRC--provide a programmatic +interface to IRC. So, for example, to send a message to a channel, instead +of typing a message in a message box and pressing ENTER, a method is called +and given a string. + +Naturally, such an interface provides vast abilities to automate interactions +with IRC or implement a human-friendly interface, such as HexChat or mIRC. + +# GOALS + +An implementation must achieve these goals: + +## Ease of Use + +For basic use, such as a bot that responds to triggers said in channel, +the details of the IRC protocol must be as invisible as possible. Just as any +user can install HexChat and join a channel and talk, similar usability has +to be achieved by the implementation. + +As an example, a HexChat user can glance at the user list or channel topic +without explicitly issuing `NAMES` or `TOPIC` IRC commands. The implementation +should thus provide similar simplicity and provide a userlist or topic +via a convenient method rather than explicit method to send the appropriate +commands and the requirement of listening for the server response events. + +## Client-Generated Events + +The implementation must allow the users of the code to emit IRC and custom +events. For example, given plugins A and B, with A performing processing +first, plugin A can mark all `NOTICE` IRC events as handled and emit them +as `PRIVMSG` events instead. From the point of view of second plugin B, no +`NOTICE` commands ever happen (as they arrive to it as `PRIVMSG`). + +Similarly, plugin A can choose to emit custom event `FOOBAR` instead of +`PRIVMSG`, to which plugin B can choose to respond to. + +## Possibility of Non-Blocking Code + +The implementation must allow the user to perform responses to events in +a non-blocking manner if they choose to. + +# DESIGN + +The implementation consists of Core code responsible for maintaining the +state of the connected client, parsing of server messages, and sending +essential messages, as well as relating messages to and from plugins. + +The implementation distribution may also include several plugins that may +be commonly needed by users. Such plugins are not enabled by default and +the user must request their inclusion with code. + +## Core + +### Client Object + +Client Object represents a connected IRC client and is aware of and can +manipulate its state, such as disconnecting, joining or parting a channel, +or sending messages. + +A program may have multiple Client Objects, but each of them can be connected +only to one IRC server. + +A relevant Client Object must be easily accessible to the user of the +implementation. This includes user's plugins responsible for handling +events. + +### diff --git a/DESIGN/specs-and-references.md b/DESIGN/specs-and-references.md new file mode 100644 index 0000000..12c1f23 --- /dev/null +++ b/DESIGN/specs-and-references.md @@ -0,0 +1,15 @@ + +# Specs + +* [RFC 1459](https://tools.ietf.org/html/rfc1459) +* [RFC 2810](https://tools.ietf.org/html/rfc2810) +* [RFC 2811](https://tools.ietf.org/html/rfc2811) +* [RFC 2812](https://tools.ietf.org/html/rfc2812) +* [RFC 2813](https://tools.ietf.org/html/rfc2813) +* [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) + +# Future + +IRCv3 group: http://ircv3.net/ -- cgit v1.1 From 40fad4debbb4e9f3100421a1687e9b0f1ec7f7ca Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 21 May 2016 18:44:25 -0400 Subject: Write some more --- DESIGN/01-main.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 16ecf24..2b4d419 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -68,3 +68,37 @@ implementation. This includes user's plugins responsible for handling events. ### + +## Message Delivery + +An event listener receives the event message in the form of an object. +The object must provide all the relevant information about the source +and content of the message. + +The message object's attributes must be mutable, and where appropriate, +it must provide the means to send the message back to the originator +of the message. For example, here's a potential implementation of +`PRIVMSG` handler that receives the message object: + + use IRC::Client::Plugin; + unit Plugin::Foo is IRC::Client::Plugin; + + method irc-privmsg ($msg) { + return IRC_NOT_HANDLED unless $msg.channel eq '#perl6'; + $msg.what = "Nice to meet you, $msg.who()"; + $msg.send; + } + +The message object should include a means to access the Client Object to +perform operations best suited for it and not the message object. Here is +a possible implementation to re-emit a `NOTICE` message sent to channel +`#perl6` as a `PRIVMSG` message. + + method irc-notice ($msg) { + if $msg.channel eq '#perl6' { + $msg.how = 'PRIVMSG'; + $msg.irc.emit: 'PRIVMSG', $msg; + } + + return IRC_NOT_HANDLED; + } -- cgit v1.1 From e4c592537e75f4eb95ef8f8c891f7f4c439b0aaa Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 09:12:45 -0400 Subject: Write some design --- DESIGN/01-main.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 155 insertions(+), 13 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 2b4d419..15f5ae1 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -67,26 +67,39 @@ A relevant Client Object must be easily accessible to the user of the implementation. This includes user's plugins responsible for handling events. -### +### Message Delivery -## Message Delivery +An event listener is defined by a method in a plugin class. The name +of the method starts with `irc-` and followed by the lowercase name of the +event. User-defined events follow the same pattern, except they start with +`irc-custom-`: + + use IRC::Client::Plugin; + unit Plugin::Foo is IRC::Client::Plugin; + + # Listen to PRIVMSG IRC events: + method irc-privmsg ($msg) { + return IRC_NEXT unless $msg.channel eq '#perl6'; + $msg.reply: 'Nice to meet you!'; + } + + method irc-custom-my-event ($some, $random, :$args) { + return IRC_NEXT unless $random > 5; + $.irc.send: where => '#perl6', what => 'Custom event triggered!'; + } An event listener receives the event message in the form of an object. The object must provide all the relevant information about the source and content of the message. The message object's attributes must be mutable, and where appropriate, -it must provide the means to send the message back to the originator +it must provide a means to send the message back to the originator of the message. For example, here's a potential implementation of `PRIVMSG` handler that receives the message object: - use IRC::Client::Plugin; - unit Plugin::Foo is IRC::Client::Plugin; - method irc-privmsg ($msg) { - return IRC_NOT_HANDLED unless $msg.channel eq '#perl6'; - $msg.what = "Nice to meet you, $msg.who()"; - $msg.send; + return IRC_NEXT unless $msg.channel eq '#perl6'; + $msg.reply: 'Nice to meet you!'; } The message object should include a means to access the Client Object to @@ -95,10 +108,139 @@ a possible implementation to re-emit a `NOTICE` message sent to channel `#perl6` as a `PRIVMSG` message. method irc-notice ($msg) { - if $msg.channel eq '#perl6' { - $msg.how = 'PRIVMSG'; - $msg.irc.emit: 'PRIVMSG', $msg; + $.irc.emit: 'PRIVMSG', $msg + if $msg.channel eq '#perl6'; + + IRC_NEXT; + } + +A plugin can send messages and emit events at will: + + method irc-connected { + Supply.interval(60).tap: { + $.irc.send: where => '#perl6', what => 'One minute passed!!'; + }; + Promise.in(60*60).then: { + $.irc.send: + where => 'Zoffix', + what => 'I lived for one hour already!", + :notice; + + $.irc.emit: 'CUSTOM-MY-EVENT', 'One hour passed!'; } + } + +## Supported Events + +### Channel Operations - return IRC_NOT_HANDLED; +[RFC 1459, 4.2](https://tools.ietf.org/html/rfc1459#section-4.2) + +#### `irc-join` + + # :zoffix!zoffix@127.0.0.1 JOIN :#perl6 + + method irc-join ($msg) { + printf "%s joined channel %s\n", .nick, .channel given $msg; } + +[RFC 1459, 4.2.1](https://tools.ietf.org/html/rfc1459#section-4.2.1). +Emitted when user joins a channel. + +#### `irc-part` + + # :zoffix!zoffix@127.0.0.1 PART #perl6 :Leaving + + method irc-part ($msg) { + printf "%s left channel %s (%s)\n", .nick, .channel, .reason given $msg; + } + +[RFC 1459, 4.2.2](https://tools.ietf.org/html/rfc1459#section-4.2.2). +Emitted when user leaves a channel. + +#### `irc-mode` + + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* + # :zoffix2!f@127.0.0.1 MODE zoffix2 +w + + method irc-mode ($msg) { + if $msg?.channel { + # channel mode change + printf "%s set mode(s) %s in channel %s\n", + .nick, .modes, .channel given $msg; + } + else { + # user mode change + printf "Nick %s set mode(s) %s on user %s\n", + .nick, .modes, .who given $msg; + } + } + +[RFC 1459, 4.2.3](https://tools.ietf.org/html/rfc1459#section-4.2.3). +Emitted when IRC `MODE` command is received. As the command is dual-purpose, +the message object will have either `.channel` method available +(for channel mode changes) or `.who` method (for user mode changes). See +also `irc-mode-channel` and `irc-mode-user` convenience events. + +For channel modes, the `.modes` method returns a list of `Pair` where key +is the mode set and the value is the argument for that mode (i.e. "limit", +"user", or "banmask") or an empty string if the mode takes no arguments. + +For user modes, the `.modes` method returns a list of `Str` of the modes +set. + +#### `irc-topic` + + # :zoffix!zoffix@127.0.0.1 TOPIC #perl6 :meow + + method irc-topic ($msg) { + printf "%s set topic of channel %s to %s\n", + .nick, .channel, .topic given $msg; + } + +[RFC 1459, 4.2.4](https://tools.ietf.org/html/rfc1459#section-4.2.4). +Emitted when a user changes topic of a channel. + +#### `irc-invite` + + # :zoffix!zoffix@127.0.0.1 INVITE zoffix2 :#perl6 + + method irc-invite ($msg) { + printf "%s invited us to channel %s\n", + .nick, .channel given $msg; + } + +[RFC 1459, 4.2.7](https://tools.ietf.org/html/rfc1459#section-4.2.7). +Emitted when a user invites us to a channel. + +### Convenience Events + +These sets of events do not have a corresponding IRC command defined by the +protocol and instead are offered to make listening for a specific kind +of events easier. + +#### `irc-mode-channel` + + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* + + method irc-mode-channel ($msg) { + printf "Nick %s with usermask %s set mode(s) %s in channel %s\n", + .nick, .usermask, .modes, .channel given $msg; + } + +Emitted when IRC `MODE` command is received and it's being operated on a +channel, see `irc-mode` event for details. + +#### `irc-mode-user` + + # :zoffix2!f@127.0.0.1 MODE zoffix2 +w + + method irc-mode-user ($msg) { + printf "Nick %s with usermask %s set mode(s) %s on user %s\n", + .nick, .usermask, .modes, .who given $msg; + } + +Emitted when IRC `MODE` command is received and it's being operated on a +user, see `irc-mode` event for details. -- cgit v1.1 From c9bac2e1889dd66078d42062cf6f4e97da766a45 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 09:17:10 -0400 Subject: Tell GitHub our codes are Perl 6 --- DESIGN/01-main.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 15f5ae1..83814d9 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -74,6 +74,7 @@ of the method starts with `irc-` and followed by the lowercase name of the event. User-defined events follow the same pattern, except they start with `irc-custom-`: +```perl6 use IRC::Client::Plugin; unit Plugin::Foo is IRC::Client::Plugin; @@ -87,6 +88,7 @@ event. User-defined events follow the same pattern, except they start with return IRC_NEXT unless $random > 5; $.irc.send: where => '#perl6', what => 'Custom event triggered!'; } +``` An event listener receives the event message in the form of an object. The object must provide all the relevant information about the source @@ -97,25 +99,30 @@ it must provide a means to send the message back to the originator of the message. For example, here's a potential implementation of `PRIVMSG` handler that receives the message object: +```perl6 method irc-privmsg ($msg) { return IRC_NEXT unless $msg.channel eq '#perl6'; $msg.reply: 'Nice to meet you!'; } +``` The message object should include a means to access the Client Object to perform operations best suited for it and not the message object. Here is a possible implementation to re-emit a `NOTICE` message sent to channel `#perl6` as a `PRIVMSG` message. +```perl6 method irc-notice ($msg) { $.irc.emit: 'PRIVMSG', $msg if $msg.channel eq '#perl6'; IRC_NEXT; } +``` A plugin can send messages and emit events at will: +```perl6 method irc-connected { Supply.interval(60).tap: { $.irc.send: where => '#perl6', what => 'One minute passed!!'; @@ -129,6 +136,7 @@ A plugin can send messages and emit events at will: $.irc.emit: 'CUSTOM-MY-EVENT', 'One hour passed!'; } } +``` ## Supported Events @@ -138,28 +146,33 @@ A plugin can send messages and emit events at will: #### `irc-join` +```perl6 # :zoffix!zoffix@127.0.0.1 JOIN :#perl6 method irc-join ($msg) { printf "%s joined channel %s\n", .nick, .channel given $msg; } +``` [RFC 1459, 4.2.1](https://tools.ietf.org/html/rfc1459#section-4.2.1). Emitted when user joins a channel. #### `irc-part` +```perl6 # :zoffix!zoffix@127.0.0.1 PART #perl6 :Leaving method irc-part ($msg) { printf "%s left channel %s (%s)\n", .nick, .channel, .reason given $msg; } +``` [RFC 1459, 4.2.2](https://tools.ietf.org/html/rfc1459#section-4.2.2). Emitted when user leaves a channel. #### `irc-mode` +```perl6 # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* # :zoffix2!f@127.0.0.1 MODE zoffix2 +w @@ -176,6 +189,7 @@ Emitted when user leaves a channel. .nick, .modes, .who given $msg; } } +``` [RFC 1459, 4.2.3](https://tools.ietf.org/html/rfc1459#section-4.2.3). Emitted when IRC `MODE` command is received. As the command is dual-purpose, @@ -192,24 +206,28 @@ set. #### `irc-topic` +```perl6 # :zoffix!zoffix@127.0.0.1 TOPIC #perl6 :meow method irc-topic ($msg) { printf "%s set topic of channel %s to %s\n", .nick, .channel, .topic given $msg; } +``` [RFC 1459, 4.2.4](https://tools.ietf.org/html/rfc1459#section-4.2.4). Emitted when a user changes topic of a channel. #### `irc-invite` +```perl6 # :zoffix!zoffix@127.0.0.1 INVITE zoffix2 :#perl6 method irc-invite ($msg) { printf "%s invited us to channel %s\n", .nick, .channel given $msg; } +``` [RFC 1459, 4.2.7](https://tools.ietf.org/html/rfc1459#section-4.2.7). Emitted when a user invites us to a channel. @@ -222,6 +240,7 @@ of events easier. #### `irc-mode-channel` +```perl6 # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* @@ -229,18 +248,21 @@ of events easier. printf "Nick %s with usermask %s set mode(s) %s in channel %s\n", .nick, .usermask, .modes, .channel given $msg; } +``` Emitted when IRC `MODE` command is received and it's being operated on a channel, see `irc-mode` event for details. #### `irc-mode-user` +```perl6 # :zoffix2!f@127.0.0.1 MODE zoffix2 +w method irc-mode-user ($msg) { printf "Nick %s with usermask %s set mode(s) %s on user %s\n", .nick, .usermask, .modes, .who given $msg; } +``` Emitted when IRC `MODE` command is received and it's being operated on a user, see `irc-mode` event for details. -- cgit v1.1 From f02d236cca1875c486dcf023e48caae60c376bb7 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 11:58:22 -0400 Subject: Wrote some more --- DESIGN/01-main.md | 236 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 217 insertions(+), 19 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 83814d9..d4692d0 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -138,13 +138,35 @@ A plugin can send messages and emit events at will: } ``` -## Supported Events +## Supported Named Events -### Channel Operations +### `irc-nick` -[RFC 1459, 4.2](https://tools.ietf.org/html/rfc1459#section-4.2) +```perl6 + # :zoffix!zoffix@127.0.0.1 NICK not-zoffix + + method irc-nick ($msg) { + printf "%s changed nickname to %s\n", .nick, .new-nick given $msg; + } +``` -#### `irc-join` +[RFC 2812, 3.1.2](https://tools.ietf.org/html/rfc2812#section-3.1.2). +Emitted when a user changes their nickname. + +### `irc-quit` + +```perl6 + # :zoffix!zoffix@127.0.0.1 QUIT :Quit: Leaving + + method irc-quit ($msg) { + printf "%s has quit (%s)\n", .nick, .reason given $msg; + } +``` + +[RFC 2812, 3.1.7](https://tools.ietf.org/html/rfc2812#section-3.1.7). +Emitted when a user quits the server. + +### `irc-join` ```perl6 # :zoffix!zoffix@127.0.0.1 JOIN :#perl6 @@ -154,10 +176,10 @@ A plugin can send messages and emit events at will: } ``` -[RFC 1459, 4.2.1](https://tools.ietf.org/html/rfc1459#section-4.2.1). -Emitted when user joins a channel. +[RFC 2812, 3.2.1](https://tools.ietf.org/html/rfc2812#section-3.2.1). +Emitted when a user joins a channel. -#### `irc-part` +### `irc-part` ```perl6 # :zoffix!zoffix@127.0.0.1 PART #perl6 :Leaving @@ -167,10 +189,10 @@ Emitted when user joins a channel. } ``` -[RFC 1459, 4.2.2](https://tools.ietf.org/html/rfc1459#section-4.2.2). -Emitted when user leaves a channel. +[RFC 2812, 3.2.2](https://tools.ietf.org/html/rfc2812#section-3.2.2). +Emitted when a user leaves a channel. -#### `irc-mode` +### `irc-mode` ```perl6 # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 @@ -185,13 +207,13 @@ Emitted when user leaves a channel. } else { # user mode change - printf "Nick %s set mode(s) %s on user %s\n", + printf "%s set mode(s) %s on user %s\n", .nick, .modes, .who given $msg; } } ``` -[RFC 1459, 4.2.3](https://tools.ietf.org/html/rfc1459#section-4.2.3). +[RFC 2812, 3.1.5](https://tools.ietf.org/html/rfc2812#section-3.1.5)/[RFC 2812, 3.2.3](https://tools.ietf.org/html/rfc2812#section-3.2.3). Emitted when IRC `MODE` command is received. As the command is dual-purpose, the message object will have either `.channel` method available (for channel mode changes) or `.who` method (for user mode changes). See @@ -204,7 +226,7 @@ is the mode set and the value is the argument for that mode (i.e. "limit", For user modes, the `.modes` method returns a list of `Str` of the modes set. -#### `irc-topic` +### `irc-topic` ```perl6 # :zoffix!zoffix@127.0.0.1 TOPIC #perl6 :meow @@ -215,23 +237,84 @@ set. } ``` -[RFC 1459, 4.2.4](https://tools.ietf.org/html/rfc1459#section-4.2.4). -Emitted when a user changes topic of a channel. +[RFC 2812, 3.2.4](https://tools.ietf.org/html/rfc2812#section-3.2.4). +Emitted when a user changes the topic of a channel. -#### `irc-invite` +### `irc-invite` ```perl6 # :zoffix!zoffix@127.0.0.1 INVITE zoffix2 :#perl6 method irc-invite ($msg) { - printf "%s invited us to channel %s\n", - .nick, .channel given $msg; + printf "%s invited us to channel %s\n", .nick, .channel given $msg; } ``` -[RFC 1459, 4.2.7](https://tools.ietf.org/html/rfc1459#section-4.2.7). +[RFC 2812, 3.2.7](https://tools.ietf.org/html/rfc2812#section-3.2.7). Emitted when a user invites us to a channel. +### `irc-kick` + +```perl6 + # :zoffix!zoffix@127.0.0.1 KICK #perl6 zoffix2 :go away + + method irc-kick ($msg) { + printf "%s kicked %s out of %s (%s)\n", + .nick, .who, .channel, .reason given $msg; + } +``` + +[RFC 2812, 3.2.8](https://tools.ietf.org/html/rfc2812#section-3.2.8). +Emitted when someone kicks a user out of a channel. + +### `irc-privmsg` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello + # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh + + method irc-privmsg ($msg) { + if $msg?.channel { + # message sent to a channel + printf "%s said `%s` to channel %s\n", + .nick, .what, .channel given $msg; + } + else { + # private message + printf "%s messaged us: %s\n", .nick, .what given $msg; + } + } +``` + +[RFC 2812, 3.3.1](https://tools.ietf.org/html/rfc2812#section-3.3.1). +Emitted when a user sends a message either to a channel +or a private message to us. See *Convenience Events* section for a number +of more convenient ways to listen to messages. + +### `irc-notice` + +```perl6 + # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me! + # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? + + method irc-notice ($msg) { + if $msg?.channel { + # notice sent to a channel + printf "%s sent a notice `%s` to channel %s\n", + .nick, .what, .channel given $msg; + } + else { + # private notice + printf "%s sent us a notice: %s\n", .nick, .what given $msg; + } + } +``` + +[RFC 2812, 3.3.2](https://tools.ietf.org/html/rfc2812#section-3.3.2). +Emitted when a user sends a notice either to a channel +or a private notice to us. See *Convenience Events* section for a number +of more convenient ways to listen to notices and messages. + ### Convenience Events These sets of events do not have a corresponding IRC command defined by the @@ -266,3 +349,118 @@ channel, see `irc-mode` event for details. Emitted when IRC `MODE` command is received and it's being operated on a user, see `irc-mode` event for details. + +### `irc-to-me` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hello + # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :hello + # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :zoffix2, hello + + method irc-to-me ($msg) { + printf "%s told us `%s` using %s\n", + .nick, .what, .how given $msg; + } +``` + +Emitted when a user sends us a message as a private message, notice, or +addresses us in a channel. The `.respond` method of the Message +Object is the most convenient way to respond back to the sender of the message. + +The `.how` method returns a `Pair` where the key is the message type used +(`PRIVMSG` or `NOTICE`) and the value is the addressee of that message +(a channel or us). + +### `irc-addressed` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :zoffix2, hello + + method irc-addressed ($msg) { + printf "%s told us `%s` in channel %s\n", + .nick, .what, .channel given $msg; + } +``` + +Emitted when a user addresses us in a channel. Specifically, this means +their message starts with our nickname, followed by optional comma or colon, +followed by whitespace. That prefix will be stripped from the message. + +### `irc-mentioned` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :Is zoffix2 a robot? + + method irc-mentioned ($msg) { + printf "%s mentioned us in channel %s when they said %s\n", + .nick, .channel, .what given $msg; + } +``` + +Emitted when a user mentions us in a channel. Specifically, this means +their message contains our nickname separated by a word boundary on each side. + +### `irc-privmsg-channel` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello + + method irc-privmsg-channel ($msg) { + printf "%s said `%s` to channel %s\n", + .nick, .what, .channel given $msg; + } +``` + +Emitted when a user sends a message to a channel. + +### `irc-privmsg-me` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh + + method irc-privmsg-me ($msg) { + printf "%s messaged us: %s\n", .nick, .what given $msg; + } +``` + +Emitted when a user sends us a private message. + +### `irc-notice-channel` + +```perl6 + # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me! + + method irc-notice-channel ($msg) { + printf "%s sent a notice `%s` to channel %s\n", + .nick, .what, .channel given $msg; + } +``` + +Emitted when a user sends a notice to a channel. + +### `irc-privmsg-me` + +```perl6 + # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? + + method irc-notice-me ($msg) { + printf "%s sent us a notice: %s\n", .nick, .what given $msg; + } +``` + +Emitted when a user sends us a private notice. + +## Supported Numeric Events + +The following are numeric IRC events the client supports. They can be +subscribed to by defining either a method listening to the numeric code +or to the name of the event as defined by [RFC 2812, section 5](https://tools.ietf.org/html/rfc2812#section-5). The names are the same +as in the RFC, except underscore is changed into a hyphen and the name +is lowercased. For example, this is a way to subscribe to event 375 that +marks the starts of MOTD (Message Of The Day): + + method irc-375 ($msg) { ... } + + # or + + method irc-rpl-motdstart ($msg) { ... } -- cgit v1.1 From 47fcfe5f2d41252a81eeea6867d369563bbfe07b Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 11:59:55 -0400 Subject: Wrote some more --- DESIGN/01-main.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index d4692d0..081cde9 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -456,8 +456,8 @@ The following are numeric IRC events the client supports. They can be subscribed to by defining either a method listening to the numeric code or to the name of the event as defined by [RFC 2812, section 5](https://tools.ietf.org/html/rfc2812#section-5). The names are the same as in the RFC, except underscore is changed into a hyphen and the name -is lowercased. For example, this is a way to subscribe to event 375 that -marks the starts of MOTD (Message Of The Day): +is lowercased. For example, this is a way to subscribe to event +`375 RPL_MOTDSTART` that marks the starts of MOTD (Message Of The Day): method irc-375 ($msg) { ... } -- cgit v1.1 From 1d2e47d04bcd6d6954e6116c29ea7b7b7432d50b Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 14:33:15 -0400 Subject: Finished with events --- DESIGN/01-main.md | 65 +++++++++++++++++++++++++++++++----------- DESIGN/specs-and-references.md | 1 + 2 files changed, 49 insertions(+), 17 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 081cde9..bc3238d 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -350,7 +350,7 @@ channel, see `irc-mode` event for details. Emitted when IRC `MODE` command is received and it's being operated on a user, see `irc-mode` event for details. -### `irc-to-me` +#### `irc-to-me` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hello @@ -371,7 +371,7 @@ The `.how` method returns a `Pair` where the key is the message type used (`PRIVMSG` or `NOTICE`) and the value is the addressee of that message (a channel or us). -### `irc-addressed` +#### `irc-addressed` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :zoffix2, hello @@ -386,7 +386,7 @@ Emitted when a user addresses us in a channel. Specifically, this means their message starts with our nickname, followed by optional comma or colon, followed by whitespace. That prefix will be stripped from the message. -### `irc-mentioned` +#### `irc-mentioned` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :Is zoffix2 a robot? @@ -400,7 +400,7 @@ followed by whitespace. That prefix will be stripped from the message. Emitted when a user mentions us in a channel. Specifically, this means their message contains our nickname separated by a word boundary on each side. -### `irc-privmsg-channel` +#### `irc-privmsg-channel` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello @@ -413,7 +413,7 @@ their message contains our nickname separated by a word boundary on each side. Emitted when a user sends a message to a channel. -### `irc-privmsg-me` +#### `irc-privmsg-me` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh @@ -425,7 +425,7 @@ Emitted when a user sends a message to a channel. Emitted when a user sends us a private message. -### `irc-notice-channel` +#### `irc-notice-channel` ```perl6 # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me! @@ -438,7 +438,7 @@ Emitted when a user sends us a private message. Emitted when a user sends a notice to a channel. -### `irc-privmsg-me` +#### `irc-privmsg-me` ```perl6 # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? @@ -450,17 +450,48 @@ Emitted when a user sends a notice to a channel. Emitted when a user sends us a private notice. -## Supported Numeric Events +#### `irc-started` -The following are numeric IRC events the client supports. They can be -subscribed to by defining either a method listening to the numeric code -or to the name of the event as defined by [RFC 2812, section 5](https://tools.ietf.org/html/rfc2812#section-5). The names are the same -as in the RFC, except underscore is changed into a hyphen and the name -is lowercased. For example, this is a way to subscribe to event -`375 RPL_MOTDSTART` that marks the starts of MOTD (Message Of The Day): +```perl6 + method irc-started { + $.do-some-sort-of-init-setup; + } +``` + +Emitted when the IRC client is started. Useful for doing setup work, like +initializing database connections, etc. Note: this event will fire only once, +even if the client reconnects to the server numerous times. *IMPORTANT:* +when this event fires, there's no guarantee we event started a connection to +the server, let alone connected successfully. - method irc-375 ($msg) { ... } +#### `irc-connected` - # or +```perl6 + method irc-connected { + $.do-some-sort-of-per-connection-setup; + } +``` + +Similar to `irc-started`, except will be emitted every time a +*successful* connection to the server is made and we joined all +of the requested channels. That is, we'll wait to either receive the +full user list or error message for each of the channels we're joining. + +### Numeric Events + +Numeric IRC events can be subscribed to by defining a method with name +`irc-` followed by the numeric code of the event (e.g. `irc-001`). The +arguments of the event can be accessed via `.args` method that returns a +list of strings: + +```perl6 + method irc-004 ($msg) { + say "Here are the arguments of the RPL_MYINFO event:"; + .say for $msg.args; + } +``` - method irc-rpl-motdstart ($msg) { ... } +See [this reference](https://www.alien.net.au/irc/irc2numerics.html) for +a detailed list of numerics and their arguments available in the wild. Note: +the client will emit an event for any received numeric with a 3-digit +code, regardless of whether it is listed in that reference. diff --git a/DESIGN/specs-and-references.md b/DESIGN/specs-and-references.md index 12c1f23..ec0bc93 100644 --- a/DESIGN/specs-and-references.md +++ b/DESIGN/specs-and-references.md @@ -1,6 +1,7 @@ # Specs +* [Numerics and other awesome info](https://www.alien.net.au/irc/) * [RFC 1459](https://tools.ietf.org/html/rfc1459) * [RFC 2810](https://tools.ietf.org/html/rfc2810) * [RFC 2811](https://tools.ietf.org/html/rfc2811) -- cgit v1.1 From eab169e80003ce7330be1e5920f8229e75c86eb6 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 14:34:07 -0400 Subject: Add TOC --- DESIGN/01-main.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index bc3238d..4ad74f5 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -1,3 +1,38 @@ +# TABLE OF CONTENTS +- [PURPOSE](#purpose) +- [GOALS](#goals) + - [Ease of Use](#ease-of-use) + - [Client-Generated Events](#client-generated-events) + - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code) +- [DESIGN](#design) + - [Core](#core) + - [Client Object](#client-object) + - [Message Delivery](#message-delivery) + - [Supported Named Events](#supported-named-events) + - [`irc-nick`](#irc-nick) + - [`irc-quit`](#irc-quit) + - [`irc-join`](#irc-join) + - [`irc-part`](#irc-part) + - [`irc-mode`](#irc-mode) + - [`irc-topic`](#irc-topic) + - [`irc-invite`](#irc-invite) + - [`irc-kick`](#irc-kick) + - [`irc-privmsg`](#irc-privmsg) + - [`irc-notice`](#irc-notice) + - [Convenience Events](#convenience-events) + - [`irc-mode-channel`](#irc-mode-channel) + - [`irc-mode-user`](#irc-mode-user) + - [`irc-to-me`](#irc-to-me) + - [`irc-addressed`](#irc-addressed) + - [`irc-mentioned`](#irc-mentioned) + - [`irc-privmsg-channel`](#irc-privmsg-channel) + - [`irc-privmsg-me`](#irc-privmsg-me) + - [`irc-notice-channel`](#irc-notice-channel) + - [`irc-privmsg-me`](#irc-privmsg-me-1) + - [`irc-started`](#irc-started) + - [`irc-connected`](#irc-connected) + - [Numeric Events](#numeric-events) + # PURPOSE The purpose of IRC::Client is to provide serve as a fully-functional IRC -- cgit v1.1 From cc8b50ef159f15c9534c10c2d51edfa76f578a1e Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 15:02:23 -0400 Subject: Restructure --- DESIGN/01-main.md | 422 +++++++++++++++++++++++++----------------------------- 1 file changed, 193 insertions(+), 229 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 4ad74f5..1380cd3 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -1,38 +1,3 @@ -# TABLE OF CONTENTS -- [PURPOSE](#purpose) -- [GOALS](#goals) - - [Ease of Use](#ease-of-use) - - [Client-Generated Events](#client-generated-events) - - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code) -- [DESIGN](#design) - - [Core](#core) - - [Client Object](#client-object) - - [Message Delivery](#message-delivery) - - [Supported Named Events](#supported-named-events) - - [`irc-nick`](#irc-nick) - - [`irc-quit`](#irc-quit) - - [`irc-join`](#irc-join) - - [`irc-part`](#irc-part) - - [`irc-mode`](#irc-mode) - - [`irc-topic`](#irc-topic) - - [`irc-invite`](#irc-invite) - - [`irc-kick`](#irc-kick) - - [`irc-privmsg`](#irc-privmsg) - - [`irc-notice`](#irc-notice) - - [Convenience Events](#convenience-events) - - [`irc-mode-channel`](#irc-mode-channel) - - [`irc-mode-user`](#irc-mode-user) - - [`irc-to-me`](#irc-to-me) - - [`irc-addressed`](#irc-addressed) - - [`irc-mentioned`](#irc-mentioned) - - [`irc-privmsg-channel`](#irc-privmsg-channel) - - [`irc-privmsg-me`](#irc-privmsg-me) - - [`irc-notice-channel`](#irc-notice-channel) - - [`irc-privmsg-me`](#irc-privmsg-me-1) - - [`irc-started`](#irc-started) - - [`irc-connected`](#irc-connected) - - [Numeric Events](#numeric-events) - # PURPOSE The purpose of IRC::Client is to provide serve as a fully-functional IRC @@ -87,9 +52,9 @@ The implementation distribution may also include several plugins that may be commonly needed by users. Such plugins are not enabled by default and the user must request their inclusion with code. -## Core +# Core -### Client Object +## Client Object Client Object represents a connected IRC client and is aware of and can manipulate its state, such as disconnecting, joining or parting a channel, @@ -102,7 +67,7 @@ A relevant Client Object must be easily accessible to the user of the implementation. This includes user's plugins responsible for handling events. -### Message Delivery +## Message Delivery An event listener is defined by a method in a plugin class. The name of the method starts with `irc-` and followed by the lowercase name of the @@ -172,191 +137,13 @@ A plugin can send messages and emit events at will: } } ``` - -## Supported Named Events - -### `irc-nick` - -```perl6 - # :zoffix!zoffix@127.0.0.1 NICK not-zoffix - - method irc-nick ($msg) { - printf "%s changed nickname to %s\n", .nick, .new-nick given $msg; - } -``` - -[RFC 2812, 3.1.2](https://tools.ietf.org/html/rfc2812#section-3.1.2). -Emitted when a user changes their nickname. - -### `irc-quit` - -```perl6 - # :zoffix!zoffix@127.0.0.1 QUIT :Quit: Leaving - - method irc-quit ($msg) { - printf "%s has quit (%s)\n", .nick, .reason given $msg; - } -``` - -[RFC 2812, 3.1.7](https://tools.ietf.org/html/rfc2812#section-3.1.7). -Emitted when a user quits the server. - -### `irc-join` - -```perl6 - # :zoffix!zoffix@127.0.0.1 JOIN :#perl6 - - method irc-join ($msg) { - printf "%s joined channel %s\n", .nick, .channel given $msg; - } -``` - -[RFC 2812, 3.2.1](https://tools.ietf.org/html/rfc2812#section-3.2.1). -Emitted when a user joins a channel. - -### `irc-part` - -```perl6 - # :zoffix!zoffix@127.0.0.1 PART #perl6 :Leaving - - method irc-part ($msg) { - printf "%s left channel %s (%s)\n", .nick, .channel, .reason given $msg; - } -``` - -[RFC 2812, 3.2.2](https://tools.ietf.org/html/rfc2812#section-3.2.2). -Emitted when a user leaves a channel. - -### `irc-mode` - -```perl6 - # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 - # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* - # :zoffix2!f@127.0.0.1 MODE zoffix2 +w - - method irc-mode ($msg) { - if $msg?.channel { - # channel mode change - printf "%s set mode(s) %s in channel %s\n", - .nick, .modes, .channel given $msg; - } - else { - # user mode change - printf "%s set mode(s) %s on user %s\n", - .nick, .modes, .who given $msg; - } - } -``` - -[RFC 2812, 3.1.5](https://tools.ietf.org/html/rfc2812#section-3.1.5)/[RFC 2812, 3.2.3](https://tools.ietf.org/html/rfc2812#section-3.2.3). -Emitted when IRC `MODE` command is received. As the command is dual-purpose, -the message object will have either `.channel` method available -(for channel mode changes) or `.who` method (for user mode changes). See -also `irc-mode-channel` and `irc-mode-user` convenience events. - -For channel modes, the `.modes` method returns a list of `Pair` where key -is the mode set and the value is the argument for that mode (i.e. "limit", -"user", or "banmask") or an empty string if the mode takes no arguments. - -For user modes, the `.modes` method returns a list of `Str` of the modes -set. - -### `irc-topic` - -```perl6 - # :zoffix!zoffix@127.0.0.1 TOPIC #perl6 :meow - - method irc-topic ($msg) { - printf "%s set topic of channel %s to %s\n", - .nick, .channel, .topic given $msg; - } -``` - -[RFC 2812, 3.2.4](https://tools.ietf.org/html/rfc2812#section-3.2.4). -Emitted when a user changes the topic of a channel. - -### `irc-invite` - -```perl6 - # :zoffix!zoffix@127.0.0.1 INVITE zoffix2 :#perl6 - - method irc-invite ($msg) { - printf "%s invited us to channel %s\n", .nick, .channel given $msg; - } -``` - -[RFC 2812, 3.2.7](https://tools.ietf.org/html/rfc2812#section-3.2.7). -Emitted when a user invites us to a channel. - -### `irc-kick` - -```perl6 - # :zoffix!zoffix@127.0.0.1 KICK #perl6 zoffix2 :go away - - method irc-kick ($msg) { - printf "%s kicked %s out of %s (%s)\n", - .nick, .who, .channel, .reason given $msg; - } -``` - -[RFC 2812, 3.2.8](https://tools.ietf.org/html/rfc2812#section-3.2.8). -Emitted when someone kicks a user out of a channel. - -### `irc-privmsg` - -```perl6 - # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello - # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh - - method irc-privmsg ($msg) { - if $msg?.channel { - # message sent to a channel - printf "%s said `%s` to channel %s\n", - .nick, .what, .channel given $msg; - } - else { - # private message - printf "%s messaged us: %s\n", .nick, .what given $msg; - } - } -``` - -[RFC 2812, 3.3.1](https://tools.ietf.org/html/rfc2812#section-3.3.1). -Emitted when a user sends a message either to a channel -or a private message to us. See *Convenience Events* section for a number -of more convenient ways to listen to messages. - -### `irc-notice` - -```perl6 - # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me! - # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? - - method irc-notice ($msg) { - if $msg?.channel { - # notice sent to a channel - printf "%s sent a notice `%s` to channel %s\n", - .nick, .what, .channel given $msg; - } - else { - # private notice - printf "%s sent us a notice: %s\n", .nick, .what given $msg; - } - } -``` - -[RFC 2812, 3.3.2](https://tools.ietf.org/html/rfc2812#section-3.3.2). -Emitted when a user sends a notice either to a channel -or a private notice to us. See *Convenience Events* section for a number -of more convenient ways to listen to notices and messages. - -### Convenience Events +# Convenience Events These sets of events do not have a corresponding IRC command defined by the protocol and instead are offered to make listening for a specific kind of events easier. -#### `irc-mode-channel` +## `irc-mode-channel` ```perl6 # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 @@ -371,7 +158,7 @@ of events easier. Emitted when IRC `MODE` command is received and it's being operated on a channel, see `irc-mode` event for details. -#### `irc-mode-user` +## `irc-mode-user` ```perl6 # :zoffix2!f@127.0.0.1 MODE zoffix2 +w @@ -385,7 +172,7 @@ channel, see `irc-mode` event for details. Emitted when IRC `MODE` command is received and it's being operated on a user, see `irc-mode` event for details. -#### `irc-to-me` +## `irc-to-me` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hello @@ -406,7 +193,7 @@ The `.how` method returns a `Pair` where the key is the message type used (`PRIVMSG` or `NOTICE`) and the value is the addressee of that message (a channel or us). -#### `irc-addressed` +## `irc-addressed` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :zoffix2, hello @@ -421,7 +208,7 @@ Emitted when a user addresses us in a channel. Specifically, this means their message starts with our nickname, followed by optional comma or colon, followed by whitespace. That prefix will be stripped from the message. -#### `irc-mentioned` +## `irc-mentioned` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :Is zoffix2 a robot? @@ -435,7 +222,7 @@ followed by whitespace. That prefix will be stripped from the message. Emitted when a user mentions us in a channel. Specifically, this means their message contains our nickname separated by a word boundary on each side. -#### `irc-privmsg-channel` +## `irc-privmsg-channel` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello @@ -448,7 +235,7 @@ their message contains our nickname separated by a word boundary on each side. Emitted when a user sends a message to a channel. -#### `irc-privmsg-me` +## `irc-privmsg-me` ```perl6 # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh @@ -460,7 +247,7 @@ Emitted when a user sends a message to a channel. Emitted when a user sends us a private message. -#### `irc-notice-channel` +## `irc-notice-channel` ```perl6 # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me! @@ -473,7 +260,7 @@ Emitted when a user sends us a private message. Emitted when a user sends a notice to a channel. -#### `irc-privmsg-me` +## `irc-privmsg-me` ```perl6 # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? @@ -485,7 +272,7 @@ Emitted when a user sends a notice to a channel. Emitted when a user sends us a private notice. -#### `irc-started` +## `irc-started` ```perl6 method irc-started { @@ -499,7 +286,7 @@ even if the client reconnects to the server numerous times. *IMPORTANT:* when this event fires, there's no guarantee we event started a connection to the server, let alone connected successfully. -#### `irc-connected` +## `irc-connected` ```perl6 method irc-connected { @@ -512,7 +299,7 @@ Similar to `irc-started`, except will be emitted every time a of the requested channels. That is, we'll wait to either receive the full user list or error message for each of the channels we're joining. -### Numeric Events +# Numeric Events Numeric IRC events can be subscribed to by defining a method with name `irc-` followed by the numeric code of the event (e.g. `irc-001`). The @@ -530,3 +317,180 @@ See [this reference](https://www.alien.net.au/irc/irc2numerics.html) for a detailed list of numerics and their arguments available in the wild. Note: the client will emit an event for any received numeric with a 3-digit code, regardless of whether it is listed in that reference. + +# Named Events + +## `irc-nick` + +```perl6 + # :zoffix!zoffix@127.0.0.1 NICK not-zoffix + + method irc-nick ($msg) { + printf "%s changed nickname to %s\n", .nick, .new-nick given $msg; + } +``` + +[RFC 2812, 3.1.2](https://tools.ietf.org/html/rfc2812#section-3.1.2). +Emitted when a user changes their nickname. + +## `irc-quit` + +```perl6 + # :zoffix!zoffix@127.0.0.1 QUIT :Quit: Leaving + + method irc-quit ($msg) { + printf "%s has quit (%s)\n", .nick, .reason given $msg; + } +``` + +[RFC 2812, 3.1.7](https://tools.ietf.org/html/rfc2812#section-3.1.7). +Emitted when a user quits the server. + +## `irc-join` + +```perl6 + # :zoffix!zoffix@127.0.0.1 JOIN :#perl6 + + method irc-join ($msg) { + printf "%s joined channel %s\n", .nick, .channel given $msg; + } +``` + +[RFC 2812, 3.2.1](https://tools.ietf.org/html/rfc2812#section-3.2.1). +Emitted when a user joins a channel. + +## `irc-part` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PART #perl6 :Leaving + + method irc-part ($msg) { + printf "%s left channel %s (%s)\n", .nick, .channel, .reason given $msg; + } +``` + +[RFC 2812, 3.2.2](https://tools.ietf.org/html/rfc2812#section-3.2.2). +Emitted when a user leaves a channel. + +## `irc-mode` + +```perl6 + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* + # :zoffix2!f@127.0.0.1 MODE zoffix2 +w + + method irc-mode ($msg) { + if $msg?.channel { + # channel mode change + printf "%s set mode(s) %s in channel %s\n", + .nick, .modes, .channel given $msg; + } + else { + # user mode change + printf "%s set mode(s) %s on user %s\n", + .nick, .modes, .who given $msg; + } + } +``` + +[RFC 2812, 3.1.5](https://tools.ietf.org/html/rfc2812#section-3.1.5)/[RFC 2812, 3.2.3](https://tools.ietf.org/html/rfc2812#section-3.2.3). +Emitted when IRC `MODE` command is received. As the command is dual-purpose, +the message object will have either `.channel` method available +(for channel mode changes) or `.who` method (for user mode changes). See +also `irc-mode-channel` and `irc-mode-user` convenience events. + +For channel modes, the `.modes` method returns a list of `Pair` where key +is the mode set and the value is the argument for that mode (i.e. "limit", +"user", or "banmask") or an empty string if the mode takes no arguments. + +For user modes, the `.modes` method returns a list of `Str` of the modes +set. + +## `irc-topic` + +```perl6 + # :zoffix!zoffix@127.0.0.1 TOPIC #perl6 :meow + + method irc-topic ($msg) { + printf "%s set topic of channel %s to %s\n", + .nick, .channel, .topic given $msg; + } +``` + +[RFC 2812, 3.2.4](https://tools.ietf.org/html/rfc2812#section-3.2.4). +Emitted when a user changes the topic of a channel. + +## `irc-invite` + +```perl6 + # :zoffix!zoffix@127.0.0.1 INVITE zoffix2 :#perl6 + + method irc-invite ($msg) { + printf "%s invited us to channel %s\n", .nick, .channel given $msg; + } +``` + +[RFC 2812, 3.2.7](https://tools.ietf.org/html/rfc2812#section-3.2.7). +Emitted when a user invites us to a channel. + +## `irc-kick` + +```perl6 + # :zoffix!zoffix@127.0.0.1 KICK #perl6 zoffix2 :go away + + method irc-kick ($msg) { + printf "%s kicked %s out of %s (%s)\n", + .nick, .who, .channel, .reason given $msg; + } +``` + +[RFC 2812, 3.2.8](https://tools.ietf.org/html/rfc2812#section-3.2.8). +Emitted when someone kicks a user out of a channel. + +## `irc-privmsg` + +```perl6 + # :zoffix!zoffix@127.0.0.1 PRIVMSG #perl6 :hello + # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh + + method irc-privmsg ($msg) { + if $msg?.channel { + # message sent to a channel + printf "%s said `%s` to channel %s\n", + .nick, .what, .channel given $msg; + } + else { + # private message + printf "%s messaged us: %s\n", .nick, .what given $msg; + } + } +``` + +[RFC 2812, 3.3.1](https://tools.ietf.org/html/rfc2812#section-3.3.1). +Emitted when a user sends a message either to a channel +or a private message to us. See *Convenience Events* section for a number +of more convenient ways to listen to messages. + +## `irc-notice` + +```perl6 + # :zoffix!zoffix@127.0.0.1 NOTICE #perl6 :Notice me! + # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? + + method irc-notice ($msg) { + if $msg?.channel { + # notice sent to a channel + printf "%s sent a notice `%s` to channel %s\n", + .nick, .what, .channel given $msg; + } + else { + # private notice + printf "%s sent us a notice: %s\n", .nick, .what given $msg; + } + } +``` + +[RFC 2812, 3.3.2](https://tools.ietf.org/html/rfc2812#section-3.3.2). +Emitted when a user sends a notice either to a channel +or a private notice to us. See *Convenience Events* section for a number +of more convenient ways to listen to notices and messages. -- cgit v1.1 From 625b182489e072cad6af5db35e750535a835696f Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 15:02:45 -0400 Subject: Add new toc --- DESIGN/01-main.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 1380cd3..1428ac4 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -1,3 +1,38 @@ +# TABLE OF CONTENTS +- [PURPOSE](#purpose) +- [GOALS](#goals) + - [Ease of Use](#ease-of-use) + - [Client-Generated Events](#client-generated-events) + - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code) +- [DESIGN](#design) +- [Core](#core) + - [Client Object](#client-object) + - [Message Delivery](#message-delivery) +- [Convenience Events](#convenience-events) + - [`irc-mode-channel`](#irc-mode-channel) + - [`irc-mode-user`](#irc-mode-user) + - [`irc-to-me`](#irc-to-me) + - [`irc-addressed`](#irc-addressed) + - [`irc-mentioned`](#irc-mentioned) + - [`irc-privmsg-channel`](#irc-privmsg-channel) + - [`irc-privmsg-me`](#irc-privmsg-me) + - [`irc-notice-channel`](#irc-notice-channel) + - [`irc-privmsg-me`](#irc-privmsg-me-1) + - [`irc-started`](#irc-started) + - [`irc-connected`](#irc-connected) +- [Numeric Events](#numeric-events) +- [Named Events](#named-events) + - [`irc-nick`](#irc-nick) + - [`irc-quit`](#irc-quit) + - [`irc-join`](#irc-join) + - [`irc-part`](#irc-part) + - [`irc-mode`](#irc-mode) + - [`irc-topic`](#irc-topic) + - [`irc-invite`](#irc-invite) + - [`irc-kick`](#irc-kick) + - [`irc-privmsg`](#irc-privmsg) + - [`irc-notice`](#irc-notice) + # PURPOSE The purpose of IRC::Client is to provide serve as a fully-functional IRC -- cgit v1.1 From b5e382ef6ff572e2b1d7330fb8c57c6a4a2e21eb Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 15:04:00 -0400 Subject: Move mode events at the end --- DESIGN/01-main.md | 58 +++++++++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 1428ac4..9758fb6 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -178,35 +178,6 @@ These sets of events do not have a corresponding IRC command defined by the protocol and instead are offered to make listening for a specific kind of events easier. -## `irc-mode-channel` - -```perl6 - # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 - # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* - - method irc-mode-channel ($msg) { - printf "Nick %s with usermask %s set mode(s) %s in channel %s\n", - .nick, .usermask, .modes, .channel given $msg; - } -``` - -Emitted when IRC `MODE` command is received and it's being operated on a -channel, see `irc-mode` event for details. - -## `irc-mode-user` - -```perl6 - # :zoffix2!f@127.0.0.1 MODE zoffix2 +w - - method irc-mode-user ($msg) { - printf "Nick %s with usermask %s set mode(s) %s on user %s\n", - .nick, .usermask, .modes, .who given $msg; - } -``` - -Emitted when IRC `MODE` command is received and it's being operated on a -user, see `irc-mode` event for details. - ## `irc-to-me` ```perl6 @@ -334,6 +305,35 @@ Similar to `irc-started`, except will be emitted every time a of the requested channels. That is, we'll wait to either receive the full user list or error message for each of the channels we're joining. +## `irc-mode-channel` + +```perl6 + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +o zoffix2 + # :zoffix!zoffix@127.0.0.1 MODE #perl6 +bbb Foo!*@* Bar!*@* Ber!*@* + + method irc-mode-channel ($msg) { + printf "Nick %s with usermask %s set mode(s) %s in channel %s\n", + .nick, .usermask, .modes, .channel given $msg; + } +``` + +Emitted when IRC `MODE` command is received and it's being operated on a +channel, see `irc-mode` event for details. + +## `irc-mode-user` + +```perl6 + # :zoffix2!f@127.0.0.1 MODE zoffix2 +w + + method irc-mode-user ($msg) { + printf "Nick %s with usermask %s set mode(s) %s on user %s\n", + .nick, .usermask, .modes, .who given $msg; + } +``` + +Emitted when IRC `MODE` command is received and it's being operated on a +user, see `irc-mode` event for details. + # Numeric Events Numeric IRC events can be subscribed to by defining a method with name -- cgit v1.1 From 24c3b1d0b52ec0ee6881d1598250fd592fa70f09 Mon Sep 17 00:00:00 2001 From: Zoffix Znet 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(+) (limited to 'DESIGN') 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 From 48cd19c4889dd583f41606d6e6d0aa13ba7ea365 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 27 May 2016 20:28:58 -0400 Subject: Add fresh TOC --- DESIGN/01-main.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index af4e47b..61c0235 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -1,4 +1,5 @@ # TABLE OF CONTENTS +- [TABLE OF CONTENTS](#table-of-contents) - [PURPOSE](#purpose) - [GOALS](#goals) - [Ease of Use](#ease-of-use) @@ -8,9 +9,13 @@ - [Core](#core) - [Client Object](#client-object) - [Message Delivery](#message-delivery) +- [Message Object Interface](#message-object-interface) + - [`.nick`](#nick) + - [`.username`](#username) + - [`.host`](#host) + - [`.usermask`](#usermask) + - [`.reply`](#reply) - [Convenience Events](#convenience-events) - - [`irc-mode-channel`](#irc-mode-channel) - - [`irc-mode-user`](#irc-mode-user) - [`irc-to-me`](#irc-to-me) - [`irc-addressed`](#irc-addressed) - [`irc-mentioned`](#irc-mentioned) @@ -20,6 +25,8 @@ - [`irc-privmsg-me`](#irc-privmsg-me-1) - [`irc-started`](#irc-started) - [`irc-connected`](#irc-connected) + - [`irc-mode-channel`](#irc-mode-channel) + - [`irc-mode-user`](#irc-mode-user) - [Numeric Events](#numeric-events) - [Named Events](#named-events) - [`irc-nick`](#irc-nick) -- cgit v1.1 From dce18cc0445348fc1623c6ae91e100a432705e34 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:46:14 -0400 Subject: Wrote some more --- DESIGN/01-main.md | 280 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 269 insertions(+), 11 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 61c0235..f6338f4 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -94,9 +94,7 @@ The implementation distribution may also include several plugins that may be commonly needed by users. Such plugins are not enabled by default and the user must request their inclusion with code. -# Core - -## Client Object +# Client Object Client Object represents a connected IRC client and is aware of and can manipulate its state, such as disconnecting, joining or parting a channel, @@ -105,11 +103,217 @@ or sending messages. A program may have multiple Client Objects, but each of them can be connected only to one IRC server. -A relevant Client Object must be easily accessible to the user of the -implementation. This includes user's plugins responsible for handling -events. +## `.irc` (access from inside a plugin) + +```perl6 + use IRC::Client::Plugin; + unit Plugin::Foo is IRC::Client::Plugin; + + method irc-privmsg-me ($msg) { + $.irc.send: + where => '#perl6', + what => "$msg.nick() just sent me a secret! It's $msg.what()"; + } +``` + +A plugin inherits from `IRC::Client::Plugin`, which provides `$.irc` +attribute containing the Client Object, allowing the plugin to utilize all +of the methods it provides. + +## `.new` + +```perl6 + my $irc = IRC::Client.new: + ... + :plugins( + IRC::Client::Plugin::Factoid.new, + My::Plugin.new, + class :: is IRC::Client::Plugin { + method irc-privmsg-me ($msg) { $msg.repond: 'Go away!'; } + }, + ); +``` + +*Not to be used inside plugins.* +Creates a new `IRC::Client` object. Along with the usual arguments like +nick, username, server address, etc, takes `:plugins` argument that +lists the plugins to include. All messages will be handed to each plugin +in the order they are defined here. + +## `.run` + +```perl6 + $irc.run; +``` + +*Not to be used inside plugins.* +Starts the client, connecting to the server and maintaining that connection +and not returning until an explicit `.quit` is issued. If the connection +breaks, the client will attempt to reconnect. + +## `.quit` + +```perl6 + $.irc.quit; + + $.irc.quit: 'Reason'; +``` + +Disconnects from the server. Takes an option string to be given to the +server as the reson for quitting. + +## `.part` + +```per6 + $.irc.part: '#perl6'; + + $.irc.part: '#perl6', 'Leaving'; +``` + +Exits a channel. Takes two positional strings: the channel to part +and an optional parting message. Causes the client object to discard any state +kept for this channel. + +## `.join` + +```perl6 + $.irc.join '#perl6', '#perl7'; +``` + +Joins channels given as positional arguments. + +## `.send` + +```perl6 + $.irc.send: where => '#perl6', what => 'Hello, Perl 6!'; + + $.irc.send: where => 'Zoffix', what => 'Hi, Zoffie!'; + + $.irc.send: where => 'Zoffix', what => 'Notice me, senpai!', :notice; +``` + +Sends a message specified by `what` argument +either to a user or a channel specified by `:where` argument. If `Bool` +argument `:notice` is set to true, will send a *notice* instead of regular +message. + +## `.nick` + +```perl6 + $.irc.nick: 'ZofBot', 'ZofBot_', 'ZofBot__'; +``` + +Attempts to change the nick of the client. Takes one or more positional +arguments that are a list of nicks to try. + +## `.emit` + +```perl6 + $.irc.emit: $msg; + + $.irc.emit: IRC::Client::Message::Privmsg.new: + nick => 'Zoffix', + what => 'Hello', + ...; + ... + method irc-privmsg ($msg) { + say "$msg.nick() said $msg.what()... or did they?"; + } +``` + +Takes an object of any of `IRC::Client::Message::*` subclass and emits it +as if it were a new event. That is, it will propagate through the plugin chain +starting at the first plugin, and not the one emiting the event, and the +plugins can't tell whether the message is self-generated or something that +came from the server. + +## `.emit-custom` + +```perl6 + $.irc.emit-custom: 'my-event', 'just', 'some', :args; +``` + +Same idea as `.emit`, except a custom event is emitted. The first positional +argument specifies the name of the event to emit. Any other arguments +given here will be passed as is to listener methods. + +## `.channel` -## Message Delivery +```perl6 + method irc-addressed ($msg) { + if $msg.what ~~ /'kick' \s+ $=\S+/ { + $msg.reply: "I don't see $ up in here" + unless $.irc.channel($msg.channel).?has: ~$; + } + + if $msg.what ~~ /'topic' \s+ $=\S+/ { + return $msg.reply: $_ + ?? "Channel $ does not exist" + !! "Topic in $ is $_.topic()" + given $.irc.channel: ~$; + } + } +``` + +Returns a `IRC::Client::Channel` object for the channel given as positional +argument, or `False` if no such channel seem to exist. That existence is +determined with `LIST` IRC command, so there will be some false negatives, +such as when attempting to get an object for a channel with secret mode set +that we are currently aren't on. + +The channel object provides the following methods. The Client Object tracks +state for any of the joined channels, so some information will be cached +and retrieved from that state, whenever possible. Otherwise, a request +to the server will be generated. Return values will be empty (empty lists +or empty strings) when requests fail. + +### `.has` + +```perl6 + $.irc.channel('#perl6').has: 'Zoffix'; +``` + +Returns `True` or `False` indicating whether a user with the given nick is +present on the channel. + +### `.topic` + +```perl6 + say "Topic of the channel is " ~ $.irc.channel('#perl6').topic; +``` + +Returns the `TOPIC` of the channel. + +### `.modes` + +```perl6 + say $.irc.channel('#perl6').modes; + # ('s', 'n', 't') +``` + +Returns a list of single-letter codes for currently active channel modes +on the channel. Note, this does not include any bans. + +### `.bans` + +```perl6 + say $.irc.channel('#perl6').bans; + # ('*!spammer@*', 'warezbot!*@*') +``` + +Returns a list of currently active ban masks on the channel. + +### `.names` + +```perl6 + say $.irc.channel('#perl6').names; + # ('@Zoffix', '+zoffixs-helper', 'not-zoffix') +``` + +Returns a list of nicks present on the channel, each potentially prefixed +with a [channel membership prefix](https://www.alien.net.au/irc/chanmembers.html) + +# Message Delivery An event listener is defined by a method in a plugin class. The name of the method starts with `irc-` and followed by the lowercase name of the @@ -175,11 +379,50 @@ A plugin can send messages and emit events at will: what => 'I lived for one hour already!", :notice; - $.irc.emit: 'CUSTOM-MY-EVENT', 'One hour passed!'; + $.irc.emit-custom: 'MY-EVENT', 'One hour passed!'; } } ``` +# Response Constants + +Multiple plugins can listen to the same event. The event message will be +handed to each of the plugins in the sequence they are defined when the +Client Object is initialized. Each handler can use predefined response +constants to signal whether the handling of this particular event message +should stop or continue onto the next plugin. These response constants +are `IRC_NEXT` and `IRC_DONE` and are exported by `IRC::Client::Plugin`. + +## `IRC_NEXT` + +```perl6 + method irc-privmsg-channel ($msg) { + return IRC_NEXT unless $msg.channel eq '#perl6'; + .... + } +``` + +Signals that the message should continue to be passed on to any further +plugins that subscribed to handle it. + +## `IRC_DONE` + +```perl6 + method irc-privmsg-channel ($msg) { + return IRC_DONE if $msg.channel eq '#perl6'; + } + + # or just... + + method irc-privmsg-channel ($msg) {} +``` + +Signals that the message has been handled and should NOT be passed on +to any further plugins. **Note:** you don't have to explicitly return this +value; anything other than returning `IRC_NEXT` is the same as returning +`IRC_DONE`. + + # Message Object Interface The message object received by all non-custom events is an event-specific @@ -497,7 +740,7 @@ Emitted when a user leaves a channel. # :zoffix2!f@127.0.0.1 MODE zoffix2 +w method irc-mode ($msg) { - if $msg?.channel { + if $msg.?channel { # channel mode change printf "%s set mode(s) %s in channel %s\n", .nick, .modes, .channel given $msg; @@ -571,7 +814,7 @@ Emitted when someone kicks a user out of a channel. # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh method irc-privmsg ($msg) { - if $msg?.channel { + if $msg.?channel { # message sent to a channel printf "%s said `%s` to channel %s\n", .nick, .what, .channel given $msg; @@ -595,7 +838,7 @@ of more convenient ways to listen to messages. # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? method irc-notice ($msg) { - if $msg?.channel { + if $msg.?channel { # notice sent to a channel printf "%s sent a notice `%s` to channel %s\n", .nick, .what, .channel given $msg; @@ -611,3 +854,18 @@ of more convenient ways to listen to messages. Emitted when a user sends a notice either to a channel or a private notice to us. See *Convenience Events* section for a number of more convenient ways to listen to notices and messages. + +# Custom Events + +There is support for custom events. A custom event is emitted by calling +`.emit-custom` method on the Client Object and is subscribed to via +`irc-custom-*` methods: + +```perl6 + $.irc.emit-custom: 'my-event', 'just', 'some', :args; + ... + method irc-custom-my-event ($just, $some, :$args) { } +``` + +No Message Object is involved in custom events. + -- cgit v1.1 From 07c63345e6f04f8175baa88e7755a4b9e0a0d000 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:46:51 -0400 Subject: Update TOC --- DESIGN/01-main.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index f6338f4..cf12f8f 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -1,16 +1,33 @@ # TABLE OF CONTENTS -- [TABLE OF CONTENTS](#table-of-contents) - [PURPOSE](#purpose) - [GOALS](#goals) - [Ease of Use](#ease-of-use) - [Client-Generated Events](#client-generated-events) - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code) - [DESIGN](#design) -- [Core](#core) - - [Client Object](#client-object) - - [Message Delivery](#message-delivery) -- [Message Object Interface](#message-object-interface) +- [Client Object](#client-object) + - [`.irc` (access from inside a plugin)](#irc-access-from-inside-a-plugin) + - [`.new`](#new) + - [`.run`](#run) + - [`.quit`](#quit) + - [`.part`](#part) + - [`.join`](#join) + - [`.send`](#send) - [`.nick`](#nick) + - [`.emit`](#emit) + - [`.emit-custom`](#emit-custom) + - [`.channel`](#channel) + - [`.has`](#has) + - [`.topic`](#topic) + - [`.modes`](#modes) + - [`.bans`](#bans) + - [`.names`](#names) +- [Message Delivery](#message-delivery) +- [Response Constants](#response-constants) + - [`IRC_NEXT`](#irc_next) + - [`IRC_DONE`](#irc_done) +- [Message Object Interface](#message-object-interface) + - [`.nick`](#nick-1) - [`.username`](#username) - [`.host`](#host) - [`.usermask`](#usermask) @@ -39,6 +56,7 @@ - [`irc-kick`](#irc-kick) - [`irc-privmsg`](#irc-privmsg) - [`irc-notice`](#irc-notice) +- [Custom Events](#custom-events) # PURPOSE -- cgit v1.1 From ab045633ba628734721b731dada076d0c4d23dfb Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:50:36 -0400 Subject: Write stuff --- DESIGN/01-main.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index cf12f8f..bfe54a4 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -60,7 +60,7 @@ # PURPOSE -The purpose of IRC::Client is to provide serve as a fully-functional IRC +The purpose of IRC::Client is to serve as a fully-functional IRC client that--unlike programs like HexChat or mIRC--provide a programmatic interface to IRC. So, for example, to send a message to a channel, instead of typing a message in a message box and pressing ENTER, a method is called @@ -119,7 +119,7 @@ manipulate its state, such as disconnecting, joining or parting a channel, or sending messages. A program may have multiple Client Objects, but each of them can be connected -only to one IRC server. +only to one IRC server. The client object provides these methods: ## `.irc` (access from inside a plugin) -- cgit v1.1 From e7deec41159d2d75950bd88ccf61d9ab1d3397af Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:51:14 -0400 Subject: Write stuff --- DESIGN/01-main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index bfe54a4..775a60e 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -121,7 +121,7 @@ or sending messages. A program may have multiple Client Objects, but each of them can be connected only to one IRC server. The client object provides these methods: -## `.irc` (access from inside a plugin) +## `$.irc` (access from inside a plugin) ```perl6 use IRC::Client::Plugin; -- cgit v1.1 From cd47243ccc31e5ba26e7a5086a9f12941f035199 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:55:01 -0400 Subject: Write stuff --- DESIGN/01-main.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 775a60e..2f98452 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -155,7 +155,7 @@ of the methods it provides. *Not to be used inside plugins.* Creates a new `IRC::Client` object. Along with the usual arguments like nick, username, server address, etc, takes `:plugins` argument that -lists the plugins to include. All messages will be handed to each plugin +lists the plugins to include. All messages will be propagated through plugins in the order they are defined here. ## `.run` @@ -198,7 +198,7 @@ kept for this channel. $.irc.join '#perl6', '#perl7'; ``` -Joins channels given as positional arguments. +Attempts to joins channels given as positional arguments. ## `.send` @@ -215,6 +215,11 @@ either to a user or a channel specified by `:where` argument. If `Bool` argument `:notice` is set to true, will send a *notice* instead of regular message. +Note that in IRC bots that respond to commands from other users a more +typical way to reply to those commands would be by calling +`.reply` method on the Message Object, rather than using `.send` method. + + ## `.nick` ```perl6 -- cgit v1.1 From c7d2a62f75d2656348ef7793b423c0dbe5e76526 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:56:58 -0400 Subject: Write stuff --- DESIGN/01-main.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 2f98452..7412e57 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -278,8 +278,9 @@ given here will be passed as is to listener methods. } ``` -Returns a `IRC::Client::Channel` object for the channel given as positional -argument, or `False` if no such channel seem to exist. That existence is +Returns an `IRC::Client::Channel` object for the channel given as positional +argument, or `False` if no such channel seems to exist. Unless our client is +currently *on* that channel, that existence is determined with `LIST` IRC command, so there will be some false negatives, such as when attempting to get an object for a channel with secret mode set that we are currently aren't on. -- cgit v1.1 From a89de7c56c9c729408b4b283406e4f62b4abc289 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 08:59:03 -0400 Subject: Write stuff --- DESIGN/01-main.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 7412e57..68db37d 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -282,14 +282,14 @@ Returns an `IRC::Client::Channel` object for the channel given as positional argument, or `False` if no such channel seems to exist. Unless our client is currently *on* that channel, that existence is determined with `LIST` IRC command, so there will be some false negatives, -such as when attempting to get an object for a channel with secret mode set -that we are currently aren't on. +such as when attempting to get an object for a channel with secret mode set. -The channel object provides the following methods. The Client Object tracks -state for any of the joined channels, so some information will be cached +The Client Object tracks state for any of the joined channels, so some +information obtainable via the Channel Object will be cached and retrieved from that state, whenever possible. Otherwise, a request to the server will be generated. Return values will be empty (empty lists -or empty strings) when requests fail. +or empty strings) when requests fail. The channel object provides the +following methods. ### `.has` -- cgit v1.1 From f7367cc30de8c5f75824d95fcc6883a9f17a9d2c Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:01:21 -0400 Subject: Write stuff --- DESIGN/01-main.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 68db37d..3b82a19 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -354,6 +354,7 @@ event. User-defined events follow the same pattern, except they start with $msg.reply: 'Nice to meet you!'; } + # Listen to custom client-generated events: method irc-custom-my-event ($some, $random, :$args) { return IRC_NEXT unless $random > 5; $.irc.send: where => '#perl6', what => 'Custom event triggered!'; @@ -364,10 +365,9 @@ An event listener receives the event message in the form of an object. The object must provide all the relevant information about the source and content of the message. -The message object's attributes must be mutable, and where appropriate, -it must provide a means to send the message back to the originator -of the message. For example, here's a potential implementation of -`PRIVMSG` handler that receives the message object: +The message object, where appropriate, must provide a means to send a reply +back to the originator of the message. For example, here's a potential +implementation of `PRIVMSG` handler that receives the message object: ```perl6 method irc-privmsg ($msg) { -- cgit v1.1 From fec1b475f9c6ff12081543565687d495f25e608f Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:04:32 -0400 Subject: Write stuff --- DESIGN/01-main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 3b82a19..1c53f82 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -370,7 +370,7 @@ back to the originator of the message. For example, here's a potential implementation of `PRIVMSG` handler that receives the message object: ```perl6 - method irc-privmsg ($msg) { + method irc-privmsg-channel ($msg) { return IRC_NEXT unless $msg.channel eq '#perl6'; $msg.reply: 'Nice to meet you!'; } -- cgit v1.1 From 2735caba94b79508f961fd4ecacb21d119fa2eef Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:05:07 -0400 Subject: Write stuff --- DESIGN/01-main.md | 14 -------------- 1 file changed, 14 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 1c53f82..848e6e9 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -376,20 +376,6 @@ implementation of `PRIVMSG` handler that receives the message object: } ``` -The message object should include a means to access the Client Object to -perform operations best suited for it and not the message object. Here is -a possible implementation to re-emit a `NOTICE` message sent to channel -`#perl6` as a `PRIVMSG` message. - -```perl6 - method irc-notice ($msg) { - $.irc.emit: 'PRIVMSG', $msg - if $msg.channel eq '#perl6'; - - IRC_NEXT; - } -``` - A plugin can send messages and emit events at will: ```perl6 -- cgit v1.1 From af0f0538da7856e3378558c4f15533c012726556 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:05:28 -0400 Subject: Write stuff --- DESIGN/01-main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 848e6e9..642fe24 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -386,7 +386,7 @@ A plugin can send messages and emit events at will: Promise.in(60*60).then: { $.irc.send: where => 'Zoffix', - what => 'I lived for one hour already!", + what => 'I lived for one hour already!', :notice; $.irc.emit-custom: 'MY-EVENT', 'One hour passed!'; -- cgit v1.1 From 0a455a32fff68cbba784c2590106da2d180737c9 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:11:21 -0400 Subject: Write stuff --- DESIGN/01-main.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 642fe24..5144710 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -439,10 +439,10 @@ 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 `-` +* *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 +* *Numeric* events always receive `IRC::Client::Message::Numeric` message object, regardless of the actual number of the event. Along with event-specific methods @@ -669,6 +669,20 @@ channel, see `irc-mode` event for details. Emitted when IRC `MODE` command is received and it's being operated on a user, see `irc-mode` event for details. +## `irc-all` + +```perl6 + method irc-all ($msg) { + say "Received an event: $msg.perl()"; + return IRC_NEXT; + } +``` + +Emitted for all events and is mostly useful for debugging. The type of the +message object received will depend on the type of the event that generated +the message. This event will be triggered *AFTER* all other event handlers +in the current plugin are processed. + # Numeric Events Numeric IRC events can be subscribed to by defining a method with name -- cgit v1.1 From e76be58e39d68f36baf86872f0165436eada3830 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:17:46 -0400 Subject: Write stuff --- DESIGN/01-main.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 5144710..55faae3 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -623,9 +623,10 @@ Emitted when a user sends us a private notice. Emitted when the IRC client is started. Useful for doing setup work, like initializing database connections, etc. Note: this event will fire only once, -even if the client reconnects to the server numerous times. *IMPORTANT:* -when this event fires, there's no guarantee we event started a connection to -the server, let alone connected successfully. +even if the client reconnects to the server numerous times. Note that +unlike most events, this event does *not* receive a Message Object. +**IMPORTANT:** when this event fires, there's no guarantee we even started a +connection to the server, let alone connected successfully. ## `irc-connected` -- cgit v1.1 From 8e5ba14cd32ce3946b3f54b9e9efeb25ae48c203 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:18:51 -0400 Subject: Write stuff --- DESIGN/01-main.md | 1 + 1 file changed, 1 insertion(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 55faae3..d80223c 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -640,6 +640,7 @@ Similar to `irc-started`, except will be emitted every time a *successful* connection to the server is made and we joined all of the requested channels. That is, we'll wait to either receive the full user list or error message for each of the channels we're joining. +Note that unlike most events, this event does *not* receive a Message Object. ## `irc-mode-channel` -- cgit v1.1 From 68fdab7eabc3e1e74f110eade7ceda5868c9c8da Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:23:41 -0400 Subject: Write stuff --- DESIGN/01-main.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index d80223c..97cd370 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -792,6 +792,10 @@ is the mode set and the value is the argument for that mode (i.e. "limit", For user modes, the `.modes` method returns a list of `Str` of the modes set. +The received message objectect will be one of the subclasses of +`IRC::Client::Message::Mode` object: `IRC::Client::Message::Mode::Channel` +or `IRC::Client::Message::Mode::User`. + ## `irc-topic` ```perl6 -- cgit v1.1 From e44022ef27089111aeede035682f767accfa3351 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:25:28 -0400 Subject: Done with design --- DESIGN/01-main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 97cd370..69e085f 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -792,7 +792,7 @@ is the mode set and the value is the argument for that mode (i.e. "limit", For user modes, the `.modes` method returns a list of `Str` of the modes set. -The received message objectect will be one of the subclasses of +The received message object will be one of the subclasses of `IRC::Client::Message::Mode` object: `IRC::Client::Message::Mode::Channel` or `IRC::Client::Message::Mode::User`. -- cgit v1.1 From 12eab2b2dc9076b9255eabe4fe7d56dd1784dad8 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 28 May 2016 09:26:09 -0400 Subject: Update toc --- DESIGN/01-main.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 69e085f..aa24d07 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -6,7 +6,7 @@ - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code) - [DESIGN](#design) - [Client Object](#client-object) - - [`.irc` (access from inside a plugin)](#irc-access-from-inside-a-plugin) + - [`$.irc` (access from inside a plugin)](#irc-access-from-inside-a-plugin) - [`.new`](#new) - [`.run`](#run) - [`.quit`](#quit) @@ -44,6 +44,7 @@ - [`irc-connected`](#irc-connected) - [`irc-mode-channel`](#irc-mode-channel) - [`irc-mode-user`](#irc-mode-user) + - [`irc-all`](#irc-all) - [Numeric Events](#numeric-events) - [Named Events](#named-events) - [`irc-nick`](#irc-nick) -- cgit v1.1 From 045775a16978c6702969b8e57dd732e7e2bd2004 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Wed, 1 Jun 2016 22:31:06 -0400 Subject: Add multi-server design --- DESIGN/01-main.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 68 insertions(+), 8 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index aa24d07..e0f3573 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -113,14 +113,74 @@ The implementation distribution may also include several plugins that may be commonly needed by users. Such plugins are not enabled by default and the user must request their inclusion with code. +# Multi-Server Interface + +The interface described in the rest of this document assumes a connection +to a single server. Should the client be connected to multiple-servers at +the time, issuing commands described will apply *every* server. **Plugin +authors must keep this fact in mind, when writing plugins, as forgetting +to handle multiple servers can result in unwanted behaviour.*** + +The same reasoning applies to the `.new` method: attributes, such as +nicknames, usernames, etc. given without associating them with a server will +apply to ALL connected servers. Configuration for individual servers is +given via `:servers` named parameter as a list of `Pairs`. The key +is the nickname of server and must be a valid method name. It's recommended +to choose something that won't end up an actual method on the Client Object. +It's guaranteed methods starting with `s-` will always be safe to use. The +value is a list of pairs that can be accepted by the Client Object as named +parameters (except for `:servers`) that specify the configuration for that +specific server, overriding any of the non-server-specific parameters already +set. + +A possible `.new` setup may look something like this: + +```perl6 + my $irc = IRC::Client.new: + :nick # nicks to try to use on ALL servers, + :servers( + s-leliana => ( + :server, + :channels<#perl #perl6 #perl7> + ), + s-morrigan => ( + :server, + :channels<#perl #perl-help> + ), + s-perler => ( + :nick # nick override + :server, + :channels<#perler> + ), + ), +``` + +Use of multiple servers is facilitated via server nicknames and using +them as a method call to obtain the correct Client Object. A special +nickname of `all` is reserved to mean the command must be issued to ALL +connected servers. For example: + +```perl6 + $.irc.quit; # quits all servers + $.irc.s-leliana.quit; # quits only the s-leliana server + + # send a message to #perl6 channel on s-morrigan server + $.irc.s-morrigan.send: where => '#perl6', what => 'hello'; +``` + +The Message Object will also contain a `.server` method value of which +is the nickname of the server from which the message arrived. In general, +the most common way to generate messages will be using `.reply` on the Message +Object, making the multi-server paradigm completely transparent. + # Client Object Client Object represents a connected IRC client and is aware of and can manipulate its state, such as disconnecting, joining or parting a channel, or sending messages. -A program may have multiple Client Objects, but each of them can be connected -only to one IRC server. The client object provides these methods: +A Client Object must support the ability to connect to multiple servers. +The client object provides these methods: ## `$.irc` (access from inside a plugin) @@ -205,9 +265,9 @@ Attempts to joins channels given as positional arguments. ```perl6 $.irc.send: where => '#perl6', what => 'Hello, Perl 6!'; - + $.irc.send: where => 'Zoffix', what => 'Hi, Zoffie!'; - + $.irc.send: where => 'Zoffix', what => 'Notice me, senpai!', :notice; ``` @@ -269,7 +329,7 @@ given here will be passed as is to listener methods. $msg.reply: "I don't see $ up in here" unless $.irc.channel($msg.channel).?has: ~$; } - + if $msg.what ~~ /'topic' \s+ $=\S+/ { return $msg.reply: $_ ?? "Channel $ does not exist" @@ -290,7 +350,7 @@ information obtainable via the Channel Object will be cached and retrieved from that state, whenever possible. Otherwise, a request to the server will be generated. Return values will be empty (empty lists or empty strings) when requests fail. The channel object provides the -following methods. +following methods. ### `.has` @@ -298,7 +358,7 @@ following methods. $.irc.channel('#perl6').has: 'Zoffix'; ``` -Returns `True` or `False` indicating whether a user with the given nick is +Returns `True` or `False` indicating whether a user with the given nick is present on the channel. ### `.topic` @@ -625,7 +685,7 @@ Emitted when a user sends us a private notice. Emitted when the IRC client is started. Useful for doing setup work, like initializing database connections, etc. Note: this event will fire only once, even if the client reconnects to the server numerous times. Note that -unlike most events, this event does *not* receive a Message Object. +unlike most events, this event does *not* receive a Message Object. **IMPORTANT:** when this event fires, there's no guarantee we even started a connection to the server, let alone connected successfully. -- cgit v1.1 From 080d88e7e85725a2676a2be027c5e37a2fb706e0 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Wed, 1 Jun 2016 22:32:36 -0400 Subject: Fix toc --- DESIGN/01-main.md | 1 + 1 file changed, 1 insertion(+) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index e0f3573..474c9cf 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -5,6 +5,7 @@ - [Client-Generated Events](#client-generated-events) - [Possibility of Non-Blocking Code](#possibility-of-non-blocking-code) - [DESIGN](#design) +- [Multi-Server Interface](#multi-server-interface) - [Client Object](#client-object) - [`$.irc` (access from inside a plugin)](#irc-access-from-inside-a-plugin) - [`.new`](#new) -- cgit v1.1 From 1cb9dda6fc541c3c14025873d994cbc1fda66257 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Wed, 1 Jun 2016 22:34:25 -0400 Subject: Blahg --- DESIGN/01-main.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 474c9cf..2ac6fcd 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -118,9 +118,10 @@ the user must request their inclusion with code. The interface described in the rest of this document assumes a connection to a single server. Should the client be connected to multiple-servers at -the time, issuing commands described will apply *every* server. **Plugin -authors must keep this fact in mind, when writing plugins, as forgetting -to handle multiple servers can result in unwanted behaviour.*** +the time, issuing commands described will apply to *every* connected server. +A server must be specified to issue a command to a single server. +**Plugin authors must keep this fact in mind, when writing plugins, as +forgetting to handle multiple servers can result in unwanted behaviour.** The same reasoning applies to the `.new` method: attributes, such as nicknames, usernames, etc. given without associating them with a server will -- cgit v1.1 From d2f08aeb0f1aa3872e971165bc3ed1f91209f11f Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Wed, 1 Jun 2016 22:36:11 -0400 Subject: Blahg --- DESIGN/01-main.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 2ac6fcd..1f771d8 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -158,9 +158,7 @@ A possible `.new` setup may look something like this: ``` Use of multiple servers is facilitated via server nicknames and using -them as a method call to obtain the correct Client Object. A special -nickname of `all` is reserved to mean the command must be issued to ALL -connected servers. For example: +them as a method call to obtain the correct Client Object. For example: ```perl6 $.irc.quit; # quits all servers -- cgit v1.1 From 495050a801901460fbd6a9c525216612b0d2f470 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Wed, 1 Jun 2016 22:46:39 -0400 Subject: Stick with the theme --- DESIGN/01-main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 1f771d8..dfee0b2 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -149,7 +149,7 @@ A possible `.new` setup may look something like this: :server, :channels<#perl #perl-help> ), - s-perler => ( + s-alistair => ( :nick # nick override :server, :channels<#perler> -- cgit v1.1 From 7348d279023fcd6d2a64f617ebb9dcaab01d2252 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 23 Jul 2016 09:12:54 -0400 Subject: Fix incorrect title --- DESIGN/01-main.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index dfee0b2..7f1b60d 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -40,7 +40,7 @@ - [`irc-privmsg-channel`](#irc-privmsg-channel) - [`irc-privmsg-me`](#irc-privmsg-me) - [`irc-notice-channel`](#irc-notice-channel) - - [`irc-privmsg-me`](#irc-privmsg-me-1) + - [`irc-notice-me`](#irc-notice-me) - [`irc-started`](#irc-started) - [`irc-connected`](#irc-connected) - [`irc-mode-channel`](#irc-mode-channel) @@ -662,7 +662,7 @@ Emitted when a user sends us a private message. Emitted when a user sends a notice to a channel. -## `irc-privmsg-me` +## `irc-notice-me` ```perl6 # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? @@ -959,4 +959,3 @@ There is support for custom events. A custom event is emitted by calling ``` No Message Object is involved in custom events. - -- cgit v1.1 From effaced84ec8df42e60b89426f5fc644cb907285 Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Sat, 23 Jul 2016 09:18:06 -0400 Subject: Replace .what with more descriptory .text --- DESIGN/01-main.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) (limited to 'DESIGN') diff --git a/DESIGN/01-main.md b/DESIGN/01-main.md index 7f1b60d..196fc1c 100644 --- a/DESIGN/01-main.md +++ b/DESIGN/01-main.md @@ -165,7 +165,7 @@ them as a method call to obtain the correct Client Object. For example: $.irc.s-leliana.quit; # quits only the s-leliana server # send a message to #perl6 channel on s-morrigan server - $.irc.s-morrigan.send: where => '#perl6', what => 'hello'; + $.irc.s-morrigan.send: where => '#perl6', text => 'hello'; ``` The Message Object will also contain a `.server` method value of which @@ -191,7 +191,7 @@ The client object provides these methods: method irc-privmsg-me ($msg) { $.irc.send: where => '#perl6', - what => "$msg.nick() just sent me a secret! It's $msg.what()"; + text => "$msg.nick() just sent me a secret! It's $msg.text()"; } ``` @@ -264,14 +264,14 @@ Attempts to joins channels given as positional arguments. ## `.send` ```perl6 - $.irc.send: where => '#perl6', what => 'Hello, Perl 6!'; + $.irc.send: where => '#perl6', text => 'Hello, Perl 6!'; - $.irc.send: where => 'Zoffix', what => 'Hi, Zoffie!'; + $.irc.send: where => 'Zoffix', text => 'Hi, Zoffie!'; - $.irc.send: where => 'Zoffix', what => 'Notice me, senpai!', :notice; + $.irc.send: where => 'Zoffix', text => 'Notice me, senpai!', :notice; ``` -Sends a message specified by `what` argument +Sends a message specified by `text` argument either to a user or a channel specified by `:where` argument. If `Bool` argument `:notice` is set to true, will send a *notice* instead of regular message. @@ -297,11 +297,11 @@ arguments that are a list of nicks to try. $.irc.emit: IRC::Client::Message::Privmsg.new: nick => 'Zoffix', - what => 'Hello', + text => 'Hello', ...; ... method irc-privmsg ($msg) { - say "$msg.nick() said $msg.what()... or did they?"; + say "$msg.nick() said $msg.text()... or did they?"; } ``` @@ -325,12 +325,12 @@ given here will be passed as is to listener methods. ```perl6 method irc-addressed ($msg) { - if $msg.what ~~ /'kick' \s+ $=\S+/ { + if $msg.text ~~ /'kick' \s+ $=\S+/ { $msg.reply: "I don't see $ up in here" unless $.irc.channel($msg.channel).?has: ~$; } - if $msg.what ~~ /'topic' \s+ $=\S+/ { + if $msg.text ~~ /'topic' \s+ $=\S+/ { return $msg.reply: $_ ?? "Channel $ does not exist" !! "Topic in $ is $_.topic()" @@ -418,7 +418,7 @@ event. User-defined events follow the same pattern, except they start with # Listen to custom client-generated events: method irc-custom-my-event ($some, $random, :$args) { return IRC_NEXT unless $random > 5; - $.irc.send: where => '#perl6', what => 'Custom event triggered!'; + $.irc.send: where => '#perl6', text => 'Custom event triggered!'; } ``` @@ -442,12 +442,12 @@ A plugin can send messages and emit events at will: ```perl6 method irc-connected { Supply.interval(60).tap: { - $.irc.send: where => '#perl6', what => 'One minute passed!!'; + $.irc.send: where => '#perl6', text => 'One minute passed!!'; }; Promise.in(60*60).then: { $.irc.send: where => 'Zoffix', - what => 'I lived for one hour already!', + text => 'I lived for one hour already!', :notice; $.irc.emit-custom: 'MY-EVENT', 'One hour passed!'; @@ -547,7 +547,7 @@ Nick, username, and host combined into a full usermask, e.g. ```perl6 $msg.reply: 'I love you too' - if $msg.what ~~ /'I love you'/; + if $msg.text ~~ /'I love you'/; ``` Replies back to a message. For example, if we received the message as a @@ -583,7 +583,7 @@ of events easier. method irc-to-me ($msg) { printf "%s told us `%s` using %s\n", - .nick, .what, .how given $msg; + .nick, .text, .how given $msg; } ``` @@ -602,7 +602,7 @@ The `.how` method returns a `Pair` where the key is the message type used method irc-addressed ($msg) { printf "%s told us `%s` in channel %s\n", - .nick, .what, .channel given $msg; + .nick, .text, .channel given $msg; } ``` @@ -617,7 +617,7 @@ followed by whitespace. That prefix will be stripped from the message. method irc-mentioned ($msg) { printf "%s mentioned us in channel %s when they said %s\n", - .nick, .channel, .what given $msg; + .nick, .channel, .text given $msg; } ``` @@ -631,7 +631,7 @@ their message contains our nickname separated by a word boundary on each side. method irc-privmsg-channel ($msg) { printf "%s said `%s` to channel %s\n", - .nick, .what, .channel given $msg; + .nick, .text, .channel given $msg; } ``` @@ -643,7 +643,7 @@ Emitted when a user sends a message to a channel. # :zoffix!zoffix@127.0.0.1 PRIVMSG zoffix2 :hey bruh method irc-privmsg-me ($msg) { - printf "%s messaged us: %s\n", .nick, .what given $msg; + printf "%s messaged us: %s\n", .nick, .text given $msg; } ``` @@ -656,7 +656,7 @@ Emitted when a user sends us a private message. method irc-notice-channel ($msg) { printf "%s sent a notice `%s` to channel %s\n", - .nick, .what, .channel given $msg; + .nick, .text, .channel given $msg; } ``` @@ -668,7 +668,7 @@ Emitted when a user sends a notice to a channel. # :zoffix!zoffix@127.0.0.1 NOTICE zoffix2 :did you notice me? method irc-notice-me ($msg) { - printf "%s sent us a notice: %s\n", .nick, .what given $msg; + printf "%s sent us a notice: %s\n", .nick, .text given $msg; } ``` @@ -908,11 +908,11 @@ Emitted when someone kicks a user out of a channel. if $msg.?channel { # message sent to a channel printf "%s said `%s` to channel %s\n", - .nick, .what, .channel given $msg; + .nick, .text, .channel given $msg; } else { # private message - printf "%s messaged us: %s\n", .nick, .what given $msg; + printf "%s messaged us: %s\n", .nick, .text given $msg; } } ``` @@ -932,11 +932,11 @@ of more convenient ways to listen to messages. if $msg.?channel { # notice sent to a channel printf "%s sent a notice `%s` to channel %s\n", - .nick, .what, .channel given $msg; + .nick, .text, .channel given $msg; } else { # private notice - printf "%s sent us a notice: %s\n", .nick, .what given $msg; + printf "%s sent us a notice: %s\n", .nick, .text given $msg; } } ``` -- cgit v1.1