fancy_command 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a9dea87fd5ed46f6476a07e75be72f244c1c837d
+  data.tar.gz: 4c2cf776cfcdacbfe3db7bc3d52347869dc5afda
+SHA512:
+  metadata.gz: 28bcca367027743454fafe3618969975ff2786710c56dc2a60a94c1f6c4f0643f40d1bdf8807ed38fbe5f5e233a333a6bdf563a60987027856b84fde8c319836
+  data.tar.gz: d35a1575f541ee3c8ed31888eb3c17cdf9cdab246b5e54a50fec5bd13ea8bc4f0fe6bbbb1de024b353cfbc35f14de3f4aefc3c0dc999bd4dc56e7b1f59065e2f

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 myobie
+
+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,194 @@
+# FancyCommand
+
+Wrapper around Open3 making it easier to live-stream command output and
+chain commands together. See [Usage](#usage) below for code examples.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fancy_command'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install fancy_command
+```
+
+## Usage
+
+The best way to explain this is with some example code:
+
+```ruby
+require 'fancy_command'
+include FancyCommand
+
+namespace :bower do
+  task :setup do
+    run("which bower").unless_success_then do
+      run "npm install -g bower", must_succeed: true
+    end
+  end
+
+  task :install => :setup do
+    run "bower install", must_succeed: true
+  end
+end
+```
+
+There are a few things to note here:
+
+* Including `FancyCommand` adds a `#run` method
+* There are chaining methods (run returns the command itself)
+* The `must_succeed` flag
+
+### Including
+
+The `FancyCommand` module impliments two includable methods:
+
+* `#run(string, **opts, &blk)`
+* `#command(string, **opts, &blk)`
+
+`#command` will instantiate a new `FancyCommand::Command` and `#run`
+will instantiate and then `#call` that command.
+
+### Chaining
+
+There are three methods that can be used to chain commands together:
+
+* `#then`
+* `#if_success_then`
+* `#unless_success_then`
+
+The all accept a block expecting either one or zero arguments. If one
+argument is expected then it will be the instance of the previous
+command.
+
+### `must_succeed: true`
+
+When this flag is set then any non-zero `exitstatus` will cause an
+exception to be raised (`FancyCommand::Command::Failed`). The exception
+impliments `#command` (the string), `#status` (the `exitstatus`), and
+`#output` (a string of the combined stdout and stderr).
+
+- - -
+
+Another example to show off is:
+
+```ruby
+require 'fancy_command'
+include FancyCommand
+
+# get the date
+
+command = run("date") | "awk '{ print $2 }'"
+puts command.output
+
+# find the Gemfiles
+
+run("ls") | command("grep Gem", accum: $stdout)
+
+# live stream build logs
+
+require 'some_websocket_client_library'
+require 'bugsnag'
+require 'bugsnag_configuration'
+socket = SomeWebsocketClientLibrary.new(ENV["WEBSOCKET_URL"])
+run("build_script.sh", accum: socket).unless_success_then do |command|
+  Bugsnag.notify(RuntimeError.new("'#{command.string}' failed", {
+    command: command.string,
+    stout: command.out,
+    sterr: command.err,
+    status: command.exitstatus,
+    pid: command.pid
+  })
+end
+```
+
+A few things to notice:
+
+* One can `#|` (or `#pipe`) commands to each other
+* Commands have `#output`
+* There is an `accum:` argument
+* A command has `#out`, `#err`, `#exitstatus`, etc
+
+### Piping
+
+All `FancyCommand::Command` instances impliment `#pipe` (and `#|`)
+which:
+
+1. Instantiates a command from a string copying the `#accum` (unless it's already a command)
+2. Copies the output of the first command to the input of the second
+3. Calls and returns the second command
+
+This is not exactly like a unix pipe, so infinite pipes will not work.
+Each command waits until it has fully executed to go on to the next one.
+If you really want to use real pipes either use `Open3.pipeline` or just
+make a command string with the pipes in it.
+
+### Output and accum
+
+The combined result of stdout and stderr is accessible as `#output`.
+However, the is also an additional object one can use to accumulate
+output as it streams in:
+
+For each line of stdout or stderr, the `accum` object receives the `#<<`
+message with the line as an argument (the line will have a \n
+character). The accumulator object does not need to be threadsafe, a
+mutex is used to make sure that the `#<<` message is never delivered
+twice at once. The easiest example is to provide `$stdout` as the
+accumulator, which will output every resulting line as it streams in.
+
+I built this feature so I could stream build logs over websockets.
+
+### Other methods
+
+The important methods are:
+
+* `#out` only stdout
+* `#err` only stderr
+* `#output` combined stdout and stderr (also should be interleaved into
+  the order of delivery from the command)
+* `#exitstatus` is the integer exit code from the command
+* `#success?` will be true only for zero exit codes
+
+### Verbose
+
+There also is a `verbose:` argument that can be passed in as true. All
+it does right now is output the command to stdout right before it is
+executed. If you want to output the command's result just use `$stdout`
+as `accum:`.
+
+Here is an example:
+
+```
+>> include FancyCommand
+=> Object
+>> c = run("date", verbose: true, accum: $stdout) | "awk '{ print $2 }'"
+$ date
+Wed Jan  7 08:53:02 CET 2015
+$ awk '{ print $2 }'
+Jan
+=> #<FancyCommand::Command:0x007fc2ad7c5b10 @string="awk '{ print $2 }'", @verbose=true, @accum=#<IO:<STDOUT>>, @in="Wed Jan  7 08:53:02 CET 2015\n", @output="Jan\n", @out="Jan\n", @err="", @status=#<Process::Status: pid 90340 exit 0>, @pid=90340, @must_succeed=false, @output_mutex=#<Mutex:0x007fc2ad7c5570>>
+```
+
+## Tests
+
+I am very sorry that there are no tests yet. I am using this in a real
+application, but yeah it needs some tests.
+
+## Contributing
+
+1. Fork it ( https://github.com/myobie/fancy_command/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/fancy_command.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fancy_command/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "fancy_command"
+  spec.version       = FancyCommand::VERSION
+  spec.authors       = ["myobie"]
+  spec.email         = ["me@nathanherald.com"]
+  spec.summary       = %q{Real-time streaming command output and other nice things}
+  spec.description   = %q{I get really tired of not having a good Command class in ruby, so here it is.}
+  spec.homepage      = "http://github.com/myobie/fancy_command"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/fancy_command/command.rb

@@ -0,0 +1,143 @@
+require 'thread'
+require 'open3'
+
+module FancyCommand
+  class Command
+    class Failed < StandardError
+      attr_reader :command, :status, :output
+
+      def initialize(command:, status:, output:)
+        @command = command
+        @status = status
+        @output = output
+        super("'#{command}' failed with status #{status} and output:\n#{output}")
+      end
+    end
+
+    attr_reader :string, :accum, :in, :out, :err, :output, :status, :pid
+
+    def initialize(string, must_succeed: false, **opts)
+      @string = string
+      @verbose = opts.fetch(:verbose, false)
+      @accum = opts.fetch(:accum) { [] }
+      @in = opts[:in]
+      @output = ""
+      @out = nil
+      @err = nil
+      @status = nil
+      @pid = nil
+      @must_succeed = must_succeed
+      @output_mutex = Mutex.new
+
+      if block_given?
+        append_in yield
+      end
+    end
+
+    def append_in(string)
+      @in ||= ""
+      @in << string
+      self
+    end
+
+    def must_succeed?
+      !!@must_succeed
+    end
+
+    def verbose?
+      !!@verbose || ENV["VERBOSE"]
+    end
+
+    def call
+      puts "$ #{string}" if verbose?
+
+      @in.freeze
+
+      Open3.popen3(string) do |i, o, e, t|
+        unless @in.nil?
+          i.print @in
+          i.close
+        end
+
+        @out, @err = [o, e].map do |stream|
+          Thread.new do
+            lines = []
+            until (line = stream.gets).nil? do
+              lines << line
+              @output_mutex.synchronize do
+                @accum << line
+                @output << line
+              end
+            end
+            lines.join
+          end
+        end.map(&:value)
+
+        @pid = t.pid
+        @status = t.value
+      end
+
+      [@out, @err, @output].each(&:freeze)
+
+      if must_succeed? && !success?
+        raise Failed, command: string, status: status.exitstatus, output: output
+      end
+
+      self
+    end
+
+    def success?
+      status.success?
+    end
+
+    def exitstatus
+      status.exitstatus
+    end
+
+    def then(&blk)
+      if blk.arity == 1
+        blk.call(self)
+      else
+        blk.call
+      end
+
+      self
+    end
+
+    def if_success_then(&blk)
+      if success?
+        if blk.arity == 1
+          blk.call(self)
+        else
+          blk.call
+        end
+      end
+
+      self
+    end
+
+    def unless_success_then(&blk)
+      unless success?
+        if blk.arity == 1
+          blk.call(self)
+        else
+          blk.call
+        end
+      end
+
+      self
+    end
+
+    def pipe(command_or_string)
+      command = if String === command_or_string
+        self.class.new(command_or_string, accum: accum, verbose: verbose?)
+      else
+        command_or_string
+      end
+
+      command.append_in(output).()
+    end
+
+    alias_method :|, :pipe
+  end
+end

data/lib/fancy_command/version.rb

@@ -0,0 +1,3 @@
+module FancyCommand
+  VERSION = "0.0.2"
+end

data/lib/fancy_command.rb

@@ -0,0 +1,16 @@
+require "fancy_command/version"
+require "fancy_command/command"
+
+module FancyCommand
+  def self.new(string, **opts, &blk)
+    Command.new(string, **opts, &blk)
+  end
+
+  def run(string, **opts, &blk)
+    command(string, **opts, &blk).()
+  end
+
+  def command(string, **opts, &blk)
+    Command.new(string, **opts, &blk)
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: fancy_command
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- myobie
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: I get really tired of not having a good Command class in ruby, so here
+  it is.
+email:
+- me@nathanherald.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- fancy_command.gemspec
+- lib/fancy_command.rb
+- lib/fancy_command/command.rb
+- lib/fancy_command/version.rb
+homepage: http://github.com/myobie/fancy_command
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Real-time streaming command output and other nice things
+test_files: []