ircinch 2.4.0

data/docs/changes.md

@@ -0,0 +1,541 @@
+# @title What has changed?
+# @markup kramdown
+
+# What has changed in 2.2?
+
+## Getting rid of CP1252 in favour of UTF-8
+
+In versions before 2.2, when using the `irc` encoding (the default),
+Cinch would use CP1252 for outgoing messages, only falling back to
+UTF-8 if a message wouldn't fit into CP1252. This is a so called
+hybrid encoding, which is used by X-Chat and the like.
+
+This encoding, however, is based on the state of 10 years ago, where
+the most popular IRC clients, such as mIRC, weren't capable of
+handling UTF-8. Nowadays, there are more clients that support UTF-8
+than there are clients that can deal with this hybrid encoding, or
+CP1252 itself. That's why, from now on, we will always use UTF-8.
+
+If you depend on outgoing messages being encoded in CP1252, please see
+{file:docs/encodings.md} on how to change the encoding.
+
+## API improvements
+
+### New methods
+
+- {Cinch::Channel#remove} has been added to support the non-standard
+REMOVE command, a friendlier alternative to kicking people.
+
+- {Cinch::Helpers.sanitize} and {Cinch::Formatting.unformat} have been
+  added to help with removing unprintable characters and mIRC
+  formatting codes from strings.
+
+### Deprecated methods
+
+In order to reduce the amount of aliases, the following ones have been
+deprecated and will be removed in a future release:
+
+- {Cinch::Channel#msg}
+- {Cinch::Channel#privmsg}
+- {Cinch::Target#msg}
+- {Cinch::Target#privmsg}
+- {Cinch::Target#safe_msg}
+- {Cinch::Target#safe_privmsg}
+- {Cinch::User#whois}
+- {Cinch::Helpers#Color}
+
+Additionally, the following method is deprecated and will be removed
+in the future:
+
+- {Cinch::Channel#to_str}
+
+# What has changed in 2.1?
+1. Color stripping
+1. Per group hooks
+1. API improvements
+   1. New methods
+   1. Changed methods
+   1. New aliases
+
+## Color stripping
+
+The new method <del>`Cinch::Utilities::String.strip_colors`</del>
+{Cinch::Formatting.unformat} allows removal of mIRC color codes from
+messages.
+
+Additionally, a new match option called `strip_colors` makes it
+possible to automatically and temporarily strip color codes before
+attempting to match a message.
+
+## Per group hooks
+
+A new option `group` for hooks allows registering hooks for specific
+groups.
+
+## API improvements
+
+### New methods
+
+#### {Cinch::Bot}
+
+- {Cinch::Bot#oper}
+
+#### {Cinch::User}
+
+- {Cinch::User#oper?}
+
+#### {Cinch::Message}
+
+- {Cinch::Message#action_reply}
+- {Cinch::Message#safe_action_reply}
+
+### Changed methods
+
+#### {Cinch::Handler}
+
+- {Cinch::Handler#call} now returns the started thread.
+
+#### {Cinch::HandlerList}
+
+- {Cinch::HandlerList#dispatch} now returns the started threads.
+
+### New aliases
+
+Due to some unfortunate naming mistakes in Cinch 2.0, Cinch 2.1 adds
+several aliases. All of the new aliases deprecate the original method
+names, which will be removed in Cinch 3.0.
+
+#### {Cinch::User}
+- {Cinch::User#monitored?} for {Cinch::User#monitored}
+- {Cinch::User#synced?} for {Cinch::User#synced}
+
+
+
+# What has changed in 2.0?
+1. Added support for SASL
+1. Added support for DCC SEND
+1. Added a fair scheduler for outgoing messages
+1. Added required plugin options
+1. Added support for colors/formatting
+1. Added network discovery
+1. Added match groups
+1. Added match options overwriting plugin options
+1. Added support for actions (/me)
+1. Added support for broken IRC networks
+1. Dynamic timers
+1. Reworked logging facilities
+1. API improvements
+   1. Helper changes
+   1. Added a Cinch::Target Target class
+   1. Cinch::Constants
+   1. New methods
+   1. Removed/Renamed methods
+   1. Handlers
+   1. The Plugin class
+   1. Channel/Target/User implement Comparable
+   1. Renamed `*Manager` to `*List`
+1. New events
+
+## Added support for SASL
+
+Cinch now supports authenticating to services via SASL. For more
+information check {Cinch::SASL}.
+
+## Added support for DCC SEND
+
+Support for sending and receiving files via DCC has been added to
+Cinch. Check {Cinch::DCC} for more information.
+
+## Added a fair scheduler for outgoing messages
+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.
+
+## Added required plugin options
+
+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.
+
+## Added support for colors/formatting
+
+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.
+
+## Added support for network discovery
+
+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}.
+
+## Reworked logging facilities
+
+The logging API has been drastically improved. Check the
+{file:docs/logging.md logging documentation} for more information.
+
+
+## Added match groups
+
+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
+
+
+## Added match options overwriting plugin options
+
+Matchers now have their own `:prefix`, `:suffix` and `:react_on`
+options which overwrite plugin options for single matchers.
+
+
+## Added support for actions (/me)
+
+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
+
+## API improvements
+
+### Helper changes
+
+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.
+
+### Added a {Cinch::Target Target} class
+
+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}
+
+### {Cinch::Constants}
+
+All constants for IRC numeric replies (`RPL_*` and `ERR_*`) have been
+moved from {Cinch} to {Cinch::Constants}
+
+### New methods
+
+#### {Cinch::Bot}
+
+- {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#unset_mode}
+- {Cinch::Bot#user_list}
+
+#### {Cinch::Channel}
+
+- {Cinch::Channel#admins}
+- {Cinch::Channel#half_ops}
+- {Cinch::Channel#ops}
+- {Cinch::Channel#owners}
+- {Cinch::Channel#voiced}
+
+#### {Cinch::Helpers}
+
+- {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
+
+##### Logging shortcuts
+- {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}
+
+- {Cinch::IRC#network}
+
+#### {Cinch::Message}
+
+- {Cinch::Message#action?}
+- {Cinch::Message#action_message}
+- {Cinch::Message#target}
+- {Cinch::Message#time}
+
+#### {Cinch::Plugin}
+
+- {Cinch::Plugin#handlers}
+- {Cinch::Plugin#timers}
+- {Cinch::Plugin#unregister}
+
+#### {Cinch::User}
+
+- {Cinch::User#away}
+- {Cinch::User#dcc_send} - See {Cinch::DCC::Outgoing::Send}
+- {Cinch::User#match}
+- {Cinch::User#monitor} - See {file:docs/common_tasks.md#checking-if-a-user-is-online Checking if a user is online}
+- {Cinch::User#monitored}
+- {Cinch::User#online?}
+- {Cinch::User#unmonitor}
+
+### Handlers
+
+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.
+
+### Removed/Renamed methods
+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 Plugin class
+
+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}.
+
+### Plugin options
+
+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:docs/migrating.md#plugin-options the migration guide} for more
+information.
+
+### Channel/Target/User implement Comparable
+
+{Cinch::Target} and thus {Cinch::Channel} and {Cinch::User} now
+implement the Comparable interface, which makes them sortable by all
+usual Ruby means.
+
+### Renamed `*Manager` to `*List`
+
+`Cinch::ChannelManager` and `Cinch::UserManager` have been renamed to
+{Cinch::ChannelList} and {Cinch::UserList} respectively.
+
+## Added support for broken IRC networks
+Special support for the following flawed IRC networks has been added:
+
+- JustinTV
+- NGameTV
+- IRCnet
+
+## Dynamic timers
+
+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}.
+
+## New options
+
+- :{file:docs/bot_options.md#dccownip dcc.own_ip}
+- :{file:docs/bot_options.md#modes modes}
+- :{file:docs/bot_options.md#maxreconnectdelay max_reconnect_delay}
+- :{file:docs/bot_options.md#localhost local_host}
+- :{file:docs/bot_options.md#delayjoins delay_joins}
+- :{file:docs/bot_options.md#saslusername sasl.username}
+- :{file:docs/bot_options.md#saslpassword sasl.password}
+
+## New events
+- :{file:docs/events.md#action action}
+- :{file:docs/events.md#away away}
+- :{file:docs/events.md#unaway unaway}
+- :{file:docs/events.md#dccsend dcc_send}
+- :{file:docs/events.md#owner owner}
+- :{file:docs/events.md#dehalfop-deop-deowner-devoice deowner}
+- :{file:docs/events.md#leaving leaving}
+- :{file:docs/events.md#online online}
+- :{file:docs/events.md#offline offline}
+
+
+# What has changed in 1.1?
+1. **New events**
+2. **New methods**
+3. **New options**
+4. **Improved logger**
+x. **Deprecated methods**
+
+## New events
+
+- :{file:docs/events.md#op op}
+- :{file:docs/events.md#dehalfop-deop-deowner-devoice deop}
+- :{file:docs/events.md#voice voice}
+- :{file:docs/events.md#dehalfop-deop-deowner-devoice devoice}
+- :{file:docs/events.md#halfop halfop}
+- :{file:docs/events.md#dehalfop-deop-deowner-devoice dehalfop}
+- :{file:docs/events.md#ban ban}
+- :{file:docs/events.md#unban unban}
+- :{file:docs/events.md#modechange mode_change}
+- :{file:docs/events.md#catchall catchall}
+
+Additionally, plugins are now able to send their own events by using
+Cinch::Bot#dispatch.
+
+## New methods
+
+### {Cinch::User#last_nick}
+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.
+
+### Cinch::User#notice, Cinch::Channel#notice and Cinch::Bot#notice
+For sending notices.
+
+### {Cinch::Message#to_s}
+Provides a nicer representation of {Cinch::Message} objects.
+
+### {Cinch::Channel#has_user?}
+Provides an easier way of checking if a given user is in a channel
+
+## New options
+- {file:docs/bot_options.md#pluginssuffix plugins.suffix}
+- {file:docs/bot_options.md#ssluse ssl.use}
+- {file:docs/bot_options.md#sslverify ssl.verify}
+- {file:docs/bot_options.md#sslcapath ssl.ca_path}
+- {file:docs/bot_options.md#sslclientcert ssl.client_cert}
+- {file:docs/bot_options.md#nicks nicks}
+- {file:docs/bot_options.md#timeoutsread timeouts.read}
+- {file:docs/bot_options.md#timeoutsconnect timeouts.connect}
+- {file:docs/bot_options.md#pinginterval ping_interval}
+- {file:docs/bot_options.md#reconnect reconnect}
+
+
+
+## Improved logger
+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 methods
+
+| 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         |

data/docs/common_mistakes.md

@@ -0,0 +1,60 @@
+# @title Common mistakes
+# @markup kramdown
+
+# I defined an initialize method in my plugin and now it doesn't work properly anymore
+
+Cinch requires plugins to set certain states for them to work
+properly. This is done by the initialize method of the Plugin module.
+If you define your own initializer, make sure to accept an arbitrary
+number of arguments (`*args`) and to call `super` as soon as possible.
+
+## Example
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      def initialize(*args)
+        super
+        my own stuff here
+      end
+    end
+
+
+# I am trying to use plugin options, but Ruby says it cannot find the `config` method
+
+A common mistake is to try and use plugin options on class level, for example to manipulate matches. This cannot work because the class itself is not connected to any bot. Plugin options only work in instance methods of plugins.
+
+The following is not possible:
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      match(config[:pattern])
+      def execute(m)
+        # ...
+      end
+    end
+
+# My handlers won't run, even though the Regexp matches.
+
+Cinch plugins have a default prefix (`/^!/`). This allows for flexible prefixes
+across the whole bot. The default prefix can be changed in `Bot#configure`:
+
+    x = Cinch::Bot.new do
+      configure do |c|
+        # ...
+        c.plugins.prefix = /^%/
+      end
+    end
+
+Alternatively, you can set the prefix for specific plugins only, by calling `set`:
+
+    class MyPlygin
+      include Cinch::Plugin
+
+      set :prefix, /^%/
+    end
+
+You can also choose to not use a prefix for specific matchers:
+
+    match /hi/, use_prefix: false

data/docs/common_tasks.md

@@ -0,0 +1,57 @@
+# @title Common Tasks
+# @markup kramdown
+
+# Checking if a user is online
+
+Cinch by itself tries to keep track of the online state of users.
+Whenever it sees someone speak, change their nick or be in a channel the
+bot is also in, it'll set the user to being online. And when a user
+quits, gets killed or cannot be whoised/contacted, its state will be
+set to offline.
+
+A problem with that information is that it can quickly become out of
+sync. Consider the following example:
+
+The bot joins a channel, sees someone in the name list and thus marks
+him as online. The bot then leaves the channel and at some later
+point, the user disconnects. The bot won't know that and still track
+the user as online.
+
+If (near-)realtime information about this state is required, one can
+use {Cinch::User#monitor} to automatically monitor the state.
+{Cinch::User#monitor #monitor} uses either the _MONITOR_ feature of modern IRCds or, if
+that's not available, periodically runs _WHOIS_ to update the
+information.
+
+Whenever a user's state changes, either the `:online` or the
+`:offline` event will be fired, as can be seen in the following
+example:
+
+    class SomePlugin
+      include Cinch::Plugin
+
+      listen_to :connect, method: :on_connect
+      listen_to :online,  method: :on_online
+      listen_to :offline, method: :on_offline
+
+      def on_connect(m)
+        User("my_master").monitor
+      end
+
+      def on_online(m, user)
+        user.send "Hello master"
+      end
+
+      def on_offline(m, user)
+        @bot.loggers.info "I miss my master :("
+      end
+    end
+
+# Sending messages to users and channels beside `m.user` and `m.channel`
+
+Cinch provides {Cinch::Helpers helper methods} to get instances of Channel
+and User objects that you can work with:
+
+    User('user').send("Hello!")        # Sends a message to user 'user'
+    Channel('#channel').send("Hello!") # Sends a message to channel '#channel'
+