command-runner 0.2.0

data/README.md

@@ -0,0 +1,57 @@
+# Command Runner [![Build Status](https://travis-ci.org/redjazz96/command-runner.png?branch=master)](https://travis-ci.org/redjazz96/command-runner)
+Runs commands.
+
+```Ruby
+require 'command/runner'
+
+line = Command::Runner.new("echo", "hello")
+message = line.pass # => #<Command::Runner::Message:...>
+message.exit_code   # => 0
+message.stdout      # => "hello\n"
+message.time        # => 0.00091773
+message.process_id  # => 9622
+message.line        # => "echo hello"
+```
+
+with interpolations...
+
+```Ruby
+line = Command::Runner.new("echo", "{interpolation}")
+message = line.pass(:interpolation => "watermelons")
+message.stdout # => "watermelons\n"
+message.line   # => "echo watermelons"
+```
+
+that escapes bad stuff...
+
+```Ruby
+message = line.pass(:interpolation => "`uname -a`")
+message.stdout # => "`uname -a`\n"
+message.line   # => "echo \\`uname\\ -a\\`"
+```
+
+unless you don't want it to.
+
+```Ruby
+line = Command::Runner.new("echo", "{{interpolation}}")
+message = line.pass(:interpolation => "`uname -a`")
+message.stdout # => "Linux Hyperion 3.8.0-25-generic #37-Ubuntu SMP Thu Jun 6 20:47:07 UTC 2013 x86_64 x86_64 x86_64 GNU/Linux\n"
+message.line   # => "echo `uname -a`"
+```
+
+It can also use different methods to run commands...
+
+```Ruby
+line = Command::Runner.new("echo", "something")
+line.backends = Command::Runner::Backends::Spawn.new
+line.pass
+```
+
+but defaults to the best one.
+
+## Compatibility
+It works on
+
+- MRI 2.0.0 and 1.9.3
+
+unless the travis build fails.

data/lib/command/runner/backends/backticks.rb

@@ -0,0 +1,84 @@
+module Command
+  class Runner
+    module Backends
+
+      # A backend that uses ticks to do its bidding.
+      class Backticks
+
+        # Returns whether or not this backend is avialable on this
+        # platform.
+        def self.available?
+          true
+        end
+
+        # Initialize the fake backend.
+        def initialize
+          super
+        end
+
+        # Run the given command and arguments, in the given environment.
+        #
+        # @param command [String] the command to run.
+        # @param arguments [String] the arguments to pass to the
+        #   command.
+        # @param env [Hash] the enviornment to run the command
+        #   under.
+        # @param options [Hash] the options to run the command under.
+        # @return [Message] information about the process that ran.
+        def call(command, arguments, env = {}, options = {})
+          super
+          output = ""
+          start_time = nil
+          end_time = nil
+
+          with_modified_env(env) do
+            start_time = Time.now
+            output << `#{command} #{arguments}`
+            end_time = Time.now
+          end
+
+          Message.new :process_id => $?.pid,
+                      :exit_code => $?.exitstatus,
+                      :finished => true,
+                      :time => (end_time - start_time).abs,
+                      :env => env,
+                      :options => {},
+                      :stdout => output,
+                      :line => line,
+                      :executed => true,
+                      :status => $?
+        end
+
+        private
+
+        # If ClimateControl is installed on this system, it runs the
+        # given block with the given environment.  If it's not, it
+        # just yields.
+        #
+        # @yield
+        # @return [Object]
+        def with_modified_env(env)
+          if defined?(ClimateControl) || climate_control?
+            ClimateControl.modify(env, &Proc.new)
+          else
+            yield
+          end
+        end
+
+        # Checks to see if ClimateControl is on this system.
+        #
+        # @return [Boolean]
+        def climate_control?
+          begin
+            require 'climate_control'
+            true
+          rescue LoadError
+            false
+          end
+        end
+
+      end
+    end
+  end
+
+end

data/lib/command/runner/backends/fake.rb

