rubysh 0.0.1

data/.gitignore

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Greg Brockman
+
+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,88 @@
+# Rubysh
+
+Rubysh: Ruby subprocesses made easy
+
+Rubysh makes shelling out easy with a __sh__-like syntax layer for Ruby:
+
+    irb -r rubysh
+    >> command = Rubysh('echo', 'hello-from-Rubysh') | Rubysh('grep', '--color', 'Rubysh')
+    >> command.run
+    hello-from-Rubysh
+    => Rubysh::Runner: echo hello-from-Rubysh | grep --color Rubysh (exitstatus: 0)
+
+Rubysh philosophy is to make simple tasks simple and complex tasks
+possible.
+
+## Motivation
+
+Existing Ruby shell libaries make it very difficult to do tasks that
+are simple in __sh__, such as:
+
+  - piping the output from one program to another
+  - redirecting a program's output to a file
+  - use a pre-tokenized array of arguments
+
+Rubysh tries to emulate __sh__'s interface and semantics as closely as
+possible.
+
+## Features
+
+Redirecting a file descriptor to a file:
+
+    # echo hello-from-Rubysh >/tmp/file.txt
+    Rubysh('echo', 'hello-from-Rubysh', Rubysh.stdout > '/tmp/file.txt')
+    Rubysh('echo', 'hello-from-Rubysh', Rubysh::FD(1) > '/tmp/file.txt')
+
+Redirecting a file descriptor to another file descriptor:
+
+    # echo hello-from-Rubysh 2>&1
+    Rubysh('echo', 'hello-from-Rubysh', Rubysh.stderr > Rubysh.stdout)
+
+Feeding standard input with a string literal:
+
+    # cat <<< "hello there"
+    Rubysh('cat', Rubysh.<<< 'hello there')
+
+Rubysh has been written to work with arbitrary file descriptors, so
+you can do the same advanced FD redirection magic you can in __sh__:
+
+    # cat 3<<< "hello there" <&3
+    Rubysh('cat', Rubysh::FD(3).<<< 'hello there', Rubysh.stdin < Rubysh::FD(3))
+
+You can also capture output to a named target (here :stdout, :stderr
+are arbitrary symbols):
+
+    command = Rubysh('echo', 'hi', Rubysh.stdout > :stdout, Rubysh.stderr > :stderr)
+    runner = command.run
+    runner.data(:stdout) # "hi\n"
+    runner.data(:stderr) # ""
+
+Support for controlled input isn't quite ready, but the syntax will be
+similar to the above. I want to support interactivity (so being able
+to write data, read some data, and then write more data), and haven't
+quite decided on the right API for this yet.
+
+## API
+
+The Rubysh helper function produces instances of __BaseCommand__. You
+can run __run__ on these to spawn a subprocess and then __wait__ for
+it to complete. Alternatively, you can do:
+
+    command = Rubysh('ls')
+    runner = command.run_async
+    runner.wait
+
+## Installation
+
+Rubysh is hosted on Rubygems. You can install by adding this line to
+your application's Gemfile:
+
+    gem 'rubysh'
+
+Or by installing directly via
+
+    $ gem install rubysh
+
+## Contributing
+
+Patches welcome! I'm happy to merge pull requests.

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+# require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs = ["lib"]
+  # t.warning = true
+  t.verbose = true
+  t.test_files = FileList['test/**/*.rb']
+end

data/lib/rubysh/base_command.rb

@@ -0,0 +1,65 @@
+require 'shellwords'
+
+module Rubysh
+  # TODO:
+  #
+  # - freeze after initialize?
+  class BaseCommand
+    def stringify_arg(arg)
+      case arg
+      when BaseCommand, BaseDirective
+        arg.stringify
+      else
+        Shellwords.shellescape(arg.to_s)
+      end
+    end
+
+    def to_s
+      "Command: #{stringify}"
+    end
+
+    def inspect
+      to_s
+    end
+
+    def create_runner
+      Runner.new(self)
+    end
+
+    def run
+      create_runner.run
+    end
+
+    def run_async
+      create_runner.run_async
+    end
+
+    def |(other)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def initialize(args)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def start_async(runner)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def wait(runner)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def stringify
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def stdout=(value)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def stdin=(value)
+      raise NotImplementedError.new("Override in subclass")
+    end
+  end
+end

