minter-raccdoc 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 H. Wade Minter
+ 
+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/Manifest

@@ -0,0 +1,8 @@
+lib/raccdoc.rb
+LICENSE
+Manifest
+raccdoc.gemspec
+Rakefile
+README
+test/raccdoc_connection_test.rb
+test/test_helper.rb

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+gem 'echoe', '~> 3.0.1'
+require 'echoe'
+require './lib/raccdoc.rb'
+
+echoe = Echoe.new("raccdoc") do |p|
+  p.author = "H. Wade Minter"
+  p.email = "minter@lunenburg.org"
+  p.summary = "A Ruby interface into the Raccdoc protocol"
+  p.runtime_dependencies = ["socket", "time"]
+  p.version = Raccdoc::VERSION
+  p.ignore_pattern = ["tmp/*", "doc/*"]
+end
+
+desc 'Generate the .gemspec file in the root directory'
+task :gemspec do
+  File.open("#{echoe.name}.gemspec", "w") {|f| f << echoe.spec.to_ruby }
+end
+task :package => :gemspec
+
+namespace :test do
+  desc 'Check test coverage'
+  task :coverage do
+    rm_f "coverage"
+    system("rcov -x '/Library/Ruby/Gems/1.8/gems/' --sort coverage #{File.join(File.dirname(__FILE__), 'test/*_test.rb')}")
+    show_test_coverage_results
+  end
+  
+  def show_test_coverage_results
+    system("open #{File.join(File.dirname(__FILE__), 'coverage/index.html')}") if PLATFORM['darwin']
+  end
+  
+  desc 'Remove coverage products'
+  task :clobber_coverage do
+    rm_r 'coverage' rescue nil
+  end
+  
+end
+

data/lib/raccdoc.rb