@@ -0,0 +1,58 @@
+module Command
+  class Runner
+    module Backends
+
+      # A fake backend.  Used to a) define what backends should respond
+      # to, and b) provide default behavior for the backends.
+      #
+      # @abstract
+      class Fake
+
+        # Returns whether or not this backend is avialable on this
+        # platform.
+        #
+        # @abstract
+        def self.available?
+          true
+        end
+
+        # Initialize the fake backend.
+        def initialize
+          @ran = []
+
+          raise NotAvailableBackendError unless self.class.available?
+        end
+
+        # Run the given command and arguments, in the given environment.
+        #
+        # @abstract
+        # @note Does nothing.
+        # @param command [String] the command to run.
+        # @param arguments [String] the arguments to pass to the
+        #   command.
+        # @param env [Hash] the enviornment to run the command
+        #   under.
+        # @param options [Hash] the options to run the command under.
+        # @return [Message] information about the process that ran.
+        def call(command, arguments, env = {}, options = {})
+          @ran << [command, arguments]
+
+          Message.new :env => env, :options => options
+        end
+
+        # Determines whether or not the given command and arguments were
+        # ran with this backend.
+        #
+        # @see #call
+        # @param command [String]
+        # @param arguments [String]
+        # @return [Boolean]
+        def ran?(command, arguments)
+          @ran.include?([command, arguments])
+        end
+
+      end
+    end
+  end
+
+end

data/lib/command/runner/backends/posix_spawn.rb

@@ -0,0 +1,36 @@
+module Command
+  class Runner
+    module Backends
+
+      # Spawns a process using POSIX::Spawn.  This is the preferred
+      # method, as POSIX::Spawn is much faster than Process.spawn.
+      class PosixSpawn < Spawn
+
+        # Determines whether or not the PosixSpawn class is available as
+        # a backend.  Does this by checking to see if posix-spawn has been
+        # installed on the local computer; if it hasn't, it returns
+        # false.
+        #
+        # @see Fake.available?
+        # @return [Boolean]
+        def self.available?
+          @_available ||= begin
+            require 'posix/spawn'
+            true
+          rescue LoadError => e
+            false
+          end
+        end
+
+        # Spawns a process with the given line, environment, and options.
+        #
+        # @see Spawn#spawn
+        # @return [Numeric]
+        def spawn(env, line, options)
+          POSIX::Spawn.spawn(env, line, options)
+        end
+
+      end
+    end
+  end
+end

data/lib/command/runner/backends/spawn.rb

@@ -0,0 +1,94 @@
+module Command
+  class Runner
+    module Backends
+
+      # Spawns a process using ruby's Process.spawn.
+      class Spawn < Fake
+
+        # (see Fake.available?)
+        def self.available?
+          Process.respond_to?(:spawn)
+        end
+
+        # Initialize the backend.
+        def initialize
+          super
+        end
+
+        # Run the given command and arguments, in the given environment.
+        #
+        # @param (see Fake#call)
+        # @return (see Fake#call)
+        def call(command, arguments, env = {}, options = {})
+          super
+          stderr_r, stderr_w = IO.pipe
+          stdout_r, stdout_w = IO.pipe
+          stdin_r,  stdin_w  = IO.pipe
+
+          new_options = options.merge(:in => stdin_r,
+            :out => stdout_w, :err => stderr_w)
+
+          if new_options[:input]
+            stdin_w.write(new_options.delete(:input))
+          end
+          stdin_w.close
+
+          line = [command, arguments].join(' ')
+
+          start_time = Time.now
+          process_id = spawn(env, line, new_options)
+
+          future do
+            _, status = wait2(process_id)
+            end_time = Time.now
+
+            [stdout_w, stderr_w].each(&:close)
+
+            Message.new :process_id => process_id,
+                        :exit_code  => status.exitstatus,
+                        :finished   => true,
+                        :time       => (start_time - end_time).abs,
+                        :env        => env,
+                        :options    => options,
+                        :stdout     => stdout_r.read,
+                        :stderr     => stderr_r.read,
+                        :line       => line,
+                        :executed   => true,
+                        :status     => status
+          end
+
+        rescue Errno::ENOENT => e
+          Message.new :exit_code => 127,
+                      :finished  => true,
+                      :time      => -1,
+                      :env       => {},
+                      :options   => {},
+                      :stdout    => "",
+                      :stderr    => e.message,
+                      :line      => line,
+                      :executed  => false
+        end
+
+        # Spawn the given process, in the environment with the
+        # given options.
+        #
+        # @see Process.spawn
+        # @return [Numeric] the process id
+        def spawn(env, line, options)
+          Process.spawn(env, line, options)
+        end
+
+        # Waits for the given process, and returns the process id and the
+        # status.
+        #
+        # @see Process.wait2
+        # @return [Array<(Numeric, Process::Status)>]
+        def wait2(process_id = -1)
+          Process.wait2(process_id)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/command/runner/backends.rb