data/lib/rubysh/base_directive.rb

@@ -0,0 +1,24 @@
+module Rubysh
+  class BaseDirective
+    def stringify
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def prepare!(runner)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def apply_parent!(runner)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    def apply!(runner)
+      raise NotImplementedError.new("Override in subclass")
+    end
+
+    # TODO: DRY up?
+    def state(runner)
+      runner.state(self)
+    end
+  end
+end

data/lib/rubysh/command.rb

@@ -0,0 +1,102 @@
+module Rubysh
+  class Command < BaseCommand
+    attr_accessor :raw_args, :directives, :args
+
+    def initialize(args)
+      @raw_args = args
+      @directives = []
+      @args = nil
+
+      process_args
+    end
+
+    def process_args
+      @args = @raw_args.map do |arg|
+        case arg
+        when BaseCommand
+          raise NotImplementedError.new('Not ready for subshells yet')
+        when BaseDirective
+          @directives << arg
+          nil
+        else
+          arg.to_s
+        end
+      end.compact
+    end
+
+    def stringify
+      @raw_args.map do |arg|
+        stringify_arg(arg)
+      end.join(' ')
+    end
+
+    def |(other)
+      Pipeline.new([self, other])
+    end
+
+    def post_fork(runner, &blk)
+      extra_post_forks(runner) << blk
+    end
+
+    def set_stdout(runner, value)
+      directive = FD.new(:stdout) > value
+      add_directive(runner, directive)
+    end
+
+    def set_stdin(runner, value)
+      directive = FD.new(:stdin) < value
+      add_directive(runner, directive)
+    end
+
+    def status(runner)
+      state(runner)[:subprocess].status
+    end
+
+    def pid(runner)
+      state(runner)[:subprocess].pid
+    end
+
+    def prepare!(runner)
+      @directives.each {|directive| directive.prepare!(runner)}
+    end
+
+    def start_async(runner)
+      # Need to call this *after* we've set up pipeline
+      # PipeWrappers. Would prefer to call it in prepare!, but then
+      # we'd have to take care of closing the FDs in the parent
+      # process here anyway.
+      prepare_subprocess(runner)
+      state(runner)[:subprocess].run
+    end
+
+    def wait(runner)
+      state(runner)[:subprocess].wait
+    end
+
+    private
+
+    def add_directive(runner, directive)
+      extra_directives(runner) << directive
+    end
+
+    def state(runner)
+      runner.state(self)
+    end
+
+    def extra_directives(runner)
+      state(runner)[:extra_directives] ||= []
+    end
+
+    def extra_post_forks(runner)
+      state(runner)[:extra_post_forks] ||= []
+    end
+
+    def prepare_subprocess(runner)
+      # extras first because they are currently only used for
+      # pipeline, which should not win out over internal redirects.
+      directives = extra_directives(runner) + @directives
+      post_forks = extra_post_forks(runner)
+      state(runner)[:subprocess] = Subprocess.new(args, directives, post_forks, runner)
+    end
+  end
+end

data/lib/rubysh/error.rb

@@ -0,0 +1,20 @@
+module Rubysh
+  module Error
+    class BaseError < Exception; end
+
+    class ExecError < BaseError
+      # Exception klass and caller from the child process
+      attr_accessor :klass, :caller
+
+      def initialize(message, klass, caller)
+        super(message)
+        @klass = klass
+        @caller = caller
+      end
+    end
+
+    class UnreachableError < BaseError; end
+    class AlreadyClosedError < BaseError; end
+    class AlreadyRunError < BaseError; end
+  end
+end

data/lib/rubysh/fd.rb

@@ -0,0 +1,43 @@
+module Rubysh
+  class FD
+    attr_accessor :fileno
+
+    def initialize(fileno)
+      case fileno
+      when Integer
+        # pass
+      when :stdin
+        fileno = 0
+      when :stdout
+        fileno = 1
+      when :stderr
+        fileno = 2
+      else
+        raise Rubysh::Error::BaseError.new("Fileno must be an integer or one of :stdin, :stdout, :stderr, not #{fileno.inspect}")
+      end
+
+      @fileno = fileno
+    end
+
+    def >(target)
+      Redirect.new(self, '>', target)
+    end
+
+    def <(target)
+      Redirect.new(self, '<', target)
+    end
+
+    def <<
+      Rubysh.<<(self)
+    end
+
+    def to_s
+      "FD: #{@fileno}"
+    end
+
+    def ==(other)
+      self.class == other.class &&
+        self.fileno == other.fileno
+    end
+  end
+end

