1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
# 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.
### 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 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:
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.
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:
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
[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.
|
