komenda 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bde725b71b20821b932fda1e83ba82215bfd27d
-  data.tar.gz: e682bef86069a8d1d175c9e2d84b14f10c3068ac
+  metadata.gz: 88de98a8e1d12b4b613978ba42a78e239e4a37d5
+  data.tar.gz: 0bf5019ac2520a5c51290d7b80a897c3c32ae86c
 SHA512:
-  metadata.gz: ea96829bf08645726f9cc7727e1531c533a528f6f3b4a8cf3cb75648e206b1b624531b89bab09d34e1df06447fd316702945af386aeda93f47add7b83fbb571e
-  data.tar.gz: de7ce00b2c06fa819b2a4b8e3efeaf3cf784e108a78d3b1479db7b3c7aa07f40cbf2599edeb09fecbc7c907c969d0c84d239f88e3e43b7fbaa22ff9a73f6c7dc
+  metadata.gz: 4ecef5f25f1866b5fe846489b26db3e6e4682a87e74d3b7a2a4adabe19ce80d886cd0239e4d6a828ac132b3d89b1cfa51b83b6a2e067d2ceb5626205997e6f24
+  data.tar.gz: b0af38deff1bb138effcda501f5c3c87b2f12ceba21d82b251ecf333347e4a76e8f344e206f44cdf26fb3e1a0cfdd50f6476ad37303ed93462b656e6e3073d4c

data/README.md

@@ -6,14 +6,14 @@ Usage
 -----
 Run a command:
 ```ruby
-Komenda.run("date")
+Komenda.run('date')
 ```
 
 The `run()` method will block until the sub process finished.
 
 It will expose the output and exit status as a `Komenda::Result` value:
 ```ruby
-result = Komenda.run("date")
+result = Komenda.run('date')
 result.stdout   # => "Tue Nov 26 14:45:03 EST 2013\n"
 result.stderr   # => ""
 result.output   # => "Tue Nov 26 14:45:03 EST 2013\n" (combined stdout + stderr)
@@ -21,9 +21,42 @@ result.status   # => 0
 result.success? # => true
 result.pid      # => 32157
 ```
+The program and its arguments can be passed as an array:
+```ruby
+result = Komenda.run(['echo', '-n', 'hello'])
+result.output   # => "hello"
+```
 
 The `run()` method has a second argument `options`, which expects these keys:
 - **`env`** (Hash): The environment variables to use. Defaults to the current process' environment.
+- **`cwd`** (String): Directory to change to before running the process. Defaults to `nil`.
+
+### Advanced usage
+The `create()` method creates a `Process` which can be `start()`ed (in a Thread) and then `wait_for()`ed until finished.
+```ruby
+process = Komenda.create('date')
+thread = process.start
+result = process.wait_for
+```
+
+To start a process and wait for it to finish, call the process' `run()` method:
+```
+process = Komenda.create('date')
+result = process.run
+```
+
+Event callbacks can be registered with `Process.on()`, for example for when output is written.
+```ruby
+process = Komenda.create('date')
+process.on(:stdout) { |output| puts "STDOUT: #{output}" }
+result = process.wait_for
+```
+The following events are emitted:
+- **`.on(:stdout) { |output| }`**: When data is available on STDOUT.
+- **`.on(:stderr) { |output| }`**: When data is available on STDERR.
+- **`.on(:output) { |output| }`**: When data is available on STDOUT or STDERR.
+- **`.on(:exit) { |result| }`**: When the process finishes.
+- **`.on(:error) { |exception| }`**: When process execution fails (e.g. executable file cannot be found).
 
 Development
 -----------
@@ -41,4 +74,4 @@ TODO
 ----
 Add options for:
 - Passing STDIN
-- Making `run()` fail when exit status is not "0"
+- Making `run()` fail when exit status is not '0'

data/lib/komenda.rb

@@ -1,18 +1,26 @@
 require 'open3'
+require 'event_emitter'
 
-require 'komenda/definition'
-require 'komenda/runner'
+require 'komenda/process_builder'
+require 'komenda/process'
 require 'komenda/result'
 
 module Komenda
 
-  # @param [String] cmd
+  # @param [String] command
+  # @param [Hash] options
+  # @return [Komenda::Process]
+  def self.create(command, options = {})
+    process_builder = Komenda::ProcessBuilder.new(command, options)
+    process_builder.create
+  end
+
+  # @param [String] command
   # @param [Hash] options
   # @return [Komenda::Result]
-  def self.run(cmd, options = {})
-    definition = Komenda::Definition.new(cmd, options)
-    runner = Komenda::Runner.new
-    runner.run(definition)
+  def self.run(command, options = {})
+    process_builder = Komenda::ProcessBuilder.new(command, options)
+    process_builder.create.run
   end
 
 end

data/lib/komenda/process.rb

