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.
Files changed (83) hide show
  1. data/LICENSE +1 -0
  2. data/README.md +3 -3
  3. data/docs/bot_options.md +435 -0
  4. data/docs/changes.md +440 -0
  5. data/docs/common_mistakes.md +35 -0
  6. data/docs/common_tasks.md +47 -0
  7. data/docs/encodings.md +67 -0
  8. data/docs/events.md +272 -0
  9. data/docs/logging.md +5 -0
  10. data/docs/migrating.md +267 -0
  11. data/docs/readme.md +18 -0
  12. data/examples/plugins/custom_prefix.rb +1 -1
  13. data/examples/plugins/dice_roll.rb +38 -0
  14. data/examples/plugins/lambdas.rb +1 -1
  15. data/examples/plugins/memo.rb +16 -10
  16. data/examples/plugins/url_shorten.rb +1 -0
  17. data/lib/cinch.rb +5 -60
  18. data/lib/cinch/ban.rb +13 -7
  19. data/lib/cinch/bot.rb +228 -403
  20. data/lib/cinch/{cache_manager.rb → cached_list.rb} +5 -1
  21. data/lib/cinch/callback.rb +3 -0
  22. data/lib/cinch/channel.rb +119 -195
  23. data/lib/cinch/{channel_manager.rb → channel_list.rb} +6 -3
  24. data/lib/cinch/configuration.rb +73 -0
  25. data/lib/cinch/configuration/bot.rb +47 -0
  26. data/lib/cinch/configuration/dcc.rb +16 -0
  27. data/lib/cinch/configuration/plugins.rb +41 -0
  28. data/lib/cinch/configuration/sasl.rb +17 -0
  29. data/lib/cinch/configuration/ssl.rb +19 -0
  30. data/lib/cinch/configuration/storage.rb +37 -0
  31. data/lib/cinch/configuration/timeouts.rb +14 -0
  32. data/lib/cinch/constants.rb +531 -369
  33. data/lib/cinch/dcc.rb +12 -0
  34. data/lib/cinch/dcc/dccable_object.rb +37 -0
  35. data/lib/cinch/dcc/incoming.rb +1 -0
  36. data/lib/cinch/dcc/incoming/send.rb +131 -0
  37. data/lib/cinch/dcc/outgoing.rb +1 -0
  38. data/lib/cinch/dcc/outgoing/send.rb +115 -0
  39. data/lib/cinch/exceptions.rb +8 -1
  40. data/lib/cinch/formatting.rb +106 -0
  41. data/lib/cinch/handler.rb +104 -0
  42. data/lib/cinch/handler_list.rb +86 -0
  43. data/lib/cinch/helpers.rb +167 -10
  44. data/lib/cinch/irc.rb +525 -110
  45. data/lib/cinch/isupport.rb +11 -9
  46. data/lib/cinch/logger.rb +168 -0
  47. data/lib/cinch/logger/formatted_logger.rb +72 -55
  48. data/lib/cinch/logger/zcbot_logger.rb +9 -24
  49. data/lib/cinch/logger_list.rb +62 -0
  50. data/lib/cinch/mask.rb +19 -10
  51. data/lib/cinch/message.rb +94 -28
  52. data/lib/cinch/message_queue.rb +70 -28
  53. data/lib/cinch/mode_parser.rb +6 -1
  54. data/lib/cinch/network.rb +104 -0
  55. data/lib/cinch/{rubyext/queue.rb → open_ended_queue.rb} +8 -1
  56. data/lib/cinch/pattern.rb +24 -4
  57. data/lib/cinch/plugin.rb +352 -177
  58. data/lib/cinch/plugin_list.rb +35 -0
  59. data/lib/cinch/rubyext/float.rb +3 -0
  60. data/lib/cinch/rubyext/module.rb +7 -0
  61. data/lib/cinch/rubyext/string.rb +9 -0
  62. data/lib/cinch/sasl.rb +34 -0
  63. data/lib/cinch/sasl/dh_blowfish.rb +71 -0
  64. data/lib/cinch/sasl/diffie_hellman.rb +47 -0
  65. data/lib/cinch/sasl/mechanism.rb +6 -0
  66. data/lib/cinch/sasl/plain.rb +26 -0
  67. data/lib/cinch/storage.rb +62 -0
  68. data/lib/cinch/storage/null.rb +12 -0
  69. data/lib/cinch/storage/yaml.rb +96 -0
  70. data/lib/cinch/syncable.rb +13 -1
  71. data/lib/cinch/target.rb +144 -0
  72. data/lib/cinch/timer.rb +145 -0
  73. data/lib/cinch/user.rb +169 -225
  74. data/lib/cinch/{user_manager.rb → user_list.rb} +7 -2
  75. data/lib/cinch/utilities/deprecation.rb +12 -0
  76. data/lib/cinch/utilities/encoding.rb +54 -0
  77. data/lib/cinch/utilities/kernel.rb +13 -0
  78. data/lib/cinch/utilities/string.rb +13 -0
  79. data/lib/cinch/version.rb +4 -0
  80. metadata +88 -47
  81. data/lib/cinch/logger/logger.rb +0 -44
  82. data/lib/cinch/logger/null_logger.rb +0 -18
  83. 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
@@ -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.
@@ -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.
@@ -0,0 +1,5 @@
1
+ # @title Logging
2
+
3
+ TODO explain the logging facilities
4
+
5
+ # Writing your own logger
@@ -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