cinch 1.1.3 → 2.0.0.pre.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/LICENSE +1 -0
- data/README.md +3 -3
- data/docs/bot_options.md +435 -0
- data/docs/changes.md +440 -0
- data/docs/common_mistakes.md +35 -0
- data/docs/common_tasks.md +47 -0
- data/docs/encodings.md +67 -0
- data/docs/events.md +272 -0
- data/docs/logging.md +5 -0
- data/docs/migrating.md +267 -0
- data/docs/readme.md +18 -0
- data/examples/plugins/custom_prefix.rb +1 -1
- data/examples/plugins/dice_roll.rb +38 -0
- data/examples/plugins/lambdas.rb +1 -1
- data/examples/plugins/memo.rb +16 -10
- data/examples/plugins/url_shorten.rb +1 -0
- data/lib/cinch.rb +5 -60
- data/lib/cinch/ban.rb +13 -7
- data/lib/cinch/bot.rb +228 -403
- data/lib/cinch/{cache_manager.rb → cached_list.rb} +5 -1
- data/lib/cinch/callback.rb +3 -0
- data/lib/cinch/channel.rb +119 -195
- data/lib/cinch/{channel_manager.rb → channel_list.rb} +6 -3
- data/lib/cinch/configuration.rb +73 -0
- data/lib/cinch/configuration/bot.rb +47 -0
- data/lib/cinch/configuration/dcc.rb +16 -0
- data/lib/cinch/configuration/plugins.rb +41 -0
- data/lib/cinch/configuration/sasl.rb +17 -0
- data/lib/cinch/configuration/ssl.rb +19 -0
- data/lib/cinch/configuration/storage.rb +37 -0
- data/lib/cinch/configuration/timeouts.rb +14 -0
- data/lib/cinch/constants.rb +531 -369
- data/lib/cinch/dcc.rb +12 -0
- data/lib/cinch/dcc/dccable_object.rb +37 -0
- data/lib/cinch/dcc/incoming.rb +1 -0
- data/lib/cinch/dcc/incoming/send.rb +131 -0
- data/lib/cinch/dcc/outgoing.rb +1 -0
- data/lib/cinch/dcc/outgoing/send.rb +115 -0
- data/lib/cinch/exceptions.rb +8 -1
- data/lib/cinch/formatting.rb +106 -0
- data/lib/cinch/handler.rb +104 -0
- data/lib/cinch/handler_list.rb +86 -0
- data/lib/cinch/helpers.rb +167 -10
- data/lib/cinch/irc.rb +525 -110
- data/lib/cinch/isupport.rb +11 -9
- data/lib/cinch/logger.rb +168 -0
- data/lib/cinch/logger/formatted_logger.rb +72 -55
- data/lib/cinch/logger/zcbot_logger.rb +9 -24
- data/lib/cinch/logger_list.rb +62 -0
- data/lib/cinch/mask.rb +19 -10
- data/lib/cinch/message.rb +94 -28
- data/lib/cinch/message_queue.rb +70 -28
- data/lib/cinch/mode_parser.rb +6 -1
- data/lib/cinch/network.rb +104 -0
- data/lib/cinch/{rubyext/queue.rb → open_ended_queue.rb} +8 -1
- data/lib/cinch/pattern.rb +24 -4
- data/lib/cinch/plugin.rb +352 -177
- data/lib/cinch/plugin_list.rb +35 -0
- data/lib/cinch/rubyext/float.rb +3 -0
- data/lib/cinch/rubyext/module.rb +7 -0
- data/lib/cinch/rubyext/string.rb +9 -0
- data/lib/cinch/sasl.rb +34 -0
- data/lib/cinch/sasl/dh_blowfish.rb +71 -0
- data/lib/cinch/sasl/diffie_hellman.rb +47 -0
- data/lib/cinch/sasl/mechanism.rb +6 -0
- data/lib/cinch/sasl/plain.rb +26 -0
- data/lib/cinch/storage.rb +62 -0
- data/lib/cinch/storage/null.rb +12 -0
- data/lib/cinch/storage/yaml.rb +96 -0
- data/lib/cinch/syncable.rb +13 -1
- data/lib/cinch/target.rb +144 -0
- data/lib/cinch/timer.rb +145 -0
- data/lib/cinch/user.rb +169 -225
- data/lib/cinch/{user_manager.rb → user_list.rb} +7 -2
- data/lib/cinch/utilities/deprecation.rb +12 -0
- data/lib/cinch/utilities/encoding.rb +54 -0
- data/lib/cinch/utilities/kernel.rb +13 -0
- data/lib/cinch/utilities/string.rb +13 -0
- data/lib/cinch/version.rb +4 -0
- metadata +88 -47
- data/lib/cinch/logger/logger.rb +0 -44
- data/lib/cinch/logger/null_logger.rb +0 -18
- data/lib/cinch/rubyext/infinity.rb +0 -1
@@ -0,0 +1,47 @@
|
|
1
|
+
# @title Common Tasks
|
2
|
+
|
3
|
+
# Checking if a user is online
|
4
|
+
|
5
|
+
Cinch by itself tries to keep track of the online state of users.
|
6
|
+
Whenever it sees someone speak, change his nick or be in a channel the
|
7
|
+
bot is also in, it'll set the user to being online. And when a user
|
8
|
+
quits, gets killed or cannot be whoised/contacted, its state will be
|
9
|
+
set to offline.
|
10
|
+
|
11
|
+
A problem with that information is that it can quickly become out of
|
12
|
+
sync. Consider the following example:
|
13
|
+
|
14
|
+
The bot joins a channel, sees someone in the name list and thus marks
|
15
|
+
him as online. The bot then leaves the channel and at some later
|
16
|
+
point, the user disconnects. The bot won't know that and still track
|
17
|
+
the user as online.
|
18
|
+
|
19
|
+
If (near-)realtime information about this state is required, one can
|
20
|
+
use {Cinch::User#monitor} to automatically monitor the state.
|
21
|
+
{Cinch::User#monitor #monitor} uses either the _MONITOR_ feature of modern IRCds or, if
|
22
|
+
that's not available, periodically runs _WHOIS_ to update the
|
23
|
+
information.
|
24
|
+
|
25
|
+
Whenever a user's state changes, either the `:online` or the
|
26
|
+
`:offline` event will be fired, as can be seen in the following
|
27
|
+
example:
|
28
|
+
|
29
|
+
class SomePlugin
|
30
|
+
include Cinch::Plugin
|
31
|
+
|
32
|
+
listen_to :connect, method: :on_connect
|
33
|
+
listen_to :online, method: :on_online
|
34
|
+
listen_to :offline, method: :on_offline
|
35
|
+
|
36
|
+
def on_connect(m)
|
37
|
+
User("my_master").monitor
|
38
|
+
end
|
39
|
+
|
40
|
+
def on_online(m, user)
|
41
|
+
user.send "Hello master"
|
42
|
+
end
|
43
|
+
|
44
|
+
def on_offline(m, user)
|
45
|
+
@bot.loggers.info "I miss my master :("
|
46
|
+
end
|
47
|
+
end
|
data/docs/encodings.md
ADDED
@@ -0,0 +1,67 @@
|
|
1
|
+
# @title Encodings
|
2
|
+
# Encodings
|
3
|
+
|
4
|
+
The IRC protocol doesn't define a specific encoding that should be
|
5
|
+
used, nor does it provide any information on which encodings _are_
|
6
|
+
being used.
|
7
|
+
|
8
|
+
At the same time, lots of different encodings have become popular on
|
9
|
+
IRC. This presents a big problem, because, if you're using a different
|
10
|
+
encoding than someone else on IRC, you'll receive their text as
|
11
|
+
garbage.
|
12
|
+
|
13
|
+
Cinch tries to work around this issue in two ways, while also keeping
|
14
|
+
the usual Ruby behaviour.
|
15
|
+
|
16
|
+
## The `encoding` option
|
17
|
+
By setting {file:bot_options.md#encoding the `encoding` option}, you
|
18
|
+
set your expectations on what encoding other users will use. Allowed
|
19
|
+
values are instances of Encoding, names of valid encodings (as
|
20
|
+
strings) and the special `:irc` encoding, which will be explained
|
21
|
+
further down.
|
22
|
+
|
23
|
+
|
24
|
+
## Encoding.default_internal
|
25
|
+
If set, Cinch will automatically convert incoming messages to the
|
26
|
+
encoding defined by `Encoding.default_internal`, unless the special
|
27
|
+
encoding `:irc` is being used as the {file:bot_options.md#encoding
|
28
|
+
`encoding option`}
|
29
|
+
|
30
|
+
## The `:irc` encoding
|
31
|
+
As mentioned earlier, people couldn't decide on a single encoding to
|
32
|
+
use. As such, specifying a single encoding would most likely lead to
|
33
|
+
problems, especially if the bot is in more than one channel.
|
34
|
+
|
35
|
+
Luckily, even though people cannot decide on a single encoding,
|
36
|
+
western countries usually either use CP1252 (Windows Latin-1) or
|
37
|
+
UTF-8. Since text encoded in CP1252 fails validation as UTF-8, it is
|
38
|
+
easy to tell the two apart. Additionally it is possible to losslessly
|
39
|
+
re-encode CP1252 in UTF-8 and as such, a small subset of UTF-8 is also
|
40
|
+
representable in CP1252.
|
41
|
+
|
42
|
+
If incoming text is valid UTF-8, it will be interpreted as such. If it
|
43
|
+
fails validation, a CP1252 → UTF-8 conversion is performed. This
|
44
|
+
ensures that you will always deal with UTF-8 in your code, even if
|
45
|
+
other people use CP1252. Note, however, that we ignore
|
46
|
+
`Encoding.default_internal` in this case and always present you with
|
47
|
+
UTF-8.
|
48
|
+
|
49
|
+
If text you send contains only characters that fit inside the
|
50
|
+
CP1252 code page, the entire line will be sent that way.
|
51
|
+
|
52
|
+
If the text doesn't fit inside the CP1252 code page, (for example if
|
53
|
+
you type Eastern European characters, or Russian) it will be sent as
|
54
|
+
UTF-8. Only UTF-8 capable clients will be able to see these characters
|
55
|
+
correctly.
|
56
|
+
|
57
|
+
## Invalid bytes and unsupported translations
|
58
|
+
If Cinch receives text in an encoding other than the one assumed, it
|
59
|
+
can happen that the message contains bytes that are not valid in the
|
60
|
+
assumed encoding. Instead of dropping the complete message, Cinch will
|
61
|
+
replace offending bytes with question marks.
|
62
|
+
|
63
|
+
Also, if you expect messages in e.g. UTF-8 but re-encode them in
|
64
|
+
CP1252 (by setting `Encoding.default_internal` to CP1252), it can
|
65
|
+
happen that some characters cannot be represented in CP1252. In such a
|
66
|
+
case, Cinch will too replace the offending characters with question
|
67
|
+
marks.
|
data/docs/events.md
ADDED
@@ -0,0 +1,272 @@
|
|
1
|
+
# @title Events
|
2
|
+
|
3
|
+
Cinch provides three kinds of events:
|
4
|
+
|
5
|
+
1. Events mapping directly to IRC commands
|
6
|
+
|
7
|
+
For example `:topic`, which will be triggered when someone changes
|
8
|
+
the topic, or `:kick`, when someone gets kicked.
|
9
|
+
|
10
|
+
2. Events mapping directly to IRC numeric codes
|
11
|
+
|
12
|
+
For example `:"401"` for `ERR_NOSUCHNICK`, which is triggered when
|
13
|
+
trying to operate on an unknown nickname, or `:"318"` for
|
14
|
+
`RPL_ENDOFWHOIS`, which is triggered after whois information have
|
15
|
+
been received.
|
16
|
+
|
17
|
+
3. Events mapping to more abstract ideas
|
18
|
+
|
19
|
+
For example `:leaving` whenever a user parts, quits or gets
|
20
|
+
kicked/killed or `:message`, which is actually a synonym for
|
21
|
+
`:privmsg`, the underlying IRC command.
|
22
|
+
|
23
|
+
# Events of the first two kinds
|
24
|
+
|
25
|
+
All events of the first two kinds behave exactly the same: When they
|
26
|
+
get triggered, the handler will be passed a single object, a reference
|
27
|
+
to the {Cinch::Message Message object}.
|
28
|
+
|
29
|
+
Example:
|
30
|
+
|
31
|
+
on :topic do |m|
|
32
|
+
# m is the message object
|
33
|
+
end
|
34
|
+
|
35
|
+
We will not further describe all possible events of the first two
|
36
|
+
categories.
|
37
|
+
|
38
|
+
# Events of the third kind
|
39
|
+
|
40
|
+
Events of the third kind can each have different signatures, as they
|
41
|
+
get passed objects directly relating to their kind, for example the
|
42
|
+
leaving user in case of `:leaving`. This document will describe all
|
43
|
+
events of that kind, their signature and example usage.
|
44
|
+
|
45
|
+
**Note: Because *all* handlers receive a {Cinch::Message Message}
|
46
|
+
object as the first argument, we will only mention and describe
|
47
|
+
additional arguments.**
|
48
|
+
|
49
|
+
## `:action`
|
50
|
+
|
51
|
+
The `:action` event is triggered when a user sends a CTCP ACTION to a
|
52
|
+
channel or the bot. CTCP ACTION is commonly refered to simply as
|
53
|
+
"actions" or "/me's", because that is the command used in most IRC
|
54
|
+
clients.
|
55
|
+
|
56
|
+
Example:
|
57
|
+
|
58
|
+
on :action, "kicks the bot" do |m|
|
59
|
+
m.reply "Ouch! Stop kicking me :(", true
|
60
|
+
end
|
61
|
+
|
62
|
+
|
63
|
+
## `:away`
|
64
|
+
|
65
|
+
The `:away` event is triggered when a user goes away. This feature
|
66
|
+
only works on networks implementing the "away-notify" extension.
|
67
|
+
|
68
|
+
Example:
|
69
|
+
|
70
|
+
on :away do |m|
|
71
|
+
debug("User %s just went away: %s" % [m.user, m.message])
|
72
|
+
end
|
73
|
+
|
74
|
+
See also {file:events.md#unaway the `:unaway` event}.
|
75
|
+
|
76
|
+
|
77
|
+
## `:ban`
|
78
|
+
|
79
|
+
The `:ban` event is triggered when a user gets banned in a channel.
|
80
|
+
|
81
|
+
One additional argument, a {Cinch::Ban Ban object}, gets passed to
|
82
|
+
the handler.
|
83
|
+
|
84
|
+
Example:
|
85
|
+
|
86
|
+
on :ban do |m, ban|
|
87
|
+
debug("%s just banned %s" % [ban.by, ban.mask])
|
88
|
+
end
|
89
|
+
|
90
|
+
See also {file:events.md#unban the `:unban` event}.
|
91
|
+
|
92
|
+
|
93
|
+
## `:catchall`
|
94
|
+
|
95
|
+
`:catchall` is a special event that gets triggered for every incoming
|
96
|
+
IRC message/command, no matter what the type is.
|
97
|
+
|
98
|
+
|
99
|
+
## `:channel`
|
100
|
+
|
101
|
+
The `:channel` event is triggered for channel messages (the usual
|
102
|
+
form of communication on IRC).
|
103
|
+
|
104
|
+
See also {file:events.md#private the `:private` event}.
|
105
|
+
|
106
|
+
|
107
|
+
## `:connect`
|
108
|
+
|
109
|
+
The `:connect` event is triggered after the bot successfully
|
110
|
+
connected to the IRC server.
|
111
|
+
|
112
|
+
One common use case for this event is setting up variables,
|
113
|
+
synchronising information etc.
|
114
|
+
|
115
|
+
|
116
|
+
## `:ctcp`
|
117
|
+
|
118
|
+
The `:ctcp` event is triggered when receiving CTCP-related messages,
|
119
|
+
for example the VERSION request.
|
120
|
+
|
121
|
+
|
122
|
+
## `:dcc_send`
|
123
|
+
|
124
|
+
`:dcc_send` gets triggered when a user tries to send a file to the
|
125
|
+
bot, using the DCC SEND protocol.
|
126
|
+
|
127
|
+
One additional argument, a {Cinch::DCC::Incoming::Send DCC::Send
|
128
|
+
object}, gets passed to the handler.
|
129
|
+
|
130
|
+
For example usage and a general explanation of DCC in Cinch check
|
131
|
+
{Cinch::DCC::Incoming::Send}.
|
132
|
+
|
133
|
+
|
134
|
+
## `:dehalfop`, `:deop`, `:deowner`, `:devoice`
|
135
|
+
|
136
|
+
These events get triggered for the respective channel operations of
|
137
|
+
taking halfop, op, owner and voice from a user.
|
138
|
+
|
139
|
+
One additional argument, the user whose rights are being modifed, gets
|
140
|
+
passed to the handler.
|
141
|
+
|
142
|
+
|
143
|
+
## `:error`
|
144
|
+
|
145
|
+
`:error` gets triggered for all numeric replies that signify errors
|
146
|
+
(`ERR_*`).
|
147
|
+
|
148
|
+
|
149
|
+
## `:halfop`
|
150
|
+
|
151
|
+
This event gets triggered when a user in a channel gets half-opped.
|
152
|
+
|
153
|
+
One additional argument, the user being half-opped, gets passed to the
|
154
|
+
handler.
|
155
|
+
|
156
|
+
|
157
|
+
## `:leaving`
|
158
|
+
|
159
|
+
`:leaving` is an event that is triggered whenever any of the following
|
160
|
+
are triggered as well: `:part`, `:quit`, `:kick`, `:kill`.
|
161
|
+
|
162
|
+
The event can thus be used for noticing when a user leaves a channel
|
163
|
+
or the network, no matter the reason.
|
164
|
+
|
165
|
+
One additional argument, the leaving user, gets passed to the handler.
|
166
|
+
|
167
|
+
Be careful not to confuse the additional argument with
|
168
|
+
{Cinch::Message#user}. For example in the case of a kick,
|
169
|
+
{Cinch::Message#user} will describe the user kicking someone, not the
|
170
|
+
one who is being kicked.
|
171
|
+
|
172
|
+
Example:
|
173
|
+
|
174
|
+
on :leaving do |m, user|
|
175
|
+
if m.channel?
|
176
|
+
debug("%s just left %s." % [user, m.channel])
|
177
|
+
else
|
178
|
+
debug("%s just left the network." % user)
|
179
|
+
end
|
180
|
+
end
|
181
|
+
|
182
|
+
|
183
|
+
|
184
|
+
## `:mode_change`
|
185
|
+
|
186
|
+
This event gets triggered whenever modes in a channel or on the bot
|
187
|
+
directly change. Unlike events like `:op`, this event is more
|
188
|
+
low-level, as the argument the handler gets passed is an array
|
189
|
+
describing every change.
|
190
|
+
|
191
|
+
|
192
|
+
## `:offline`
|
193
|
+
|
194
|
+
This event is triggered when a
|
195
|
+
{file:common_tasks.md#checking-if-a-user-is-online monitored user}
|
196
|
+
goes offline.
|
197
|
+
|
198
|
+
One additional argument, the user going offline, gets passed to the
|
199
|
+
handler.
|
200
|
+
|
201
|
+
|
202
|
+
## `:online`
|
203
|
+
|
204
|
+
This event is triggered when a
|
205
|
+
{file:common_tasks.md#checking-if-a-user-is-online monitored user}
|
206
|
+
comes online.
|
207
|
+
|
208
|
+
One additional argument, the user coming online, gets passed to the
|
209
|
+
handler.
|
210
|
+
|
211
|
+
|
212
|
+
## `:op`
|
213
|
+
|
214
|
+
This event gets triggered when a user in a channel gets opped.
|
215
|
+
|
216
|
+
One additional argument, the user being opped, gets passed to the
|
217
|
+
handler.
|
218
|
+
|
219
|
+
|
220
|
+
## `:owner`
|
221
|
+
|
222
|
+
|
223
|
+
This event gets triggered when a user in a channel receives
|
224
|
+
owner-status.
|
225
|
+
|
226
|
+
One additional argument, the user receiving owner-status, gets passed
|
227
|
+
to the handler.
|
228
|
+
|
229
|
+
|
230
|
+
## `:message`
|
231
|
+
|
232
|
+
The `:message` event is triggered for messages directed at either a
|
233
|
+
channel or directly at the bot. It's synonymous with `:privmsg`.
|
234
|
+
|
235
|
+
|
236
|
+
## `:private`
|
237
|
+
|
238
|
+
The `:private` event is triggered for messages directly towarded at
|
239
|
+
the bot (think /query in traditional IRC clients).
|
240
|
+
|
241
|
+
See also {file:events.md#channel the `:channel` event}.
|
242
|
+
|
243
|
+
|
244
|
+
## `:unaway`
|
245
|
+
|
246
|
+
The `:unaway` event is triggered when a user no longer is away. This
|
247
|
+
feature only works on networks implementing the "away-notify"
|
248
|
+
extension.
|
249
|
+
|
250
|
+
Example:
|
251
|
+
|
252
|
+
on :unaway do |m|
|
253
|
+
debug("User %s no longer is away." % m.user)
|
254
|
+
end
|
255
|
+
|
256
|
+
See also {file:events.md#away the `:away` event}.
|
257
|
+
|
258
|
+
|
259
|
+
## `:unban`
|
260
|
+
|
261
|
+
The `:unban` event is triggered when a user gets unbanned in a
|
262
|
+
channel.
|
263
|
+
|
264
|
+
One additional argument, a {Cinch::Ban Ban object}, gets passed to the
|
265
|
+
handler.
|
266
|
+
|
267
|
+
|
268
|
+
## `:voice`
|
269
|
+
This event gets triggered when a user in a channel gets voiced.
|
270
|
+
|
271
|
+
One additional argument, the user being voiced, gets passed to the
|
272
|
+
handler.
|
data/docs/logging.md
ADDED
data/docs/migrating.md
ADDED
@@ -0,0 +1,267 @@
|
|
1
|
+
# @title Migration Guide
|
2
|
+
# Migration Guide
|
3
|
+
|
4
|
+
This document explains how to migrate between API incompatible
|
5
|
+
versions of Cinch.
|
6
|
+
|
7
|
+
## Migrating from 1.x to 2.x
|
8
|
+
|
9
|
+
## Plugins
|
10
|
+
|
11
|
+
### New methods
|
12
|
+
|
13
|
+
Plugins have the following (new) instance and class methods, which you
|
14
|
+
shouldn't and usually mustn't overwrite:
|
15
|
+
|
16
|
+
- `#bot`
|
17
|
+
- `#config`
|
18
|
+
- `#handlers`
|
19
|
+
- `#storage`
|
20
|
+
- `#synchronize`
|
21
|
+
- `#timers`
|
22
|
+
- `#unregister`
|
23
|
+
- `::call_hooks`
|
24
|
+
- `::check_for_missing_options`
|
25
|
+
- `::ctcp`
|
26
|
+
- `::ctcps`
|
27
|
+
- `::help=`
|
28
|
+
- `::help`
|
29
|
+
- `::hook`
|
30
|
+
- `::hooks`
|
31
|
+
- `::listen_to`
|
32
|
+
- `::listeners`
|
33
|
+
- `::match`
|
34
|
+
- `::matchers`
|
35
|
+
- `::plugin_name=`
|
36
|
+
- `::plugin_name`
|
37
|
+
- `::prefix=`
|
38
|
+
- `::prefix`
|
39
|
+
- `::react_on`
|
40
|
+
- `::reacting_on=`
|
41
|
+
- `::reacting_on`
|
42
|
+
- `::required_options=`
|
43
|
+
- `::required_options`
|
44
|
+
- `::set`
|
45
|
+
- `::suffix=`
|
46
|
+
- `::suffix`
|
47
|
+
- `::timer`
|
48
|
+
- `::timers`
|
49
|
+
|
50
|
+
Note: The list does also include methods from prior versions.
|
51
|
+
|
52
|
+
|
53
|
+
### Plugin options
|
54
|
+
|
55
|
+
Previously, plugins used a DSL-like way of setting options like the
|
56
|
+
plugin prefix. This contradicts with the general idea of plugins being
|
57
|
+
ordinary Ruby classes and also caused a lot of code and documentation
|
58
|
+
smell.
|
59
|
+
|
60
|
+
Instead of having methods like `#prefix` double as both attribute
|
61
|
+
getter and setter, options can now be set in two different ways: Using
|
62
|
+
ordinary attribute setters or using the
|
63
|
+
{Cinch::Plugin::ClassMethods#set #set} method.
|
64
|
+
|
65
|
+
#### Cinch 1.x
|
66
|
+
|
67
|
+
class MyPlugin
|
68
|
+
include Cinch::Plugin
|
69
|
+
|
70
|
+
prefix /^!/
|
71
|
+
help "some help message"
|
72
|
+
match /foo/
|
73
|
+
def execute(m)
|
74
|
+
# ...
|
75
|
+
end
|
76
|
+
end
|
77
|
+
|
78
|
+
#### Cinch 2.x, attribute setters
|
79
|
+
|
80
|
+
class MyPlugin
|
81
|
+
include Cinch::Plugin
|
82
|
+
|
83
|
+
self.prefix = /^!/
|
84
|
+
self.help = "some help message"
|
85
|
+
match /foo/
|
86
|
+
def execute(m)
|
87
|
+
# ...
|
88
|
+
end
|
89
|
+
end
|
90
|
+
|
91
|
+
#### Cinch 2.x, `#set` method
|
92
|
+
|
93
|
+
class MyPlugin
|
94
|
+
include Cinch::Plugin
|
95
|
+
|
96
|
+
set :prefix, /^!/
|
97
|
+
set :help, "some help message"
|
98
|
+
match /foo/
|
99
|
+
def execute(m)
|
100
|
+
# ...
|
101
|
+
end
|
102
|
+
end
|
103
|
+
|
104
|
+
#### Cinch 2.x, `#set` method, alternative syntax
|
105
|
+
|
106
|
+
class MyPlugin
|
107
|
+
include Cinch::Plugin
|
108
|
+
|
109
|
+
set prefix: /^!/,
|
110
|
+
help: "some help message"
|
111
|
+
match /foo/
|
112
|
+
def execute(m)
|
113
|
+
# ...
|
114
|
+
end
|
115
|
+
end
|
116
|
+
|
117
|
+
|
118
|
+
### No more automatic matcher with the plugin's name
|
119
|
+
|
120
|
+
Cinch does not add a default matcher with the plugin's name anymore.
|
121
|
+
If you've been relying on the following to work
|
122
|
+
|
123
|
+
class Footastic
|
124
|
+
include Cinch::Plugin
|
125
|
+
|
126
|
+
def execute(m)
|
127
|
+
# this will triger on "!footastic"
|
128
|
+
end
|
129
|
+
end
|
130
|
+
|
131
|
+
you will have to rewrite it using an explicit matcher:
|
132
|
+
|
133
|
+
class Footastic
|
134
|
+
include Cinch::Plugin
|
135
|
+
|
136
|
+
match "footastic"
|
137
|
+
def execute(m)
|
138
|
+
# ...
|
139
|
+
end
|
140
|
+
end
|
141
|
+
|
142
|
+
### No more default `#execute` and `#listen` methods
|
143
|
+
|
144
|
+
Plugins do not come with default `#execute` and `#listen` methods
|
145
|
+
anymore, which means that specifying a matcher or listener without
|
146
|
+
providing the required methods will always result in an exception.
|
147
|
+
|
148
|
+
### Programmatically registering plugins
|
149
|
+
|
150
|
+
If you're using the API to register plugins on your own, you will have
|
151
|
+
to use the new {Cinch::PluginList} class and its methods, instead of
|
152
|
+
using `Cinch::Bot#register_plugin` or `Cinch::Bot#register_plugins`,
|
153
|
+
which have been removed.
|
154
|
+
|
155
|
+
The PluginList instance is available via {Cinch::Bot#plugins}.
|
156
|
+
|
157
|
+
## Logging
|
158
|
+
|
159
|
+
Logging in Cinch 2.x has been greatly improved. Instead of only
|
160
|
+
supporting one logger and having all logging-relevant methods in
|
161
|
+
{Cinch::Bot}, we've introduced the {Cinch::LoggerList} class, which
|
162
|
+
manages an infinite number of loggers. Included with Cinch are the
|
163
|
+
{Cinch::Logger::FormattedLogger formatted logger}, known from Cinch
|
164
|
+
1.x, and a new {Cinch::Logger::ZcbotLogger Zcbot logger}, a logger
|
165
|
+
emulating the log output of Zcbot, a format which can be parsed by
|
166
|
+
{http://pisg.sourceforge.net/ pisg}.
|
167
|
+
|
168
|
+
### Log levels
|
169
|
+
|
170
|
+
The old `@config.verbose` option has been replaced with a finely
|
171
|
+
tunable log level system. Each logger has {Cinch::Logger#level its own
|
172
|
+
level}, but it is also possible to {Cinch::LoggerList#level= set the
|
173
|
+
level for all loggers at once}.
|
174
|
+
|
175
|
+
The available levels, in ascending order of verbosity, are:
|
176
|
+
|
177
|
+
- fatal
|
178
|
+
- error
|
179
|
+
- warn
|
180
|
+
- info
|
181
|
+
- log
|
182
|
+
- debug
|
183
|
+
|
184
|
+
### Methods
|
185
|
+
|
186
|
+
All logging related methods (`Cinch::Bot#debug` et al) have been
|
187
|
+
removed from the Bot class and instead moved to the loggers and the
|
188
|
+
{Cinch::LoggerList LoggerList}. If you want to log messages from your
|
189
|
+
plugins or handlers, you should use {Cinch::Bot#loggers} to access the
|
190
|
+
{Cinch::LoggerList LoggerList} and then call the right methods on
|
191
|
+
that. Alterntively you can also use the logging-related helper methods
|
192
|
+
provided by {Cinch::Helpers}.
|
193
|
+
|
194
|
+
For more information on the logging architecture as well as examples
|
195
|
+
on how to use it, check the {file:logging.md Logging readme}.
|
196
|
+
|
197
|
+
## Prefix/suffix + string semantics
|
198
|
+
|
199
|
+
Behaviour of string prefixes and suffixes has been adapted to match
|
200
|
+
that of matchers.
|
201
|
+
|
202
|
+
That means that if the prefix or suffix are strings, the ^ or $ anchor
|
203
|
+
will be prepended/appened.
|
204
|
+
|
205
|
+
## Hooks and their return value
|
206
|
+
|
207
|
+
Hooks now behave as filters. If a hook returns `false`, the message
|
208
|
+
will not further be processed in a particular plugin.
|
209
|
+
|
210
|
+
## Constants
|
211
|
+
|
212
|
+
All constants for numeric replies (e.g. `RPL_INFO`) have been moved from
|
213
|
+
{Cinch} to {Cinch::Constants}. Thus `Cinch::RPL_INFO` becomes
|
214
|
+
{Cinch::Constants::RPL_INFO}, same for all other numeric constants.
|
215
|
+
|
216
|
+
## Bot configuration
|
217
|
+
|
218
|
+
Bot configuration now uses {Cinch::Configuration special classes}
|
219
|
+
instead of OpenStructs. Thus, assignments like
|
220
|
+
|
221
|
+
configure do |c|
|
222
|
+
c.timeouts = OpenStruct.new({:read => 240, :connect => 10})
|
223
|
+
end
|
224
|
+
|
225
|
+
are not possible anymore and have to be written as either
|
226
|
+
|
227
|
+
configure do |c|
|
228
|
+
c.timeouts.read = 240
|
229
|
+
c.timeouts.connect = 10
|
230
|
+
end
|
231
|
+
|
232
|
+
or
|
233
|
+
|
234
|
+
configure do |c|
|
235
|
+
c.timeouts.load({:read => 240, :connect => 10})
|
236
|
+
end
|
237
|
+
|
238
|
+
The second version is especially interesting to tools like
|
239
|
+
{https://github.com/netfeed/cinchize Cinchize}, which load the
|
240
|
+
configuration from a YAML file. For more information see
|
241
|
+
{file:bot_options.md Bot options}.
|
242
|
+
|
243
|
+
|
244
|
+
## Various removed methods
|
245
|
+
|
246
|
+
See {file:changes.md#removedrenamed-methods What's changed}
|
247
|
+
|
248
|
+
|
249
|
+
## `on`-handlers now only accepts one pattern
|
250
|
+
|
251
|
+
In previous versions, {Cinch::Bot#on} accepted a variable amount of patterns
|
252
|
+
to match against. This feature was rarely used and has hence been
|
253
|
+
removed. If you've been using constructs like
|
254
|
+
|
255
|
+
on :message, [/this/, /that/] do |m|
|
256
|
+
# ...
|
257
|
+
end
|
258
|
+
|
259
|
+
you will have to rewrite them as follows:
|
260
|
+
|
261
|
+
b = lambda { |m|
|
262
|
+
# ...
|
263
|
+
}
|
264
|
+
|
265
|
+
[/this/, /that/].each do |pattern|
|
266
|
+
on :message, pattern, &b
|
267
|
+
end
|