newton 0.0.1

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Dominik Honnef <dominikh@fork-bomb.org>
+
+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,189 @@
+# Newton – Adding new forces to your bots
+
+Newton started as a fork of
+[Isaac](http://github.com/ichverstehe/isaac). Nowadays, however, they
+only share 1% of code and basic DSL ideas and are not compatible to each other.
+
+## Features/characteristics
+### yard documentation
+
+Newton uses yard to document all available methods, providing detailed
+information on expected parameters, return values and raised
+exceptions. Where appropriate, examples are provided.
+
+### Extensive test suite using baretest
+Current status: planned
+
+Newton will use baretest to test all aspects of Newton. Right now we
+are waiting for the 0.5 release of baretest before we start writing
+any tests, as the 0.5 release will bring major changes.
+
+### Object-oriented interface
+
+One aspect of nearly all IRC bot frameworks written in Ruby is that
+they don't make use of OO but instead rely on a rather functional
+approach. This might make sense for **really** simple tasks, but as
+soon as you want to deal with more information or implement anything
+extensive, it gets hairy.
+
+Instead of passing around strings and having methods like
+`Bot#kick(channel, user, reason)`, Newton provides proper abstraction
+and object-orientation like `Channel#kick(user, reason)`.
+
+And whenever we do have to deal with strings (e.g. when matching
+commands), Newton provides `Channel(channel)` and `User(user)` helper
+methods.
+
+### Key/value store
+Current status: implemented
+
+Newton provides a basic key/value store (a Hash) to store information
+across different handler invocations:
+
+    configure do |c|
+      …
+      store[:messages] = []
+    end
+
+    on :channel, /^store this: (.+)$/ do |message|
+      store[:messages] << message
+    end
+
+### Threading
+
+Unlike most other IRC bot frameworks, Newton executes handlers each in
+its own thread. This prevents bots from locking up on long operations,
+but also means that bots have to be written with thread-safety in
+mind.
+
+#### synchronize(key) do .. end
+
+In order to avoid race conditions, Newton provides an easy way of
+synchronizing pieces of code using `synchronize`. Each call to
+synchronize expects a name and a block.
+
+    configure do |c|
+      …
+      store[:i] = 0
+    end
+
+    on :channel, /^start counting!/ do
+      synchronize(:my_counter) do
+        10.times do
+          val = store[:i]
+          # at this point, another thread might've incremented :i already.
+          # this thread wouldn't know about it, though.
+          store[:i] = val + 1
+        end
+      end
+
+      channel.send store[:i].to_s
+    end
+
+On any message that equals "start counting!", our bot will increment
+the value in `store[:i]` by 10, one for one.
+
+If we did not use `synchronize`, the value might not be higher by ten
+at the end of the loop because of known possible race conditions, at
+least in certain implementations of Ruby.
+
+### Constants
+
+Nobody is able to remember all IRC numeric replies (e.g. 401 for "no
+such nick"). Unfortunately, some frameworks, like for example Isaac,
+require you to uses those codes when hooking on errors (`on :error,
+401 do`). Those codes, however, also all have a name, e.g.
+ERR_NOSUCHNICK instead of 401 – and Newton provides all of those names
+as constants.
+
+### Known signals
+:ctcp
+: for CTCP requests
+:ping
+: Whenever the **server** pings us. Do not confuse this with CTCP PING
+:message
+: Applies to both channel and private messages
+:channel
+: On channel messages
+:private
+: On private messages (also refered to as "queries")
+:error
+: On errors returned by the server
+:disconnect
+: gets called when the connection to the server is being interrupted
+
+### Colorized log output
+
+Ever had to debug a bot and couldn't be arsed reading a wall of
+unformatted log output of IRC commands? Help is on its way! Newton
+will by default output colorized logs if printing to a terminal –
+output redirected to a file or pipe will remain without color codes.
+
+### Customg logging
+
+If you want to print debug statements, you can use
+`FormattedLogger.debug(message)`.
+
+### Just a note on fork()
+
+Because of how Newton internally works, reusing a bot in a forked Ruby
+process will yield unexpected results.
+
+### Flood control
+
+Newton tries to optimize the use of the local send queue as well as
+the receive queue of the IRC server. This means that Newton will send
+as many messages as possible without any delay, while at the same time
+making sure that we won't be kicked for excess flood. Newton does this
+by calculating the amount of messages the server is likely to have
+processed and comparing that value to the maximum allowed number of
+messages in the receive queue.
+
+#### Planned feature
+Note: the following is just an idea.
+
+Furthermore, Newton sorts the send queue to make sure that important
+messages (PING replies, mostly) are sent before any other messages.
+Additionally, if the queue contains messages targeted at different
+receivers (say, different channels), they will be sorted in a fair
+way.
+
+Example:
+- we got 4 channels, "A", "B", "C" and "D"
+- we send 2 messages to each channel. first 2 to "A", then 2 to "B" and so on
+
+A naive queue would send the messages in this order:
+A, A, B, B, C, C, D, D
+
+Newton's queue, however, will order them in this way:
+A, B, C, D, A, B, C, D
+
+This will indeed mean a higher perceived delay for each individual
+channel. It will, however, make sure that all channels will be treated
+fair.
+
+### ISUPPORT
+
+Newton parses and understands
+[ISUPPORT](http://www.irc.org/tech_docs/005.html) and thus provides
+adequate error handling, mode parsing and checks.
+
+#### Strictness
+
+Newton can operate in two different modes: _strict_ and _forgiving_.
+Those can be set using the _strictness_ option.
+
+##### strict
+
+When invoking unsupported IRC commands (e.g. KNOCK) or disobeying
+limits like the max length of topics, Newton will raise an exception.
+
+##### forgiving
+
+Unsupported IRC commands will still be sent to the server and length
+restrictions will just be ignored (in most cases, the server will
+truncate overlong information)
+
+## Examples
+
+See _examples/_

data/Rakefile

@@ -0,0 +1,6 @@
+task :default => :test
+
+task :test do
+  require 'rake/runtest'
+  Rake.run_tests
+end

data/examples/autovoice.rb

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+require 'newton'
+
+# Give this bot ops in a channel and it'll auto voice
+# visitors
+#
+# Enable with !autovoice on
+# Disable with !autovoice off
+
+bot = Newton::Bot.new do
+  configure do |c|
+    c.nick    = "newton_autovoice"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+    c.verbose = true
+
+    store[:autovoice] = true
+  end
+
+  on :connect do
+    join "#dominikh-tests"
+  end
+
+  on :join do
+    unless user == bot # don't try to voice ourself
+      channel.voice(user) if store[:autovoice]
+    end
+  end
+
+  on :message, "!autovoice on" do
+    if channel.opped?(user)
+      store[:autovoice] = true
+      reply "Autovoicing is now enabled"
+    end
+  end
+
+  on :message, "!autovoice off" do
+    if channel.opped?(user)
+      store[:autovoice] = false
+      reply "Autovoicing is now disabled"
+    end
+  end
+end
+
+bot.start

data/examples/echo_bot.rb

@@ -0,0 +1,22 @@
+$LOAD_PATH.unshift '../lib'
+
+require 'newton'
+
+bot = Newton::Bot.new do
+  configure do |c|
+    c.nick    = "echo_bot"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+    c.verbose = true
+  end
+
+  on :connect do
+    join "#dominikh-tests"
+  end
+
+  on :message do
+    reply message
+  end
+end
+
+bot.start

data/examples/excess_flood.rb

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift '../lib'
+require 'newton'
+
+bot = Newton::Bot.new do
+  configure do |c|
+    c.nick    = "The_Echo_Bot"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+    c.verbose = true
+  end
+
+  on :connect do
+    join "#dominikh-tests"
+  end
+
+  on :channel, /flood/ do
+    20.times do |i|
+      reply "#{i}:: Let me take you down to the city for a while, just a little while, oh yes. This should never exceed, plz thx u"
+    end
+  end
+end
+
+bot.start

data/examples/memo.rb

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+require 'newton'
+
+class Memo < Struct.new(:user, :channel, :text, :time)
+  def to_s
+    "[%s] <%s/%s> %s" % [time.asctime, channel.name, user.nick, text]
+  end
+end
+
+bot = Newton::Bot.new do
+  configure do |c|
+    c.nick    = "newton_memo"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+    c.verbose = true
+
+    store[:memos] = Hash.new {|h,k| h[k] = []}
+  end
+
+  on :connect do
+    join "#dominikh-tests"
+  end
+
+  on :message do
+    unless store[:memos][user].empty?
+      while memo = store[:memos][user].shift
+        user.send memo
+      end
+    end
+  end
+
+  on :message, /^test (.+) (.+)$/ do |a, b|
+    p [a, b]
+  end
+
+  on :message, /^!memo (\S+) (.+)$/ do |target, text|
+    p [target, text]
+    target = User(target)
+    if user == target
+      reply "You cannot leave memos for yourself.", true
+    elsif target == bot
+      reply "You cannot leave memos for me.", true
+    else
+      store[:memos][target] << Memo.new(user, channel, text, Time.now)
+      reply "Memo for #{target} recorded.", true
+    end
+  end
+end
+
+bot.start

data/examples/schema.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH.unshift '../lib'
+require 'newton'
+
+bot = Newton::Bot.new do
+  configure do |c|
+    c.nick    = "SomeBot"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+    c.realname = 'Isaac Hayes'
+    c.verbose  = true
+  end
+
+  helpers do
+    def check(channel)
+      channel.send "this channel, #{channel}, is awesome!"
+    end
+  end
+
+  on :connect do
+    join "#dominikh-tests"
+    User("asdfhaskfdhaskdfhaskdfasdf").send "foo"
+  end
+
+  on :private, /^t (.*)/ do |text|
+    reply "You said: " + text
+  end
+
+  on :channel, /quote/ do
+    reply "#{user} requested a quote: 'Smoking, a subtle form of suicide.' - Vonnegut"
+  end
+
+  on :channel, /status/ do
+    check(channel)
+  end
+
+  on :error, ERR_NOSUCHNICK do
+    debug "Ok, #{params[1]} doesn't exist."
+  end
+end
+
+bot.start

data/examples/secure_eval.rb

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+require 'newton'
+
+bot = Newton::Bot.new do
+  configure do |c|
+    c.nick    = "newton_eval"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+    c.verbose = true
+
+    store[:allowed_users] = %w(DominikH)
+  end
+
+  helpers do
+    def allowed_user?(user)
+      # First we want to refresh the user's information (to prevent
+      # identity theft)…
+      user.whois
+
+      store[:allowed_users].include?(user.authname)
+    end
+  end
+
+  on :connect do
+    join "#dominikh-tests"
+  end
+
+  on :message, /^!eval (.+)/ do |command|
+    if allowed_user?(user)
+      reply eval(command), true
+    else
+      reply "You are not allowed to evaluate ruby statements"
+    end
+  end
+
+  on :message, /^allow (.+)/ do |target|
+    if allowed_user?(user)
+      store[:allowed_users] << target
+      reply "User added"
+    else
+      reply "You are not allowed to add new users", true
+    end
+  end
+end
+
+bot.start

data/lib/newton/ban.rb

@@ -0,0 +1,40 @@
+require "newton/mask"
+module Newton
+  class Ban
+    # @return [Mask, String]
+    attr_reader :mask
+
+    # @return [String]
+    attr_reader :by
+
+    # @return [Time]
+    attr_reader :created_at
+
+    # @return [Boolean]
+    attr_reader :extended
+
+    def initialize(mask, by, at)
+      @by, @created_at = by, at
+      if mask =~ /^\$/
+        @extended = true
+        @mask     = mask
+      else
+        @extended = false
+        @mask = Mask.new(mask)
+      end
+    end
+
+    # @return [Boolean] true if the ban matches `user`
+    # @raise [Exceptions::UnsupportedFeature] Newton does not support Freenode's extended bans
+    def match(user)
+      raise UnsupportedFeature, "extended bans (freenode) are not supported yet" if @extended
+      @mask =~ user
+    end
+    alias_method :=~, :match
+
+    # @return [String]
+    def to_s
+      @mask.to_s
+    end
+  end
+end