data/lib/rubysh/pipe.rb

@@ -0,0 +1,4 @@
+module Rubysh
+  class Pipe < Directive
+  end
+end

data/lib/rubysh/pipeline.rb

@@ -0,0 +1,70 @@
+module Rubysh
+  class Pipeline < BaseCommand
+    attr_accessor :pipeline
+
+    def initialize(pipeline)
+      raise Rubysh::Error::BaseError.new("Cannot create an empty pipeline") if pipeline.length == 0
+      @pipeline = pipeline
+    end
+
+    # sh semantics are that your exitstatus is that of the last in the
+    # pipeline
+    def status(runner)
+      @pipeline[-1].status(runner)
+    end
+
+    def pid(runner)
+      @pipeline[-1].pid(runner)
+    end
+
+    def prepare!(runner)
+      @pipeline.each {|command| command.prepare!(runner)}
+    end
+
+    def pipeline_pairs
+      @pipeline[0...-1].zip(@pipeline[1..-1])
+    end
+
+    def stringify
+      @pipeline.map {|cmd| cmd.stringify}.join(' | ')
+    end
+
+    def |(other)
+      self.class.new(pipeline + [other])
+    end
+
+    def start_async(runner)
+      last_pipe = nil
+
+      pipeline_pairs.each do |left, right|
+        # TODO: maybe create an object to represent the pipe
+        # relationship, instead of manually assembling here.
+        #
+        # Don't want to have more than 2 pipes open at a time, so need
+        # to #run_async and #close here.
+        pipe = Subprocess::PipeWrapper.new
+        setup_pipe(runner, pipe, left, right)
+
+        left.start_async(runner)
+        last_pipe.close if last_pipe
+        last_pipe = pipe
+      end
+
+      @pipeline[-1].start_async(runner)
+      last_pipe.close if last_pipe
+    end
+
+    def setup_pipe(runner, pipe, left, right)
+      left.set_stdout(runner, pipe.writer)
+      right.set_stdin(runner, pipe.reader)
+    end
+
+    def wait(runner)
+      # It's likely we should actually wait for these in parallel; I'm
+      # not really sure right now. Might be tricky to avoid waiting
+      # for other processes run by this program (could probably use
+      # process groups for that?)
+      @pipeline.each {|cmd| cmd.wait(runner)}
+    end
+  end
+end

data/lib/rubysh/redirect.rb

