irc-socket 0.9

data/README.rdoc

@@ -0,0 +1,39 @@
+== Description
+
+IRCSocket is an IRC wrapper around a TCPSocket. It implements all of the major 
+commands laid out in {RFC 2812}[http://irchelp.org/irchelp/rfc/rfc2812.txt].
+All these commands are available as instance methods of an IRCSocket Object.
+
+API documentation is available {here}[http://rdoc.injekt.net/irc-socket]
+
+== Example
+ irc = IRCSocket.new('irc.freenode.org')
+ irc.connect
+
+ if irc.connected?
+   irc.nick "HulkHogan"
+   irc.user "Hulk", 0, "*", "I am Hulk Hogan"
+
+   while line = irc.read
+        
+     # Join a channel after MOTD
+     if line.split[1] == '376'
+       irc.join "#mychannel"
+     end
+
+     puts "Received: #{line}"
+   end
+ end
+
+== Installation
+ gem install irc-socket
+
+Or alternatively you can clone the Github repository
+ git clone https://github.com/injekt/irc-socket
+
+
+== Author
+* Lee Jarvis - ljjarvis@gmail.com
+
+== Notes
+I may have missed something in the RFC. Patches welcome.  

data/Rakefile

@@ -0,0 +1,58 @@
+require "rake"
+require "rake/clean"
+require "rake/gempackagetask"
+require "spec/rake/spectask"
+require "rake/rdoctask"
+
+NAME = 'irc-socket'
+VERSION = '0.9'
+CLEAN.include ["*.gem", "rdoc"]
+
+RDOC_OPTS = [
+  "-U", "--main", "README.rdoc",
+  "--op", "rdoc",
+]
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add %w(README.rdoc lib/irc-socket.rb)
+end
+
+desc "Run specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = Dir['spec/*.rb']
+end
+
+desc "Package"
+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 #{NAME} version"
+task :version do
+  puts VERSION
+end
+
+desc "Upload rdoc to injekt.net"
+task :upload => [:clean, :rdoc] do
+  sh("scp -r rdoc/* injekt@injekt.net:/var/www/injekt.net/rdoc/irc-socket")
+end
+
+task :default => [:spec]
+

data/lib/irc-socket.rb

@@ -0,0 +1,290 @@
+require 'socket'
+
+# == Author
+# * Lee Jarvis - ljjarvis@gmail.com
+#
+#
+# == Description
+#
+# IRCSocket is an IRC wrapper around a TCPSocket. It implements all of the major 
+# commands laid out in {RFC 2812}[http://irchelp.org/irchelp/rfc/rfc2812.txt].
+# All these commands are available as instance methods of an IRCSocket Object.
+#
+# == Example
+#  irc = IRCSocket.new('irc.freenode.org')
+#  irc.connect
+#
+#  if irc.connected?
+#    irc.nick "HulkHogan"
+#    irc.user "Hulk", 0, "*", "I am Hulk Hogan"
+#
+#    while line = irc.read
+#         
+#      # Join a channel after MOTD
+#      if line.split[1] == '376'
+#        irc.join "#mychannel"
+#      end
+#
+#      puts "Received: #{line}"
+#    end
+#  end
+#
+# === Block Form
+#  IRCSocket.new('irc.freenode.org') do |irc|
+#    irc.nick "SpongeBob"
+#    irc.user "Spongey", 0, "*", "Square Pants"
+#
+#    puts irc.read
+#  end
+class IRCSocket
+
+  # The server our socket is connected to
+  attr_reader :server
+
+  # The port our socket is connected on
+  attr_reader :port
+
+  # The TCPSocket instance
+  attr_reader :socket
+
+  # Creates a new IRCSocket and automatically connects
+  #
+  # === Example
+  #  irc = IRCSocket.open('irc.freenode.org')
+  #
+  #  while data = irc.read
+  #    puts data
+  #  end
+  def self.open(server, port=6667)
+    irc = new(server, port)
+    irc.connect
+    irc
+  end
+  
+  # Create a new IRCSocket to connect to +server+ on +port+. Defaults to port 6667.
+  # If an optional code block is given, it will be passed an instance of the IRCSocket.
+  # NOTE: Using the block form does not mean the socket will send the applicable QUIT
+  # command to leave the IRC server. You must send this yourself.
+  def initialize(server, port=6667)
+    @server = server
+    @port = port
+
+    @socket = nil
+    @connected = false
+
+    if block_given?
+      connect
+      yield self      
+    end
+  end
+  
+  # Check if our socket is alive and connected to an IRC server
+  def connected?
+    @connected
+  end
+  alias connected connected?
+  
+  # Connect to an IRC server, returns true on a successful connection, or
+  # raises otherwise
+  def connect
+    @socket = TCPSocket.new(server, port)
+  rescue Interrupt
+    raise
+  rescue Exception
+    raise
+  else
+    @connected = true
+  end
+
+  # Read the next line in from the server. If no arguments are passed
+  # the line will have the CRLF chomp'ed. Returns nil if no data could be read
+  def read(chompstr="\r\n")
+    if data = @socket.gets("\r\n")
+      data.chomp(chompstr) if chompstr
+      data
+    else
+      nil
+    end
+  rescue IOError
+    nil
+  end
+
+  # Write to our Socket and append CRLF
+  def write(data)
+    @socket.write(data + "\r\n")
+  rescue IOError
+    raise
+  end
+
+  # Sugar for #write
+  def raw(*args) # :nodoc:
+    args.last.insert(0, ':') unless args.last.nil?
+    args.join(' ').strip
+  end
+
+  # More sugar
+  def write_optional(command, *optional) # :nodoc:
+    command = "#{command} #{optional.join(' ')}" if optional
+    write(command.strip)
+  end
+  private :raw, :write_optional
+
+  # Send PASS command
+  def pass(password)
+    write("PASS #{password}")
+  end
+
+  # Send NICK command
+  def nick(nickname)
+    write("NICK #{nickname}")
+  end
+
+  # Send USER command - 
+  def user(user, mode, unused, realname)
+    write("USER #{user} #{mode} #{unused} :#{realname}")
+  end
+
+  # Send OPER command
+  def oper(name, password)
+    write("OPER #{name} #{password}")
+  end
+
+  # Send the MODE command.
+  # Should probably implement a better way of doing this
+  def mode(channel, *modes)
+    write("MODE #{channel} #{modes.join(' ')}")
+  end
+
+  # Send QUIT command
+  def quit(message=nil)
+    raw("QUIT", message)
+  end
+
+  # Send JOIN command - Join a channel with given password
+  def join(channel, password=nil)
+    write("JOIN #{channel}")
+  end
+
+  # Send PART command - 
+  def part(channel, message=nil)
+    raw("PART", channel, message)
+  end
+
+  # Send TOPIC command
+  def topic(channel, topic=nil)
+    raw("TOPIC", channel, topic)
+  end
+
+  # Send NAMES command
+  def names(*channels)
+    write("NAMES #{channels.join(',') unless channels.empty?}")
+  end
+
+  # Send LIST command
+  def list(*channels)
+    write("LIST #{channels.join(',') unless channels.empty?}")
+  end
+
+  # Send INVITE
+  def invite(nickname, channel)
+    write("INVITE #{nickname} #{channel}")
+  end
+
+  # Send KICK
+  def kick(channel, user, comment=nil)
+    raw("KICK", channel, user, comment)
+  end
+
+  # Send PRIVMSG
+  def privmsg(target, message)
+    write("PRIVMSG #{target} :#{message}")
+  end
+
+  # Send NOTICE
+  def notice(target, message)
+    write("NOTICE #{target} :#{message}")
+  end
+
+  # Send MOTD
+  def motd(target=nil)
+    write_optional("MOTD", target)
+  end
+
+  # Send VERSION
+  def version(target=nil)
+    write_optional("VERSION", target)
+  end
+
+  # Send STATS
+  def stats(*params)
+    write_optional("STATS", params)
+  end
+
+  # Send TIME
+  def time(target=nil)
+    write_optional("TIME", target)
+  end
+
+  # Send INFO
+  def info(target=nil)
+    write_optional("INFO", target)
+  end
+
+  # Send SQUERY
+  def squery(target, message)
+    write("SQUERY #{target} :#{message}")
+  end
+
+  # Send WHO
+  def who(*params)
+    write_optional("WHO", params)
+  end
+
+  # Send WHOIS
+  def whois(*params)
+    write_optional("WHOIS", params)
+  end
+
+  # Send WHOWAS
+  def whowas(*params)
+    write_optional("WHOWAS", params)
+  end
+
+  # Send KILL
+  def kill(user, message)
+    write("KILL #{user} :#{message}")
+  end
+
+  # Send PING
+  def ping(server)
+    write("PING #{server}")
+  end
+
+  # Send PONG
+  def pong(server)
+    write("PONG #{server}")
+  end
+
+  # Send AWAY
+  def away(message=nil)
+    raw("AWAY", message)
+  end
+
+  # Send USERS
+  def users(target=nil)
+    write_optional("USERS", target)
+  end
+
+  # Send USERHOST
+  def userhost(*users)
+    write("USERHOST #{users.join(' ')}")
+  end
+
+  # Close our socket instance
+  def close
+    @socket.close if connected?
+  end
+
+end
+
+

data/spec/irc-socket_spec.rb

@@ -0,0 +1,81 @@
+require File.expand_path('../../lib/irc-socket', __FILE__)
+
+class IRCSocket
+  def write(data)
+    return data
+  end
+end
+
+commands = [
+  [:pass,    %w(foobar),                        "PASS foobar"],
+  [:nick,    %(ipsum),                          "NICK ipsum"],
+  [:user,    ["guest", 0, '*', "real name"],    "USER guest 0 * :real name"],
+  [:oper,    %w(foo bar),                       "OPER foo bar"],
+  [:mode,    %w(#foo +v bar),                   "MODE #foo +v bar"],
+  [:quit,    %w(goodbye),                       "QUIT :goodbye"],
+  [:join,    %w(#mychan),                       "JOIN #mychan"],
+  [:part,    %w(#mychan),                       "PART #mychan"],
+  [:part,    %w(#mychan cya!),                  "PART #mychan :cya!",           "with part message"],
+  [:topic,   %w(#mychan newtopic),              "TOPIC #mychan :newtopic"],
+  [:names,   %w(#foo #bar),                     "NAMES #foo,#bar"],
+  [:list,    %w(#foo #bar),                     "LIST #foo,#bar"],
+  [:invite,  %w(foo #mychan),                   "INVITE foo #mychan"],
+  [:kick,    %w(#chan villian),                 "KICK #chan villian"],
+  [:kick,    %w(#chan villian gtfo!),           "KICK #chan villian :gtfo!",    "with kick reason"],
+  [:privmsg, ['#chan', 'foo bar baz'],          "PRIVMSG #chan :foo bar baz"],
+  [:notice,  ['#chan', 'foo bar baz'],          "NOTICE #chan :foo bar baz"],
+  [:motd,    %w(someserver),                    "MOTD someserver"],
+  [:version, %w(anotherserver),                 "VERSION anotherserver"],
+  [:stats,   %w(m server),                      "STATS m server"],
+  [:time,    %w(irc.someserver.net),            "TIME irc.someserver.net"],
+  [:info,    %w(foobar),                        "INFO foobar"],
+  [:squery,  %w(irchelp HELPME),                "SQUERY irchelp :HELPME"],
+  [:who,     %w(*.com o),                       "WHO *.com o"],
+  [:whois,   %w(foo.org user),                  "WHOIS foo.org user"],
+  [:whowas,  %w(foo.org user),                  "WHOWAS foo.org user"],
+  [:kill,    ['badperson', 'get out!'],         "KILL badperson :get out!"],
+  [:ping,    %w(010123444),                     "PING 010123444"],
+  [:pong,    %w(irc.foobar.org),                "PONG irc.foobar.org"],
+  [:away,    [],                                "AWAY"],
+  [:away,    ['gone for lunch'],              "AWAY :gone for lunch"],
+  [:users,   %w(irc.foobar.org),                "USERS irc.foobar.org"],
+  [:userhost, %w(foo bar baz),                  "USERHOST foo bar baz"],
+]
+
+describe "IRCSocket" do
+  before do
+    @irc = IRCSocket.new('irc.myserver.net')
+  end
+  
+  describe "::new" do
+    it "should return an IRCSocket" do
+      @irc.class.should == IRCSocket
+    end
+
+    it "should default to port 6667" do
+      @irc.port.should == 6667
+    end
+
+    it "should not automatically connect" do
+      @irc.connected.should == false
+    end
+
+    it "should set socket instance as nil" do
+      @irc.socket.should == nil
+    end
+
+  end
+
+  describe "IRC commands as per rfc2812" do
+    commands.each do |requirements|
+      meth, params, pass, extra = *requirements
+      describe "##{meth}" do
+        it "should send a #{meth.to_s.upcase} command #{extra if extra}" do
+          @irc.send(meth, *params).should == pass
+        end
+      end
+    end
+  end
+
+end
+

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: irc-socket
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  version: "0.9"
+platform: ruby
+authors: 
+- Lee 'injekt' Jarvis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-22 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bacon
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id002
+description: An IRC wrapper around TCPSocket
+email: ljjarvis@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- spec/irc-socket_spec.rb
+- lib/irc-socket.rb
+has_rdoc: true
+homepage: http://wiki.github.com/injekt/irc-socket
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --quiet
+- --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: An IRC wrapper around TCPSocket
+test_files: []
+