@@ -0,0 +1,361 @@
+module Raccdoc
+  
+  VERSION = '0.0.1'
+  require 'socket'
+  require 'time'
+
+  class Connection
+    
+    attr_reader :host
+    
+    # Creates a new Raccdoc connection.  By default, it connects to bbs.iscabbs.com, port 6145, which is the
+    # ISCABBS server.
+    #
+    # If a :user and :password is not supplied, a guest/anonymous login is done.  Most, if not all, posting is
+    # restricted under this account.  
+    #
+    # If the TCP connection fails, or the login is rejected, and exception is raised.
+    def initialize(param_args = {:host => 'bbs.iscabbs.com', :port => '6145', :user => nil, :password => nil})
+      args = {:host => 'bbs.iscabbs.com', :port => '6145', :user => nil, :password => nil }
+
+      args.merge!(param_args)
+      begin
+        @socket = TCPSocket.new(args[:host],args[:port])
+      rescue Errno::ECONNREFUSED
+        raise RuntimeError, "Could not connect to #{args[:host]}, port #{args[:port]}\n"
+      end
+    
+      response = @socket.readline.chomp
+      unless response.match(/^2/)
+        raise RuntimeError, response
+      end
+
+      if (args[:user] && args[:password])
+        @socket.puts("LOGIN #{args[:user]}\t#{args[:password]}")
+        response = @socket.readline.chomp
+        unless response.match(/^2/)
+          raise RuntimeError, response
+        end
+      end
+      @host = args[:host]
+    end
+    
+    # Closes the Raccdoc connection, then closes the socket.
+    def logout
+      unless @socket.closed?
+        @socket.puts "QUIT" 
+
+        response = @socket.readline.chomp
+        unless response.match(/^2/)
+          raise RuntimeError, response
+        end
+        @socket.close
+      end
+    end
+    
+    # Tests the TCP socket to make sure that it's still connected to the remote server.
+    def connected?
+      @socket.closed? ? false : true
+    end
+    
+    # Sets the active forum on the server to the specified forum name or ID, and returns a new Raccdoc::Forum object.
+    #
+    # The forum can be specified by number (0), or name ("Lobby" or "Program")
+    def jump(forum = 0)
+      Raccdoc::Forum.new(@socket, forum.to_s)
+    end
+    
+    # Returns a hash of forum information.  The key is the forum ID number, and the value is a hash containing the following data:
+    #
+    # * name - The forum name
+    # * lastnote - The earliest post ID number in the forum
+    # * admin - The handle of the forum admin
+    #
+    # Note that this does not return actual Raccdoc::Forum objects in the interest of saving resources, so you'll need to jump to the forum that you want.
+    def forums(type="all")
+      @socket.puts "LIST #{type}"
+      forums = Hash.new
+
+      response = @socket.readline.chomp
+      unless response.match(/^3/)
+        raise RuntimeError, response
+      end
+
+      while line = @socket.readline.chomp
+        break if line.match(/^\.$/)
+        tmp = Hash.new
+        line.split(/\t/).each do |pair|
+          (key, value) = pair.split(/:/)
+          if key == "admin"
+            value = value.split('/')[1]
+          end
+          tmp[key.to_sym] = value
+        end
+        id = tmp[:topic].to_i
+        forums[id] = tmp
+      end
+
+      return forums
+    end
+    
+  end
+  
+  class Forum
+    
+    attr_reader :id
+    attr_reader :name
+    attr_reader :admin
+    
+    # Sets the active forum on the server to the specified forum number (0) or name (Lobby, Program), then returns a new Raccdoc::Forum object.
+    #
+    # There are three variables exposed through attr_reader:
+    #
+    # * id - The forum ID number
+    # * name - The forum name
+    # * admin - The name of the forum administrator
+    def initialize(socket, forum = 0)
+      @socket = socket
+      @socket.puts "TOPIC #{forum.to_s}"
+      response = @socket.readline.chomp
+      unless response.match(/^2/)
+        raise RuntimeError, response
+      end
+
+      @headers = {}
+      tuples = response.split(/\t/)
+      tuples.delete_at(0)
+      tuples.each do |pair|
+        (key, value) = pair.split(/:/)
+        @headers[key.downcase.to_sym] = value
+      end
+      
+      @id = @headers[:topic]
+      @name = @headers[:name]
+      @admin = @headers[:admin]
+    end
+    
+    # Returns an array of all current post IDs in the forum.
+    def noteids
+      noteids = Array.new
+      @socket.puts("XHDR noteno")
+      response = @socket.readline.chomp
+      unless response.match(/^3/)
+        raise RuntimeError, response
+      end
+
+      while line = @socket.readline.chomp
+        break if line.match(/^\.$/)
+        (tag,noteid) = line.split(/:/)
+        noteids.push(noteid.to_i)
+      end
+
+      return noteids
+    end
+    
+    # Returns a hash of the forum information.  Keys are:
+    #
+    # * from - The username of the user who last updated the FI
+    # * date - The date the forum information was last updated (a Time object)
+    # * body - The actual text of the FI
+    def forum_information
+      fi = Hash.new
+      @socket.puts("SHOW info")
+      response = @socket.readline.chomp
+      unless response.match(/^3/)
+        raise RuntimeError, response
+      end
+
+      # Get header information
+      while line = @socket.readline.chomp
+        break if line.match(/^$/)
+        (key, value) = line.split(/: /)
+        if key.downcase == "date"
+          value = Time.parse(value)
+        end
+        fi[key.downcase.to_sym] = value
+      end
+
+      body = ""
+      while line = @socket.readline
+        break if line.match(/^\.$/)
+        body << line
+      end
+      fi[:body] = body
+
+      return fi
+    end
+    
+    # Sets the current user's first-unread pointer to the specified number.  Any posts greater than that number will be listed as unread.
+    def first_unread=(postid = 0)
+      @socket.puts("SETRC #{postid.to_s}")
+      response = @socket.readline.chomp
+      unless response.match(/^2/)
+        raise RuntimeError, response
+      end
+    end
+    
+    # Returns the post ID number of the last read post in the forum.  Any posts greater than that number can be considered unread.
+    def first_unread
+      @socket.puts("SHOW rcval")
+      response = @socket.readline.chomp
+      unless response.match(/^2/)
+        raise RuntimeError, response
+      end
+      response.match(/\d+.*?:\s+(\d+)/)
+      return $1
+    end
+    
+    # Returns a hash of information about the posts in the forum.  The hash is keyed off of the post ID, and the value is a hash containing the following information:
+    #
+    # * author - The username of the user who created the post
+    # * date - The date the post was created or, if the post is anonymous, the current date in UTC
+    # * subject - The first line of the post
+    # * size - The size of the post in bytes
+    # * authority - If the post was made with Sysop or Forum Manager status, this is set    
+    # 
+    # You may provide an optional range (in the form "start_id-end_id") to limit the number of posts returned.  The default is to return all posts in the forum.
+    def post_headers(range = "")
+      @socket.puts("XHDR ALL #{range}")
+      response = @socket.readline.chomp
+      unless response.match(/^3/)
+        raise RuntimeError, response
+      end
+
+      posts = Hash.new
+
+      while (line = @socket.readline.chomp)
+        break if line.match(/^\.$/)
+        tmpdata = Hash.new
+        line.split(/\t/).each do |tuple|
+          (key, value) = tuple.split(/:/, 2)
+          tmpdata[key.downcase.to_sym] = value 
+        end
+        tmpdata[:date] = tmpdata[:date] ? Time.parse(tmpdata[:date]) : Time.new.getgm
+        tmpdata[:author] = tmpdata[:"formal-author"] ? tmpdata[:"formal-author"].split('/')[1] : 'Anonymous'
+        posts[tmpdata[:noteno]] = tmpdata
+      end
+      return posts
+    end
+    
+    # Returns a new Raccdoc::Post object for the specified post ID in the current forum.
+    def read(postid)
+      Post.new(@socket,postid)
+    end
+    
+    # Creates a new post in the current forum using the text provided in the argument.  
+    #
+    # Returns a new Raccdoc::Post object that results from reading the newly created post.
+    def post(body)
+      @socket.puts("POST")
+      response = @socket.readline.chomp
+      unless response.match(/^3/)
+        raise RuntimeError, response
+      end
+
+      @socket.puts(body)
+      @socket.puts(".")
+
+      response = @socket.readline.chomp
+      if response.match(/^2/)
+        postid = response.split(/:\s+/)[1]
+        return Post.new(@socket,postid)
+      else
+        raise RuntimeError, response
+      end
+    end
+    
+    # Checks to see if the currently logged in user has permission to post in the current forum.  
+    #
+    # Returns true or false.
+    def post?
+      @socket.puts("OKAY POST")
+      response = @socket.readline.chomp
+      if response.match(/^2/)
+        return true
+      elsif response.match(/^4/)
+        return false
+      else
+        raise RuntimeError, response
+      end
+    end
+  end
+  
+  class Post
+    
+    attr_reader :id
+    attr_reader :date
+    attr_reader :author
+    attr_reader :body
+    
+    # Creates a new Raccdoc::Post object by reading the specified post.
+    #
+    # Useful information returned:
+    #
+    # * id - The numerical post ID
+    # * date - The date the post was made (or the current date in UTC if the post is anonymous)
+    # * author - The username of the user that created the post
+    # * body - The textual body of the post.
+    def initialize(socket,postid)
+      @socket = socket
+      @socket.puts "READ #{postid}"
+      response = @socket.readline.chomp
+      unless response.match(/^3/)
+        raise RuntimeError, response
+      end
+
+      # Get header information
+      post = Hash.new
+
+      while line = @socket.readline.chomp
+        break if line.match(/^$/)
+        (key,value) = line.split(/: /)
+        post[key.downcase.to_sym] = value
+      end
+      post[:id] = postid
+      post[:date] = post[:date] ? Time.parse(post[:date]) : Time.new.getgm
+      post[:author] = post[:'formal-author'] ? post[:'formal-author'].split('/')[1] : 'Anonymous'
+
+      post[:body] = ""
+      while (line = @socket.readline)
+        break if line.match(/^\.$/)
+        post[:body] << line
+      end
+      
+      @id = post[:id]
+      @date = post[:date]
+      @author = post[:author]
+      @body = post[:body]
+      return post
+    end
+    
+    # Checks to see if the currently-logged-in user has permission to delete the current post.  
+    #
+    # Returns true or false
+    def delete?
+      @socket.puts("OKAY DELETE NOTE #{self.id}")
+      response = @socket.readline.chomp
+      if response.match(/^2/)
+        return true
+      elsif response.match(/^4/)
+        return false
+      else
+        raise RuntimeError, response
+      end
+    end
+    
+    # Attempts to delete the current post.  
+    #
+    # Returns true or false
+    def delete
+      @socket.puts("DELETE NOTE #{self.id}")
+      response = @socket.readline.chomp
+      if response.match(/^2/)
+        return true
+      elsif response.match(/^4/)
+        return false
+      else response.match(/^2/)
+        raise RuntimeError, response
+      end
+    end
+  end
+end

