cinch 1.1.3 → 2.0.0.pre.1

data/docs/common_tasks.md

@@ -0,0 +1,47 @@
+# @title Common Tasks
+
+# 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 his 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

data/docs/encodings.md

@@ -0,0 +1,67 @@
+# @title Encodings
+# Encodings
+
+The IRC protocol doesn't define a specific encoding that should be
+used, nor does it provide any information on which encodings _are_
+being used.
+
+At the same time, lots of different encodings have become popular on
+IRC. This presents a big problem, because, if you're using a different
+encoding than someone else on IRC, you'll receive their text as
+garbage.
+
+Cinch tries to work around this issue in two ways, while also keeping
+the usual Ruby behaviour.
+
+## The `encoding` option
+By setting {file:bot_options.md#encoding the `encoding` option}, you
+set your expectations on what encoding other users will use. Allowed
+values are instances of Encoding, names of valid encodings (as
+strings) and the special `:irc` encoding, which will be explained
+further down.
+
+
+## Encoding.default_internal
+If set, Cinch will automatically convert incoming messages to the
+encoding defined by `Encoding.default_internal`, unless the special
+encoding `:irc` is being used as the {file:bot_options.md#encoding
+`encoding option`}
+
+## The `:irc` encoding
+As mentioned earlier, people couldn't decide on a single encoding to
+use. As such, specifying a single encoding would most likely lead to
+problems, especially if the bot is in more than one channel.
+
+Luckily, even though people cannot decide on a single encoding,
+western countries usually either use CP1252 (Windows Latin-1) or
+UTF-8. Since text encoded in CP1252 fails validation as UTF-8, it is
+easy to tell the two apart. Additionally it is possible to losslessly
+re-encode CP1252 in UTF-8 and as such, a small subset of UTF-8 is also
+representable in CP1252.
+
+If incoming text is valid UTF-8, it will be interpreted as such. If it
+fails validation, a CP1252 → UTF-8 conversion is performed. This
+ensures that you will always deal with UTF-8 in your code, even if
+other people use CP1252. Note, however, that we ignore
+`Encoding.default_internal` in this case and always present you with
+UTF-8.
+
+If text you send contains only characters that fit inside the
+CP1252 code page, the entire line will be sent that way.
+
+If the text doesn't fit inside the CP1252 code page, (for example if
+you type Eastern European characters, or Russian) it will be sent as
+UTF-8. Only UTF-8 capable clients will be able to see these characters
+correctly.
+
+## Invalid bytes and unsupported translations
+If Cinch receives text in an encoding other than the one assumed, it
+can happen that the message contains bytes that are not valid in the
+assumed encoding. Instead of dropping the complete message, Cinch will
+replace offending bytes with question marks.
+
+Also, if you expect messages in e.g. UTF-8 but re-encode them in
+CP1252 (by setting `Encoding.default_internal` to CP1252), it can
+happen that some characters cannot be represented in CP1252. In such a
+case, Cinch will too replace the offending characters with question
+marks.

data/docs/events.md

