gofer 0.0.1 → 0.1.0

data/HISTORY.md

@@ -0,0 +1,10 @@
+# Revision History
+
+### v0.1.0 20/04/2011
+
+ * Replace string return from run with a 'response' object
+ * Removed 'within' functionality - will be replaced by 'open' later
+ 
+### v0.0.1 03/04/2011
+
+ * Initial release

data/README.md

@@ -5,73 +5,67 @@
 **Gofer** has been written to support the needs of system automation scripts. As such, **gofer** will:
 
   * automatically raise an error if a command returns a non-zero exit status
-  * print and capture STDOUT automatically
-  * print STDERR but don't capture it
-  * override the above: return non-zero exit status instead of raising an error, capture STDERR, suppress output
+  * print and capture STDOUT and STDERR automatically
+  * allow you to access captured STDOUT and STDERR individually or as a combined string
+  * override the above: return non-zero exit status instead of raising an error, suppress output
 
 ## Examples
 
-    # in a block
-    Gofer::Host.new('ubuntu', 'my.host.com', :identity_file => 'key.pem').within do
-      # Basic usage
-      run "sudo stop mysqld"
+### Instantiation
 
-      # Copying files
-      upload 'file' 'remote_file'
-      download 'remote_dir', 'dir'
+    h = Gofer::Host.new('ubuntu', 'my.host.com', :identity_file => 'key.pem')
 
-      # Filesystem inspection
-      if exists?('remote_directory')
-        run "rm -rf 'remote_directory'"
-      end
+### Run a command
 
-      # read/ls
-      puts read('a_remote_file')
-      puts ls('a_remote_dir').join(", ")
+    h.run "sudo stop mysqld"
 
-      # error handling - default to critical failure if a command fails
-      run "false" # this will fail
-      run "false", :capture_exit_status => true # this won't ...
-      puts last_exit_status # and will make the exit status available
+### Copy some files
 
-      # stderr/stdout
-      hello = run "echo hello" # will print 'hello'
-      puts hello # will print "hello\n"
+    h.upload 'file', 'remote_file'
+    h.download 'remote_dir', 'dir'
 
-      goodbye = run "echo goodbye 1>&2"
-      # goodbye will be empty, as we don't capture stderr by default
-  
-      goodbye = run "echo goodbye 1>&2", :capture_stderr => true # unless you ask for it
-
-      # output suppression
-      run "echo noisy", :quiet => true  # don't output from our command
-      run "echo noisier 1>&2", :quiet_stderr => true # don't even output stderr!
+### Interact with the filesystem
 
+    if h.exists?('remote_directory')
+      h.run "rm -rf 'remote_directory'"
     end
 
-    # using the instance directly
-    h = Gofer::Host.new('ubuntu', 'my.host.com')
-    h.run('sudo mysqld stop')
-    h.upload('file', 'remote_file')
-    # etc..
+    puts h.read('a_remote_file')
+    puts h.ls('a_remote_dir').join(", ")
+    
+### Respond to command errors
+
+    h.run "false" # this will fail
+    response = h.run "false", :capture_exit_status => true # this won't ...
+    puts response.exit_status # and will make the exit status available
+
+### Capture output
+
+    response = h.run "echo hello; echo goodbye 1>&2\n"
+    puts response         # will print "hello\n"
+    puts response.stdout  # will also print "hello\n"
+    puts response.stderr  # will print "goodbye\n"
+    puts response.output  # will print "hello\ngoodbye\n"
+
+### Suppress output
+
+    h.run "echo noisy", :quiet => true  # don't output from our command
+    h.run "echo noisier 1>&2", :quiet_stderr => true # don't even output stderr!
 
 ## Planned Features
 
-    write("a string buffer", 'a_remote_file')
+    h.write("a string buffer", 'a_remote_file')
     # constant connection (no reconnect for each action)
-    h = Gofer::Host.new(..., :keep_open => true)
-    h.run( ... )
-    h.close
-
+    Gofer::Host.new(...).open do |h|
+      h.run( ... )
+    end
+    
     # overriding defaults
-    set :quiet => true
-    set :capture_exit_status => false
-
-    # Separate the command from the arguments, system() style
-    run "echo" "Some" "arguments" "with" "'quotes'" "in" "them"
+    h.set :quiet => true
+    h.set :capture_exit_status => false
     
     # Local system usage, too:
