cinch 1.0.2 → 1.1.0

data/README.md

@@ -1,4 +1,4 @@
-Cinch - An IRC Bot Building Framework
+Cinch - The IRC Bot Building Framework
 =====================================
 
 Description
@@ -17,8 +17,6 @@ If you'd like to test your own Cinch experiments you can do so in the
 [irc.freenode.org](irc://irc.freenode.org/cinch-bots). For general
 support, join [#cinch](irc://irc.freenode.org/cinch).
 
-This original document can be found [here](http://doc.injekt.net/cinch).
-
 Installation
 ------------
 
@@ -32,7 +30,7 @@ You can install the latest Cinch gem using RubyGems
 
 Alternatively you can check out the latest code directly from Github
 
-    git clone http://github.com/injekt/cinch.git
+    git clone http://github.com/cinchrb/cinch.git
 
 Example
 -------
@@ -61,54 +59,37 @@ Features
 
 ### Documentation
 
-Cinch provides a documented API, which is online for your viewing pleasure [here](http://doc.injekt.net/cinch).
+Cinch provides a documented API, which is online for your viewing pleasure
+[here](http://rubydoc.info/github/cinchrb/cinch/master/).
 
 ### Object Oriented
 
-Many IRC bots (and there are, so **many**) are great, but we see so little of them take
-advantage of the awesome Object Oriented Interface which most Ruby programmers will have
-become accustomed to and grown to love.
+Many IRC bots (and there are, **so** many) are great, but we see so little of
+them take advantage of the awesome Object Oriented Interface which most Ruby
+programmers will have become accustomed to and grown to love.
 
-Well, Cinch uses this functionality to it's advantage. Rather than having to pass around
-a reference to a channel or a user, to another method, which then passes it to
-another method (by which time you're confused about what's going on) -- Cinch provides
-an OOP interface for even the simpliest of tasks, making your code simple and easy
-to comprehend.
+Well, Cinch uses this functionality to its advantage. Rather than having to
+pass around a reference to a channel or a user, to another method, which then
+passes it to another method (by which time you're confused about what's
+going on) -- Cinch provides an OOP interface for even the simpliest of tasks,
+making your code simple and easy to comprehend.
 
 ### Threaded
 
-Unlike a lot of popular IRC frameworks, Cinch is threaded. But wait, don't let that
-scare you. It's totally easy to grasp.
-
-Each of Cinch's plugins and handlers are executed in their own personal thread. This
-means the main thread can stay focused on what it does best, providing non-blocking
-reading and writing to an IRC server. This will prevent your bot from locking up
-when one of your plugins starts doing some intense operations. Damn that's handy.
-
-### Key/Value Store
+Unlike a lot of popular IRC frameworks, Cinch is threaded. But wait, don't let
+that scare you. It's totally easy to grasp.
 
-We have listened to your requests and implemented a bot-wide key/value store. You can
-now store data and use it across your handlers. Here's an example:
-
-    configure do |c|
-      store[:friends] = []
-    end
-
-    on :message, /^add friend (.+)$/ do |m, friend|
-      store[:friends] << friend
-    end
-
-    on :message /^get friends$/ do |m|
-      m.reply "Your friends are: #{store[:friends].join(', ')}"
-    end
-
-Neat, right?
+Each of Cinch's plugins and handlers are executed in their own personal thread.
+This means the main thread can stay focused on what it does best, providing
+non-blocking reading and writing to an IRC server. This will prevent your bot
+from locking up when one of your plugins starts doing some intense operations.
+Damn that's handy.
 
 ### Plugins
 
-That's right folks, Cinch provides a modular based plugin system. This is a feature
-many people have bugged us about for a long time. It's finally here, and it's
-as awesome as you had hoped!
+That's right folks, Cinch provides a modular based plugin system. This is a
+feature many people have bugged us about for a long time. It's finally here,
+and it's as awesome as you had hoped!
 
 This system allows you to create feature packed plugins without interfering with
 any of the Cinch internals. Everything in your plugin is self contained, meaning
@@ -180,13 +161,13 @@ Please note that although we very much appreciate all of your efforts, Cinch
 will not accept patches in aid of Ruby 1.8 compatibility. We have no intention
 of supporting Ruby versions below 1.9.1.
 
-Fork the project, implement your awesome feature in it's own branch, and send
+Fork the project, implement your awesome feature in its own branch, and send
 a pull request to one of the Cinch collaborators. We'll be more than happy
 to check it out.
 
-Just remember, no specs, no cookies!
-
 ### Contributors
 - darix &lt;darix [at] nordisch.org&gt; (wrote the message splitting algorithm)
 - robgleeson (thanks for testing, contributing a lot of ideas,
   discussing design decisions etc)
+- Emil Loer (http://github.com/thedjinn) for improving the handling of
+  unexpected disconnects and reconnects.

data/examples/basic/autovoice.rb

@@ -22,7 +22,7 @@ bot = Cinch::Bot.new do
     end
   end
 
-  on :channel, /^!autovoice (on|off)/ do |m, option|
+  on :channel, /^!autovoice (on|off)$/ do |m, option|
     @autovoice = option == "on"
 
     m.reply "Autovoice is now #{@autovoice ? 'enabled' : 'disabled'}"

data/examples/basic/join_part.rb

@@ -10,10 +10,6 @@ bot = Cinch::Bot.new do
     @admin = "injekt"
   end
 
-  on :connect do
-    bot.join "#cinch"
-  end
-
   helpers do
     def is_admin?(user)
       true if user.nick == @admin

data/examples/plugins/autovoice.rb

@@ -9,7 +9,7 @@ require 'cinch'
 class Autovoice
   include Cinch::Plugin
   listen_to :join
-  match /autovoice (on|off)/
+  match /autovoice (on|off)$/
 
   def listen(m)
     unless m.user.nick == bot.nick
@@ -28,13 +28,10 @@ bot = Cinch::Bot.new do
   configure do |c|
     c.nick            = "cinch_autovoice"
     c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
     c.verbose         = true
     c.plugins.plugins = [Autovoice]
   end
-
-  on :connect do
-    bot.join "#cinch"
-  end
 end
 
 bot.start

data/examples/plugins/google.rb

@@ -14,10 +14,9 @@ class Google
     title = res.text
     link = res.at('a')[:href]
     desc = res.at("./following::div").children.first.text
+    CGI.unescape_html "#{title} - #{desc} (#{link})"
   rescue
     "No results found"
-  else
-    CGI.unescape_html "#{title} - #{desc} (#{link})"
   end
 
   def execute(m, query)

data/examples/plugins/hooks.rb

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+require 'cinch'
+
+class HooksDemo
+  include Cinch::Plugin
+
+  hook :pre, method: :generate_random_number
+  def generate_random_number(m)
+    # Hooks are called in the same thread as the handler and thus
+    # using thread local variables is possible.
+    Thread.current[:rand] = Kernel.rand
+  end
+
+  hook :post, method: :cheer
+  def cheer(m)
+    m.reply "Yay, I successfully ran a command…"
+  end
+
+  match "rand"
+  def execute(m)
+    m.reply "Random number: " + Thread.current[:rand].to_s
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick            = "cinch_hooks"
+    c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
+    c.verbose         = true
+    c.plugins.plugins = [HooksDemo]
+  end
+end
+
+
+bot.start

data/examples/plugins/lambdas.rb

@@ -0,0 +1,35 @@
+require 'cinch'
+
+class DirectAddressing
+  include Cinch::Plugin
+
+  # Note: the lambda will be executed in the context it has been
+  # defined in, in this case the class DirectAddressing (and not an
+  # instance of said class).
+  #
+  # The reason we are using a lambda is that the bot's nick can change
+  # and the prefix has to be up to date.
+  prefix lambda{ |m| m.bot.nick + ": " }
+
+  match "hello", method: :greet
+  def greet(m)
+    m.reply "Hello to you, too."
+  end
+
+  match "rename", method: :rename
+  def rename(m)
+    @bot.nick += "_"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick            = "cinch_lambda"
+    c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
+    c.verbose         = true
+    c.plugins.plugins = [DirectAddressing]
+  end
+end
+
+bot.start

data/examples/plugins/last_nick.rb

@@ -0,0 +1,24 @@
+require 'cinch'
+
+class Nickchange
+  include Cinch::Plugin
+  listen_to :nick
+
+  def listen(m)
+    # This will send a PM to the user who changed his nick and inform
+    # him of his old nick.
+    m.reply "Your old nick was: #{m.user.last_nick}" ,true
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick            = "cinch_nickchange"
+    c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
+    c.verbose         = true
+    c.plugins.plugins = [Nickchange]
+  end
+end
+
+bot.start

data/examples/plugins/multiple_matches.rb

@@ -1,11 +1,5 @@
 require 'cinch'
 
-# Give this bot ops in a channel and it'll auto voice
-# visitors
-#
-# Enable with !autovoice on
-# Disable with !autovoice off
-
 class MultiCommands
   include Cinch::Plugin
   match /command1 (.+)/, method: :command1
@@ -29,13 +23,10 @@ bot = Cinch::Bot.new do
   configure do |c|
     c.nick            = "cinch_multi"
     c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
     c.verbose         = true
     c.plugins.plugins = [MultiCommands]
   end
-
-  on :connect do
-    bot.join "#dominikh"
-  end
 end
 
 bot.start

data/examples/plugins/own_events.rb

@@ -0,0 +1,37 @@
+require 'cinch'
+
+class RandomNumberGenerator
+  def initialize(bot)
+    @bot = bot
+  end
+
+  def start
+    while true
+      sleep 5 # pretend that we are waiting for some kind of entropy
+      @bot.dispatch(:random_number, nil, Kernel.rand)
+    end
+  end
+end
+
+class DoSomethingRandom
+  include Cinch::Plugin
+
+  listen_to :random_number
+  def listen(m, number)
+    Channel("#cinch-bots").send "I got a random number: #{number}"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick            = "cinch_events"
+    c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
+    c.verbose         = true
+    c.plugins.plugins = [DoSomethingRandom]
+  end
+end
+
+
+Thread.new { RandomNumberGenerator.new(bot).start }
+bot.start

data/examples/plugins/timer.rb

@@ -0,0 +1,22 @@
+require 'cinch'
+
+class TimedPlugin
+  include Cinch::Plugin
+
+  timer 5, method: :timed
+  def timed
+    Channel("#cinch-bots").send "5 seconds have passed"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick            = "cinch_timer"
+    c.server          = "irc.freenode.org"
+    c.channels        = ["#cinch-bots"]
+    c.verbose         = true
+    c.plugins.plugins = [TimedPlugin]
+  end
+end
+
+bot.start

data/examples/plugins/url_shorten.rb

@@ -25,7 +25,7 @@ end
 bot = Cinch::Bot.new do
   configure do |c|
     c.server = "irc.freenode.org"
-    c.channels = ["#cinch"]
+    c.channels = ["#cinch-bots"]
   end
 end
 

data/lib/cinch.rb

@@ -1,7 +1,7 @@
 require 'cinch/bot'
 
 module Cinch
-  VERSION = '1.0.2'
+  VERSION = '1.1.0'
 
   # @return [String]
   # @todo Handle mIRC color codes more gracefully.
@@ -9,4 +9,53 @@ module Cinch
   def self.filter_string(string)
     string.gsub(/[\x00-\x1f]/, '')
   end
+
+  # @api private
+  def self.encode_incoming(string, encoding)
+    string = string.dup
+    if encoding == :irc
+      # 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 allows you to see non-ASCII from mIRC
+      # users (non-UTF-8) and other users sending you UTF-8.
+      #
+      # (from http://xchat.org/encoding/#hybrid)
+      string.force_encoding("UTF-8")
+      if !string.valid_encoding?
+        string.force_encoding("CP1252").encode!("UTF-8", {:invalid => :replace, :undef => :replace})
+      end
+    else
+      string.force_encoding(encoding).encode!({:invalid => :replace, :undef => :replace})
+      string = string.chars.select { |c| c.valid_encoding? }.join
+    end
+
+    return string
+  end
+
+  # @api private
+  def self.encode_outgoing(string, encoding)
+    string = string.dup
+    if encoding == :irc
+      # If your text contains only characters that fit inside the CP1252
+      # code page (aka Windows Latin-1), the entire line will be sent
+      # that way. mIRC users should see it correctly. XChat users who
+      # are using UTF-8 will also see it correctly, because it will fail
+      # UTF-8 validation and will be assumed to be CP1252, even by older
+      # XChat versions.
+      #
+      # If the text doesn't fit inside the CP1252 code page, (for eaxmple 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
+      #
+      # (from http://xchat.org/encoding/#hybrid)
+      begin
+        string.encode!("CP1252")
+      rescue Encoding::UndefinedConversionError
+      end
+    else
+      string.encode!(encoding, {:invalid => :replace, :undef => :replace})
+    end
+
+    return string
+  end
 end

data/lib/cinch/ban.rb

@@ -4,15 +4,18 @@ module Cinch
     # @return [Mask, String]
     attr_reader :mask
 
-    # @return [String]
+    # @return [User]
     attr_reader :by
 
     # @return [Time]
     attr_reader :created_at
 
-    # @return [Boolean]
+    # @return [Boolean] whether this is an extended ban (as used by for example Freenode)
     attr_reader :extended
 
+    # @param [String] mask The mask
+    # @param [User] by The user who created the ban
+    # @param [Time] at The time at which the ban was created
     def initialize(mask, by, at)
       @by, @created_at = by, at
       if mask =~ /^\$/