@@ -0,0 +1,17 @@
+module Command
+
+  class Runner
+
+    # The different backends that the runner can take.  Each of them have a
+    # different method of executing the process.
+    module Backends
+
+      autoload :Fake, "command/runner/backends/fake"
+      autoload :Spawn, "command/runner/backends/spawn"
+      autoload :Backticks, "command/runner/backends/backticks"
+      autoload :PosixSpawn, "command/runner/backends/posix_spawn"
+
+    end
+
+  end
+end

data/lib/command/runner/exceptions.rb

@@ -0,0 +1,10 @@
+module Command
+
+  class Runner
+
+    # Raised when a backend is instantized on a platform that doesn't
+    # support it.
+    class NotAvailableBackendError < StandardError; end
+
+  end
+end

data/lib/command/runner/message.rb

@@ -0,0 +1,101 @@
+module Command
+  class Runner
+
+    # This contains information about the process that was run, such as
+    # its exit code, process id, and even time it took to run.
+    class Message
+
+      # Initialize the message with the given data about the process.
+      #
+      # @param data [Hash] the data about the process.
+      # @option data [Numeric] :exit_code (0) the code the process
+      #   exited with.
+      # @option data [Numeric] :process_id (-1) the process id the
+      #   process ran under.
+      # @option data [Numeric] :time (0) the amount of time the
+      #   process took to run, in seconds.
+      # @option data [Boolean] :executed (false) whether or not the
+      #   process was actually executed.
+      # @option data [Hash] :env ({}) the environment the process
+      #   ran under.
+      # @option data [Hash] :options ({}) the options that the process
+      #   was run under.
+      # @option data [String] :stdout ("\n") the output the command
+      #   outputted on stdout.  This does not include output on stderr.
+      # @option data [String] :stderr ("") the output the command
+      #   outputted on stderr.  This does not include output on stdout.
+      # @option data [String] :line ("") the line that was executed.
+      # @option data [Process::Status] :status (nil) the status of the
+      #   process.
+      def initialize(data)
+        {
+          :executed   => false,
+          :time       => 0,
+          :process_id => -1,
+          :exit_code  => 0,
+          :env        => {},
+          :options    => {},
+          :stdout     => "\n",
+          :stderr     => "",
+          :line       => "",
+          :status     => nil
+        }.merge(data).each do |k, v|
+          instance_variable_set(:"@#{k}", (v.dup rescue v))
+        end
+      end
+
+      # Whether or not the process was actually executed.
+      #
+      # @return [Boolean]
+      def executed?
+        @executed
+      end
+
+      # Whether or not the exit code was non-zero.
+      #
+      # @return [Boolean]
+      def nonzero_exit?
+        exit_code != 0
+      end
+
+      # @!attribute [r] exit_code
+      #   The code the process exited with.
+      #
+      #   @return [Numeric]
+      # @!attribute [r] process_id
+      #   The process id the process ran under.
+      #
+      #   @return [Numeric]
+      # @!attribute [r] time
+      #   The amount of time the process took to run, in seconds.
+      #
+      #   @return [Numeric]
+      # @!attribute [r] stdout
+      #   The standard out of the process that was executed.
+      #
+      #   @return [String]
+      # @!attribute [r] stderr
+      #   The standard error of the process that was executed.
+      #
+      #   @return [String]
+      # @!attribute [r] options
+      #   The options that the user passed when executing the process.
+      #
+      #   @return [Hash]
+      # @!attribute [r] line
+      #   The exact line that was executed.
+      #
+      #   @return [String]
+      # @!attribute [r] status
+      #   The status of the process.
+      #
+      #   @return [Process::Status]
+      [:exit_code, :process_id, :time, :stdout, :stderr, :options,
+        :line, :status].each do |key|
+        define_method(key) { instance_variable_get(:"@#{key}") }
+      end
+
+
+    end
+  end
+end