-    run "hostname" # > my.macbook.com
+    Gofer::Localhost.new.run "hostname" # > my.macbook.com
 
 ## Testing
   
@@ -82,6 +76,7 @@
  
 * ls, exists?, directory? should use sftp if available rather than shell commands
 * wrap STDOUT with host prefix for easy identification of system output
+* RDoc
 
 ## License
 

data/lib/gofer.rb

@@ -1,4 +1,5 @@
 require 'gofer/ssh_wrapper'
+require 'gofer/response'
 require 'gofer/host'
 require 'gofer/version'
 

data/lib/gofer/host.rb

@@ -7,7 +7,7 @@ module Gofer
  
   class Host
 
-    attr_reader :last_exit_status, :hostname
+    attr_reader :hostname
 
     def initialize username, _hostname, identity_file=nil
       @hostname = _hostname
@@ -15,18 +15,15 @@ module Gofer
     end
 
     def run command, opts={}
-      @ssh.run command, opts
-      if opts[:capture_exit_status]
-        @last_exit_status = @ssh.last_exit_status
-      elsif @ssh.last_exit_status != 0
+      response = @ssh.run command, opts
+      if !opts[:capture_exit_status] && response.exit_status != 0
         raise HostError.new(self, "Command #{command} failed with exit status #{@ssh.last_exit_status}")
       end
-      @ssh.last_output
+      response
     end
 
     def exists? path
-      @ssh.run "sh -c '[ -e #{path} ]'"
-      @ssh.last_exit_status == 0
+      @ssh.run("sh -c '[ -e #{path} ]'").exit_status == 0
     end
 
     def read path
@@ -34,16 +31,15 @@ module Gofer
     end
 
     def directory? path
-      @ssh.run "sh -c '[ -d #{path} ]'"
-      @ssh.last_exit_status == 0
+      @ssh.run("sh -c '[ -d #{path} ]'").exit_status == 0
     end
 
     def ls path
-      @ssh.run "ls -1 #{path}", :quiet => true
-      if @ssh.last_exit_status == 0
-        @ssh.last_output.strip.split("\n")
+      response = @ssh.run "ls -1 #{path}", :quiet => true
+      if response.exit_status == 0
+        response.stdout.strip.split("\n")
       else
-        raise HostError.new(self, "Could not list #{path}, exit status #{@ssh.last_exit_status}")
+        raise HostError.new(self, "Could not list #{path}, exit status #{response.exit_status}")
       end
     end
 
@@ -54,9 +50,5 @@ module Gofer
     def download from, to
       @ssh.download from, to, :recursive => directory?(from)
     end
-
-    def within &block
-      instance_eval &block
-    end
   end
 end

data/lib/gofer/response.rb

@@ -0,0 +1,13 @@
+module Gofer
+  class Response < String
+    attr_reader :stdout, :stderr, :output, :exit_status
+    
+    def initialize (_stdout, _stderr, _output, _exit_status)
+      super _stdout
+      @stdout = _stdout
+      @stderr = _stderr
+      @output = _output
+      @exit_status = _exit_status
+    end
+  end
+end

data/lib/gofer/ssh_wrapper.rb

@@ -15,9 +15,11 @@ module Gofer
     end
 
     def run command, opts={}
+      response = nil
       Net::SSH.start(*net_ssh_credentials) do |ssh|
-        ssh_execute(ssh, command, opts)
+        response = ssh_execute(ssh, command, opts)
       end
+      response
     end
     
     def read_file path
@@ -55,7 +57,7 @@ module Gofer
     end
 
     def ssh_execute(ssh, command, opts={})
-      output = ''
+      stdout, stderr, output = '', '', ''
       exit_code = 0
       ssh.open_channel do |channel|
         channel.exec(command) do |ch, success|
@@ -64,13 +66,15 @@ module Gofer
           end
 
           channel.on_data do |ch, data|  # stdout
+            stdout += data
             output += data
             $stdout.print data unless opts[:quiet]
           end
 
           channel.on_extended_data do |ch, type, data|
             next unless type == 1 # only handle stderr
-            output += data if opts[:capture_stderr]
+            stderr += data
+            output += data
             $stderr.print data unless opts[:quiet_stderr]
           end
 
@@ -83,9 +87,7 @@ module Gofer
       end
 
       ssh.loop
