cinch 2.0.0.pre.7 → 2.0.0

data/README.md

@@ -141,7 +141,7 @@ text. Cinch also provides a way for your plugins to log custom
 messages:
 
     on :message, /hello/ do |m|
-      bot.logger.debug "Someone said hello"
+      debug "Someone said hello"
     end
 
 Authors

data/docs/bot_options.md

@@ -2,8 +2,6 @@
 # @markup kramdown
 
 # Options
-Note: This page describes options of Cinch. It does not describe how
-to set options specific to plugins.
 
 ## channels
 Type
@@ -59,7 +57,7 @@ Description
 
 
 ### Notes
-- {file:encodings.md More information on how Cinch handles encoding issues}
+- {file:docs/encodings.md More information on how Cinch handles encoding issues}
 
 ## local_host
 Type
@@ -114,7 +112,7 @@ Description
 ### Notes
 - If your bot gets kicked for excess flood, try lowering the value of
   `messages_per_second`.
-- See also: {file:bot_options.md#serverqueuesize `server_queue_size`}
+- See also: {file:docs/bot_options.md#serverqueuesize `server_queue_size`}
 
 ## message_split_end
 Type
@@ -175,7 +173,7 @@ Default value
 : `nil`
 
 Description
-: This option overrules {file:bot_options.md#nick `nick`} and allows Cinch
+: This option overrules {file:docs/bot_options.md#nick `nick`} and allows Cinch
   to try multiple nicks before adding underscores.
 
 
@@ -209,7 +207,7 @@ Description
 
 ### Notes
 - The ping interval should be smaller than
-  {file:bot_options.md#timeoutsread `timeouts.read`} to prevent Cinch from
+  {file:docs/bot_options.md#timeoutsread `timeouts.read`} to prevent Cinch from
   falsely declaring a connection dead.
 
 
@@ -348,7 +346,7 @@ Description
 ### Notes
 - If your bot gets kicked for excess flood, try lowering the value of
   `server_queue_size`.
-- See also: {file:bot_options.md#messagespersecond `messages_per_second`}
+- See also: {file:docs/bot_options.md#messagespersecond `messages_per_second`}
 
 ## ssl
 
@@ -382,7 +380,7 @@ Default value
 
 Description
 : The path to a directory with certificates. This has to be set
-  properly for {file:bot_options.md#sslverify `ssl.verify`} to work.
+  properly for {file:docs/bot_options.md#sslverify `ssl.verify`} to work.
 
 
 ### ssl.client_cert

data/docs/changes.md

@@ -94,7 +94,7 @@ needs to be aware of available features/quirks, check out
 ## Reworked logging facilities
 
 The logging API has been drastically improved. Check the
-{file:logging.md logging documentation} for more information.
+{file:docs/logging.md logging documentation} for more information.
 
 
 ## Added match groups
@@ -225,7 +225,6 @@ moved from {Cinch} to {Cinch::Constants}
 #### {Cinch::Plugin}
 
 - {Cinch::Plugin#handlers}
-- {Cinch::Plugin#storage}
 - {Cinch::Plugin#timers}
 - {Cinch::Plugin#unregister}
 
@@ -234,7 +233,7 @@ moved from {Cinch} to {Cinch::Constants}
 - {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#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}
@@ -297,7 +296,7 @@ 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
+{file:docs/migrating.md#plugin-options the migration guide} for more
 information.
 
 ### Channel/Target/User implement Comparable
@@ -342,24 +341,24 @@ For more information on timers, see the {Cinch::Timer Timer documentation}.
 
 ## New options
 
-- :{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: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: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}
+- :{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?
@@ -371,16 +370,16 @@ x. **Deprecated methods**
 
 ## New events
 
-- :{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}
+- :{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.
@@ -401,16 +400,16 @@ Provides a nicer representation of {Cinch::Message} objects.
 Provides an easier way of checking if a given user is in a channel
 
 ## New options
-- {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}
+- {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}
 
 
 

data/docs/encodings.md

@@ -16,7 +16,7 @@ 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
+By setting {file:docs/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
@@ -26,7 +26,7 @@ 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 `:irc` is being used as the {file:docs/bot_options.md#encoding
 `encoding option`}
 
 ## The `:irc` encoding

data/docs/events.md

@@ -72,7 +72,7 @@ Example:
       debug("User %s just went away: %s" % [m.user, m.message])
     end
 
-See also {file:events.md#unaway the `:unaway` event}.
+See also {file:docs/events.md#unaway the `:unaway` event}.
 
 
 ## `:ban`
@@ -88,7 +88,7 @@ Example:
       debug("%s just banned %s" % [ban.by, ban.mask])
     end
 
-See also {file:events.md#unban the `:unban` event}.
+See also {file:docs/events.md#unban the `:unban` event}.
 
 
 ## `:catchall`
@@ -102,7 +102,7 @@ IRC message/command, no matter what the type is.
 The `:channel` event is triggered for channel messages (the usual
 form of communication on IRC).
 
-See also {file:events.md#private the `:private` event}.
+See also {file:docs/events.md#private the `:private` event}.
 
 
 ## `:connect`
@@ -193,7 +193,7 @@ describing every change.
 ## `:offline`
 
 This event is triggered when a
-{file:common_tasks.md#checking-if-a-user-is-online monitored user}
+{file:docs/common_tasks.md#checking-if-a-user-is-online monitored user}
 goes offline.
 
 One additional argument, the user going offline, gets passed to the
@@ -203,7 +203,7 @@ handler.
 ## `:online`
 
 This event is triggered when a
-{file:common_tasks.md#checking-if-a-user-is-online monitored user}
+{file:docs/common_tasks.md#checking-if-a-user-is-online monitored user}
 comes online.
 
 One additional argument, the user coming online, gets passed to the
@@ -239,7 +239,7 @@ channel or directly at the bot. It's synonymous with `:privmsg`.
 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}.
+See also {file:docs/events.md#channel the `:channel` event}.
 
 
 ## `:unaway`
@@ -254,7 +254,7 @@ Example:
       debug("User %s no longer is away." % m.user)
     end
 
-See also {file:events.md#away the `:away` event}.
+See also {file:docs/events.md#away the `:away` event}.
 
 
 ## `:unban`

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

@@ -1,6 +1,55 @@
 # @title Logging
 # @markup kramdown
 
-TODO explain the logging facilities
+# 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::Loggers::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`.
 
 # Writing your own logger
+
+This section will follow soon. For now just look at the code of
+already implemented loggers.

data/docs/migrating.md

@@ -18,7 +18,6 @@ shouldn't and usually mustn't overwrite:
 - `#bot`
 - `#config`
 - `#handlers`
-- `#storage`
 - `#synchronize`
 - `#timers`
 - `#unregister`
@@ -193,7 +192,7 @@ 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}.
+on how to use it, check the {file:docs/logging.md Logging readme}.
 
 ## Prefix/suffix + string semantics
 
@@ -239,12 +238,12 @@ or
 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}.
+{file:docs/bot_options.md Bot options}.
 
 
 ## Various removed methods
 
-See {file:changes.md#removedrenamed-methods What's changed}
+See {file:docs/changes.md#removedrenamed-methods What's changed}
 
 
 ## `on`-handlers now only accepts one pattern

data/docs/plugins.md

@@ -0,0 +1,4 @@
+# @title Plugins
+# @markup kramdown
+
+Content will follow soon…

data/lib/cinch/bot.rb

@@ -47,7 +47,7 @@ require "cinch/configuration/bot"
 require "cinch/configuration/plugins"
 require "cinch/configuration/ssl"
 require "cinch/configuration/timeouts"
-require "cinch/configuration/storage"
+# require "cinch/configuration/storage"
 require "cinch/configuration/dcc"
 require "cinch/configuration/sasl"
 
@@ -171,7 +171,7 @@ module Cinch
     # Registers a handler.
     #
     # @param [String, Symbol, Integer] event the event to match. For a
-    #   list of available events, check the {file:events.md Events
+    #   list of available events, check the {file:docs/events.md Events
     #   documentation}.
     #
     # @param [Regexp, Pattern, String] regexp every message of the
@@ -290,12 +290,11 @@ module Cinch
       end while @config.reconnect and not @quitting
     end
 
-    # TODO document this
     def stop
-      @plugins.each do |plugin|
-        plugin.storage.save
-        plugin.storage.unload
-      end
+      # @plugins.each do |plugin|
+      #   plugin.storage.save
+      #   plugin.storage.unload
+      # end
     end
 
     # @endgroup

data/lib/cinch/channel.rb

@@ -380,6 +380,18 @@ module Cinch
       @users.clear
     end
 
+    def msg(text, notice = false)
+      text = text.to_s
+      if @modes["c"]
+        # Remove all formatting and colors if the channel doesn't
+        # allow colors.
+        text.gsub!(/[\x02\x1F\x16\x0F]|\x03\d{2}(,\d{2})?/, "")
+      end
+      super(text, notice)
+    end
+    alias_method :send, :msg
+    alias_method :privmsg, :msg
+
     # @return [Fixnum]
     def hash
       @name.hash

data/lib/cinch/configuration/bot.rb

@@ -8,7 +8,7 @@ module Cinch
                       :realname, :user, :messages_per_second, :server_queue_size,
                       :strictness, :message_split_start, :message_split_end,
                       :max_messages, :plugins, :channels, :encoding, :reconnect, :max_reconnect_delay,
-                      :local_host, :timeouts, :ping_interval, :storage, :dcc]
+                      :local_host, :timeouts, :ping_interval, :dcc, :shared, :sasl]
 
       # (see Configuration.default_config)
       def self.default_config
@@ -37,9 +37,10 @@ module Cinch
           :timeouts => Configuration::Timeouts.new,
           :ping_interval => 120,
           :delay_joins => 0,
-          :storage => Configuration::Storage.new,
+          # :storage => Configuration::Storage.new,
           :dcc => Configuration::DCC.new,
           :sasl => Configuration::SASL.new,
+          :shared => {},
         }
       end
     end

data/lib/cinch/dcc/outgoing/send.rb

@@ -27,7 +27,7 @@ module Cinch
       # but sending files will probably be the most common case.
       #
       # If you're behind a NAT it is necessary to explicitly set the
-      # external IP using the {file:bot_options.md#dccownip dcc.own_ip
+      # external IP using the {file:docs/bot_options.md#dccownip dcc.own_ip
       # option}.
       #
       # @example Sending a file to a user

data/lib/cinch/helpers.rb

@@ -1,4 +1,3 @@
-# TODO @since for all methods
 module Cinch
   # The Helpers module contains a number of methods whose purpose is
   # to make writing plugins easier by hiding parts of the API. The
@@ -19,6 +18,7 @@ module Cinch
     #   on :message, /^message (.+)$/ do |m, target|
     #     Target(target).send "hi!"
     #   end
+    # @since 2.0.0
     def Target(target)
       return target if target.is_a?(Target)
       Target.new(target, bot)
@@ -32,6 +32,7 @@ module Cinch
     #   on :message, /^please join (#.+)$/ do |m, target|
     #     Channel(target).join
     #   end
+    # @since 1.0.0
     def Channel(channel)
       return channel if channel.is_a?(Channel)
       bot.channel_list.find_ensured(channel)
@@ -46,6 +47,7 @@ module Cinch
     #     user = User(target)
     #     m.reply "%s is named %s and connects from %s" % [user.nick, user.name, user.host]
     #   end
+    # @since 1.0.0
     def User(user)
       return user if user.is_a?(User)
       if user == bot.nick
@@ -121,6 +123,11 @@ module Cinch
 
     # (see Logger#log)
     def log(messages, event = :debug, level = event)
+      if self.is_a?(Cinch::Plugin)
+        messages = Array(messages).map {|m|
+          "[#{self.class}] " + m
+        }
+      end
       @bot.loggers.log(messages, event, level)
     end
 

data/lib/cinch/plugin.rb

@@ -10,7 +10,7 @@ module Cinch
   #
   # Most of the instance methods are for use by the Cinch framework
   # and part of the private API, but some will also be used by plugin
-  # authors, mainly {#config}, {#synchronize}, {#storage} and {#bot}.
+  # authors, mainly {#config}, {#synchronize} and {#bot}.
   module Plugin
     include Helpers
 
@@ -172,10 +172,15 @@ module Cinch
       # @option options [Boolean] :use_suffix (true) If true, the
       #   plugin suffix will automatically be appended to the
       #   pattern.
+      # @option options [String, Regexp, Proc] prefix (nil) A prefix
+      #   overwriting the per-plugin prefix.
+      # @option options [String, Regexp, Proc] suffix (nil) A suffix
+      #   overwriting the per-plugin suffix.
+      # @option options [Symbol, Fixnum] react_on (:message) The
+      #   {file:docs/events.md event} to react on.
       # @option options [Symbol] :group (nil) The group the match belongs to.
       # @return [Matcher]
       # @todo Document match/listener grouping
-      # @todo document new options
       def match(pattern, options = {})
         options = {:use_prefix => true, :use_suffix => true, :method => :execute, :group => nil, :prefix => nil, :suffix => nil, :react_on => nil}.merge(options)
         if options[:react_on]
@@ -191,15 +196,7 @@ module Cinch
       # @overload listen_to(*types, options = {})
       #   @param [String, Symbol, Integer] *types Events to listen to. Available
       #     events are all IRC commands in lowercase as symbols, all numeric
-      #     replies, and the following:
-      #
-      #       - :channel (a channel message)
-      #       - :private (a private message)
-      #       - :message (both channel and private messages)
-      #       - :error   (IRC errors)
-      #       - :ctcp    (ctcp requests)
-      #       - :action  (actions, aka /me)
-      #
+      #     replies and all events listed in the {file:docs/events.md list of events}.
       #   @param [Hash] options
       #   @option options [Symbol] :method (:listen) The method to
       #     execute
@@ -292,7 +289,11 @@ module Cinch
       def call_hooks(type, event, instance, args)
         stop = __hooks(type, event).find { |hook|
           # stop after the first hook that returns false
-          instance.__send__(hook.method, *args) == false
+          if hook.method.respond_to?(:call)
+            instance.instance_exec(*args, &hook.method) == false
+          else
+            instance.__send__(hook.method, *args) == false
+          end
         }
 
         !stop
@@ -432,14 +433,14 @@ module Cinch
     attr_reader :timers
 
     # @return [Storage] The per-plugin persistent storage
-    attr_reader :storage
+    # attr_reader :storage
 
     # @api private
     def initialize(bot)
       @bot = bot
       @handlers = []
       @timers   = []
-      @storage  = bot.config.storage.backend.new(@bot.config.storage, self)
+      # @storage  = bot.config.storage.backend.new(@bot.config.storage, self)
       __register
     end
 
@@ -468,6 +469,10 @@ module Cinch
       @bot.config.plugins.options[self.class] || {}
     end
 
+    def shared
+      @bot.config.shared
+    end
+
     # @api private
     def self.included(by)
       by.extend ClassMethods

data/lib/cinch/storage.rb

@@ -1,5 +1,6 @@
 module Cinch
-  # @since 2.0.0
+  # @note The interface of this class isn't fixed yet. You shouldn't
+  #   use it yet.
   class Storage
     include Enumerable
 

data/lib/cinch/target.rb

@@ -121,6 +121,14 @@ module Cinch
       send "\001#{message}\001"
     end
 
+    def concretize
+      if @bot.isupport["CHANTYPES"].include?(@name[0])
+        @bot.channel_list.find_ensured(@name)
+      else
+        @bot.user_list.find_ensured(@name)
+      end
+    end
+
     # @return [Boolean]
     def eql?(other)
       self == other

data/lib/cinch/version.rb

@@ -1,4 +1,4 @@
 module Cinch
   # Version of the library
-  VERSION = '2.0.0-pre.7'
+  VERSION = '2.0.0'
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: cinch
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.7
-  prerelease: 6
+  version: 2.0.0
+  prerelease: 
 platform: ruby
 authors:
 - Dominik Honnef
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-17 00:00:00.000000000 Z
+date: 2012-03-24 00:00:00.000000000 Z
 dependencies: []
 description: A simple, friendly DSL for creating IRC bots
 email:
@@ -21,10 +21,12 @@ files:
 - LICENSE
 - README.md
 - docs/changes.md
+- docs/getting_started.md
 - docs/readme.md
 - docs/bot_options.md
 - docs/common_mistakes.md
 - docs/events.md
+- docs/plugins.md
 - docs/encodings.md
 - docs/logging.md
 - docs/common_tasks.md
@@ -133,9 +135,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.15