data/raccdoc.gemspec

@@ -0,0 +1,41 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{raccdoc}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["H. Wade Minter"]
+  s.date = %q{2009-01-12}
+  s.description = %q{A Ruby interface into the Raccdoc protocol}
+  s.email = %q{minter@lunenburg.org}
+  s.extra_rdoc_files = ["lib/raccdoc.rb", "LICENSE", "README"]
+  s.files = ["lib/raccdoc.rb", "LICENSE", "Manifest", "raccdoc.gemspec", "Rakefile", "README", "test/raccdoc_connection_test.rb", "test/test_helper.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Raccdoc", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{raccdoc}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{A Ruby interface into the Raccdoc protocol}
+  s.test_files = ["test/raccdoc_connection_test.rb", "test/test_helper.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<socket>, [">= 0"])
+      s.add_runtime_dependency(%q<time>, [">= 0"])
+      s.add_development_dependency(%q<echoe>, [">= 0"])
+    else
+      s.add_dependency(%q<socket>, [">= 0"])
+      s.add_dependency(%q<time>, [">= 0"])
+      s.add_dependency(%q<echoe>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<socket>, [">= 0"])
+    s.add_dependency(%q<time>, [">= 0"])
+    s.add_dependency(%q<echoe>, [">= 0"])
+  end
+end

data/test/raccdoc_connection_test.rb

@@ -0,0 +1,73 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class RaccdocConnectionTest < Test::Unit::TestCase
+  def setup
+    @socket = mock()
+  end
+  
+  def test_valid_anonymous_connection
+    TCPSocket.expects(:new).returns(@socket)
+    @socket.expects(:readline).returns("200 Server started 	seed:Ci0B2YeMio8ftYjElTa+EQ==")
+    bbs = Raccdoc::Connection.new(:host => 'test.bbs.example')
+    assert_equal bbs.class, Raccdoc::Connection
+    assert_equal bbs.host, "test.bbs.example"
+  end
+  
+  def test_connection_refused_anonymous
+    TCPSocket.expects(:new).with('test.bbs.example', '6145').raises(Errno::ECONNREFUSED)
+    assert_raise(RuntimeError, 'Could not connect to test.bbs.example, port 6145') do
+      bbs = Raccdoc::Connection.new(:host => 'test.bbs.example')
+    end
+  end
+  
+  def test_connection_bad_login
+    socket = mock()
+    socket.stubs(:readline).returns("200 Server started 	seed:Ci0B2YeMio8ftYjElTa+EQ==").then.returns("405 Cannot process login 	Invalid password")
+    socket.stubs(:puts)
+    TCPSocket.expects(:new).returns(socket)
+    assert_raise(RuntimeError, '404 User does not exist') do
+      bbs = Raccdoc::Connection.new(:host => 'test.bbs.example', :user => 'Bugcrusher', :password => 'BadPassword')
+    end
+  end
+  
+  def test_connection_that_returns_unknown_status
+    socket = mock()
+    TCPSocket.expects(:new).returns(socket)
+    socket.expects(:readline).returns("999 Stuff is messed up")
+    assert_raise(RuntimeError) do
+      bbs = Raccdoc::Connection.new(:host => 'test.bbs.example')
+    end
+  end
+  
+  def test_logout_succeeds
+    @socket.stubs(:puts)
+    @socket.stubs(:close)
+    @socket.stubs(:closed?).returns(false)
+    TCPSocket.expects(:new).returns(@socket)
+    @socket.stubs(:readline).returns("200 Server started 	seed:Ci0B2YeMio8ftYjElTa+EQ==").then.returns("201 Session ended")
+    bbs = Raccdoc::Connection.new(:host => 'test.bbs.example')
+    bbs.logout
+  end
+  
+  def test_logout_fails
+    @socket.stubs(:puts)
+    @socket.stubs(:close)
+    @socket.stubs(:closed?).returns(false)
+    TCPSocket.expects(:new).returns(@socket)
+    @socket.stubs(:readline).returns("200 Server started 	seed:Ci0B2YeMio8ftYjElTa+EQ==").then.returns("999 Something Broke")
+    bbs = Raccdoc::Connection.new(:host => 'test.bbs.example')
+    assert_raise(RuntimeError) do
+      bbs.logout
+    end
+  end
+  
+  def test_connected
+    @socket.stubs(:puts)
+    @socket.stubs(:closed?).returns(false)
+    TCPSocket.expects(:new).returns(@socket)
+    @socket.stubs(:readline).returns("200 Server started 	seed:Ci0B2YeMio8ftYjElTa+EQ==").then.returns("999 Something Broke")
+    bbs = Raccdoc::Connection.new(:host => 'test.bbs.example')
+    assert_equal bbs.connected?, true
+  end
+    
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'test/unit'
+$:.unshift File.dirname(__FILE__) + '/../lib'
+require 'raccdoc'
+require 'rubygems'
+require 'mocha'

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification 
+name: minter-raccdoc
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- H. Wade Minter
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-12 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: socket
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: time
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: echoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A Ruby interface into the Raccdoc protocol
+email: minter@lunenburg.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- lib/raccdoc.rb
+- LICENSE
+- README
+files: 
+- lib/raccdoc.rb
+- LICENSE
+- Manifest
+- raccdoc.gemspec
+- Rakefile
+- README
+- test/raccdoc_connection_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: ""
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Raccdoc
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: raccdoc
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A Ruby interface into the Raccdoc protocol
+test_files: 
+- test/raccdoc_connection_test.rb
+- test/test_helper.rb