@@ -0,0 +1,272 @@
+# @title Events
+
+Cinch provides three kinds of events:
+
+1. Events mapping directly to IRC commands
+
+   For example `:topic`, which will be triggered when someone changes
+   the topic, or `:kick`, when someone gets kicked.
+
+2. Events mapping directly to IRC numeric codes
+
+   For example `:"401"` for `ERR_NOSUCHNICK`, which is triggered when
+   trying to operate on an unknown nickname, or `:"318"` for
+   `RPL_ENDOFWHOIS`, which is triggered after whois information have
+   been received.
+
+3. Events mapping to more abstract ideas
+
+   For example `:leaving` whenever a user parts, quits or gets
+   kicked/killed or `:message`, which is actually a synonym for
+   `:privmsg`, the underlying IRC command.
+
+# Events of the first two kinds
+
+All events of the first two kinds behave exactly the same: When they
+get triggered, the handler will be passed a single object, a reference
+to the {Cinch::Message Message object}.
+
+Example:
+
+    on :topic do |m|
+      # m is the message object
+    end
+
+We will not further describe all possible events of the first two
+categories.
+
+# Events of the third kind
+
+Events of the third kind can each have different signatures, as they
+get passed objects directly relating to their kind, for example the
+leaving user in case of `:leaving`. This document will describe all
+events of that kind, their signature and example usage.
+
+**Note: Because *all* handlers receive a {Cinch::Message Message}
+  object as the first argument, we will only mention and describe
+  additional arguments.**
+
+## `:action`
+
+The `:action` event is triggered when a user sends a CTCP ACTION to a
+channel or the bot. CTCP ACTION is commonly refered to simply as
+"actions" or "/me's", because that is the command used in most IRC
+clients.
+
+Example:
+
+    on :action, "kicks the bot" do |m|
+      m.reply "Ouch! Stop kicking me :(", true
+    end
+
+
+## `:away`
+
+The `:away` event is triggered when a user goes away. This feature
+only works on networks implementing the "away-notify" extension.
+
+Example:
+
+    on :away do |m|
+      debug("User %s just went away: %s" % [m.user, m.message])
+    end
+
+See also {file:events.md#unaway the `:unaway` event}.
+
+
+## `:ban`
+
+The `:ban` event is triggered when a user gets banned in a channel.
+
+One additional argument, a {Cinch::Ban Ban object}, gets passed to
+the handler.
+
+Example:
+
+    on :ban do |m, ban|
+      debug("%s just banned %s" % [ban.by, ban.mask])
+    end
+
+See also {file:events.md#unban the `:unban` event}.
+
+
+## `:catchall`
+
+`:catchall` is a special event that gets triggered for every incoming
+IRC message/command, no matter what the type is.
+
+
+## `:channel`
+
+The `:channel` event is triggered for channel messages (the usual
+form of communication on IRC).
+
+See also {file:events.md#private the `:private` event}.
+
+
+## `:connect`
+
+The `:connect` event is triggered after the bot successfully
+connected to the IRC server.
+
+One common use case for this event is setting up variables,
+synchronising information etc.
+
+
+## `:ctcp`
+
+The `:ctcp` event is triggered when receiving CTCP-related messages,
+for example the VERSION request.
+
+
+## `:dcc_send`
+
+`:dcc_send` gets triggered when a user tries to send a file to the
+bot, using the DCC SEND protocol.
+
+One additional argument, a {Cinch::DCC::Incoming::Send DCC::Send
+object}, gets passed to the handler.
+
+For example usage and a general explanation of DCC in Cinch check
+{Cinch::DCC::Incoming::Send}.
+
+
+## `:dehalfop`, `:deop`, `:deowner`, `:devoice`
+
+These events get triggered for the respective channel operations of
+taking halfop, op, owner and voice from a user.
+
+One additional argument, the user whose rights are being modifed, gets
+passed to the handler.
+
+
+## `:error`
+
+`:error` gets triggered for all numeric replies that signify errors
+(`ERR_*`).
+
+
+## `:halfop`
+
+This event gets triggered when a user in a channel gets half-opped.
+
+One additional argument, the user being half-opped, gets passed to the
+handler.
+
+
+## `:leaving`
+
+`:leaving` is an event that is triggered whenever any of the following
+are triggered as well: `:part`, `:quit`, `:kick`, `:kill`.
+
+The event can thus be used for noticing when a user leaves a channel
+or the network, no matter the reason.
+
+One additional argument, the leaving user, gets passed to the handler.
+
+Be careful not to confuse the additional argument with
+{Cinch::Message#user}. For example in the case of a kick,
+{Cinch::Message#user} will describe the user kicking someone, not the
+one who is being kicked.
+
+Example:
+
+    on :leaving do |m, user|
+      if m.channel?
+        debug("%s just left %s." % [user, m.channel])
+      else
+        debug("%s just left the network." % user)
+      end
+    end
+
+
+
+## `:mode_change`
+
+This event gets triggered whenever modes in a channel or on the bot
+directly change. Unlike events like `:op`, this event is more
+low-level, as the argument the handler gets passed is an array
+describing every change.
+
+
+## `:offline`
+
+This event is triggered when a
+{file:common_tasks.md#checking-if-a-user-is-online monitored user}
+goes offline.
+
+One additional argument, the user going offline, gets passed to the
+handler.
+
+
+## `:online`
+
+This event is triggered when a
+{file:common_tasks.md#checking-if-a-user-is-online monitored user}
+comes online.
+
+One additional argument, the user coming online, gets passed to the
+handler.
+
+
+## `:op`
+
+This event gets triggered when a user in a channel gets opped.
+
+One additional argument, the user being opped, gets passed to the
+handler.
+
+
+## `:owner`
+
+
+This event gets triggered when a user in a channel receives
+owner-status.
+
+One additional argument, the user receiving owner-status, gets passed
+to the handler.
+
+
+## `:message`
+
+The `:message` event is triggered for messages directed at either a
+channel or directly at the bot. It's synonymous with `:privmsg`.
+
+
+## `:private`
+
+The `:private` event is triggered for messages directly towarded at
+the bot (think /query in traditional IRC clients).
+
+See also {file:events.md#channel the `:channel` event}.
+
+
+## `:unaway`
+
+The `:unaway` event is triggered when a user no longer is away. This
+feature only works on networks implementing the "away-notify"
+extension.
+
+Example:
+
+    on :unaway do |m|
+      debug("User %s no longer is away." % m.user)
+    end
+
+See also {file:events.md#away the `:away` event}.
+
+
+## `:unban`
+
+The `:unban` event is triggered when a user gets unbanned in a
+channel.
+
+One additional argument, a {Cinch::Ban Ban object}, gets passed to the
+handler.
+
+
+## `:voice`
+This event gets triggered when a user in a channel gets voiced.
+
+One additional argument, the user being voiced, gets passed to the
+handler.

data/docs/logging.md

@@ -0,0 +1,5 @@
+# @title Logging
+
+TODO explain the logging facilities
+
+# Writing your own logger

data/docs/migrating.md

@@ -0,0 +1,267 @@
+# @title Migration Guide
+# Migration Guide
+
+This document explains how to migrate between API incompatible
+versions of Cinch.
+
+## Migrating from 1.x to 2.x
+
+## Plugins
+
+### New methods
+
+Plugins have the following (new) instance and class methods, which you
+shouldn't and usually mustn't overwrite:
+
+- `#bot`
+- `#config`
+- `#handlers`
+- `#storage`
+- `#synchronize`
+- `#timers`
+- `#unregister`
+- `::call_hooks`
+- `::check_for_missing_options`
+- `::ctcp`
+- `::ctcps`
+- `::help=`
+- `::help`
+- `::hook`
+- `::hooks`
+- `::listen_to`
+- `::listeners`
+- `::match`
+- `::matchers`
+- `::plugin_name=`
+- `::plugin_name`
+- `::prefix=`
+- `::prefix`
+- `::react_on`
+- `::reacting_on=`
+- `::reacting_on`
+- `::required_options=`
+- `::required_options`
+- `::set`
+- `::suffix=`
+- `::suffix`
+- `::timer`
+- `::timers`
+
+Note: The list does also include methods from prior versions.
+
+
+### Plugin options
+
+Previously, plugins used a DSL-like way of setting options like the
+plugin prefix. This contradicts with the general idea of plugins being
+ordinary Ruby classes and also caused a lot of code and documentation
+smell.
+
+Instead of having methods like `#prefix` double as both attribute
+getter and setter, options can now be set in two different ways: Using
+ordinary attribute setters or using the
+{Cinch::Plugin::ClassMethods#set #set} method.
+
+#### Cinch 1.x
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      prefix /^!/
+      help "some help message"
+      match /foo/
+      def execute(m)
+        # ...
+      end
+    end
+
+#### Cinch 2.x, attribute setters
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      self.prefix = /^!/
+      self.help   = "some help message"
+      match /foo/
+      def execute(m)
+        # ...
+      end
+    end
+
+#### Cinch 2.x, `#set` method
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      set :prefix, /^!/
+      set :help,   "some help message"
+      match /foo/
+      def execute(m)
+        # ...
+      end
+    end
+
+#### Cinch 2.x, `#set` method, alternative syntax
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      set prefix: /^!/,
+          help:   "some help message"
+      match /foo/
+      def execute(m)
+        # ...
+      end
+    end
+
+
+### No more automatic matcher with the plugin's name
+
+Cinch does not add a default matcher with the plugin's name anymore.
+If you've been relying on the following to work
+
+    class Footastic
+      include Cinch::Plugin
+
+      def execute(m)
+        # this will triger on "!footastic"
+      end
+    end
+
+you will have to rewrite it using an explicit matcher:
+
+    class Footastic
+      include Cinch::Plugin
+
+      match "footastic"
+      def execute(m)
+        # ...
+      end
+    end
+
+### No more default `#execute` and `#listen` methods
+
+Plugins do not come with default `#execute` and `#listen` methods
+anymore, which means that specifying a matcher or listener without
+providing the required methods will always result in an exception.
+
+### Programmatically registering plugins
+
+If you're using the API to register plugins on your own, you will have
+to use the new {Cinch::PluginList} class and its methods, instead of
+using `Cinch::Bot#register_plugin` or `Cinch::Bot#register_plugins`,
+which have been removed.
+
+The PluginList instance is available via {Cinch::Bot#plugins}.
+
+## Logging
+
+Logging in Cinch 2.x has been greatly improved. Instead of only
+supporting one logger and having all logging-relevant methods in
+{Cinch::Bot}, we've introduced the {Cinch::LoggerList} class, which
+manages an infinite number of loggers. Included with Cinch are the
+{Cinch::Logger::FormattedLogger formatted logger}, known from Cinch
+1.x, and a new {Cinch::Logger::ZcbotLogger Zcbot logger}, a logger
+emulating the log output of Zcbot, a format which can be parsed by
+{http://pisg.sourceforge.net/ pisg}.
+
+### Log levels
+
+The old `@config.verbose` option has been replaced with a finely
+tunable log level system. Each logger has {Cinch::Logger#level its own
+level}, but it is also possible to {Cinch::LoggerList#level= set the
+level for all loggers at once}.
+
+The available levels, in ascending order of verbosity, are:
+
+- fatal
+- error
+- warn
+- info
+- log
+- debug
+
+### Methods
+
+All logging related methods (`Cinch::Bot#debug` et al) have been
+removed from the Bot class and instead moved to the loggers and the
+{Cinch::LoggerList LoggerList}. If you want to log messages from your
+plugins or handlers, you should use {Cinch::Bot#loggers} to access the
+{Cinch::LoggerList LoggerList} and then call the right methods on
+that. Alterntively you can also use the logging-related helper methods
+provided by {Cinch::Helpers}.
+
+For more information on the logging architecture as well as examples
+on how to use it, check the {file:logging.md Logging readme}.
+
+## Prefix/suffix + string semantics
+
+Behaviour of string prefixes and suffixes has been adapted to match
+that of matchers.
+
+That means that if the prefix or suffix are strings, the ^ or $ anchor
+will be prepended/appened.
+
+## Hooks and their return value
+
+Hooks now behave as filters. If a hook returns `false`, the message
+will not further be processed in a particular plugin.
+
+## Constants
+
+All constants for numeric replies (e.g. `RPL_INFO`) have been moved from
+{Cinch} to {Cinch::Constants}. Thus `Cinch::RPL_INFO` becomes
+{Cinch::Constants::RPL_INFO}, same for all other numeric constants.
+
+## Bot configuration
+
+Bot configuration now uses {Cinch::Configuration special classes}
+instead of OpenStructs. Thus, assignments like
+
+    configure do |c|
+      c.timeouts = OpenStruct.new({:read => 240, :connect => 10})
+    end
+
+are not possible anymore and have to be written as either
+
+    configure do |c|
+      c.timeouts.read    = 240
+      c.timeouts.connect = 10
+    end
+
+or
+
+    configure do |c|
+      c.timeouts.load({:read => 240, :connect => 10})
+    end
+
+The second version is especially interesting to tools like
+{https://github.com/netfeed/cinchize Cinchize}, which load the
+configuration from a YAML file. For more information see
+{file:bot_options.md Bot options}.
+
+
+## Various removed methods
+
+See {file:changes.md#removedrenamed-methods What's changed}
+
+
+## `on`-handlers now only accepts one pattern
+
+In previous versions, {Cinch::Bot#on} accepted a variable amount of patterns
+to match against. This feature was rarely used and has hence been
+removed. If you've been using constructs like
+
+    on :message, [/this/, /that/] do |m|
+      # ...
+    end
+
+you will have to rewrite them as follows:
+
+    b = lambda { |m|
+      # ...
+    }
+
+    [/this/, /that/].each do |pattern|
+      on :message, pattern, &b
+    end