ircinch 2.4.0

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

data/docs/plugins.md

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

data/docs/readme.md

@@ -0,0 +1,20 @@
+# @title README
+# @markup kramdown
+
+
+- {file:docs/changes.md Changelog}
+- {file:docs/migrating.md Migration guides}
+
+# Important documents
+
+The following is a list of important documents to read.
+
+- {file:docs/bot_options.md Bot options}
+- {file:docs/common_tasks.md Common Tasks}
+- {file:docs/common_mistakes.md Common mistakes}
+- {Cinch::DCC DCC}
+- {file:docs/encodings.md Encodings}
+- {file:docs/logging.md Logging}
+- {Cinch::SASL SASL}
+- {Cinch::Formatting Formatting messages}
+- {file:docs/events.md Events}

data/examples/basic/autovoice.rb

@@ -0,0 +1,32 @@
+require "ircinch"
+
+# Give this bot ops in a channel and it'll auto voice
+# visitors
+#
+# Enable with !autovoice on
+# Disable with !autovoice off
+#
+# It starts out disabled.
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick = "ircinch_autovoice"
+    c.server = "irc.libera.chat"
+    c.verbose = true
+    c.channels = ["#ircinch-bots"]
+  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 "cgi"
+require "ircinch"
+require "nokogiri"
+require "open-uri"
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.nick = "MrIrCinch"
+    c.channels = ["#ircinch-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(URI.parse(url).open).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,14 @@
+require "ircinch"
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-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,35 @@
+require "ircinch"
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.nick = "IrCinchBot"
+    c.channels = ["#cinch-bots"]
+  end
+
+  # Who should be able to access these plugins
+  def admin
+    "injekt"
+  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 ||= m.channel
+
+    if channel
+      bot.part(channel) if is_admin?(m.user)
+    end
+  end
+end
+
+bot.start

data/examples/basic/memo.rb

@@ -0,0 +1,39 @@
+require "ircinch"
+
+class Memo < Struct.new(:nick, :channel, :text, :time)
+  def to_s
+    "[#{time.asctime}] <#{channel}/#{nick}> #{text}"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-bots"]
+  end
+
+  def memos
+    {}
+  end
+
+  on :message do |m|
+    if memos.has_key?(m.user.nick)
+      m.user.send memos.delete(m.user.nick).to_s
+    end
+  end
+
+  on :message, /^!memo (.+?) (.+)/ do |m, nick, message|
+    if memos.key?(nick)
+      m.reply "There's already a memo for #{nick}. You can only store one right now"
+    elsif nick == m.user.nick
+      m.reply "You can't leave memos for yourself.."
+    elsif nick == bot.nick
+      m.reply "You can't leave memos for me.."
+    else
+      memos[nick] = Memo.new(m.user.nick, m.channel, message, Time.now)
+      m.reply "Added memo for #{nick}"
+    end
+  end
+end
+
+bot.start

data/examples/basic/msg.rb

@@ -0,0 +1,15 @@
+require "ircinch"
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.nick = "IrCinchBot"
+    c.channels = ["#ircinch-bots"]
+  end
+
+  on :message, /^!msg (.+?) (.+)/ do |m, who, text|
+    User(who).send text
+  end
+end
+
+bot.start

data/examples/basic/seen.rb

@@ -0,0 +1,37 @@
+require "ircinch"
+
+class Seen < Struct.new(:who, :where, :what, :time)
+  def to_s
+    "[#{time.asctime}] #{who} was seen in #{where} saying #{what}"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-bots"]
+  end
+
+  def users
+    {}
+  end
+
+  # Only log channel messages
+  on :channel do |m|
+    users[m.user.nick] = Seen.new(m.user.nick, m.channel, m.message, Time.new)
+  end
+
+  on :channel, /^!seen (.+)/ do |m, nick|
+    if nick == bot.nick
+      m.reply "That's me!"
+    elsif nick == m.user.nick
+      m.reply "That's you!"
+    elsif users.key?(nick)
+      m.reply users[nick].to_s
+    else
+      m.reply "I haven't seen #{nick}"
+    end
+  end
+end
+
+bot.start

data/examples/basic/urban_dict.rb

@@ -0,0 +1,36 @@
+require "cgi"
+require "ircinch"
+require "nokogiri"
+require "open-uri"
+
+# This bot connects to urban dictionary and returns the first result
+# for a given query, replying with the result directly to the sender
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.nick = "MrIrCinch"
+    c.channels = ["#ircinch-bots"]
+  end
+
+  helpers do
+    # This method assumes everything will go ok, it's not the best method
+    # of doing this *by far* and is simply a helper method to show how it
+    # can be done.. it works!
+    def urban_dict(query)
+      url = "http://www.urbandictionary.com/define.php?term=#{CGI.escape(query)}"
+      CGI.unescape_html Nokogiri::HTML(URI.parse(url)).open.css("div.meaning").first.text.gsub(/\s+/, " ").strip
+    rescue
+      nil
+    end
+  end
+
+  on :message, /^!urban (.+)/ do |m, term|
+    m.reply(urban_dict(term) || "No results found", true)
+  end
+end
+
+bot.start
+
+# injekt> !urban cinch
+# MrIrCinch> injekt: describing an action that's extremely easy.

data/examples/basic/url_shorten.rb

@@ -0,0 +1,36 @@
+require "cgi"
+require "ircinch"
+require "open-uri"
+
+# Automatically shorten URL's found in messages
+# Using the tinyURL API
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-bots"]
+  end
+
+  helpers do
+    def shorten(url)
+      url = URI.open("http://tinyurl.com/api-create.php?url=#{CGI.escape(url)}").parse
+      (url == "Error") ? nil : url
+    rescue OpenURI::HTTPError
+      nil
+    end
+  end
+
+  on :channel do |m|
+    urls = URI.extract(m.message, "http")
+
+    unless urls.empty?
+      short_urls = urls.map { |url| shorten(url) }.compact
+
+      unless short_urls.empty?
+        m.reply short_urls.join(", ")
+      end
+    end
+  end
+end
+
+bot.start

data/examples/plugins/autovoice.rb

@@ -0,0 +1,37 @@
+require "ircinch"
+
+# Give this bot ops in a channel and it'll auto voice
+# visitors
+#
+# Enable with !autovoice on
+# Disable with !autovoice off
+
+class Autovoice
+  include Cinch::Plugin
+  listen_to :join
+  match(/autovoice (on|off)$/)
+
+  def listen(m)
+    unless m.user.nick == bot.nick
+      m.channel.voice(m.user) if @autovoice
+    end
+  end
+
+  def execute(m, option)
+    @autovoice = option == "on"
+
+    m.reply "Autovoice is now #{@autovoice ? "enabled" : "disabled"}"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.nick = "ircinch_autovoice"
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-bots"]
+    c.verbose = true
+    c.plugins.plugins = [Autovoice]
+  end
+end
+
+bot.start

data/examples/plugins/custom_prefix.rb

@@ -0,0 +1,22 @@
+require "ircinch"
+
+class SomeCommand
+  include Cinch::Plugin
+
+  set :prefix, /^~/
+  match "somecommand"
+
+  def execute(m)
+    m.reply "Successful"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-bots"]
+    c.plugins.plugins = [SomeCommand]
+  end
+end
+
+bot.start

data/examples/plugins/dice_roll.rb

@@ -0,0 +1,38 @@
+require "ircinch"
+
+class DiceRoll
+  include Cinch::Plugin
+
+  # [[<repeats>#]<rolls>]d<sides>[<+/-><offset>]
+  match(/roll (?:(?:(\d+)#)?(\d+))?d(\d+)(?:([+-])(\d+))?/)
+  def execute(m, repeats, rolls, sides, offset_op, offset)
+    repeats = repeats.to_i
+    repeats = 1 if repeats < 1
+    rolls = rolls.to_i
+    rolls = 1 if rolls < 1
+
+    total = 0
+
+    repeats.times do
+      rolls.times do
+        score = rand(sides.to_i) + 1
+        if offset_op
+          score = score.send(offset_op, offset.to_i)
+        end
+        total += score
+      end
+    end
+
+    m.reply "Your dice roll was: #{total}", true
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.libera.chat"
+    c.channels = ["#ircinch-bots"]
+    c.plugins.plugins = [DiceRoll]
+  end
+end
+
+bot.start