@@ -0,0 +1,181 @@
+module Rubysh
+  # Note that in bash, the semantics of redirection appear to be
+  # following (tested empirically, rather than reading a spec):
+  #
+  # - [a<&b] and [a>&b] mean the same thing: copy FD b to a
+  #   (try 'echo test 3>/tmp/testing.txt 1<&3')
+  # - [a<&a] appears to be a no-op: ls /dev/fd 9<&9
+  # - If b != a is an invalid file descriptor, then [a>&b] throws an
+  #   error.
+  # - Pathnames can only be on the right-hand side of a redirect.
+  class Redirect < BaseDirective
+    VALID_DIRECTIONS = ['<', '>', '>>']
+
+    attr_accessor :source, :direction, :target
+
+    def initialize(source, direction, target)
+      unless VALID_DIRECTIONS.include?(direction)
+        raise Rubysh::Error::BaseError.new("Direction must be one of #{VALID_DIRECTIONS.join(', ')}, not #{direction.inspect}")
+      end
+
+      unless source.kind_of?(IO) || source.kind_of?(FD) || source.kind_of?(Integer)
+        raise Rubysh::Error::BaseError.new("Invalid source: #{source.inspect}. Source must be an IO, a Rubysh::FD, or an Integer.")
+      end
+
+      unless target.respond_to?(:fileno) || target.kind_of?(Integer) || target.kind_of?(String) || target.kind_of?(Symbol)
+        raise Rubysh::Error::BaseError.new("Invalid target: #{target.inspect}. Target must respond to :fileno or be an Integer, a String, or a Symbol.")
+      end
+
+      @source = source
+      @target = target
+      @direction = direction
+    end
+
+    def printable_source
+      Util.to_fileno(source)
+    end
+
+    def printable_target
+      case target
+      when Symbol
+        target.inspect
+      else
+        Util.to_fileno(target)
+      end
+    end
+
+    # TODO: support files
+    def stringify
+      source_file = printable_source
+      target_file = printable_target
+
+      case direction
+      when '<', '>>'
+        source_file = nil if source_file == 0
+      when '>'
+        source_file = nil if source_file == 1
+      else
+        raise Rubysh::Error::BaseError.new("Unrecognized direction: #{direction.inspect}")
+      end
+
+      ampersand = target_file.kind_of?(Integer) ? '&' : nil
+
+      "#{source_file}#{direction}#{ampersand}#{target_file}"
+    end
+
+    def to_s
+      "Redirect: #{stringify}"
+    end
+
+    def ==(other)
+      self.class == other.class &&
+        self.printable_source == other.printable_source &&
+        self.printable_target == other.printable_target
+    end
+
+    def reading?
+      direction == '<'
+    end
+
+    def target_reading?
+      !reading?
+    end
+
+    def writing?
+      !reading?
+    end
+
+    def target_writing?
+      !writing?
+    end
+
+    def truncate?
+      direction == '>'
+    end
+
+    def named_target?
+      target.kind_of?(Symbol)
+    end
+
+    def target_name
+      raise Rubysh::Error::BaseError.new("Not a named target") unless named_target?
+      target
+    end
+
+    def prepare!(runner)
+      prepare_target(runner)
+    end
+
+    def prepare_target(runner)
+      return unless named_target?
+      targets = runner.targets
+      if targets.include?(target_name)
+        raise Rubysh::Error::BaseError.new("#{runner} already has a named target: #{target_name.inspect}")
+      end
+
+      pipe = Subprocess::PipeWrapper.new
+
+      targets[target_name] = {
+        :target_reading? => target_reading?,
+        :target => target_reading? ? pipe.reader : pipe.writer,
+        :complement => target_reading? ? pipe.writer : pipe.reader,
+        :buffer => []
+      }
+    end
+
+    # E.g. Rubysh.stdin < :stdin
+    def apply_parent!(runner)
+      return unless named_target?
+      target_state = runner.target_state(target_name)
+      target_state[:complement].close
+    end
+
+    def apply!(runner)
+      Rubysh.log.info("About to apply #{self} for #{$$}")
+
+      # Open the target
+      target_io = file_as_io(runner, target)
+
+      target_fd = Util.to_fileno(target_io)
+      source_fd = Util.to_fileno(source)
+
+      # Copy target -> source
+      Util.dup2(target_fd, source_fd)
+      Util.set_cloexec(source_fd, false)
+    end
+
+    private
+
+    # If providing your own open FD, you have to set cloexec yourself.
+    def file_as_io(runner, file, default_to_cloexec=true)
+      return file if file.kind_of?(IO)
+      # If it's an FD, canonicalize to the FD number
+      file = Util.to_fileno(file)
+
+      if file.kind_of?(Integer)
+        io = Util.io_without_autoclose(file)
+        # Someone else opened
+        default_to_cloexec = false
+      elsif file.kind_of?(String) && reading?
+        io = File.open(file)
+      elsif file.kind_of?(String) && writing? && truncate?
+        # Make the following cases explicit for future compatability
+        # (also to make it clear on an exception which case is at
+        # fault).
+        io = File.open(file, 'w')
+      elsif file.kind_of?(String) && writing? && !truncate?
+        io = File.open(file, 'a')
+      elsif file.kind_of?(Symbol)
+        target_state = runner.target_state(file)
+        io = target_state[:complement]
+        # Someone else opened
+        default_to_cloexec = false
+      else
+        raise Rubysh::Error::BaseError.new("Unrecognized file spec: #{file.inspect}")
+      end
+
+      io.fcntl(Fcntl::F_SETFD, Fcntl::FD_CLOEXEC) if default_to_cloexec
+      io
+    end
+  end
+end