cinch 0.3.5 → 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Lee Jarvis, Dominik Honnef
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+Cinch - An IRC Bot Building Framework
+=====================================
+
+Description
+-----------
+
+Cinch is an IRC Bot Building Framework for quickly creating IRC bots in
+Ruby with minimal effort. It provides a simple interface based on plugins and
+rules. It's as easy as creating a plugin, defining a rule, and watching your
+profits flourish.
+
+Cinch will do all of the hard work for you, so you can spend time creating cool
+plugins and extensions to wow your internet peers.
+
+If you'd like to test your own Cinch experiments you can do so in the
+\#cinch-bots IRC channel on
+[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
+------------
+
+### RubyGems
+
+You can install the latest Cinch gem using RubyGems
+
+    gem install cinch
+
+### GitHub
+
+Alternatively you can check out the latest code directly from Github
+
+    git clone http://github.com/injekt/cinch.git
+
+Example
+-------
+
+Your typical Hello, World application in Cinch would go something like this:
+
+    require 'cinch'
+
+    bot = Cinch::Bot.new do
+      configure do |c|
+        c.server = "irc.freenode.org"
+        c.channels = ["#cinch-bots"]
+      end
+
+      on :message, "hello" do |m|
+        m.reply "Hello, #{m.user.nick}"
+      end
+    end
+
+    bot.start
+
+More examples can be found in the `examples` directory.
+
+Features
+--------
+
+### Documentation
+
+Cinch provides a documented API, which is online for your viewing pleasure [here](http://doc.injekt.net/cinch).
+
+### 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.
+
+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.
+
+### 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
+
+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?
+
+### 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!
+
+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
+you can share your favorite plugins among your friends and release a ton of
+your own plugins for others to use
+
+Want to see the same Hello, World application in plugin form? Sure you do!
+
+    require 'cinch'
+
+    class Hello
+      include Cinch::Plugin
+
+      match "hello"
+
+      def execute(m)
+        m.reply "Hello, #{m.user.nick}"
+      end
+    end
+
+    bot = Cinch::Bot.new do
+      configure do |c|
+        c.server = "irc.freenode.org"
+        c.channels = ["#cinch-bots"]
+        c.plugins.plugins = [Hello]
+      end
+    end
+
+    bot.start
+
+More information can be found in the {Cinch::Plugin} documentation.
+
+### Numeric Replies
+
+Do you know what IRC code 401 represents? How about 376? or perhaps 502?
+Sure you don't (and if you do, you're as geeky as us!). Cinch doesn't expect you
+to store the entire IRC RFC code set in your head, and rightfully so!
+
+That's exactly why Cinch has a ton of constants representing these numbers
+so you don't have to remember them. We're so nice.
+
+### Pretty Output
+
+Ever get fed up of watching those boring, frankly unreadable lines
+flicker down your terminal screen whilst your bot is online? Help is
+at hand! By default, Cinch will colorize all text it sends to a
+terminal, meaning you get some pretty damn awesome readable coloured
+text. Cinch also provides a way for your plugins to log custom
+messages:
+
+    on :message, /hello/ do |m|
+      bot.logger.debug "Someone said hello"
+    end
+
+Authors
+-------
+
+* [Lee Jarvis](http://injekt.net)
+* [Dominik Honnef](http://fork-bomb.org)
+
+Contribute
+----------
+
+Love Cinch? Love Ruby? Love helping? Of course you do! If you feel like Cinch
+is missing that awesome jaw-dropping feature and you want to be the one to
+make this magic happen, you can!
+
+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
+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)

data/Rakefile

@@ -1,56 +1,66 @@
-require "rake"
-require "rake/clean"
-require "rake/gempackagetask"
-require "spec/rake/spectask"
-
-begin
-  require 'hanna/rdoctask'
-rescue LoadError
-  require 'rake/rdoctask'
-end
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
 
-require 'lib/cinch'
-
-NAME = 'cinch'
-VERSION = Cinch::VERSION
-TITLE = "Cinch: The IRC Bot Building Framework"
-CLEAN.include ["*.gem", "rdoc"]
-RDOC_OPTS = [
-  "-U", "--title", TITLE,
-  "--op", "rdoc",
-  "--main", "README.rdoc"
-]
-
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.options += RDOC_OPTS
-  rdoc.rdoc_files.add %w(README.rdoc lib/**/*.rb)
-end
+$LOAD_PATH.unshift('lib') unless $LOAD_PATH.include?('lib')
+require 'cinch'
 
-desc "Package"
-task :package => [:clean] do |p|
-  sh "gem build #{NAME}.gemspec"
+CLEAN.include ["doc"]
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
 end
 
-desc "Install gem"
-task :install => [:package] do
-  sh "sudo gem install ./#{NAME}-#{VERSION} --local"
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', 'README.md']
+  t.options = [
+    '-m', 'markdown', 
+    '--hide-void-return',
+    '--quiet',
+    '--title', "Cinch #{Cinch::VERSION} Documentation",
+    '--main', 'README.md',
+  ] 
 end
 
-desc "Uninstall gem"
-task :uninstall => [:clean] do
-  sh "sudo gem uninstall #{NAME}"
+namespace :gem do
+  desc "Build gem"
+  task :build => ["rake:clean"] do
+    sh("gem build cinch.gemspec")
+  end
+
+  desc "Uninstall gem (not root)"
+  task :uninstall do
+    sh("gem uninstall cinch -v #{Cinch::VERSION}")
+  end
+
+  desc "Release to rubygems"
+  task :release => [:build] do
+    sh("gem push ./cinch-#{Cinch::VERSION}.gem")
+  end
+
+  desc "Install gem (not root)"
+  task :install => :build do
+    sh("gem install ./cinch-#{Cinch::VERSION} --local")
+  end
 end
 
-desc "Upload gem to gemcutter"
-task :release => [:package] do
-  sh "gem push ./#{NAME}-#{VERSION}.gem"
+namespace :doc do
+  desc "Upload documentation"
+  task :push => [:yard] do
+    # XXX rename once merge is complete
+    sh("scp -r doc injekt:injekt.net/doc/cinch-merge")
+  end
 end
 
-desc "Run all specs"
-Spec::Rake::SpecTask.new(:spec) do |t|
-  t.spec_files = Dir['spec/**/*_spec.rb']
+task :version do
+  puts "Cinch version #{Cinch::VERSION}"
 end
 
-task :default => [:clean, :spec]
+desc "Install gem (not root)"
+task :install => "gem:install"
+
+task :default => :spec
 

data/examples/basic/autovoice.rb

@@ -0,0 +1,32 @@
+require 'cinch'
+
+# Give this bot ops in a channel and it'll auto voice
+# visitors
+#
+# Enable with !autovoice on
+# Disable with !autovoice off
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick            = "cinch_autovoice"
+    c.server          = "irc.freenode.org"
+    c.verbose         = true
+    c.channels        = ["#cinch-bots"]
+
+    @autovoice        = true
+  end
+
+  on :join do |m|
+    unless m.user.nick == bot.nick # We shouldn't attempt to voice ourselves
+      m.channel.voice(m.user) if @autovoice
+    end
+  end
+
+  on :channel, /^!autovoice (on|off)/ do |m, option|
+    @autovoice = option == "on"
+
+    m.reply "Autovoice is now #{@autovoice ? 'enabled' : 'disabled'}"
+  end
+end
+
+bot.start

data/examples/basic/google.rb

@@ -0,0 +1,35 @@
+require 'cinch'
+require 'open-uri'
+require 'nokogiri'
+require 'cgi'
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server   = "irc.freenode.net"
+    c.nick     = "MrCinch"
+    c.channels = ["#cinch-bots"]
+  end
+
+  helpers do
+    # Extremely basic method, grabs the first result returned by Google
+    # or "No results found" otherwise
+    def google(query)
+      url = "http://www.google.com/search?q=#{CGI.escape(query)}"
+      res = Nokogiri::HTML(open(url)).at("h3.r")
+
+      title = res.text
+      link = res.at('a')[:href]
+      desc = res.at("./following::div").children.first.text
+    rescue
+      "No results found"
+    else
+      CGI.unescape_html "#{title} - #{desc} (#{link})"
+    end
+  end
+
+  on :message, /^!google (.+)/ do |m, query|
+    m.reply google(query)
+  end
+end
+
+bot.start

data/examples/basic/hello.rb

@@ -0,0 +1,15 @@
+require 'cinch'
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.freenode.org"
+    c.channels = ["#cinch-bots"]
+  end
+
+  on :message, "hello" do |m|
+    m.reply "Hello, #{m.user.nick}"
+  end
+end
+
+bot.start
+

data/examples/basic/join_part.rb

@@ -0,0 +1,38 @@
+require 'cinch'
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server   = "irc.freenode.org"
+    c.nick     = "CinchBot"
+    c.channels = ["#cinch-bots"]
+
+    # Who should be able to access these plugins
+    @admin = "injekt"
+  end
+
+  on :connect do
+    bot.join "#cinch"
+  end
+
+  helpers do
+    def is_admin?(user)
+      true if user.nick == @admin
+    end
+  end
+
+  on :message, /^!join (.+)/ do |m, channel|
+    bot.join(channel) if is_admin?(m.user)
+  end
+
+  on :message, /^!part(?: (.+))?/ do |m, channel|
+    # Part current channel if none is given
+    channel = channel || m.channel
+
+    if channel
+      bot.part(channel) if is_admin?(m.user)
+    end
+  end
+end
+
+bot.start
+