grinch 1.0.0

data/docs/getting_started.md

@@ -0,0 +1,184 @@
+# @title Getting Started
+# @markup kramdown
+
+# Getting Started
+
+This short guide will show you how to easily and quickly write your
+own IRC bot with Cinch.
+
+# What Cinch really is
+
+First and foremost, it is important to understand that Cinch is more
+of an API for IRC access than a full-blown bot framework like Autumn
+or Rbot.
+
+There will be no enforced directory structures, no magical places from
+which plugins will be loaded and no obscure, "fancy" names. Plugins
+will be plugins and not "leaves".
+
+This, however, does not mean that Cinch requires you to be familiar
+with the internals of the IRC protocol. Quite the opposite: A very
+high-level abstraction is provided, allowing things such as
+
+    Channel("#cinch").users.each do |user, modes|
+      user.send "I am watching you!"
+    end
+
+to work.
+
+
+Furthermore, the API has been designed in a way that it sticks true to
+the way Ruby looks and behaves. Plugins are normal classes that mix-in
+a module, functions of the bot are implemented as normal methods and
+so on.
+
+# Hello, World
+
+The following will describe one of the most basic IRC bots you can
+write in Cinch: One that joins a specific channel and responds to
+"hello" by saying "Hello, World".
+
+
+    require "cinch"
+
+    bot = Cinch::Bot.new do
+      configure do |c|
+        c.server   = "irc.freenode.net"
+        c.channels = ["#cinch-bots"]
+      end
+
+      on :message, "hello" do |m|
+        m.reply "Hello, World"
+      end
+    end
+
+    bot.start
+
+
+Note that this is the entire file and all you need for the basic bot
+to work. Save the above example to a file and run it with Ruby.
+
+## In Detail
+
+So, what are we actually doing in that short piece of code? First, we
+create a new bot in line 3 and conigure it in lines 4–6 –
+{Cinch::Bot#configure configure} simply yields the configuration
+object, which allows you to configure various things. In this example,
+we only set which server to connect to and which channel to join.
+Another often-used option is the nickname of the bot
+({file:docs/bot_options.md#nick c.nick}). For an overview of all
+available options, see {file:docs/bot_options.md the list of options}.
+
+Following, we define a basic message handler. In its simplest form,
+{Cinch::Bot#on on} expects two arguments: The kind of message to react
+to and the pattern to match. In this case, the kind is
+{file:docs/events.md#message :message}, which means that the bot will
+respond to both messages in channels as well as messages sent directly
+to the bot. For a list of all kinds, called events, see
+{file:docs/events.md the list of events}.
+
+For the pattern we use a basic string, which means that the message
+has to be exactly that string. It mustn't have anything before or
+after the word "hello". Another way of using {Cinch::Bot#on on} is by using
+regular expressions:
+
+    on :message, /^\d{4}$/ do |m|
+      # ...
+    end
+
+will match all messages that consist of exactly four digits and
+nothing else.
+
+Whenever a message matches the handler we just defined, the block we
+provided will be called, with the message object, and optionally
+capture groups of the regular expression, passed to it.
+
+The message object allows insight into the nature of the message, i.e.
+who sent it, when was it sent etc, and also provides the
+{Cinch::Message#reply reply} method, an easy way of responding to a
+message. If the message was sent to a channel, {Cinch::Message#reply
+reply} will respond to the channel, otherwise directly to the user.
+
+We then use exactly that {Cinch::Message#reply reply} method to send back "Hello, World"
+whenever someone says "hello".
+
+That's it!
+
+# on-handlers vs. plugins
+
+Using `on` might be nice and handy for writing simple bots, but if you
+want to write a more complex bot, providing lots of different features
+to its users, then using plugins might be a better solution.
+
+But what are plugins, exactly? Technically, plugins are implemented as
+Ruby classes that mix-in a {Cinch::Plugin specific module} to get
+access to various methods.
+
+To have an example to work with, we'll convert our "Hello, World" bot
+to using the plugin API:
+
+    require "cinch"
+
+    class HelloWorld
+      include Cinch::Plugin
+
+      match "hello"
+      def execute(m)
+        m.reply "Hello, World"
+      end
+    end
+
+    bot = Cinch::Bot.new do
+      configure do |c|
+        c.server = "irc.freenode.net"
+        c.channels = ["#cinch-bots"]
+        c.plugins.plugins = [HelloWorld]
+      end
+    end
+
+    bot.start
+
+The first thing to notice is that we wrote a new class called
+`HelloWorld`, and that we use {Cinch::Plugin::ClassMethods#match
+match} instead of `on` to define our handler. Furthermore, we didn't
+specify a message type nor did we provide any blocks.
+
+But let's back up and proceed in smaller steps to see how plugins are built.
+
+First thing after defining a new class is to include {Cinch::Plugin} –
+This module will provide methods like
+{Cinch::Plugin::ClassMethods#match match} and also allows Cinch to
+control the class in specific ways required for plugins to work.
+
+Then we use aforementioned `match`, instead of `on`, to specify what
+messages we want to react to. We didn't have to specify the message
+type because plugins default to {file:docs/events.md#message :message}.
+
+We then define a method called `execute`, which is pretty much the
+same as blocks are to on-handlers. And from here on, everything is the
+same.
+
+The only thing left to do is to tell Cinch to use our plugin, by
+adding it to {file:docs/bot_options.md#pluginsplugins c.plugins.plugins}.
+
+One important thing remains to note: Plugins have a
+{file:docs/bot_options.md#pluginsprefix prefix}, a string (or pattern)
+that gets appended to all patterns you define, and by default this
+prefix is `/^!/`. This means that in order to invoke our HelloWorld
+plugin, a user has to say "!hello" instead of "hello". This prefix can
+be configured on a per-plugin or global basis, but that's not in the
+scope of this document.
+
+# Final Words
+
+This short guide only explains the basics of using Cinch, so that you
+can get started as quickly as possible. For more advanced topics, you
+will want to read the specific documents:
+
+- {file:docs/plugins.md Plugins}
+- {file:docs/bot_options.md A list of all available bot options}
+- {file:docs/events.md A list of all available events}
+- {file:docs/encodings.md Dealing with encodings}
+- {file:docs/logging.md Logging in Cinch}
+- {file:docs/common_tasks.md A cookbook for common tasks}
+- {file:docs/common_mistakes.md A list of common mistakes and how to avoid them}

data/docs/logging.md

@@ -0,0 +1,90 @@
+# @title Logging
+# @markup kramdown
+
+# Using the logger
+
+Plugins can use the logging facility for logging their own messages,
+either by using the logging related helper methods (#debug, #info, and
+so on) or by directly interfacing with {Cinch::LoggerList}, which is
+available via `@bot.loggers`.
+
+Example:
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      match "foo"
+      def execute(m)
+        debug "Starting handler..."
+        info  "Some more important information"
+        debug "Done."
+      end
+    end
+
+# Logger levels
+
+Cinch uses a priority-based logging system, using the types `:debug`,
+`:log`, `:info`, `:warn`, `:error` and `:fatal`, each of them
+displaying less information than the previous.
+
+By default, the logging level to display is set to `:debug`, which
+will include all possible kinds of log events, including the rather
+verbose debug output caused by plugins.
+
+`:log` will hide debug output but still contain the raw IRC log and
+from there on, the levels are rather self-explanatory.
+
+## Changing the level
+
+The level can be changed for single loggers or all loggers at once, by either using {Cinch::Logger#level=} or {Cinch::LoggerList#level=} respectively.
+
+Example:
+
+    bot = Cinch::Bot.new { }
+    bot.loggers << Cinch::Logger::FormattedLogger.new(File.open("/tmp/log.log", "a"))
+    bot.loggers.level = :debug
+    bot.loggers.first.level  = :info
+
+This will set all loggers to the `:debug` level (which actually is the
+default already) and the first logger (which is the default STDOUT
+logger) to `:info`.
+
+# Log filtering
+
+Sometimes it is undesirable to log a message unchanged. For example
+when identifying to the network, passwords might be sent in plain
+text. To prevent such information from appearing in logs, {Cinch::LogFilter log filters}
+can be employed.
+
+Log filters take a log message as input and return a new message. This
+allows removing/masking out passwords or other undesired information.
+Additionally, messages can be dropped entirely by returning nil.
+
+It is possible to use more than one filter, in which case they will be
+called in order, each acting on the previous filter's output.
+
+Filters can be installed by adding them to {Cinch::LoggerList#filters}.
+
+An example (and very simple) password filter might look like this:
+
+    class PasswordFilter
+      def initialize(bot)
+        @bot = bot
+      end
+
+      def filter(message, event)
+        message.gsub(@bot.config.password, "*" * @bot.config.password.size)
+      end
+    end
+
+This filter will replace the password in all log messages (except for
+exceptions). It could further discriminate by looking at `event` and
+only modify outgoing IRC messages. It could also use the
+{Cinch::Message} class to parse the message and only operate on the
+actual message component, not channel names and similar. How fancy
+your filtering needs to be depends on you.
+
+# Writing your own logger
+
+This section will follow soon. For now just look at the code of
+already implemented loggers.

data/docs/migrating.md

@@ -0,0 +1,267 @@
+# @title Migration Guide
+# @markup kramdown
+
+# 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`
+- `#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=`
+- `::react_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:docs/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:docs/bot_options.md Bot options}.
+
+
+## Various removed methods
+
+See {file:docs/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