-      
-      @last_exit_status = exit_code
-      @last_output = output
+      Gofer::Response.new(stdout, stderr, output, exit_code)
     end
   end
 end

data/lib/gofer/version.rb

@@ -1,3 +1,3 @@
 module Gofer
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/gofer/integration_spec.rb

@@ -49,19 +49,26 @@ describe Gofer do
   end
 
   describe :run do
-    it "should run a command and capture its output" do
-      output = @host.run "echo hello", :quiet => true
-      output.should == "hello\n"
-    end
-
-    it "should run a command not capture its stderr by default" do
-      output = @host.run "echo hello 1>&2", :quiet_stderr => true
-      output.should == ""
-    end
-
-    it "should run a command capture its stderr if asked" do
-      output = @host.run "echo hello 1>&2", :quiet_stderr => true, :capture_stderr => true
-      output.should == "hello\n"
+    describe "with stdout and stderr responses" do
+      before :all do 
+        @response = @host.run "echo stdout; echo stderr 1>&2", :quiet => true, :quiet_stderr => true
+      end
+    
+      it "should capture stdout in @response.stdout" do
+        @response.stdout.should == "stdout\n"
+      end
+    
+      it "should capture stderr in @response.stderr" do
+        @response.stderr.should == "stderr\n"
+      end
+    
+      it "should combine captured stdout / stderr in @response.output" do
+        @response.output.should == "stdout\nstderr\n"
+      end
+    
+      it "@response by itself should be the captured stdout" do
+        @response.should == "stdout\n"
+      end
     end
   
     it "should error if a command returns a non-zero response" do
@@ -69,8 +76,8 @@ describe Gofer do
     end
 
     it "should capture a non-zero exit status if asked" do
-      @host.run "false", :capture_exit_status => true
-      @host.last_exit_status.should == 1
+      response = @host.run "false", :capture_exit_status => true
+      response.exit_status.should == 1
     end
   end
 
@@ -154,12 +161,4 @@ describe Gofer do
       end
     end
   end
-
-  describe :within do
-    it "should execute commands in the context of the host instance" do
-      @host.within do
-        run("echo sup", :quiet => true).should == "sup\n"
-      end
-    end
-  end
 end

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: gofer
 version: !ruby/object:Gem::Version 
-  hash: 29
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 1
-  version: 0.0.1
+  prerelease: 
+  version: 0.1.0
 platform: ruby
 authors: 
 - Michael Pearson
@@ -15,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-03 01:00:00 +11:00
+date: 2011-04-20 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,11 +21,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 33
-        segments: 
-        - 2
-        - 0
-        - 23
         version: 2.0.23
   type: :runtime
   version_requirements: *id001
@@ -42,19 +32,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 31
-        segments: 
-        - 1
-        - 0
-        - 4
         version: 1.0.4
   type: :runtime
   version_requirements: *id002
-description: |
-  
-  Gofer provides a flexible and reliable model for performing tasks on remote
-  server using Net::SSH
-
+description: "\n\
+  Gofer provides a flexible and reliable model for performing tasks on remote\n\
+  server using Net::SSH\n"
 email: 
 - mipearson@gmail.com
 executables: []
@@ -66,12 +49,13 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- HISTORY.md
 - README.md
 - Rakefile
 - gofer.gemspec
 - lib/gofer.rb
 - lib/gofer/host.rb
-- lib/gofer/options.rb
+- lib/gofer/response.rb
 - lib/gofer/ssh_wrapper.rb
 - lib/gofer/version.rb
 - spec/gofer/integration_spec.rb
@@ -90,23 +74,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: run commands on remote servers using SSH

data/lib/gofer/options.rb

@@ -1,37 +0,0 @@
-# Unused, keeping for later use.
-module Gofer
-  class Options
-    VALID_OPTIONS => %w{identity_file}
-
-    def valid_options
-      VALID_OPTIONS
-    end
-  
-    def initialize
-      @options = {}
-    end
-
-    def merge_in opts={}
-      opts.each |k,v|
-        set k, v
-      end
-    end
-  
-    def set k, v
-      k = option_valid_check(k)
-      @options[k] = v
-    end
-
-    def get k
-      k = option_valid_check(k)
-      @options[k] 
-    end
-   
-    private
-
-    def option_valid_check(k) 
-      k = k.to_s
-      raise "Invalid option #{k}" unless valid_options.include?(k)
-    end
-  end
-end