scallop 0.3.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a0715eb2ba21f83bd3fc10ec7195b994ac5e31d346fb6b1bc200aaf5e00cf0b
-  data.tar.gz: b1ec1adfd41dea460a08c48e71e58153d26e3126552af14c010a2a87de29020b
+  metadata.gz: fc5152e49392ede55c37e9deca067897a24056e3d91b102eb6450e52f776e59f
+  data.tar.gz: 6ee2973cbc1ef539df8f9dccf45f03e50e83a92ae1907c9d0d3652f2d9de2711
 SHA512:
-  metadata.gz: 4f06ae937fa91af87b1ae1c6e475314f08ab311186021b8982195954e87c21b2bf0fe30197ad7bbe086a382c219476bf56bb166c646e8f4366148f56fbf7e5ca
-  data.tar.gz: dc56ec977de18c408fb07e7c589545a28b38a5d12ebc56907acb5bbac7ba325512a4c0b623580df60509bc21b0dcb9215b1bd576f86a76c3906adce22149ce0d
+  metadata.gz: 04220fa89226641cb40cc2e74603fa5949be4adfff1d7f700e399fec3e18addca74fb72f92ee643487792d35bfcc056d25b999ca79b47f007684796fc4e03620
+  data.tar.gz: aca77b550c6513dd52058935181d1224d2014983a92b6723d8bbb63444c5513b200e1375e3a636ba6edeedf5b70f900d7b4ec40ceafdb360d3fee85b9752361f

data/.rubocop.yml

@@ -0,0 +1,11 @@
+AllCops:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/LineLength:
+  Max: 120
+Metrics/MethodLength:
+  Max: 20
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma

data/Gemfile

@@ -1,6 +1,8 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in scallop.gemspec
 gemspec

data/Gemfile.lock

@@ -1,19 +1,25 @@
 PATH
   remote: .
   specs:
-    scallop (0.3.0)
-      hashie (~> 3.0)
+    scallop (0.9.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.0)
     coderay (1.1.2)
     diff-lcs (1.3)
-    hashie (3.6.0)
+    docile (1.3.2)
+    jaro_winkler (1.5.3)
+    json (2.2.0)
     method_source (0.9.2)
