cinch 1.1.3 → 2.0.0.pre.1
Sign up to get free protection for your applications and to get access to all the features.
- 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
|