@@ -0,0 +1,109 @@
+module Komenda
+  class Process
+
+    attr_reader :output
+
+    include EventEmitter
+
+    # @param [ProcessBuilder] process_builder
+    def initialize(process_builder)
+      @process_builder = process_builder
+      @output = {:stdout => '', :stderr => '', :combined => ''}
+      @exit_status = nil
+      @thread = nil
+
+      on(:stdout) { |data| @output[:stdout] += data }
+      on(:stderr) { |data| @output[:stderr] += data }
+      on(:output) { |data| @output[:combined] += data }
+      process_builder.events.each do |event|
+        on(event[:type], &event[:listener])
+      end
+    end
+
+    # @return [Thread]
+    def start
+      raise 'Already started' if is_started?
+      @thread = Thread.new { run_process(@process_builder) }
+    end
+
+    # @return [Komenda::Result]
+    def wait_for
+      raise 'Process not started' unless is_started?
+      @thread.join
+      result
+    end
+
+    # @return [Komenda::Result]
+    def run
+      start unless is_started?
+      wait_for
+    end
+
+    # @return [TrueClass, FalseClass]
+    def running?
+      raise 'Process not started' unless is_started?
+      @thread.alive?
+    end
+
+    # @return [Komenda::Result]
+    def result
+      raise 'Process not started' unless is_started?
+      raise 'Process not finished' unless is_finished?
+      Komenda::Result.new(@output, @exit_status)
+    end
+
+    private
+
+    # @return [TrueClass, FalseClass]
+    def is_started?
+      !@thread.nil?
+    end
+
+    # @return [TrueClass, FalseClass]
+    def is_finished?
+      !@exit_status.nil?
+    end
+
+    # @param [ProcessBuilder] process_builder
+    def run_process(process_builder)
+      begin
+        if process_builder.cwd.nil?
+          run_popen3(process_builder)
+        else
+          Dir.chdir(process_builder.cwd) { run_popen3(process_builder) }
+        end
+      rescue Exception => exception
+        emit(:error, exception)
+        raise exception
+      end
+    end
+
+    # @param [ProcessBuilder] process_builder
+    def run_popen3(process_builder)
+      Open3.popen3(process_builder.env, *process_builder.command) do |stdin, stdout, stderr, wait_thr|
+        stdin.close
+
+        streams_read_open = [stdout, stderr]
+        begin
+          streams_read_available, _, _ = IO.select(streams_read_open)
+
+          streams_read_available.each do |stream|
+            if stream.eof?
+              stream.close
+              streams_read_open.delete(stream)
+            else
+              data = stream.readpartial(4096)
+              emit(:stdout, data) if stdout === stream
+              emit(:stderr, data) if stderr === stream
+              emit(:output, data)
+            end
+          end
+        end until streams_read_open.empty?
+
+        @exit_status = wait_thr.value
+        emit(:exit, result)
+      end
+    end
+
+  end
+end

data/lib/komenda/process_builder.rb

@@ -0,0 +1,31 @@
+module Komenda
+  class ProcessBuilder
+
+    attr_reader :command
+    attr_reader :env
+    attr_reader :cwd
+    attr_reader :events
+
+    # @param [String, String[]] command
+    # @param [Hash] options
+    def initialize(command, options = {})
+      defaults = {
+        :env => ENV.to_hash,
+        :cwd => nil,
+        :events => {},
+      }
+      options = defaults.merge(options)
+
+      @command = command.is_a?(Array) ? command.map { |v| String(v) } : String(command)
+      @env = Hash[options[:env].to_hash.map { |k, v| [String(k), String(v)] }]
+      @cwd = options[:cwd].nil? ? nil : String(options[:cwd])
+      @events = Hash[options[:events].to_hash.map { |k, v| [k.to_sym, v.to_proc] }]
+    end
+
+    # @return [Komenda::Process]
+    def create
+      Komenda::Process.new(self)
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: komenda
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Cargo Media
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-02 00:00:00.000000000 Z
+date: 2015-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: event_emitter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: Convenience wrapper around `Open3` to run shell commands in Ruby.
 email: hello@cargomedia.ch
 executables: []
@@ -62,9 +76,9 @@ files:
 - LICENSE
 - README.md
 - lib/komenda.rb
-- lib/komenda/definition.rb
+- lib/komenda/process.rb
+- lib/komenda/process_builder.rb
 - lib/komenda/result.rb
-- lib/komenda/runner.rb
 homepage: https://github.com/cargomedia/komenda
 licenses:
 - MIT

data/lib/komenda/definition.rb

@@ -1,20 +0,0 @@
-module Komenda
-  class Definition
-
-    attr_reader :cmd
-    attr_reader :env
-
-    # @param [String] cmd
-    # @param [Hash] options
-    def initialize(cmd, options = {})
-      defaults = {
-        :env => ENV.to_hash,
-      }
-      options = defaults.merge(options)
-
-      @cmd = String(cmd)
-      @env = Hash[options[:env].to_hash.map { |k, v| [String(k), String(v)] }]
-    end
-
-  end
-end

data/lib/komenda/runner.rb

@@ -1,37 +0,0 @@
-module Komenda
-  class Runner
-
-    # @param [Komenda::Definition] definition
-    # @return [Komenda::Result]
-    def run(definition)
-      output = {:stdout => '', :stderr => '', :combined => ''}
-      status = nil
-
-      Open3.popen3(definition.env, definition.cmd) do |stdin, stdout, stderr, wait_thr|
-        stdin.close
-
-        streams_read_open = [stdout, stderr]
-        begin
-          streams_read_available, _, _ = IO.select(streams_read_open)
-
-          streams_read_available.each do |stream|
-            if stream.eof?
-              stream.close
-              streams_read_open.delete(stream)
-            else
-              data = stream.readpartial(4096)
-              output[:stdout] += data if stdout === stream
-              output[:stderr] += data if stderr === stream
-              output[:combined] += data
-            end
-          end
-        end until streams_read_open.empty?
-
-        status = wait_thr.value
-      end
-
-      Komenda::Result.new(output, status)
-    end
-
-  end
-end