ftp_service 0.1.1 → 0.2.0

data/.gitignore

@@ -16,6 +16,8 @@ tmtags
 ## PROJECT::GENERAL
 coverage
 rdoc
+doc
 pkg
+.yardoc
 
 ## PROJECT::SPECIFIC

data/CHANGELOG.markdown

@@ -0,0 +1,10 @@
+# v0.2.0 (2010-03-08)
+
+* Add `FtpService#write_request` and `FtpService#read_response` methods,
+  making this thing actually usable.
+
+* Switch to Markdown + Yardoc for rdocs.
+
+# v0.1.1 (2010-03-08)
+
+* First version. Opens a connection but that's it. Useful, huh?

data/README.markdown

@@ -0,0 +1,37 @@
+# FTP Service
+
+An FTP Service is like a web service except stupid. You send your
+request by uploading an xml file and get your response by downloading
+another xml file. Have you ever had to deal with something like that? I
+have.
+
+RDocs on [rdoc.info](http://rdoc.info/projects/blaix/ftp_service).
+
+Source code on [github](http://github.com/blaix/ftp_service).
+
+## Installation
+  
+    gem install ftp_service
+    
+## Usage
+
+    require 'ftp_service'
+  
+    FtpService.open('host', 'user', 'pass') do |service|
+      path = '/the/remote/path'
+      service.write_request("#{path}/request.xml", '<foo>bar</foo>')
+      response = service.read_response("#{path}/response.xml")
+    end
+
+* `read_response` will block while it polls the server waiting for a
+  response.
+* Temp files are created for the local request and response files and
+  deleted when no longer needed.
+
+For more details, see the
+[RDocs](http://rdoc.info/projects/blaix/ftp_service) (sike they are
+really yardocs!).
+  
+## Copyright
+
+Copyright (c) 2010 Justin Blake. See LICENSE for details.

data/Rakefile

@@ -12,6 +12,7 @@ begin
     gem.authors = ["Justin Blake"]
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "mocha", ">= 0.9.8"
+    gem.add_development_dependency "yard", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
@@ -25,6 +26,14 @@ Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.spec_files = FileList['spec/**/*_spec.rb']
 end
 
+namespace :spec do
+  Spec::Rake::SpecTask.new(:doc) do |spec|
+    spec.libs << 'lib' << 'spec'
+    spec.spec_files = FileList['spec/**/*_spec.rb']
+    spec.spec_opts << '--format specdoc'
+  end
+end
+
 Spec::Rake::SpecTask.new(:rcov) do |spec|
   spec.libs << 'lib' << 'spec'
   spec.pattern = 'spec/**/*_spec.rb'
@@ -35,12 +44,13 @@ task :spec => :check_dependencies
 
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "ftp_service #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |y|
+    y.files << '-' << 'CHANGELOG.*'
+  end
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
 end

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/ftp_service.gemspec

@@ -5,29 +5,31 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ftp_service}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Justin Blake"]
-  s.date = %q{2010-03-05}
+  s.date = %q{2010-03-08}
   s.description = %q{An FTP Service is like a web service except stupid. You send your request by uploading an xml file and get your response by downloading another xml file.}
   s.email = %q{justin@megablaix.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+     "README.markdown"
   ]
   s.files = [
-    ".document",
-     ".gitignore",
+    ".gitignore",
+     "CHANGELOG.markdown",
      "LICENSE",
-     "README.rdoc",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "ftp_service.gemspec",
      "lib/ftp_service.rb",
+     "lib/tempfile_helper.rb",
      "spec/ftp_service_spec.rb",
      "spec/spec.opts",
-     "spec/spec_helper.rb"
+     "spec/spec_helper.rb",
+     "spec/tempfile_helper_spec.rb"
   ]
   s.homepage = %q{http://github.com/blaix/ftp_service}
   s.rdoc_options = ["--charset=UTF-8"]
@@ -36,7 +38,8 @@ Gem::Specification.new do |s|
   s.summary = %q{A class for dealing with the worst possible type of "web" service.}
   s.test_files = [
     "spec/ftp_service_spec.rb",
-     "spec/spec_helper.rb"
+     "spec/spec_helper.rb",
+     "spec/tempfile_helper_spec.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -46,13 +49,16 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<mocha>, [">= 0.9.8"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
     else
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<mocha>, [">= 0.9.8"])
+      s.add_dependency(%q<yard>, [">= 0"])
     end
   else
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<mocha>, [">= 0.9.8"])
+    s.add_dependency(%q<yard>, [">= 0"])
   end
 end
 

data/lib/ftp_service.rb

@@ -1,17 +1,31 @@
 require 'net/ftp'
+require 'tempfile_helper'
 
 # Class for dealing with a service that acts like a web service, except
 # over FTP. Meaning an xml request is uploaded as a file, and the
 # response xml is downloaded as another file.
+#
+# Typical usage:
+# 
+#   FtpService.open('host', 'user', 'pass') do |service|
+#     path = '/the/remote/path'
+#     service.write_request("#{path}/request.xml", '<foo>bar</foo>')
+#     response = service.read_response("#{path}/response.xml")
+#   end
+#
+# or (the sucky way):
+#
+#   path = '/the/remote/path'
+#   service = FtpService.new('host', 'user', 'pass')
+#   service.write_request("#{path}/request.xml", '<foo>bar</foo>')
+#   response = service.read_response("#{path}/response.xml")
+#   service.close
 class FtpService
   
   # Open a connection to the FTP server and return an FtpService object.
-  # The object must be closed explicitely.
-  #
-  #   ftp_service = FtpService.open(host, user, pass)
-  #   ftp_service.write_request(path, request)
-  #   response = ftp_service.read_response(path)
-  #   ftp_service.close
+  # The object must be closed explicitely. See FtpServier#open for a
+  # better way to do this that will automatically close the connection,
+  # even if an exception is raised.
   def initialize(host, user, pass)
     @ftp = Net::FTP.open(host, user, pass)
   end
@@ -19,11 +33,6 @@ class FtpService
   # Open a connection and pass an FtpService instance to the block. The
   # instance will be closed when the block finishes, or when an
   # exception is raised.
-  #
-  #   FtpService.open(host, user, pass) do |ftp_service|
-  #     ftp_service.write_request(path, request)
-  #     response = ftp_service.read_response(path)
-  #   end
   def self.open(host, user, pass)
     instance = new(host, user, pass)
     begin
@@ -33,6 +42,21 @@ class FtpService
     end
   end
   
+  # Write `request` to a local temp file and upload it to `remote_path`
+  # on the FTP server.
+  def write_request(request, remote_path)
+    tmp = TempfileHelper.write(request, 'request')
+    @ftp.puttextfile(tmp.path, remote_path)
+  end
+  
+  # Download the file at `remote_path` from the FTP server to a  local
+  # temp file and return its contents.
+  def read_response(remote_path)
+    TempfileHelper.read('response') do |tmp|
+      @ftp.gettextfile(remote_path, tmp.path)
+    end
+  end
+  
   # Close the connection to the FTP server.
   def close
     @ftp.close

data/lib/tempfile_helper.rb

@@ -0,0 +1,20 @@
+require 'tempfile'
+
+module TempfileHelper
+  extend self
+  
+  def read(name = nil)
+    tempfile = nil
+    name ||= Time.now.to_f
+    Tempfile.open(name) { |tempfile| yield(tempfile) }
+    File.read(tempfile.path)
+  end
+  
+  def write(content, name = nil)
+    name ||= Time.now.to_f.to_s
+    file = Tempfile.new(name)
+    file.write(content)
+    file.close
+    file
+  end
+end

data/spec/ftp_service_spec.rb

@@ -7,35 +7,35 @@ describe "FtpService" do
   end
   
   describe '.new(host, user, pass)' do
-    it 'should connect to the requested ftp server' do
+    it 'connects to the requested ftp server' do
       Net::FTP.expects(:open).with('host', 'user', 'pass').returns(@ftp)
       FtpService.new('host', 'user', 'pass')
     end
 
-    it 'should yield an instance of the ftp service' do
+    it 'returns an instance of the ftp service' do
       service = FtpService.new('host', 'user', 'pass')
       service.should be_a(FtpService)
     end
   end
   
   describe '.open(host, user, pass)' do
-    it 'should connect to the requested ftp server' do
+    it 'connects to the requested ftp server' do
       Net::FTP.expects(:open).with('host', 'user', 'pass').returns(@ftp)
       FtpService.open('host', 'user', 'pass') {}
     end
 
-    it 'should yield an instance of the ftp service' do
+    it 'yields an instance of the ftp service' do
       service = nil
       FtpService.open('host', 'user', 'pass') { |service| }
       service.should be_a(FtpService)
     end
     
-    it 'should automatically close the connection' do
+    it 'automatically closes the connection' do
       @ftp.expects(:close)
       FtpService.open('host', 'user', 'pass') {}
     end
     
-    it 'should close the connection even if an exception is raised' do
+    it 'closes the connection even if an exception is raised' do
       @ftp.expects(:close)
       lambda {
         FtpService.open('host', 'user', 'pass') { raise "boom" }
@@ -43,8 +43,43 @@ describe "FtpService" do
     end
   end
   
+  describe '#write_request(path, request)' do
+    before do
+      @tempfile = stub('tempfile', :path => '/local/path')
+      @service = FtpService.new('host', 'user', 'pass')
+    end
+    
+    it "saves the request to a temp file" do
+      TempfileHelper.expects(:write).with('request', optionally(anything)).returns(@tempfile)
+      @service.write_request('request', '/remote/path')
+    end
+    
+    it "uploads the request to `path` on the FTP server" do
+      TempfileHelper.stubs(:write).returns(@tempfile)
+      @ftp.expects(:puttextfile).with('/local/path', '/remote/path')
+      @service.write_request('request', '/remote/path')
+    end
+  end
+  
+  describe '#read_response(path)' do
+    before do
+      tempfile = stub('tempfile', :path => '/local/path')
+      TempfileHelper.stubs(:read).returns('response').yields(tempfile)
+      @service = FtpService.new('host', 'user', 'pass')
+    end
+    
+    it "downloads the response at `path` from the FTP server" do
+      @ftp.expects(:gettextfile).with('/remote/path', '/local/path')
+      @service.read_response('/remote/path')
+    end
+    
+    it "returns the contents of the downloaded response" do
+      @service.read_response('/remote/path').should == "response"
+    end
+  end
+  
   describe '#close' do
-    it 'should close the connection to the ftp server' do
+    it 'closes the connection to the ftp server' do
       @ftp.expects(:close)
       FtpService.new('host', 'user', 'pass').close
     end

data/spec/tempfile_helper_spec.rb

@@ -0,0 +1,62 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'tempfile_helper'
+
+describe "TempfileHelper" do
+  describe '.read([name]) { |tempfile| }' do
+    before do
+      @tempfile = nil
+      TempfileHelper.read { |@tempfile| }
+    end
+    
+    it "yields a Tempfile object" do
+      @tempfile.should be_a(Tempfile)
+    end
+    
+    it "closes the tempfile object after the block executes" do
+      @tempfile.should be_closed
+    end
+    
+    it "closes the tempfile object even if an exception is raised" do
+      tempfile = nil
+      lambda {
+        TempfileHelper.read { |tempfile| raise "boom" }
+      }.should raise_error
+      tempfile.should be_closed
+    end
+    
+    it "accepts an optional name for the tempfile" do
+      tempfile = nil
+      TempfileHelper.read('the_name') { |tempfile| }
+      tempfile.path.should include('the_name')
+    end
+    
+    it "returns contents of the tempfile after the block is executed" do
+      TempfileHelper.read do |tempfile|
+        tempfile.write('the contents')
+      end.should == 'the contents'
+    end
+  end
+  
+  describe '.write_temp_file(content[, name])' do
+    before do
+      @tempfile = TempfileHelper.write('the content')
+    end
+    
+    it "returns a tempfile object" do
+      @tempfile.should be_a(Tempfile)
+    end
+    
+    it "writes the passed content to the temp file" do
+      File.read(@tempfile.path).should == 'the content'
+    end
+    
+    it "closes the tempfile object" do
+      @tempfile.should be_closed
+    end
+
+    it "accepts an optional name for the temp file" do
+      tempfile = TempfileHelper.write('the content', 'the_name')
+      tempfile.path.should include('the_name')
+    end
+  end
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Justin Blake
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-05 00:00:00 -05:00
+date: 2010-03-08 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -45,6 +45,18 @@ dependencies:
         version: 0.9.8
   type: :development
   version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
 description: An FTP Service is like a web service except stupid. You send your request by uploading an xml file and get your response by downloading another xml file.
 email: justin@megablaix.com
 executables: []
@@ -53,19 +65,21 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.markdown
 files: 
-- .document
 - .gitignore
+- CHANGELOG.markdown
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - VERSION
 - ftp_service.gemspec
 - lib/ftp_service.rb
+- lib/tempfile_helper.rb
 - spec/ftp_service_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- spec/tempfile_helper_spec.rb
 has_rdoc: true
 homepage: http://github.com/blaix/ftp_service
 licenses: []
@@ -99,3 +113,4 @@ summary: A class for dealing with the worst possible type of "web" service.
 test_files: 
 - spec/ftp_service_spec.rb
 - spec/spec_helper.rb
+- spec/tempfile_helper_spec.rb

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE

data/README.rdoc

@@ -1,40 +0,0 @@
-= FTP Service
-
-An FTP Service is like a web service except stupid. You send your
-request by uploading an xml file and get your response by downloading
-another xml file. Have you ever had to deal with something like that? I
-have.
-
-== Installation
-  
-  gem install ftp_service
-    
-== Usage
-
-  require 'ftp_service'
-  
-  FtpService.open('host', 'user', 'pass') do |service|
-    path = '/the/remote/path'
-    service.write_request("#{path}/request.xml", '<foo>bar</foo>')
-    response = service.read_response("#{path}/response.xml")
-  end
-
-* +read_response+ will block while it polls the server waiting for a
-  response.
-* Temp files are created for the local request and response files and
-  deleted when no longer needed.
-  
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history. (if you want
-  to have your own version, that is fine but bump version in a commit by
-  itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2010 Justin Blake. See LICENSE for details.