+    parallel (1.17.0)
+    parser (2.6.3.0)
+      ast (~> 2.4.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
+    rainbow (3.0.0)
     rake (10.5.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -28,6 +34,22 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
+    rspec_junit_formatter (0.4.1)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (0.71.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.10.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    unicode-display_width (1.6.0)
 
 PLATFORMS
   ruby
@@ -37,7 +59,10 @@ DEPENDENCIES
   pry (~> 0.12)
   rake (~> 10.0)
   rspec (~> 3.0)
+  rspec_junit_formatter (~> 0.4)
+  rubocop (~> 0.71)
   scallop!
+  simplecov (~> 0.16)
 
 BUNDLED WITH
    1.17.2

data/README.md

@@ -1,6 +1,21 @@
+[![Gem Version](https://badge.fury.io/rb/scallop.svg)](https://badge.fury.io/rb/scallop)
+[![CircleCI](https://circleci.com/gh/fetlife/scallop.svg?style=svg)](https://circleci.com/gh/fetlife/scallop)
+[![Maintainability](https://api.codeclimate.com/v1/badges/b7d9660aa51c7205fbac/maintainability)](https://codeclimate.com/github/fetlife/scallop/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/b7d9660aa51c7205fbac/test_coverage)](https://codeclimate.com/github/fetlife/scallop/test_coverage)
+
 # Scallop
 
-Simple shell wrapper
+![](./scallop.png)
+
+Ergonomic shell wrapper.
+
+Features:
+
+* Easy access to command's output (stdout & stderr)
+* Failure handling
+* Parameterization
+* Measuring execution time
+* No dependencies
 
 ## Installation
 
@@ -20,4 +35,66 @@ Or install it yourself as:
 
 ## Usage
 
-[See specs](./spec/scallop_spec.rb)
+To run `sudo -u chuck grep -R /home/chuck`
+
+```ruby
+result = Scallop.sudo(:chuck).cmd(:grep, '-R', '/home/chuck').run
+```
+
+You can then check whether command succeeded
+
+```ruby
+result.success?
+```
+
+See its output
+
+```ruby
+result.stdout
+result.stderr
+result.output # STDOUT and STDERR combined
+```
+
+You can also access information about command execution time
+
+```ruby
+result.timing.real # Elapsed real time
+result.timing.stime # System CPU time
+result.timing.utime # User CPU time
+result.timing.total # Total time, that is utime + stime + cutime + cstime
+```
+
+### Handling failures with exceptions
+
+If you replace `run` with `run!`, exception will be raised in case command fails
+
+```ruby
+begin
+  Scallop.cmd(some_command).run!
+rescue Scallop::Errors::CommandFailed => error
+  # you can access result right on the error itself
+  error.result.stderr
+end
+```
+
+### Piping
+
+To run `cat /some/file | grep something`
+
+```ruby
+command = Scallop.cmd(:cat, '/some/file') | Scallop.cmd(:grep, 'something')
+command.run
+```
+
+### Parameterization
+
+```ruby
+stored_command = Scallop.cmd(:rm, '-rf', Scallop::Param[:path])
+
+stored_command.set(path: '/foo').run # rm -rf /foo
+stored_command.set(path: '/bar').run # rm -rf /bar
+```
+
+--------
+
+You can also [check specs](./spec/scallop_spec.rb) for examples.

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,14 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "scallop"
+require 'bundler/setup'
+require 'scallop'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require 'pry'
+Pry.start

data/lib/scallop.rb

@@ -1,129 +1,13 @@
-require "hashie"
-require "open3"
-
-require "scallop/version"
-
-class Scallop
-  module Errors
-    class CommandFailed < StandardError
-      attr_reader :result
-
-      def initialize(message, result)
-        @result = result
-        super(message)
-      end
-    end
-
-    class ValidationFailed < StandardError
-    end
-  end
-
-  class Result < Hashie::Dash
-    property :stdout, required: true
-    property :stderr, required: true
-    property :status, required: true
-
-    def self.from_capture3(result)
-      stdout, stderr, status = result
-      new(stdout: stdout.strip, stderr: stderr.strip, status: status)
-    end
-
-    def success?
-      status.success?
-    end
-
-    # stdout & stderr combined
-    def output
-      @_output ||= [stdout, stderr].reject { |s| s.nil? || s.empty? }.join("\n")
-    end
-  end
-
-  class Param < Hashie::Dash
-    property :key, required: true
-  end
-
-  class << self
-    DSL_METHODS = %i{ cmd run run! sudo }
-
-    DSL_METHODS.each do |method|
-      define_method(method) do |*args|
-        new.public_send(method, *args)
-      end
-    end
-
-    def param(key)
-      Param.new(key: key)
-    end
-  end
-
-  def initialize
-    @params = {}
-  end
-
-  def sudo(sudo = true)
-    dup
-      .tap do |instance|
-        instance.instance_eval { @sudo = sudo }
-      end
-      .freeze
-  end
-
-  def cmd(*cmd)
-    dup
-      .tap do |instance|
-        instance.instance_eval { @cmd = cmd }
-      end
-      .freeze
-  end
-
-  def set(params)
-    new_params = @params.merge(params)
-
-    dup
-      .tap do |instance|
-        instance.instance_eval { @params = new_params }
-      end
-      .freeze
-  end
-
-  def to_command
-    raise Errors::ValidationFailed.new("cmd missing") if @cmd.nil?
-
-    prefix =
-      case @sudo
-      when true then "sudo"
-      when String, Symbol then "sudo -u #{@sudo}"
-      else nil
-      end
-
-    cmd =
-      [*@cmd]
-        .flatten
-        .map do |cmd_part|
-          case cmd_part
-          when Param
-            @params[cmd_part.key].tap do |value|
-              raise Errors::ValidationFailed.new("value for param '#{cmd_part.key}' not set") if value.nil?
-            end
-          else
-            cmd_part.to_s
-          end
-        end
-        .map(&Shellwords.method(:escape))
-        .join(" ")
-
-    [prefix, cmd].compact.join(" ")
-  end
-
-  def run
-    to_command
-      .yield_self(&Open3.method(:capture3))
-      .yield_self(&Result.method(:from_capture3))
-  end
-
-  def run!
-    run.tap do |result|
-      raise Errors::CommandFailed.new(result.stderr, result) unless result.success?
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'open3'
+require 'shellwords'
+
+require 'scallop/command_builder'
+require 'scallop/errors'
+require 'scallop/executor'
+require 'scallop/param'
+require 'scallop/public_api'
+require 'scallop/result'
+require 'scallop/version'

data/lib/scallop/command_builder.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Scallop
+  # Implements command building interface with immutability.
+  class CommandBuilder
+    def initialize
+      @params = {}
+      @cmd = []
+    end
+
+    def sudo(sudo = true)
+      dup
+        .tap do |instance|
+          instance.instance_eval { @sudo = sudo }
+        end
+        .freeze
+    end
+
+    def cmd(*cmd)
+      dup
+        .tap do |instance|
+          instance.instance_eval { @cmd += cmd }
+        end
+        .freeze
+    end
+
+    def read_cmd
+      @cmd
+    end
+
+    def set(params)
+      new_params = @params.merge(params)
+
+      dup
+        .tap do |instance|
+          instance.instance_eval { @params = new_params }
+        end
+        .freeze
+    end
+
+    def |(other)
+      cmd(:|, other.read_cmd)
+    end
+
+    def run
+      Executor.run(to_command)
+    end
+
+    def run!
+      Executor.run!(to_command)
+    end
+
+    def to_command
+      raise Errors::ValidationFailed, 'cmd missing' if @cmd.empty?
+
+      [build_prefix, build_command].compact.join(' ')
+    end
+
+    private
+
+    def build_prefix
+      case @sudo
+      when true then 'sudo'
+      when String, Symbol then "sudo -u #{@sudo}"
+      end
+    end
+
+    def build_command
+      [*@cmd]
+        .flatten
+        .map do |cmd_part|
+          case cmd_part
+          when Param
+            value = @params[cmd_part.key]
+            raise Errors::ValidationFailed, "value for param '#{cmd_part.key}' not set" if value.nil?
+
+            Shellwords.escape(value.to_s)
+          when :|
+            cmd_part
+          else
+            Shellwords.escape(cmd_part.to_s)
+          end
+        end
+        .join(' ')
+    end
+  end
+end

data/lib/scallop/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Scallop
+  module Errors
+    # Error representing command failure.
+    class CommandFailed < StandardError
+      attr_reader :result
+
+      def initialize(message, result)
+        @result = result
+        super(message)
+      end
+    end
+
+    # Error representing absense of required parameters or incorrect usage
+    class ValidationFailed < StandardError
+    end
+  end
+end

data/lib/scallop/executor.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Scallop
+  # Executes command and returns result.
+  module Executor
+    def self.run(command)
+      capture3, timing = measure do
+        Open3.capture3(command)
+      end
+      build_result(capture3, timing)
+    end
+
+    def self.run!(command)
+      run(command).tap do |result|
+        raise Errors::CommandFailed.new(result.stderr, result) unless result.success?
+      end
+    end
+
+    def self.measure
+      result = nil
+      timing = Benchmark.measure { result = yield }
+      [result, timing]
+    end
+
+    def self.build_result(capture3, timing)
+      stdout, stderr, status = capture3
+
+      Result
+        .new(
+          stdout: stdout.strip,
+          stderr: stderr.strip,
+          status: status,
+          timing: timing,
+        )
+        .freeze
+    end
+  end
+end

data/lib/scallop/param.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Scallop
+  # Represents named command parameter.
+  class Param
+    def self.[](key)
+      new(key)
+    end
+
+    attr_reader :key
+
+    def initialize(key)
+      @key = key
+    end
+  end
+end

data/lib/scallop/public_api.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Scallop
+  # Adds ergonomic public API methods.
+  module PublicAPI
+    METHODS = %i[cmd sudo].freeze
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # :nodoc:
+    module ClassMethods
+      METHODS.each do |method|
+        define_method(method) do |*args|
+          CommandBuilder.new.public_send(method, *args)
+        end
+      end
+    end
+  end
+
+  include PublicAPI
+end

data/lib/scallop/result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Scallop
+  # Represents a result of command execution.
+  class Result
+    attr_reader :stdout
+    attr_reader :stderr
+    attr_reader :status
+    attr_reader :timing
+    attr_reader :output
+
+    def initialize(stdout:, stderr:, status:, timing:)
+      @stdout = stdout
+      @stderr = stderr
+      @status = status
+      @timing = timing
+      @output = [stdout, stderr].reject { |s| s.nil? || s.empty? }.join("\n")
+    end
+
+    def success?
+      @status.success?
+    end
+  end
+end

data/lib/scallop/version.rb

@@ -1,3 +1,5 @@
-class Scallop
-  VERSION = "0.3.2"
+# frozen_string_literal: true
+
+module Scallop
+  VERSION = '0.9.0'
 end

data/scallop.gemspec

@@ -1,34 +1,36 @@
+# frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "scallop/version"
+require 'scallop/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "scallop"
+  spec.name          = 'scallop'
   spec.version       = Scallop::VERSION
-  spec.authors       = ["FetLife"]
-  spec.email         = ["dev@fetlife.com"]
+  spec.authors       = ['FetLife']
+  spec.email         = ['dev@fetlife.com']
 
-  spec.summary       = "Simple shell wrapper"
-  spec.description   = "Simple shell wrapper"
-  spec.homepage      = "https://github.com/fetlife/scallop"
-  spec.license       = "MIT"
+  spec.summary       = 'Ergonomic shell wrapper.'
+  spec.description   = 'Ergonomic shell wrapper.'
+  spec.homepage      = 'https://github.com/fetlife/scallop'
+  spec.license       = 'MIT'
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|.circleci)/}) || f.end_with?('.png')
+    end
   end
-  spec.bindir = "bin"
+  spec.bindir = 'bin'
   spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.required_ruby_version = ">= 2.6.0"
+  spec.required_ruby_version = '>= 2.3.0'
 
-  spec.add_dependency "hashie", "~> 3.0"
-
-  spec.add_development_dependency "bundler", "~> 1.17"
-  spec.add_development_dependency "pry", "~> 0.12"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler', '~> 1.17'
+  spec.add_development_dependency 'pry', '~> 0.12'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.4'
+  spec.add_development_dependency 'rubocop', '~> 0.71'
+  spec.add_development_dependency 'simplecov', '~> 0.16'
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: scallop
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.9.0
 platform: ruby
 authors:
 - FetLife
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-18 00:00:00.000000000 Z
+date: 2019-06-22 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: hashie
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,7 +66,49 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Simple shell wrapper
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.71'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.71'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+description: Ergonomic shell wrapper.
 email:
 - dev@fetlife.com
 executables:
@@ -91,6 +119,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -100,6 +129,12 @@ files:
 - bin/console
 - bin/setup
 - lib/scallop.rb
+- lib/scallop/command_builder.rb
+- lib/scallop/errors.rb
+- lib/scallop/executor.rb
+- lib/scallop/param.rb
+- lib/scallop/public_api.rb
+- lib/scallop/result.rb
 - lib/scallop/version.rb
 - scallop.gemspec
 homepage: https://github.com/fetlife/scallop
@@ -114,7 +149,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -124,5 +159,5 @@ requirements: []
 rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
-summary: Simple shell wrapper
+summary: Ergonomic shell wrapper.
 test_files: []