data/lib/command/runner/version.rb

@@ -0,0 +1,9 @@
+module Command
+
+  class Runner
+
+    # The current version of Runner.
+    VERSION = "0.2.0"
+
+  end
+end

data/lib/command/runner.rb

@@ -0,0 +1,133 @@
+require 'shellwords'
+require 'future'
+
+require 'command/runner/version'
+require 'command/runner/message'
+require 'command/runner/exceptions'
+require 'command/runner/backends'
+
+module Command
+
+  # This handles the execution of commands.
+  class Runner
+
+    class << self
+      # Gets the default backend to use with the messenger.
+      # Defaults to the best available backend.
+      #
+      # @return [#call] a backend to use.
+      def backend
+        @backend ||= best_backend
+      end
+
+      # Returns the best backend for messenger to use.
+      #
+      # @return [#call] a backend to use.
+      def best_backend
+        if Backends::PosixSpawn.available?
+          Backends::PosixSpawn.new
+        elsif Backends::Spawn.available?
+          Backends::Spawn.new
+        elsif Backends::Backticks.available?
+          Backends::Backticks.new
+        else
+          Backends::Fake.new
+        end
+      end
+
+      # Sets the default backend to use with the messenger.
+      attr_writer :backend
+    end
+
+    # The command the messenger was initialized with.
+    #
+    # @return [String]
+    attr_reader :command
+
+    # The arguments the messenger was initialized with.
+    #
+    # @return [String]
+    attr_reader :arguments
+
+    # The options the messenger was initialized with.
+    #
+    # @return [Hash]
+    def options
+      @options.dup.freeze
+    end
+
+    # Gets the backend to be used by the messenger.  If it is not defined
+    # on the instance, it'll get the class default.
+    #
+    # @see Messenger.backend
+    # @return [#call] a backend to use.
+    def backend
+      @backend || self.class.backend
+    end
+
+    # Sets the backend to be used by the messenger.  This is local to the
+    # instance.
+    attr_writer :backend
+
+    # Initialize the messenger.
+    #
+    # @param command [String] the name of the command file to run.
+    # @param arguments [String] the arguments to pass to the command.
+    #   may contain interpolated values, like +{key}+ or +{{key}}+.
+    # @param options [Hash] the options for the messenger.
+    def initialize(command, arguments, options = {})
+      @command = command
+      @arguments = arguments
+      @options = options
+    end
+
+    # Runs the command and arguments with the given interpolations;
+    # defaults to no interpolations.
+    def pass(interops = {}, options = {})
+      backend.call(*[contents(interops), options.delete(:env) || {}, options].flatten)
+    end
+
+    # The command line being run by the runner. Interpolates the
+    # arguments with the given interpolations.
+    #
+    # @see #interpolate
+    # @param interops [Hash] the interpolations to make.
+    # @return [Array<(String, String)>] the command line that will be run.
+    def contents(interops = {})
+      [command, interpolate(arguments, interops)]
+    end
+
+    # Interpolates the given string with the given interpolations.
+    # The keys of the interpolations should be alphanumeric,
+    # including underscores and dashes.  It will search the given
+    # string for +{key}+ and +{{key}}+; if it finds the former, it
+    # replaces it with the escaped value.  If it finds the latter, it
+    # replaces it with the value directly.
+    #
+    # @param string [String] the string to interpolate.
+    # @param interops [Hash] the interpolations to make.
+    # @return [String] the interpolated string.
+    def interpolate(string, interops = {})
+      interops = interops.to_a.map { |(k, v)| { k.to_s => v } }.inject(&:merge) || {}
+
+      string.gsub(/(\{{1,2})([0-9a-zA-Z_\-]+)(\}{1,2})/) do |m|
+        if interops.key?($2) && $1.length == $3.length
+          if $1.length < 2 then escape(interops[$2].to_s) else interops[$2] end
+        else
+          m
+        end
+      end
+    end
+
+    private
+
+    # Escape the given string for a shell.
+    #
+    # @param string [String] the string to escape.
+    # @return [String] the escaped string.
+    def escape(string)
+      Shellwords.escape(string)
+    end
+
+  end
+end

