- Added support for SASL
- Added support for DCC SEND
- Added a fair scheduler for outgoing messages
- Added required plugin options
- Added support for colors/formatting
- Added network discovery
- Added match groups
- Added match options overwriting plugin options
- Added support for actions (/me)
- Added support for broken IRC networks
- Dynamic timers
- Reworked logging facilities
- API improvements
- Helper changes
- Added a Cinch::Target Target class
- Cinch::Constants
- New methods
- Removed/Renamed methods
- Handlers
- The Plugin class
- Channel/Target/User implement Comparable
- Renamed
*Manager
to*List
- New events
Cinch now supports authenticating to services via SASL. For more information check {Cinch::SASL}.
Support for sending and receiving files via DCC has been added to Cinch. Check {Cinch::DCC} for more information.
Cinch always provided sophisticated throttling to avoid getting kicked due to excess flood. One major flaw, however, was that it used a single FIFO for all messages, thus preferring early message targets and penalizing later ones.
Now Cinch uses a round-robin approach, having one queue per message target (channels and users) and one for generic commands.
Plugins can now require specific options to be set. If any of those options are not set, the plugin will automatically refuse being loaded.
This is useful for example for plugins that require API keys to interact with web services.
The new attribute is called {Cinch::Plugin::ClassMethods#required_options required_options}.
Example:
class MyPlugin
include Cinch::Plugin
set :required_options, [:foo, :bar]
# ...
end
# ...
bot.configure do |c|
c.plugins.plugins = [MyPlugin]
c.plugins.options[MyPlugin] = {:foo => 1}
end
# The plugin won't load because the option :bar is not set.
# Instead it will print a warning.
A new {Cinch::Formatting module} and {Cinch::Helpers#Format helper} for adding colors and formatting to messages has been added. See the {Cinch::Formatting module's documentation} for more information on usage.
Cinch now tries to detect the network it connects to, including the running IRCd. For most parts this is only interesting internally, but if you're writing advanced plugins that hook directly into IRC and needs to be aware of available features/quirks, check out {Cinch::IRC#network} and {Cinch::Network}.
The logging API has been drastically improved. Check the {file:logging.md logging documentation} for more information.
A new option for matchers, :group
, allows grouping multiple matchers
to a group. What's special is that in any group, only the first
matching handler will be executed.
Example:
class Foo
include Cinch::Plugin
match /foo (\d+)/, group: :blegh, method: :foo1
match /foo (.+)/, group: :blegh, method: :foo2
match /foo .+/, method: :foo3
def foo1(m, arg)
m.reply "foo1"
end
def foo2(m, arg)
m.reply "foo2"
end
def foo3(m)
m.reply "foo3"
end
end
# 02:05:39 dominikh │ !foo 123
# 02:05:40 cinch │ foo1
# 02:05:40 cinch │ foo3
# 02:05:43 dominikh │ !foo bar
# 02:05:44 cinch │ foo2
# 02:05:44 cinch │ foo3
Matchers now have their own :prefix
, :suffix
and :react_on
options which overwrite plugin options for single matchers.
A new event, {:action
} has been added and can be used for matching
actions as follows:
match "kicks the bot", react_on: :action
def execute(m)
m.reply "Ouch!"
end
The helper methods {Cinch::Helpers#User User()} and {Cinch::Helpers#Channel Channel()} have been extracted from {Cinch::Bot} and moved to {Cinch::Helpers their own module} which can be reused in various places.
Since {Cinch::Channel} and {Cinch::User} share one common interface for sending messages, it only makes sense to have a common base class. {Cinch::Target This new class} takes care of sending messages and removes this responsibility from {Cinch::Channel}, {Cinch::User} and {Cinch::Bot}
All constants for IRC numeric replies (RPL_*
and ERR_*
) have been
moved from {Cinch} to {Cinch::Constants}
- {Cinch::Bot#channel_list}
- {Cinch::Bot#handlers}
- {Cinch::Bot#loggers}
- {Cinch::Bot#loggers=}
- {Cinch::Bot#modes}
- {Cinch::Bot#modes=}
- {Cinch::Bot#set_mode}
- {Cinch::Bot#stop}
- {Cinch::Bot#unset_mode}
- {Cinch::Bot#user_list}
- {Cinch::Channel#admins}
- {Cinch::Channel#half_ops}
- {Cinch::Channel#ops}
- {Cinch::Channel#owners}
- {Cinch::Channel#voiced}
- {Cinch::Helpers#Target} -- For creating a {Cinch::Target Target} which can receive messages
- {Cinch::Helpers#Timer} -- For creating new timers anywhere
- {Cinch::Helpers#rescue_exception} -- For rescueing and automatically logging an exception
- {Cinch::Helpers#Format} -- For adding colors and formatting to messages
- {Cinch::Helpers#debug}
- {Cinch::Helpers#error}
- {Cinch::Helpers#exception}
- {Cinch::Helpers#fatal}
- {Cinch::Helpers#incoming}
- {Cinch::Helpers#info}
- {Cinch::Helpers#log}
- {Cinch::Helpers#outgoing}
- {Cinch::Helpers#warn}
- {Cinch::IRC#network}
- {Cinch::Message#action?}
- {Cinch::Message#action_message}
- {Cinch::Message#target}
- {Cinch::Message#time}
- {Cinch::Plugin#handlers}
- {Cinch::Plugin#storage}
- {Cinch::Plugin#timers}
- {Cinch::Plugin#unregister}
- {Cinch::User#away}
- {Cinch::User#dcc_send} - See {Cinch::DCC::Outgoing::Send}
- {Cinch::User#match}
- {Cinch::User#monitor} - See {file:common_tasks.md#checking-if-a-user-is-online Checking if a user is online}
- {Cinch::User#monitored}
- {Cinch::User#online?}
- {Cinch::User#unmonitor}
Internally, Cinch uses {Cinch::Handler Handlers} for listening to and matching events. In previous versions, this was hidden from the user, but now they're part of the public API, providing valuable information and the chance to {Cinch::Handler#unregister unregister handlers} alltogether.
{Cinch::Bot#on} now returns the created handler and {Cinch::Plugin#handlers} allows getting a plugin's registered handlers.
The following methods have been removed:
| Removed method | Replacement |
|----------------------------------------+---------------------------------------------------------------------------------|
| Cinch::Bot#halt | next
or break
(Ruby keywords) |
| Cinch::Bot#raw | {Cinch::IRC#send} |
| Cinch::Bot#msg | {Cinch::Target#msg} |
| Cinch::Bot#notice | {Cinch::Target#notice} |
| Cinch::Bot#safe_msg | {Cinch::Target#safe_msg} |
| Cinch::Bot#safe_notice | {Cinch::Target#safe_notice} |
| Cinch::Bot#action | {Cinch::Target#action} |
| Cinch::Bot#safe_action | {Cinch::Target#safe_action} |
| Cinch::Bot#dispatch | {Cinch::HandlerList#dispatch} |
| Cinch::Bot#register_plugins | {Cinch::PluginList#register_plugins} |
| Cinch::Bot#register_plugin | {Cinch::PluginList#register_plugin} |
| Cinch::Bot#logger | {Cinch::Bot#loggers} |
| Cinch::Bot#logger= | |
| Cinch::Bot#debug | {Cinch::LoggerList#debug} |
| Cinch::IRC#message | {Cinch::IRC#send} |
| Cinch::Logger::Logger#log_exception | {Cinch::Logger#exception} |
| Class methods in Plugin to set options | A new {Cinch::Plugin::ClassMethods#set set} method as well as attribute setters |
The {Cinch::Plugin Plugin} class has been drastically improved to look and behave more like a proper Ruby class instead of being some abstract black box.
All attributes of a plugin (name, help message, matchers, …) are being made available via attribute getters and setters. Furthermore, it is possible to access a Plugin instance's registered handlers and timers, as well as unregister plugins.
For a complete overview of available attributes and methods, see {Cinch::Plugin} and {Cinch::Plugin::ClassMethods}.
The aforementioned changes also affect the way plugin options are
being set: Plugin options aren't set with DSL-like methods anymore but
instead are made available via {Cinch::Plugin::ClassMethods#set a
set
method} or alternatively plain attribute setters.
See {file:migrating.md#plugin-options the migration guide} for more information.
{Cinch::Target} and thus {Cinch::Channel} and {Cinch::User} now implement the Comparable interface, which makes them sortable by all usual Ruby means.
Cinch::ChannelManager
and Cinch::UserManager
have been renamed to
{Cinch::ChannelList} and {Cinch::UserList} respectively.
Special support for the following flawed IRC networks has been added:
- JustinTV
- NGameTV
- IRCnet
It is now possible to create new timers from any method/handler. It is also possible to {Cinch::Timer#stop stop existing timers} or {Cinch::Timer#start restart them}.
The easiest way of creating new timers is by using the {Cinch::Helpers#Timer Timer helper method}, even though it is also possible, albeit more complex, to create instances of {Cinch::Timer} directly.
Example:
match /remind me in (\d+) seconds/
def execute(m, seconds)
Timer(seconds.to_i, shots: 1) do
m.reply "This is your reminder.", true
end
end
For more information on timers, see the {Cinch::Timer Timer documentation}.
- :{file:bot_options.md#dccownip dcc.own_ip}
- :{file:bot_options.md#modes modes}
- :{file:bot_options.md#maxreconnectdelay max_reconnect_delay}
- :{file:bot_options.md#localhost local_host}
- :{file:bot_options.md#delayjoins delay_joins}
- :{file:bot_options.md#saslusername sasl.username}
- :{file:bot_options.md#saslpassword sasl.password}
- :{file:events.md#action action}
- :{file:events.md#away away}
- :{file:events.md#unaway unaway}
- :{file:events.md#dccsend dcc_send}
- :{file:events.md#owner owner}
- :{file:events.md#dehalfop-deop-deowner-devoice deowner}
- :{file:events.md#leaving leaving}
- :{file:events.md#online online}
- :{file:events.md#offline offline}
- New events
- New methods
- New options
- Improved logger x. Deprecated methods
- :{file:events.md#op op}
- :{file:events.md#dehalfop-deop-deowner-devoice deop}
- :{file:events.md#voice voice}
- :{file:events.md#dehalfop-deop-deowner-devoice devoice}
- :{file:events.md#halfop halfop}
- :{file:events.md#dehalfop-deop-deowner-devoice dehalfop}
- :{file:events.md#ban ban}
- :{file:events.md#unban unban}
- :{file:events.md#modechange mode_change}
- :{file:events.md#catchall catchall}
Additionally, plugins are now able to send their own events by using Cinch::Bot#dispatch.
Stores the last nick of a user. This can for example be used in on :nick
to compare a user's old nick against the new one.
For sending notices.
Provides a nicer representation of {Cinch::Message} objects.
Provides an easier way of checking if a given user is in a channel
- {file:bot_options.md#pluginssuffix plugins.suffix}
- {file:bot_options.md#ssluse ssl.use}
- {file:bot_options.md#sslverify ssl.verify}
- {file:bot_options.md#sslcapath ssl.ca_path}
- {file:bot_options.md#sslclientcert ssl.client_cert}
- {file:bot_options.md#nicks nicks}
- {file:bot_options.md#timeoutsread timeouts.read}
- {file:bot_options.md#timeoutsconnect timeouts.connect}
- {file:bot_options.md#pinginterval ping_interval}
- {file:bot_options.md#reconnect reconnect}
The {Cinch::Logger::FormattedLogger formatted logger} (which is the default one) now contains timestamps. Furthermore, it won't emit color codes if not writing to a TTY.
Additionally, it can now log any kind of object, not only strings.
| Deprecated method | Replacement | |-----------------------------+------------------------------------| | Cinch::User.find_ensured | Cinch::UserManager#find_ensured | | Cinch::User.find | Cinch::UserManager#find | | Cinch::User.all | Cinch::UserManager#each | | Cinch::Channel.find_ensured | Cinch::ChannelManager#find_ensured | | Cinch::Channel.find | Cinch::ChannelManager#find | | Cinch::Channel.all | Cinch::ChannelManager#each |