sponge 0.2.8

data/README.rdoc

@@ -0,0 +1,30 @@
+== Sponge
+
+Sponge is a simple, lightweight IRC library for Ruby.
+
+
+== Example
+  
+See http://rdoc.injekt.net/sponge/Sponge/IRC/Client.html for a quick example
+
+
+== Notes
+
+Please note that this is an early release. Though the code should work fine, there
+are no specs and it lacks documenation. These will be added soon.
+
+== Installation
+
+  gem install sponge
+  
+or alternatively you can checkout the latest revision from github
+
+  git clone git://github.com/injekt/sponge
+
+
+== TODO
+
+* Finish this README
+* Create specs
+* Complete documentation
+* Create more rake tasks

data/Rakefile

@@ -0,0 +1,54 @@
+require "rake"
+require "rake/clean"
+require "rake/gempackagetask"
+require "find"
+require "rake/rdoctask"
+require "lib/sponge/version"
+ 
+NAME = 'sponge'
+VERSION = Sponge::VERSION
+TITLE = "Sponge: The simple IRC library"
+CLEAN.include ["*.gem", ".config", "rdoc"]
+RDOC_OPTS = [
+  "--line-numbers", "--inline-source",
+  "--title", TITLE,
+  "--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
+
+desc "Package sponge"
+task :package=>[:clean] do |p|
+  sh "gem build #{NAME}.gemspec"
+end
+
+desc "Install gem"
+task :install=>[:package] do
+  sh "sudo gem install ./#{NAME}-#{VERSION} --local"
+end
+ 
+desc "Uninstall gem"
+task :uninstall=>[:clean] do
+  sh "sudo gem uninstall #{NAME}"
+end
+ 
+desc "Upload gem to gemcutter"
+task :release=>[:package] do
+  sh "gem push ./#{NAME}-#{VERSION}.gem"
+end
+
+desc "Print latest #{NAME} version"
+task :version do
+  puts VERSION
+end
+
+desc "Upload rdoc to injekt.net"
+task :upload do
+  sh("scp -rP 2295 rdoc/ injekt@injekt.net:/var/www/localhost/rdoc.injekt.net/sponge")
+end
+
+task :default => [:rdoc, :package]

data/examples/client.rb

@@ -0,0 +1,20 @@
+require 'sponge'
+
+client = Sponge::IRC::Client.new do
+  server "irc.freenode.org"
+  nickname "Sponge"
+end
+
+# 376 is the command for end of motd
+client.on "376" do |irc, message|
+  irc.join "#mychannel"
+end
+
+# Add a callback for when someone (including ourselves) joins a channel
+client.on "JOIN" do |irc, message|
+  unless message.nick == 'Sponge'
+    message.reply "Hi there #{message.nick}, welcome to #{message.channel}!"
+  end
+end
+
+client.run

data/examples/socket.rb

@@ -0,0 +1,9 @@
+require 'sponge'
+
+sock = Sponge::IRC::Socket.open('irc.freenode.org')
+sock.nick "SpongeBot"
+sock.user "SpongeBot", "sponge", "sponge", "Sponge IRC bot"
+sock.join "#mychan"
+sock.privmsg "#mychan", "Hello!"
+sock.part "#mychan"
+sock.quit "Quitting.."

data/lib/sponge.rb

@@ -0,0 +1,23 @@
+# Copyright (c) 2010 Lee 'injekt' Jarvis <ljjarvis@gmail.com>
+# All files in this distribution are subject to the terms of the Ruby license.
+
+module Sponge
+  BASE = File.expand_path(File.dirname(__FILE__))
+  $LOAD_PATH.unshift(BASE)
+  
+  # Stdlib
+  require 'socket'
+  require 'pp'
+  require 'ostruct'
+  
+  # Sponge core
+  require 'sponge/version'
+  
+  # IRC library
+  require 'sponge/irc/socket'
+  require 'sponge/irc/parser'
+  require 'sponge/irc/message'
+  require 'sponge/irc/user'
+  require 'sponge/irc/client'
+  require 'sponge/irc/listeners'
+end

data/lib/sponge/irc/client.rb

@@ -0,0 +1,158 @@
+module Sponge
+  module IRC
+    
+    # == Author
+    # * Lee Jarvis - ljjarvis@gmail.com
+    #
+    # == Description
+    # TODO
+    #
+    # == Usage
+    #
+    # === Minimal Example
+    #   client = Sponge::IRC::Client.new do
+    #     server "irc.freenode.org"
+    #     nickname "MyNick"
+    #   end
+    #
+    #   client.run
+    #
+    # === Mapping a Listener
+    #   client = Sponge::IRC::Client.new do
+    #     server "irc.freenode.org"
+    #     nickname "MyNick"
+    #     realname "Mr Sponge Bot"
+    #   end
+    #
+    #   # Join a channel once we've seen end of MOTD
+    #   client.on(376) do |irc, message|
+    #     irc.join "#mychan"
+    #   end
+    #
+    #   client.on(:JOIN) do |irc, message|
+    #     message.reply "Hi #{message.nick}. Welcome to #{message.channel}!"
+    #   end
+    #
+    #   client.run
+    class Client
+      # The current IRC::Socket this Client is using
+      attr_reader :irc
+      
+      # Client configuration options
+      attr_reader :config
+      
+      def initialize(server=nil, opts={}, &blk)
+        @config = OpenStruct.new(opts.merge(OptionsDSL.new(server, &blk).options))
+        @config.port ||= 6667
+        
+        @irc = IRC::Socket.new(config.server, config.port)
+        @irc.client = self
+        @parser = IRC::Parser.new(self)
+        @listeners = IRC::Listeners.new(self)
+        
+        setup_username
+      end
+      
+      # Start our connection
+      def connect
+        puts "Connecting to #{irc.server} on #{irc.port}"
+        irc.connect unless irc.connected?
+
+        irc.nick(config.nickname)
+        irc.user(config.username, config.hostname, "*", config.realname)
+                
+        puts "Connected" if irc.connected?
+      end
+      
+      # Map listeners to an IRC command. For example:
+      #
+      #   client.on("376") do |irc, message|
+      #     irc.join "#mychan"
+      #   end
+      #
+      #   client.on(:JOIN) do |irc, message|
+      #     message.reply "Hi, #{message.nick}. Welcome to #{message.channel}"
+      #   end
+      #
+      # * +irc+ - The Clients Sponge::IRC::Socket
+      # * +message+ - The current Sponge::IRC::Message
+      def on(*commands, &blk)
+        @listeners.add(*commands, &blk)
+      end
+      
+      # Change clients nickname
+      def set_nick(new)
+        config.nickname = new
+        @irc.nick(new)
+      end
+      
+      # Sugar for IRC::Parser#parse
+      def process(data)
+        message = @parser.parse(data)
+        @listeners.handle(message) if message
+      end
+      
+      # Reads the next line from the IRC server whilst we're connected.
+      # Sends the line to #process
+      def run
+        connect unless irc.connected?
+        process(irc.read) while irc.connected?
+      end
+      
+      # Quit our IRC socket and exit the Client
+      def quit
+        @irc.quit
+        exit
+      end
+      
+      private
+      
+      def setup_username
+        raise "You must set a nickname" unless nick = config.nickname
+        config.username ||= nick
+        config.hostname ||= nick
+        config.realname ||= nick
+      end
+     
+      # == Author
+      # * Lee Jarvis - ljjarvis@gmail.com
+      #
+      # == Description
+      # TODO
+      class OptionsDSL
+        attr_reader :options
+        
+        def initialize(server=nil, &blk)
+          @options = {}
+          server(server) if server         
+          instance_eval(&blk)
+        end
+        
+        def server(val)
+          @options[:server] = val
+        end
+        
+        def port(val)
+          @options[:port] = val
+        end
+        
+        def nickname(val)
+          @options[:nickname] = val
+        end
+        
+        def username(val)
+          @options[:username] = val
+        end
+        
+        def hostname(val)
+          @options[:hostname] = val
+        end
+        
+        def realname(val)
+          @options[:realname] = val
+        end
+      end
+      
+    end
+  end
+end

data/lib/sponge/irc/listeners.rb

@@ -0,0 +1,69 @@
+module Sponge
+  module IRC
+    
+    # == Author
+    # * Lee Jarvis
+    #
+    #
+    #
+    class Listeners
+      
+      # == Author
+      # * Lee Jarvis
+      #
+      #
+      class Listener
+        def initialize(command, &blk)
+          @callback = blk
+        end
+        
+        def call(*args)
+          @callback.call(args)
+        end
+      end
+      
+      # The IRC::Client using this Listener List
+      attr_reader :client
+      
+      def initialize(client)
+        @client = client
+        @list = {}
+        
+        # Add the default PING reply
+        add(:PING) {|i, m| i.pong(m.text) }
+      end
+      
+      # Add a new Listener to the Listener List
+      # * See IRC::Client#on
+      def add(*commands, &blk)
+        commands.each do |command|
+          command = command.to_s
+          raise "listener for #{command} already exists" if @list.key?(command)
+          @list[command] = Listener.new(command, &blk)
+        end
+      end
+      
+      # Remove a listener from our list
+      def delete(command)
+        @list.delete(command)
+      end
+      
+      def [](command)
+        @list[command]
+      end
+      
+      # Invoke #call on a Listener if it exists passing an IRC::Message
+      def handle(message)
+        raise "Not a IRC::Message" unless message.is_a?(Sponge::IRC::Message)
+        if @list.key?(message.command)
+          @list[message.command].call(client.irc, message)
+        end
+      end
+      
+      def all
+        @list
+      end
+    
+    end
+  end
+end

data/lib/sponge/irc/message.rb

@@ -0,0 +1,90 @@
+module Sponge
+  module IRC
+    
+    # == Author
+    # * Lee Jarvis
+    #
+    # == Description
+    # This class should *only* be used by IRC::Parser
+    #
+    # == Synopsis
+    #
+    #
+    class Message
+      
+      # Our IRC::Client
+      attr_reader :client
+      
+      # Our IRC::Socket instance
+      attr_reader :irc
+      
+      # The raw IRC string received from the server
+      attr_reader :raw
+      
+      # The message prefix passed from IRC::Parser
+      attr_reader :prefix
+      
+      # The IRC Command (PRIVMSG, MODE, 376, 372, etc)
+      attr_reader :command
+      
+      # Channel the message is for
+      attr_accessor :channel
+      
+      # The channel or the client name (if it's a private message)
+      attr_reader :for
+      
+      # The IRC::User this message is from
+      attr_accessor :from
+      
+      # The nick the message is from (sugar for IRC::User#nick)
+      attr_accessor :nick
+      
+      # Message text
+      attr_accessor :text
+      
+      # All params
+      attr_reader :params
+      
+      def initialize(client, raw, prefix, command, params)
+        @client = client
+        @irc = client.irc
+        @raw = raw
+        @prefix = prefix
+        @command = command
+        @params = []
+        params.scan(/(?!:)(\S+)|:(.*)/) { @params << ($1 || $2) } if params
+        
+        @channel = nil
+        @for = nil
+        @from = nil
+        @nick = nil
+      end
+      
+      def for=(who)
+        @for = who
+        @channel = who if who =~ /^[\#&]+/
+      end
+      
+      def private?
+        @channel
+      end
+      
+      def public?
+        !@channel
+      end
+      
+      # Reply to a message with a PRIVMSG back to the sender (channel or nick)
+      def reply(message)
+        who = channel || from
+        @irc.privmsg(who, message)
+      end
+      
+      # Reply to a user with their nickname prefix'd
+      def answer(message)
+        return unless nick && channel
+        @irc.privmsg(channel, [nick, message].join(': '))
+      end
+      
+    end
+  end
+end

data/lib/sponge/irc/parser.rb

@@ -0,0 +1,41 @@
+module Sponge
+  module IRC
+    
+    # == Author
+    # * Lee Jarvis - ljjarvis@gmail.com
+    #
+    # == Description
+    #
+    # == Synopsis
+    #
+    class Parser
+
+      # Our IRC::Client instance
+      attr_reader :client
+      
+      def initialize(client)
+        @client = client
+      end
+      
+      # Parses a raw IRC server message and returns a nicely encapsulated IRC::Message
+      # for you to play with
+      def parse(data)
+        return unless data
+        raise "Unknown Message" unless matches = data.match(/\A(?:\:(\S+)\s)?([A-Z0-9]+?)\s(.+?)\Z/)
+        prefix, command, params = matches.captures
+        
+        message = IRC::Message.new(client, data, prefix, command, params)
+        message.for = message.params.first
+        message.text = message.params.last
+        
+        if prefix && usermatch = prefix.match(/^(\S+?)!(\S+?)@(\S+?)$/)
+          message.from = IRC::User.new(client, *usermatch.captures)
+          message.nick = message.from.nick
+        end
+        
+        message
+      end
+      
+    end
+  end
+end

data/lib/sponge/irc/socket.rb

@@ -0,0 +1,165 @@
+module Sponge
+  module IRC
+    
+    # == Author
+    # * Lee Jarvis - ljjarvis@gmail.com
+    #
+    # == Description
+    # Sponge::IRC::Socket is a simple wrapper around TCPSocket. It provides simple
+    # functionality to interact with IRC servers.
+    #
+    # Note that when creating a new IRC::Socket, I generally assign the instance to a
+    # variable named <em>irc</em> throughout the documentation.
+    #
+    # == Synopsis
+    #   irc = Sponge::IRC::Socket.open('irc.2600.net')
+    #   irc.nick "SpongeBot"
+    #   irc.user "SpongeBot", "sponge", "sponge", "Sponge IRC bot"
+    #   irc.join "#mychan"
+    #   irc.privmsg "#mychan", "Hello!"
+    #   irc.part "#mychan"
+    #   irc.quit "Quitting.."
+    #
+    class Socket
+ 
+      # The Client using this Socket (if one at all)
+      attr_accessor :client
+      
+      # The server address we're connected to
+      attr_reader :server
+      
+      # The port our socket is connected on
+      attr_reader :port
+      
+      # Create a new IRC::Socket and connect to it
+      def self.open(server, port=6667)
+        sock = new(server, port)
+        sock.connect
+        sock
+      end
+    
+      # Creates a new IRC::Socket. This doesn't automatically connect.
+      # If you want to do that use IRC::Socket.open
+      def initialize(server, port=6667)
+        @server = server
+        @port = port
+        
+        @client = nil
+        @connected = false
+      end
+      
+      # Connect to our IRC server if we haven't already connected
+      def connect
+        return if connected?
+        
+        @socket = TCPSocket.new(server, port)
+      rescue Interrupt
+        raise
+      rescue Exception
+        raise
+      else
+        @connected = true
+      end
+      
+      # Check if our Socket is currently connected to a server
+      def connected?
+        @connected
+      end
+      
+      # Send a message to our server, appending CR-LF
+      def write(data)
+        @socket.print(data + "\r\n")
+      rescue IOError
+        raise
+      end
+      
+      # Read the next line from the server. Chomps the trailing CR-LF
+      # Returns nil if there are issues with reading from the Socket.
+      # This method also safely shuts down our IRC::Socket by sending
+      # the QUIT command before exiting, it then closes the socket and exits
+      # the program.
+      def read
+        if data = @socket.gets
+          data.chomp("\r\n")
+        else
+          @connected = false
+          nil
+        end
+      rescue Interrupt
+        puts "\nInterrupted. Shutting down safely."
+        if connected?
+          quit("Client Interrupted")
+          close
+          exit 1
+        end
+      rescue IOError
+        @connected = false
+        nil
+      end
+      
+      # Close our socket
+      def close
+        @socket.close
+      rescue IOError
+      end
+        
+      # Send the USER command, usually to log into the server
+      def user(user, host, server, real)
+        write("USER #{user} #{host} #{server} :#{real}")
+      end
+      
+      # Change our nickname
+      def nick(nick)
+        write("NICK #{nick}")
+      end
+      
+      # Send a PRIVMSG to a specific user or channel
+      def privmsg(recipient, message)
+        write("PRIVMSG #{recipient} :#{message}")
+      end
+      
+      # Send a NOTICE to a specific user or channel
+      def notice(recipient, message)
+        write("NOTICE #{recipient} :#{message}")
+      end
+      
+      # Join a channel, using a password is necessary
+      def join(channel, password=nil)
+        write("JOIN #{channel}#{password ? password : ''}")
+      end
+      
+      # Part a channel(s)
+      def part(*channels)
+        write("PART #{channels.join(',')}")
+      end
+      
+      # Set the topic on a given channel
+      def topic(channel, topic)
+        write("TOPIC #{channel} :#{topic}")
+      end
+      
+      # Kick nick from channel
+      def kick(channel, nick, reason="")
+        write("KICK #{channel} #{nick} :#{reason}")
+      end
+      
+      # Send a PONG command 
+      def pong(server)
+        write("PONG #{server}")
+      end
+      
+      # Set ourselves as being away, (or not-away if a message is not given)
+      def away(message=nil)
+        write("AWAY#{message ? ':'+message : ''}")
+      end
+      
+      # Send the QUIT command to our IRC server
+      # This also closes our IRC::Socket
+      def quit(reason="Cya!")
+        write("QUIT :#{reason}")
+        close
+      end
+      
+    end
+  end
+end

data/lib/sponge/irc/user.rb

@@ -0,0 +1,35 @@
+module Sponge
+  module IRC
+    class User
+      
+      # Our IRC::Client
+      attr_reader :client
+      
+      # The nickname of this User
+      attr_reader :nick
+      
+      # The username of this User
+      attr_reader :user
+      
+      # The hostname of this User
+      attr_reader :host
+      
+      def initialize(client, nick, user, host)
+        @client = client
+        @nick = nick
+        @user = user
+        @host = host
+      end
+      
+      # Check if the User is us
+      def me?
+        client.config.nickname == nick
+      end
+      
+      def to_s
+        @nick
+      end
+      
+    end
+  end
+end

data/lib/sponge/version.rb

@@ -0,0 +1,12 @@
+module Sponge
+  MAJOR = 0
+  MINOR = 2
+  TINY = 8
+  
+  VERSION = [MAJOR, MINOR, TINY].join('.')
+  
+  # The current Version of Sponge you're using
+  def self.version
+    VERSION
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: sponge
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 8
+  version: 0.2.8
+platform: ruby
+authors: 
+- Lee 'injekt' Jarvis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-05 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: A simple IRC library
+email: ljjarvis@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- examples/client.rb
+- examples/socket.rb
+- lib/sponge/version.rb
+- lib/sponge/irc/listeners.rb
+- lib/sponge/irc/client.rb
+- lib/sponge/irc/message.rb
+- lib/sponge/irc/socket.rb
+- lib/sponge/irc/user.rb
+- lib/sponge/irc/parser.rb
+- lib/sponge.rb
+has_rdoc: true
+homepage: http://rdoc.injekt.net/sponge
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --quiet
+- --line-numbers
+- --inline-source
+- --title
+- "Sponge: The Simple IRC library"
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 8
+      - 4
+      version: 1.8.4
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A simple IRC library
+test_files: []
+