data/spec/messenger_spec.rb

@@ -0,0 +1,60 @@
+describe Command::Runner do
+
+  before :each do
+    Command::Runner.backend = Command::Runner::Backends::Fake.new
+  end
+
+  subject do
+    Command::Runner.new(command, arguments)
+  end
+
+  context "interpolating strings" do
+    let(:command) { "echo" }
+    let(:arguments) { "some {interpolation}" }
+
+    it "interpolates correctly" do
+      subject.contents(:interpolation => "test").should == ["echo", "some test"]
+    end
+
+    it "escapes bad values" do
+      subject.contents(:interpolation => "`bad value`").should == ["echo", "some \\`bad\\ value\\`"]
+    end
+
+    it "doesn't interpolate interpolation values" do
+      subject.contents(:interpolation => "{other}", :other => "hi").should == ["echo", "some \\{other\\}"]
+    end
+  end
+
+  context "double interpolated strings" do
+    let(:command) { "echo" }
+    let(:arguments) { "some {{interpolation}}" }
+
+    it "interpolates correctly" do
+      subject.contents(:interpolation => "test").should == ["echo", "some test"]
+    end
+
+    it "doesn't escape bad values" do
+      subject.contents(:interpolation => "`bad value`").should == ["echo", "some `bad value`"]
+    end
+  end
+
+  context "misinterpolated strings" do
+    let(:command) { "echo" }
+    let(:arguments) { "some {{interpolation}" }
+
+    it "doesn't interpolate" do
+      subject.contents(:interpolation => "test").should == ["echo", "some {{interpolation}"]
+    end
+  end
+
+  context "selects backends" do
+    it "selects the best backend" do
+      Command::Runner::Backends::PosixSpawn.stub(:available?).and_return(false)
+      Command::Runner::Backends::Spawn.stub(:available?).and_return(true)
+      Command::Runner.best_backend.should be_instance_of Command::Runner::Backends::Spawn
+
+      Command::Runner::Backends::PosixSpawn.stub(:available?).and_return(true)
+      Command::Runner.best_backend.should be_instance_of Command::Runner::Backends::PosixSpawn
+    end
+  end
+end

data/spec/spawn_spec.rb

@@ -0,0 +1,31 @@
+describe Command::Runner::Backends::Spawn do
+
+  next unless Process.respond_to? :spawn
+
+  it "is available" do
+    Command::Runner::Backends::Spawn.should be_available
+  end
+
+  it "returns a message" do
+    value = subject.call("echo", "hello")
+    value.should be_instance_of Command::Runner::Message
+    value.should be_executed
+  end
+
+  it "doesn't block" do
+    start_time = Time.now
+    value = subject.call("sleep", "0.5")
+    end_time = Time.now
+
+    (end_time - start_time).should be_within((1.0/100)).of(0)
+    value.time.should be_within((1.0/100)).of(0.5)
+  end
+
+  it "can not be available" do
+    Command::Runner::Backends::Spawn.stub(:available?).and_return(false)
+
+    expect {
+      Command::Runner::Backends::Spawn.new
+    }.to raise_error(Command::Runner::NotAvailableBackendError)
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: command-runner
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Jeremy Rodi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: promise
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! "  Runs a command or two in the shell with arguments that can be\n
+  \ interpolated with the interpolation syntax.\n"
+email: redjazz96@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/command/runner/version.rb
+- lib/command/runner/exceptions.rb
+- lib/command/runner/backends.rb
+- lib/command/runner/message.rb
+- lib/command/runner/backends/fake.rb
+- lib/command/runner/backends/backticks.rb
+- lib/command/runner/backends/posix_spawn.rb
+- lib/command/runner/backends/spawn.rb
+- lib/command/runner.rb
+- spec/messenger_spec.rb
+- spec/spawn_spec.rb
+homepage: http://github.com/redjazz96/command-runner
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Runs commands.
+test_files: []
+has_rdoc: false