shellter 0.9.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rvmrc

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in shellter.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Andrew Eberbach
+
+MIT License
+
+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/README.md

@@ -0,0 +1,89 @@
+# Shellter
+
+Do YOU like to fork(2)? Do YOU like cocaine(https://github.com/thoughtbot/cocaine)? Of course, we all do. The problem is that I needed a ever-rounder wheel than what I've found. The Escape gem was a nice place to find shell escaping... but it didn't do interpolation or actually execute anything. The Cocaine gem was a nice place to find interpolation, but its escaping was a bit too simple for my tastes and it didn't manage STDERR, STDOUT in a way that let me inspect them easily afterward. I've also always wanted to be able to start a process in the background without having to worry about what I need to close and open and how many times I need to fork (but if you want to know everything about it, I'd suggest you read http://workingwithunixprocesses.com/). 
+
+So in the grand spirit of the GitHubs here's a gem that does all of the above. The idea is that your result is going to be more than just an exit status. Here's what you'll get:
+
+* The fully interpolated command that was last run
+* The exit status
+* The entire STDERR and STDOUT
+* The PID
+
+Yes, of course I'm using POpen4 under the covers. The interpolation is taken from Cocaine and modified to use Escape to do the shell escaping. 
+
+The point is that it's supposed to be an easy-to-remember, easy-to-use library that takes care of everything else. 
+
+## Backgrounding
+
+Sure there's a ton of gems that let you manage background processes and the like. Daemons (http://daemons.rubyforge.org/) is an obvious example. Sometimes, though, you just want to "fire and forget." Shellter provides a SIMPLE way of demonizing a command whilst returning you its PID so that you can do with it what you like.  
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'shellter'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install shellter
+
+## Usage
+
+The most basic usage is like this:
+
+	result = Shellter.run("ls")
+	
+That's it. This returns a Shellter::Command which has the following variables:
+
+	result.pid
+	result.stdout
+	result.stderr
+	result.last_command # the fully-interpolated command that was run
+	
+Want to pass arguments that you KNOW are safe? 
+
+	Shellter.run("ls", "-l", "*.rb") # ls -l *.rb
+	
+Want to pass arguments that might have spaces in them? 
+
+	myvar = "'\"\'some ../../weird#""'`#{}` filena_?me"
+	Shellter.run("ls", "-l", ":weird", :weird => myvar) # ls -l \''"'\''some ../../weird#'\''`` filena_?me'
+	
+	hateful = "'$(rm -rf *.foo)"
+	Shellter.run("ls", "-l", ":weird", :weird => hateful) # ls -l \''$(rm -rf *.foo)'
+
+Want to raise an exception if the command doesn't return 0?
+	
+	Shellter.run!("ls", "*.missing") # RuntimeError: Execution failed, with exit code 256
+	
+Want to find out if the command ran ok?
+
+	Shellter.run("ls", "*.missing").success? # false
+	
+Want to provide a list of exit codes that you're ok with? 
+
+	Shellter.run!("ls", "*.missing", :expected_outcodes => [0, 256]).success? # true
+	
+Want to start that command in the background? 
+
+	Shellter.run("ls", :background => true)
+	
+*NOTE:* When backgrounded, the command `fork`s twice in order to fully detach from the session. This, of course, means that the stderr, and stdout will be empty. The pid, however, will be of the last `fork` before `exec`-ing.
+
+*NOTE:* Before backgrounding we check to see if `fork` is actually available and throw an Exception if it isn't. 
+
+Also included is an implementation of the UNIX `which` command:
+
+	Shellter.which("ls") # /bin/ls
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/shellter/class_methods.rb

@@ -0,0 +1,39 @@
+module Shellter
+  module ClassMethods
+    def run(command, *arguments)
+      Command.new(command, *arguments).tap do |command|
+        options = arguments.extract_options!
+        command.run(options)
+      end
+    end
+    
+    def run!(command, *arguments)
+      run(command, *arguments).tap do |result|
+        raise "Execution failed, with exit code #{result.exit_code}" unless result.success?
+      end
+    end
+
+    def which(command, paths = nil)
+      paths ||= ENV["PATH"].split(File::PATH_SEPARATOR)
+      extensions = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+
+      paths.each do |path|
+        extensions.each do |extension|          
+          path_with_extension(path, command, extension).tap do |path_to_command|
+            if File.exists?(path_to_command) && File.executable?(path_to_command)
+              return path_to_command 
+            end
+          end
+        end
+      end
+
+      nil
+    end
+
+    private
+
+    def path_with_extension(path, command, extension)
+      File.join(File.expand_path(path), "#{command}#{extension}")
+    end
+  end
+end

data/lib/shellter/command.rb

@@ -0,0 +1,111 @@
+module Shellter
+  class Command
+
+    attr_reader :pid
+    attr_reader :stdout
+    attr_reader :stderr
+    attr_reader :last_command
+
+    def initialize(command, *arguments)
+      options = arguments.extract_options!
+
+      @expected_outcodes = options.delete(:expected_outcodes)
+      @expected_outcodes ||= [0]
+
+      @command = command
+      @arguments = arguments      
+    end
+
+    def run(options = {})
+      with_env(options) do
+        with_runner(options) do |runner|
+          with_interpolated_command(options) do |command|
+            @status = runner.run(command) do |stdout, stderr, stdin, pid|
+              stdin.close
+              @stdout = stdout.read
+              @stderr = stderr.read
+              @pid = pid
+            end
+          end
+        end
+      end
+    end  
+
+    def exit_code
+      @status.to_i
+    end
+
+    def success?
+      @expected_outcodes.include?(exit_code)
+    end
+
+    private
+    
+    def interpolate(pattern, vars)
+      # interpolates :variables and :{variables}
+      pattern.gsub(%r#:(?:\w+|\{\w+\})#) do |match|
+        key = match[1..-1]
+        key = key[1..-2] if key[0,1] == '{'
+        if invalid_variables.include?(key)
+          raise InterpolationError,
+            "Interpolation of #{key} isn't allowed."
+        end
+        interpolation(vars, key) || match
+      end
+    end
+
+    def invalid_variables
+      %w(expected_outcodes swallow_stderr logger)
+    end
+
+    def interpolation(vars, key)
+      if vars.key?(key.to_sym)
+        Escape.shell_single_word(vars[key.to_sym])
+      end
+    end
+
+    def with_env(options = {}, &block)
+      begin
+        saved_env = ENV.to_hash
+        # Bundler.with_clean_env(&block)
+        # command = %Q{. #{vars_file_path} && #{script}}
+        # ENV.update(self.class.environment)
+        yield
+      ensure
+        ENV.update(saved_env)
+      end
+    end
+
+    def with_interpolated_command(options, &block)
+      [].tap do |command_line|
+        command_line << Escape.shell_single_word(@command)
+        command_line += interpolated_arguments(options)
+        
+        command_line.join(" ").tap do |command|
+          @last_command = command        
+          yield command
+        end
+      end
+    end
+    
+    def interpolated_arguments(vars)      
+      @arguments.map do |argument|
+        interpolate(argument, vars)
+      end
+    end
+
+    def with_runner(options = {}, &block)
+      if options[:background]
+        yield Runners::Background.new(options)
+      elsif windows?
+        yield Runners::Windows.new(options)
+      else
+        yield Runners::Base.new(options)
+      end
+    end
+
+    def windows?
+      !!(RbConfig::CONFIG['host_os'] =~ /mswin|mingw/)      
+    end
+  end
+end

data/lib/shellter/core_ext.rb

@@ -0,0 +1,36 @@
+begin 
+  require 'active_support/core_ext/array/extract_options'
+rescue LoadError
+  
+  class Hash
+    # By default, only instances of Hash itself are extractable.
+    # Subclasses of Hash may implement this method and return
+    # true to declare themselves as extractable. If a Hash
+    # is extractable, Array#extract_options! pops it from
+    # the Array when it is the last element of the Array.
+    def extractable_options?
+      instance_of?(Hash)
+    end
+  end
+
+  class Array
+    # Extracts options from a set of arguments. Removes and returns the last
+    # element in the array if it's a hash, otherwise returns a blank hash.
+    #
+    #   def options(*args)
+    #     args.extract_options!
+    #   end
+    #
+    #   options(1, 2)           # => {}
+    #   options(1, 2, :a => :b) # => {:a=>:b}
+    def extract_options!
+      if last.is_a?(Hash) && last.extractable_options?
+        pop
+      else
+        {}
+      end
+    end
+  end
+    
+end
+  

data/lib/shellter/runners/background.rb

@@ -0,0 +1,42 @@
+module Shellter
+  module Runners
+    class Background < Base
+      def run(command, &block)
+        ensure_forking!
+
+        # io for child process
+        reader, writer = IO.pipe 
+
+        # first fork, create a session leader
+        fork do
+          reader.close
+          Process.setsid 
+
+          # second fork, create a detached child
+          # and write its pid to the writer pipe
+          result = fork do
+            Dir.chdir "/" 
+            STDIN.reopen "/dev/null" 
+            STDOUT.reopen "/dev/null", "a" 
+            STDERR.reopen "/dev/null", "a"
+
+            exec command             
+          end
+          
+          # write the pid of the forked child to the pipe
+          writer.puts result
+        end
+
+        writer.close
+        
+        yield StringIO.new, StringIO.new, StringIO.new, reader.gets.strip.to_i
+      end
+      
+      private
+
+      def ensure_forking!
+        raise RuntimeError, "Cannot fork on this system!" unless Process.respond_to?(:fork)      
+      end
+    end
+  end
+end

data/lib/shellter/runners/base.rb

@@ -0,0 +1,13 @@
+module Shellter
+  module Runners
+    class Base
+      def initialize(options = {})
+        
+      end
+      
+      def run(command, &block)
+        POpen4.popen4(command, &block)
+      end
+    end
+  end
+end

data/lib/shellter/runners/windows.rb

@@ -0,0 +1,9 @@
+module Shellter
+  module Runners
+    class Windows < Base
+      def run(command, mode = "b", &block)
+        POpen4.popen4(command, mode, &block)
+      end    
+    end
+  end
+end

data/lib/shellter/version.rb

@@ -0,0 +1,3 @@
+module Shellter
+  VERSION = "0.9.0"
+end

data/lib/shellter.rb

@@ -0,0 +1,17 @@
+require 'escape'
+require 'popen4'
+
+require 'shellter/core_ext'
+
+module Shellter
+  autoload :ClassMethods, "shellter/class_methods"
+  autoload :Command, "shellter/command"
+  autoload :VERSION, "shellter/version"
+  
+  module Runners
+    autoload :Background, "shellter/runners/background"
+    autoload :Base, "shellter/runners/base"
+  end
+  
+  extend ClassMethods
+end

data/shellter.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/shellter/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Andrew Eberbach"]
+  gem.email         = ["andrew@ebertech.ca"]
+  gem.description   = %q{A library to help with command line launching}
+  gem.summary       = %q{A rounder wheel version of its predecessors.}
+  gem.homepage      = "https://github.com/ebertech/shellter"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "shellter"
+  gem.require_paths = ["lib"]
+  gem.version       = Shellter::VERSION
+  
+  gem.add_dependency "popen4"
+  gem.add_dependency "escape"
+  
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "pry-doc"
+  gem.add_development_dependency "pry-nav"
+  gem.add_development_dependency "simplecov"
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: shellter
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+  prerelease: 
+platform: ruby
+authors:
+- Andrew Eberbach
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: popen4
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: escape
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: pry-doc
+  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: pry-nav
+  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: simplecov
+  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: A library to help with command line launching
+email:
+- andrew@ebertech.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/shellter.rb
+- lib/shellter/class_methods.rb
+- lib/shellter/command.rb
+- lib/shellter/core_ext.rb
+- lib/shellter/runners/background.rb
+- lib/shellter/runners/base.rb
+- lib/shellter/runners/windows.rb
+- lib/shellter/version.rb
+- shellter.gemspec
+homepage: https://github.com/ebertech/shellter
+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.24
+signing_key: 
+specification_version: 3
+summary: A rounder wheel version of its predecessors.
+test_files: []
+has_rdoc: