circus 0.0.0 → 0.1.0

data/README.rdoc

@@ -6,6 +6,79 @@ An event driven IRC gem without a DSL or any EOF magick
  
 Tim Sjoberg (bedlamp AT gmail.com)
 
+== Quick How-to
+
+Install the gem
+  gem install circus
+
+How to connect
+  require 'circus'
+  
+  irc = Circus::IRC.new
+  irc.connect
+
+IRC#connect is a blocking call. It will only return when you're disconnected
+
+IRC#new takes a bunch of config parameters in the form of a hash, their names should be self explanatory
+  :server
+  :port
+  :nick
+  :username
+  :realname
+  :sendspeed #length of time between messages. this is for flood protection. default is 0.5 seconds
+  :timeout #If this amount of time, in seconds, is reached, circus considers itself disconnected
+  :eol #the line delimiter. you should hopefully never need to change this
+  :debug #if this is set to true, circus will output everything it does in stdout
+  :password #this is the password for the irc server if there is one. default is unset
+
+For example
+  irc = Circus::IRC.new :server => "irc.freenode.org", :nick => "Circus-IRC"
+
+Alternatively, you can set the values after instantiation by calling #config_value=, for example
+  irc = Circus::IRC.new
+  irc.nick = "NewNick"
+  irc.server = "another.server.com"
+
+To send stuff, you have a bunch of methods at your disposal. Each given with example parameters
+  irc.action "#circus", "jumps up and down" #does a ctcp ACTION, or /me in your irc client
+  irc.ctcp "user", "VERSION" #does a normal ctcp and puts in the \001s for you
+  irc.ctcp_reply "user", "VERSION Ruby using Circus-IRC 0.0.0"
+  irc.join "#circus"
+  irc.kick "#circus", "user", "no noobs allowed" #third parameter can be left out
+  irc.mode "#circus", "+o", "awesome_user" #third parameter optional. For example
+  irc.mode "Circus-IRC", "+B"
+  irc.nick "Circus-IRC"
+  irc.notice "user", "message"
+  irc.part "#circus"
+  irc.pass "password" #you shouldn't need to use this. use the password config value
+  irc.pong "value" #you also never need to use this. this is already handled
+  irc.privmsg "#circus", "Hello"
+  irc.quit "reason"
+  irc.raw "DCCALLOW +user" #for all those pesky additions
+  irc.topic "#circus", "New topic for channel #circus"
+  irc.user "user 0 * realname" #again, you shouldn't need this. use the config values
+
+As previously mentioned, it is event driven. Before calling connect, you can subscribe to any number of events, or multiple times to the same event. For a full list look in lib/irc/commands.rb. You can pass subscribe the string or the symbol version, for example
+  irc.subscribe(:ENDOFMOTD) do
+    irc.join "#circus"
+  end
+
+or
+  irc.subscribe("376") do
+    irc.join "#circus"
+  end
+
+You are going to need to know how many arguments a block is expecting if you are going to use them. Unfortunately the only way to this is to know the irc protocol, or trial and error. As an example, to create an echo bot (in channels only):
+  irc.subscribe(:PRIVMSG) do |message, sender, receiver|
+    if receiver =~ /^#/
+      irc.privmsg receiver, message
+    end
+  end
+
+==Disclaimer
+
+This gem is not designed to make it really easy to write irc bots, its designed to make it really easy to build a framework to create irc bots. This gem has been tested working in ruby 1.9
+
 == License
 
 This software is distributed under the BEER-WARE license. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/circus.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{circus}
-  s.version = "0.0.0"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tim Sjoberg"]
-  s.date = %q{2010-07-01}
+  s.date = %q{2010-07-02}
   s.description = %q{A relatively simple event driven irc gem without a DSL or any EOF magick}
   s.email = %q{bedlamp@gmail.com}
   s.extra_rdoc_files = [
@@ -48,6 +48,7 @@ Gem::Specification.new do |s|
      "lib/irc/messages/user.rb",
      "lib/irc/parser.rb",
      "spec/circus_spec.rb",
+     "spec/irc_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb"
   ]
@@ -57,7 +58,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.7}
   s.summary = %q{A relatively simple event driven irc gem}
   s.test_files = [
-    "spec/circus_spec.rb",
+    "spec/irc_spec.rb",
+     "spec/circus_spec.rb",
      "spec/spec_helper.rb"
   ]
 

data/lib/irc.rb

@@ -13,7 +13,7 @@ module Circus
   class IRC
     
     def initialize(options = {})
-      @default  = { :server     =>  "za.shadowfire.org",
+      @default  = { :server     =>  "irc.freenode.net",
                     :port       =>  6667,
                     :nick       =>  "Circus-IRC",
                     :username   =>  "circus",
@@ -43,6 +43,12 @@ module Circus
       @event_manager.subscribe(type, &block)
     end
     
+    %w(server port nick username realname send_speed timeout eol debug password).each do |config_value|
+      define_method("#{config_value}=".to_sym) do |new_value|
+        @config[config_value.to_sym] = new_value
+      end
+    end
+    
     def method_missing(name, *args)
       message_class = "Circus::Messages::#{name.to_s.downcase.classify}"
       message_class = message_class.constantize

data/spec/irc_spec.rb

@@ -0,0 +1,39 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Circus::IRC, "#new without parameters" do
+  before(:each) do
+    @irc = Circus::IRC.new
+  end
+  
+  it "defines default values if none are given" do
+    config = @irc.instance_variable_get("@config")
+    config[:server].should == "irc.freenode.net"
+    config[:port].should == 6667
+    config[:nick].should == "Circus-IRC"
+    config[:username].should == "circus"
+    config[:realname].should == "Using ruby with Circus IRC"
+    config[:send_speed].should == 0.5
+    config[:timeout].should == 15*60
+    config[:eol].should == "\r\n"
+    config[:debug].should == false
+  end
+  
+  it "should not define a password if none is given" do
+    @irc.instance_variable_get("@config")[:password].should be_nil
+  end
+  
+  it "should update the config value when calling .param=" do
+    @irc.instance_variable_get("@config")[:nick].should == "Circus-IRC"
+    @irc.nick = "NewNick"
+    @irc.instance_variable_get("@config")[:nick].should == "NewNick"
+    
+    @irc.instance_variable_get("@config")[:password].should be_nil
+    @irc.password = "secret"
+    @irc.instance_variable_get("@config")[:password].should == "secret"
+    
+    #if nick and password work, they should all work. now we just need to check that the methods exist
+    %w(server port nick username realname send_speed timeout eol debug password).each do |config_value|
+      fail "no method #{config_value}= defined" unless @irc.respond_to?("#{config_value}=".to_sym)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,10 +1,9 @@
-$LOAD_PATH.unshift(File.dirname(__FILE__))
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'rubygems'
-require 'circus'
 require 'spec'
 require 'spec/autorun'
 
+require File.join(File.dirname(__FILE__), '..', 'lib', 'circus')
+
 Spec::Runner.configure do |config|
   
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: circus
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 27
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 0
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Tim Sjoberg
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-01 00:00:00 +02:00
+date: 2010-07-02 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -91,6 +91,7 @@ files:
 - lib/irc/messages/user.rb
 - lib/irc/parser.rb
 - spec/circus_spec.rb
+- spec/irc_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
 has_rdoc: true
@@ -128,5 +129,6 @@ signing_key:
 specification_version: 3
 summary: A relatively simple event driven irc gem
 test_files: 
+- spec/irc_spec.rb
 - spec/circus_spec.rb
 - spec/spec_helper.rb