cliver 0.1.5 → 0.2.0

data/README.md

@@ -2,42 +2,94 @@
 
 Sometimes Ruby apps shell out to command-line executables, but there is no
 standard way to ensure those underlying dependencies are met. Users usually
-find out via a nasty stack-trace and whatever wasn't captured on stderr.
+find out via a nasty stack-trace and whatever wasn't captured on stderr, or by
+the odd behavior exposed by a version mismatch.
 
-`Cliver` is a simple gem that provides an easy way to make assertions about
+`Cliver` is a simple gem that provides an easy way to detect and use
 command-line dependencies. Under the covers, it uses [rubygems/requirements][]
 so it supports the version requirements you're used to providing in your
 gemspec.
 
 ## Usage
 
+### Detect and Detect!
+
+The detect methods search your entire path until they find a matching executable
+or run out of places to look.
+
 ```ruby
-Cliver.assert('subl')                      # no version requirements
-Cliver.assert('bzip2', '~> 1.0.6')         # one version requirement
-Cliver.assert('racc', '>= 1.0', '< 1.4.9') # many version requirements
+# no version requirements
+Cliver.detect('subl')
+# => '/Users/yaauie/.bin/subl'
+
+# one version requirement
+Cliver.detect('bzip2', '~> 1.0.6')
+# => '/usr/bin/bzip2'
+
+# many version requirements
+Cliver.detect('racc', '>= 1.0', '< 1.4.9')
+# => '/Users/yaauie/.rbenv/versions/1.9.3-p194/bin/racc'
+
+# dependency not met
+Cliver.detect('racc', '~> 10.4.9')
+# => nil
+
+# detect! raises Cliver::Dependency::NotMet exceptions when the dependency
+# cannot be met.
+Cliver.detect!('ruby', '1.8.5')
+#  Cliver::Dependency::VersionMismatch
+#    Could not find an executable ruby that matched the
+#    requirements '1.8.5'. Found versions were {'/usr/bin/ruby'=> '1.8.7'}
+Cliver.detect!('asdfasdf')
+#  Cliver::Dependency::NotFound
+#    Could not find an executable asdfasdf on your path
 ```
 
-If the executable can't be found on your path at all, a 
-`Cliver::Assertion::DependencyNotFound` exception is raised; if the version
-reached does not meet the requirements, a `Cliver::Assertion::DependencyVersionMismatch`
-exception is raised; both inherit from `Cliver::Assertion::DependencyNotMet`
+### Assert
+
+The assert method is useful when you do not have control over how the
+dependency is shelled-out to and require that the first matching executable on
+your path satisfies your version requirements. It is the equivalent of the
+detect! method with `strict: true` option.
 
 ## Advanced Usage:
 
+### Version Detectors
+
 Some programs don't provide nice 'version 1.2.3' strings in their `--version`
 output; `Cliver` lets you provide your own version detector with a pattern.
 
 ```ruby
 Cliver.assert('python', '~> 1.7',
-              detector: Cliver::Detector.new(/(?<=Python )[0-9][.0-9a-z]+/))
+              detector: /(?<=Python )[0-9][.0-9a-z]+/)
 ```
 
 Other programs don't provide a standard `--version`; `Cliver::Detector` also
 allows you to provide your own arg to get the version:
 
+```ruby
+# single-argument command
+Cliver.assert('janky', '~> 10.1.alpha',
+              detector: '--release-version')
+
+# multi-argument command
+Cliver.detect('ruby', '~> 1.8.7',
+              detector: [['-e', 'puts RUBY_VERSION']])
+```
+
+You can use both custom pattern and custom command by supplying an array:
+
 ```ruby
 Cliver.assert('janky', '~> 10.1.alpha',
-              detector: Cliver::Detector.new('--release-version'))
+              detector: ['--release-version', /.*/])
+```
+
+And even supply multiple arguments in an Array, too:
+
+```ruby
+# multi-argument command
+Cliver.detect('ruby', '~> 1.8.7',
+              detector: ['-e', 'puts RUBY_VERSION'])
 ```
 
 Alternatively, you can supply your own detector (anything that responds to
@@ -55,6 +107,8 @@ And since some programs don't always spit out nice semver-friendly version
 numbers at all, a filter proc can be supplied to clean it up. Note how the
 filter is applied to both your requirements and the executable's output:
 
+### Filters
+
 ```ruby
 Cliver.assert('built-thing', '~> 2013.4r8273',
               filter: proc { |ver| ver.tr('r','.') })
@@ -63,6 +117,17 @@ Cliver.assert('built-thing', '~> 2013.4r8273',
 Since `Cliver` uses `Gem::Requirement` for version comparrisons, it obeys all
 the same rules including pre-release semantics.
 
+### Search Path
+
+By default, Cliver uses `ENV['PATH']` as its search path, but you can provide
+your own. If the asterisk symbol (`*`) is included in your string, it is
+replaced `ENV['PATH']`.
+
+```ruby
+Cliver.detect('gadget', path: './bins/:*')
+# => 'Users/yaauie/src/project-a/bins/gadget'
+```
+
 ## Supported Platforms
 
 The goal is to have full support for all platforms running ruby >= 1.9.2,

data/lib/cliver.rb

@@ -1,20 +1,48 @@
 # encoding: utf-8
 require 'cliver/version'
-require 'cliver/which'
-require 'cliver/assertion'
+require 'cliver/dependency'
 require 'cliver/detector'
 require 'cliver/filter'
 
 # Cliver is tool for making dependency assertions against
 # command-line executables.
 module Cliver
-  # @see Cliver::Assertion
-  # @overload (see Cliver::Assertion#initialize)
-  # @param (see Cliver::Assertion#initialize)
-  # @raise (see Cliver::Assertion#assert!)
-  # @return (see Cliver::Assertion#assert!)
+
+  # The primary interface for the Cliver gem allows detection of an executable
+  # on your path that matches a version requirement, or raise an appropriate
+  # exception to make resolution simple and straight-forward.
+  # @see Cliver::Dependency
+  # @overload (see Cliver::Dependency#initialize)
+  # @param (see Cliver::Dependency#initialize)
+  # @raise (see Cliver::Dependency#detect!)
+  # @return (see Cliver::Dependency#detect!)
+  def self.detect!(*args, &block)
+    Dependency::new(*args, &block).detect!
+  end
+
+  # A non-raising variant of {::detect!}, simply returns false if dependency
+  # cannot be found.
+  # @see Cliver::Dependency
+  # @overload (see Cliver::Dependency#initialize)
+  # @param (see Cliver::Dependency#initialize)
+  # @raise (see Cliver::Dependency#detect)
+  # @return (see Cliver::Dependency#detect)
+  def self.detect(*args, &block)
+    Dependency::new(*args, &block).detect
+  end
+
+  # A legacy interface for {::detect} with the option `strict: true`, ensures
+  # that the first executable on your path matches the requirements.
+  # @see Cliver::Dependency
+  # @overload (see Cliver::Dependency#initialize)
+  # @param (see Cliver::Dependency#initialize)
+  # @option options [Boolean] :strict (true) @see Cliver::Dependency::initialize
+  # @raise (see Cliver::Dependency#assert!)
+  # @return (see Cliver::Dependency#assert!)
   def self.assert(*args, &block)
-    Assertion.new(*args, &block).assert!
+    options = args.last.kind_of?(Hash) ? args.pop : {}
+    args << options.merge(:strict => true)
+    Dependency::new(*args, &block).detect!
   end
 
   extend self
@@ -28,7 +56,7 @@ module Cliver
   def dependency_unmet?(*args, &block)
     Cliver.assert(*args, &block)
     false
-  rescue Assertion::DependencyNotMet => error
+  rescue Dependency::NotMet => error
     # Cliver::Assertion::VersionMismatch -> 'Version Mismatch'
     reason = error.class.name.split(':').last.gsub(/([a-z])([A-Z])/, '\\1 \\2')
     "#{reason}: #{error.message}"

data/lib/cliver/dependency.rb

@@ -0,0 +1,198 @@
+# encoding: utf-8
+require 'rubygems/requirement'
+
+module Cliver
+  # This is how a dependency is specified.
+  class Dependency
+
+    # An exception class raised when assertion is not met
+    NotMet = Class.new(ArgumentError)
+
+    # An exception that is raised when executable present, but
+    # no version that matches the requirements is present.
+    VersionMismatch = Class.new(Dependency::NotMet)
+
+    # An exception that is raised when executable is not present at all.
+    NotFound = Class.new(Dependency::NotMet)
+
+    # A pattern for extracting a {Gem::Version}-parsable version
+    PARSABLE_GEM_VERSION = /[0-9]+(.[0-9]+){0,4}(.[a-zA-Z0-9]+)?/.freeze
+
+    # @overload initialize(executables, *requirements, options = {})
+    #   @param executables [String,Array<String>] api-compatible executable names
+    #                                      e.g, ['python2','python']
+    #   @param requirements [Array<String>, String] splat of strings
+    #     whose elements follow the pattern
+    #       [<operator>] <version>
+    #     Where <operator> is optional (default '='') and in the set
+    #       '=', '!=', '>', '<', '>=', '<=', or '~>'
+    #     And <version> is dot-separated integers with optional
+    #     alphanumeric pre-release suffix. See also
+    #     {http://docs.rubygems.org/read/chapter/16 Specifying Versions}
+    #   @param options [Hash<Symbol,Object>]
+    #   @option options [Cliver::Detector] :detector (Detector.new)
+    #   @option options [#to_proc, Object] :detector (see Detector::generate)
+    #   @option options [#to_proc] :filter ({Cliver::Filter::IDENTITY})
+    #   @option options [Boolean]  :strict (false)
+    #                                      true -  fail if first match on path fails
+    #                                              to meet version requirements.
+    #                                              This is used for Cliver::assert.
+    #                                      false - continue looking on path until a
+    #                                              sufficient version is found.
+    #   @option options [String]   :path   ('*') the path on which to search
+    #                                      for executables. If an asterisk (`*`) is
+    #                                      included in the supplied string, it is
+    #                                      replaced with `ENV['PATH']`
+    #
+    #   @yieldparam executable_path [String] (see Detector#detect_version)
+    #   @yieldreturn [String] containing a version that, once filtered, can be
+    #                         used for comparrison.
+    def initialize(executables, *args, &detector)
+      options = args.last.kind_of?(Hash) ? args.pop : {}
+      @detector = Detector::generate(detector || options[:detector])
+      @filter = options.fetch(:filter, Filter::IDENTITY).extend(Filter)
+      @path = options.fetch(:path, '*')
+      @strict = options.fetch(:strict, false)
+
+      @executables = Array(executables).dup.freeze
+
+      @requirement = args unless args.empty?
+    end
+
+    # Get all the installed versions of the api-compatible executables.
+    # If a block is given, it yields once per found executable, lazily.
+    # @yieldparam executable_path [String]
+    # @yieldparam version [String]
+    # @yieldreturn [Boolean] - true if search should stop.
+    # @return [Hash<String,String>] executable_path, version
+    def installed_versions
+      return enum_for(:installed_versions) unless block_given?
+
+      find_executables.each do |executable_path|
+        version = detect_version(executable_path)
+
+        break(2) if yield(executable_path, version)
+      end
+    end
+
+    # The non-raise variant of {#detect!}
+    # @return (see #detect!)
+    #   or nil if no match found.
+    def detect
+      detect!
+    rescue Dependency::NotMet
+      nil
+    end
+
+    # Detects an installed version of the executable that matches the
+    # requirements.
+    # @return [String] path to an executable that meets the requirements
+    # @raise [Cliver::Dependency::NotMet] if no match found
+    def detect!
+      installed = {}
+      installed_versions.each do |path, version|
+        installed[path] = version
+        return path if requirement_satisfied_by?(version)
+        strict?
+      end
+
+      # dependency not met. raise the appropriate error.
+      raise_not_found! if installed.empty?
+      raise_version_mismatch!(installed)
+    end
+
+    private
+
+    # @api private
+    # @return [Gem::Requirement]
+    def filtered_requirement
+      @filtered_requirement ||= begin
+        Gem::Requirement.new(@filter.requirements(@requirement))
+      end
+    end
+
+    # @api private
+    # @param raw_version [String]
+    # @return [Boolean]
+    def requirement_satisfied_by?(raw_version)
+      return true unless @requirement
+      parsable_version = @filter.apply(raw_version)[PARSABLE_GEM_VERSION]
+      parsable_version || raise(ArgumentError) # TODO: make descriptive
+      filtered_requirement.satisfied_by? Gem::Version.new(parsable_version)
+    end
+
+    # @api private
+    # @raise [Cliver::Dependency::NotFound] with appropriate error message
+    def raise_not_found!
+      raise Dependency::NotFound.new <<-EOERR
+        Could not find an executable #{@executables} on your path.
+      EOERR
+    end
+
+    # @api private
+    # @raise [Cliver::Dependency::VersionMismatch] with appropriate error message
+    # @param installed [Hash<String,String>] the found versions
+    def raise_version_mismatch!(installed)
+      raise Dependency::VersionMismatch.new <<-EOERR
+        Could not find an executable #{executable_description} that matched the
+        requirements #{requirements_description}.
+        Found versions were #{installed.inspect}
+      EOERR
+    end
+
+    # @api private
+    # @return [String] a plain-language representation of the executables
+    #   for which we were searching
+    def executable_description
+      quoted_exes = @executables.map {|exe| "'#{exe}'" }
+      return quoted_exes.first if quoted_exes.size == 1
+
+      last_quoted_exec = quoted_exes.pop
+      "#{quoted_exes.join(', ')} or #{last_quoted_exec}"
+    end
+
+    # @api private
+    # @return [String] a plain-language representation of the requirements
+    def requirements_description
+      @requirement.map {|req| "'#{req}'" }.join(', ')
+    end
+
+    # If strict? is true, only attempt the first matching executable on the path
+    # @api private
+    # @return [Boolean]
+    def strict?
+      false | @strict
+    end
+
+    # Given a path to an executable, detect its version
+    # @api private
+    # @param executable_path [String]
+    # @return [String]
+    # @raise [ArgumentError] if version cannot be detected.
+    def detect_version(executable_path)
+      # No need to shell out if we are only checking its presence.
+      return '99.version_detection_not_required' unless @requirement
+
+      raw_version = @detector.to_proc.call(executable_path)
+      raw_version || raise(ArgumentError,
+                           "The detector #{@detector} failed to detect the" +
+                           "version of the executable at '#{executable_path}'")
+    end
+
+    # Analog of Windows `where` command, or a `which` that finds *all*
+    # matching executables on the supplied path.
+    # @return [Enumerable<String>] - the executables found, lazily.
+    def find_executables
+      return enum_for(:find_executables) unless block_given?
+
+      exts = ENV.has_key?('PATHEXT') ? ENV.fetch('PATHEXT').split(';') : ['']
+      paths = @path.sub('*', ENV['PATH']).split(File::PATH_SEPARATOR)
+      cmds = strict? ? @executables.first(1) : @executables
+
+      cmds.product(paths, exts).map do |cmd, path, ext|
+        exe = File.join(path, "#{cmd}#{ext}")
+        yield exe if File.executable?(exe)
+      end
+    end
+  end
+end

data/lib/cliver/detector.rb

@@ -5,9 +5,16 @@ module Cliver
   # Default implementation of the detector needed by Cliver::Assertion,
   # which will take anything that #respond_to?(:to_proc)
   class Detector < Struct.new(:command_arg, :version_pattern)
+    # @param detector_argument [#call, Object]
+    #   If detector_argument responds to #call, return it; otherwise attempt
+    #   to create an instance of self.
+    def self.generate(detector_argument)
+      return detector_argument if detector_argument.respond_to?(:call)
+      new(*Array(detector_argument))
+    end
 
     # Default pattern to use when searching {#version_command} output
-    DEFAULT_VERSION_PATTERN = /version [0-9][.0-9a-z]+/i.freeze
+    DEFAULT_VERSION_PATTERN = /(version ?)?[0-9][.0-9a-z]+/i.freeze
 
     # Default command argument to use against the executable to get
     # version output
@@ -15,22 +22,25 @@ module Cliver
 
     # Forgiving input, allows either argument if only one supplied.
     #
-    # @overload initialize(command_arg)
+    # @overload initialize(*command_args)
+    #   @param command_args [Array<String>]
     # @overload initialize(version_pattern)
-    # @overload initialize(command_arg, version_pattern)
-    # @param command_arg [String]
-    # @param version_pattern [Regexp]
+    #   @param version_pattern [Regexp]
+    # @overload initialize(*command_args, version_pattern)
+    #   @param command_args [Array<String>]
+    #   @param version_pattern [Regexp]
     def initialize(*args)
-      command_arg = args.shift if args.first.kind_of?(String)
-      version_pattern = args.shift
-      super(command_arg, version_pattern)
+      version_pattern = args.pop if args.last.kind_of?(Regexp)
+      command_args = args unless args.empty?
+
+      super(command_args, version_pattern)
     end
 
     # @param executable_path [String] - the path to the executable to test
     # @return [String] - should be contain {Gem::Version}-parsable
     #                    version number.
     def detect_version(executable_path)
-      output = `#{version_command(executable_path).shelljoin} 2>&1`
+      output = shell_out_and_capture version_command(executable_path).shelljoin
       output[version_pattern]
     end
 
@@ -53,7 +63,7 @@ module Cliver
 
     # The argument to pass to the executable to get current version
     # Defaults to {DEFAULT_COMMAND_ARG}
-    # @return [String]
+    # @return [String, Array<String>]
     def command_arg
       super || DEFAULT_COMMAND_ARG
     end
@@ -61,7 +71,15 @@ module Cliver
     # @param executable_path [String] the executable to test
     # @return [Array<String>]
     def version_command(executable_path)
-      [executable_path, command_arg]
+      [executable_path, *Array(command_arg)]
+    end
+
+    private
+
+    # @api private
+    # A boundary that is useful for testing.
+    def shell_out_and_capture(command)
+      `#{command} 2>&1`
     end
   end
 end

data/lib/cliver/filter.rb

@@ -6,13 +6,23 @@ module Cliver
     # The identity filter returns its input unchanged.
     IDENTITY = proc { |version| version }
 
+    # Apply to a list of requirements
+    # @param requirements [Array<String>]
+    # @return [Array<String>]
     def requirements(requirements)
       requirements.map do |requirement|
         req_parts = requirement.split(/\b(?=\d)/, 2)
         version = req_parts.last
-        version.replace call(version)
+        version.replace apply(version)
         req_parts.join
       end
     end
+
+    # Apply to some input
+    # @param version [String]
+    # @return [String]
+    def apply(version)
+      to_proc.call(version)
+    end
   end
 end

data/lib/cliver/version.rb

@@ -2,5 +2,5 @@
 
 module Cliver
   # Cliver follows {http://semver.org SemVer}
-  VERSION = '0.1.5'
+  VERSION = '0.2.0'
 end

data/spec/cliver/detector_spec.rb

@@ -21,7 +21,7 @@ describe Cliver::Detector do
     let(:version_arg) { '--release-version' }
     let(:args) { [version_arg] }
 
-    its(:command_arg) { should eq version_arg }
+    its(:command_arg) { should eq [version_arg] }
     its(:version_pattern) { should eq defaults[:version_pattern] }
   end
 
@@ -38,7 +38,7 @@ describe Cliver::Detector do
     let(:regexp_arg) { /.*/ }
     let(:args) { [version_arg, regexp_arg] }
 
-    its(:command_arg) { should eq version_arg }
+    its(:command_arg) { should eq [version_arg] }
     its(:version_pattern) { should eq regexp_arg }
   end
 end

data/spec/cliver_spec.rb

@@ -1,31 +1,203 @@
 # encoding: utf-8
 require 'cliver'
+require 'spec_helper'
 
 describe Cliver do
-  it { should respond_to :assert }
-
-  it { should respond_to :dependency_unmet? }
-  context '#dependency_unmet?' do
-    let(:requirements) { [] }
-    let(:detector) { proc { } }
-    subject { Cliver.dependency_unmet?(executable, *requirements, &detector) }
-    context 'when dependency is met' do
-      let(:executable) { 'ruby' }
+  # The setup. Your test will likeley interact with subject.
+  let(:action) { Cliver.public_send(method, *args, &block) }
+  subject { action }
+
+  # These can get overridden in context blocks
+  let(:method) { raise ArgumentError, 'spec didn\'t specify :method' }
+  let(:args) { raise ArgumentError, 'spec didn\'t specify :args' }
+  let(:block) { version_map.method(:fetch) }
+
+  before(:each) do
+    File.stub(:executable?) { |path| executables.include? path }
+    # Cliver::Dependency.any_instance.stub(:detect_version) do |arg|
+    #   version_map[arg]
+    # end
+  end
+
+  let(:options) do
+    {
+      :path =>       path,
+      :executable => executable,
+    }
+  end
+  let(:executables) { version_map.keys }
+  let(:args) do
+    args = [Array(executable)]
+    args.concat Array(requirement)
+    args << options
+  end
+
+  let(:path) { 'foo/bar:baz/bingo' }
+  let(:executable) { 'doodle' }
+  let(:requirement) { '~>1.1'}
+
+  context 'when first-found version is sufficient' do
+
+    let(:version_map) do
+      {'baz/bingo/doodle' => '1.2.1'}
+    end
+
+    context '::assert' do
+      let(:method) { :assert }
+      it 'should not raise' do
+        expect { action }.to_not raise_exception
+      end
+    end
+
+    context '::dependency_unmet?' do
+      let(:method) { :dependency_unmet? }
       it { should be_false }
     end
-    context 'when dependency is present, but wrong version' do
-      let(:executable) { 'ruby' }
-      let(:requirements) { ['~> 0.1.0'] }
-      let(:detector) { proc { RUBY_VERSION.sub('p', '.') } }
-      it { should_not be_false }
-      it { should match 'Dependency Version Mismatch:' }
-      it { should match "expected .+ 'ruby' to be #{requirements}" }
-    end
-    context 'when dependency is not present' do
-      let(:executable) { 'ruxxxby' }
-      it { should_not be_false }
-      it { should match 'Dependency Not Found:' }
-      it { should match "'#{executable}' could not be found" }
+    context '::detect' do
+      let(:method) { :detect }
+      it { should eq 'baz/bingo/doodle' }
+    end
+    context '::detect!' do
+      let(:method) { :detect! }
+      it 'should not raise' do
+        expect { action }.to_not raise_exception
+      end
+      it { should eq 'baz/bingo/doodle' }
+    end
+  end
+
+  context 'when first-found version insufficient' do
+    let(:version_map) do
+      {'baz/bingo/doodle' => '1.0.1'}
+    end
+    context '::assert' do
+      let(:method) { :assert }
+      it 'should raise' do
+        expect { action }.to raise_exception Cliver::Dependency::VersionMismatch
+      end
+    end
+    context '::dependency_unmet?' do
+      let(:method) { :dependency_unmet? }
+      it { should be_true }
+    end
+    context '::detect' do
+      let(:method) { :detect }
+      it { should be_nil }
+    end
+    context '::detect!' do
+      let(:method) { :detect! }
+      it 'should not raise' do
+        expect { action }.to raise_exception Cliver::Dependency::VersionMismatch
+      end
+    end
+
+    context 'and when sufficient version found later on path' do
+      let(:version_map) do
+        {
+          'foo/bar/doodle'    => '0.0.1',
+          'baz/bingo/doodle'  => '1.1.0',
+        }
+      end
+      context '::assert' do
+        let(:method) { :assert }
+        it 'should raise' do
+          expect { action }.to raise_exception Cliver::Dependency::VersionMismatch
+        end
+      end
+      context '::dependency_unmet?' do
+        let(:method) { :dependency_unmet? }
+        it { should be_true }
+      end
+      context '::detect' do
+        let(:method) { :detect }
+        it { should eq 'baz/bingo/doodle'}
+      end
+      context '::detect!' do
+        let(:method) { :detect! }
+        it 'should not raise' do
+          expect { action }.to_not raise_exception
+        end
+        it { should eq 'baz/bingo/doodle' }
+      end
+    end
+  end
+
+  context 'when no found version' do
+    let(:version_map) { {} }
+
+    context '::assert' do
+      let(:method) { :assert }
+      it 'should raise' do
+        expect { action }.to raise_exception Cliver::Dependency::NotFound
+      end
+    end
+    context '::dependency_unmet?' do
+      let(:method) { :dependency_unmet? }
+      it { should be_true }
+    end
+    context '::detect' do
+      let(:method) { :detect }
+      it { should be_nil }
+    end
+    context '::detect!' do
+      let(:method) { :detect! }
+      it 'should not raise' do
+        expect { action }.to raise_exception Cliver::Dependency::NotFound
+      end
+    end
+  end
+
+  context 'with fallback executable names' do
+    let(:executable) { ['primary', 'fallback'] }
+    let(:requirement) { '~> 1.1' }
+    context 'when primary exists after secondary in path' do
+      context 'and primary sufficient' do
+        let(:version_map) do
+          {
+            'baz/bingo/primary' => '1.1',
+            'foo/bar/fallback' => '1.1'
+          }
+        end
+        context '::detect' do
+          let(:method) { :detect }
+          it { should eq 'baz/bingo/primary' }
+        end
+      end
+      context 'and primary insufficient' do
+        let(:version_map) do
+          {
+            'baz/bingo/primary' => '2.1',
+            'foo/bar/fallback' => '1.1'
+          }
+        end
+        context 'the secondary' do
+          context '::detect' do
+            let(:method) { :detect }
+            it { should eq 'foo/bar/fallback' }
+          end
+        end
+      end
+    end
+    context 'when primary does not exist in path' do
+      context 'and sufficient secondary does' do
+        let(:version_map) do
+          {
+            'foo/bar/fallback' => '1.1'
+          }
+        end
+        context '::detect' do
+          let(:method) { :detect }
+          it { should eq 'foo/bar/fallback' }
+        end
+      end
+    end
+
+    context 'neither found' do
+      context '::detect' do
+        let(:version_map) { {} }
+        let(:method) { :detect }
+        it { should be_nil }
+      end
     end
   end
 end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+# 1.8.x doesn't support public_send and we use it in spec,
+# so we emulate it in this monkeypatch.
+class Object
+  def public_send(method, *args, &block)
+    case method.to_s
+    when *private_methods
+      raise NoMethodError, "private method `#{method}' called for #{self}"
+    when *protected_methods
+      raise NoMethodError, "protected method `#{method}' called for #{self}"
+    else
+      send(method, *args, &block)
+    end
+  end unless method_defined?(:public_send)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cliver
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-23 00:00:00.000000000 Z
+date: 2013-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -124,16 +124,13 @@ files:
 - Rakefile
 - cliver.gemspec
 - lib/cliver.rb
-- lib/cliver/assertion.rb
+- lib/cliver/dependency.rb
 - lib/cliver/detector.rb
 - lib/cliver/filter.rb
 - lib/cliver/version.rb
-- lib/cliver/which.rb
-- lib/cliver/which/posix.rb
-- lib/cliver/which/windows.rb
-- spec/cliver/assertion_spec.rb
 - spec/cliver/detector_spec.rb
 - spec/cliver_spec.rb
+- spec/spec_helper.rb
 homepage: https://www.github.com/yaauie/cliver
 licenses:
 - MIT
@@ -160,7 +157,7 @@ signing_key:
 specification_version: 3
 summary: Cross-platform version constraints for cli tools
 test_files:
-- spec/cliver/assertion_spec.rb
 - spec/cliver/detector_spec.rb
 - spec/cliver_spec.rb
+- spec/spec_helper.rb
 has_rdoc: yard

data/lib/cliver/assertion.rb

@@ -1,89 +0,0 @@
-# encoding: utf-8
-require 'open3'
-require 'rubygems/requirement'
-
-module Cliver
-  # The core of Cliver, Assertion is responsible for detecting the
-  # installed version of a binary and determining if it meets the requirements
-  class Assertion
-
-    include Which # platform-specific implementation of `which`
-
-    # An exception class raised when assertion is not met
-    DependencyNotMet = Class.new(ArgumentError)
-
-    # An exception that is raised when executable present is the wrong version
-    DependencyVersionMismatch = Class.new(DependencyNotMet)
-
-    # An exception that is raised when executable is not present
-    DependencyNotFound = Class.new(DependencyNotMet)
-
-    # A pattern for extracting a {Gem::Version}-parsable version
-    PARSABLE_GEM_VERSION = /[0-9]+(.[0-9]+){0,4}(.[a-zA-Z0-9]+)?/.freeze
-
-    # @overload initialize(executable, *requirements, options = {})
-    # @param executable [String]
-    # @param requirements [Array<String>, String] splat of strings
-    #   whose elements follow the pattern
-    #     [<operator>] <version>
-    #   Where <operator> is optional (default '='') and in the set
-    #     '=', '!=', '>', '<', '>=', '<=', or '~>'
-    #   And <version> is dot-separated integers with optional
-    #   alphanumeric pre-release suffix. See also
-    #   {http://docs.rubygems.org/read/chapter/16 Specifying Versions}
-    # @param options [Hash<Symbol,Object>]
-    # @option options [Cliver::Detector, #to_proc] :detector (Detector.new)
-    # @option options [#to_proc] :filter ({Cliver::Filter::IDENTITY})
-    # @yieldparam [String] full path to executable
-    # @yieldreturn [String] containing a {Gem::Version}-parsable substring
-    def initialize(executable, *args, &detector)
-      options = args.last.kind_of?(Hash) ? args.pop : {}
-      @detector = detector || options.fetch(:detector) { Detector.new }
-      @filter = options.fetch(:filter, Filter::IDENTITY).extend(Filter)
-
-      @executable = executable.dup.freeze
-
-      unless args.empty?
-        @requirement = Gem::Requirement.new(@filter.requirements(args))
-      end
-    end
-
-    # @raise [DependencyVersionMismatch] if installed version does not match
-    # @raise [DependencyNotFound] if no installed version on your path
-    def assert!
-      version = installed_version ||
-                raise(DependencyNotFound,
-                      "required command-line executable '#{@executable}' " +
-                      'could not be found on your PATH.')
-
-      if @requirement && !@requirement.satisfied_by?(Gem::Version.new(version))
-        raise DependencyVersionMismatch,
-              "expected command-line executable '#{@executable}' to " +
-              "be #{@requirement}, got #{version}"
-      end
-    end
-
-    # Finds the executable on your path using {Cliver::Which};
-    # if the executable is present and version requirements are specified,
-    # uses the specified detector to get the current version.
-    # @private
-    # @return [nil]    if no version present
-    # @return [String] Gem::Version-parsable string version
-    # @return [true]   if present and no requirements (optimization)
-    def installed_version
-      executable_path = which(@executable)
-      return nil unless executable_path
-      return true unless @requirement
-
-      version_string = @detector.to_proc.call(executable_path)
-      version_string &&= @filter.to_proc.call(version_string)
-      (version_string && version_string[PARSABLE_GEM_VERSION]).tap do |version|
-        unless version
-          raise ArgumentError,
-                "found command-line executable #{@executable} at " +
-                "'#{executable_path}' but could not detect its version."
-        end
-      end
-    end
-  end
-end

data/lib/cliver/which.rb

@@ -1,17 +0,0 @@
-# encoding: utf-8
-
-module Cliver
-  # The `which` command we love on many posix-systems needs analogues on other
-  # systems. The Which module congitionally includes the correct implementation
-  # into itself, so you can include it into something else.
-  module Which
-    case RbConfig::CONFIG['host_os']
-    when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-      require 'cliver/which/windows'
-      include Cliver::Which::Windows
-    else
-      require 'cliver/which/posix'
-      include Cliver::Which::Posix
-    end
-  end
-end

data/lib/cliver/which/posix.rb

@@ -1,22 +0,0 @@
-# encoding: utf-8
-require 'shellwords'
-
-module Cliver
-  module Which
-    # Posix implementation of Which
-    # Required and mixed into Cliver::Which in posix environments
-    module Posix
-      # Posix adapter to `which`
-      # @param executable [String]
-      # @return [nil,String] - path to found executable
-      def which(executable)
-        which = `which #{Shellwords.escape executable} 2>&1`
-        executable_path = which.chomp
-        return nil if executable_path.empty?
-        executable_path
-      rescue Errno::ENOENT
-        raise '"which" must be on your path to use Cliver on this system.'
-      end
-    end
-  end
-end

data/lib/cliver/which/windows.rb

@@ -1,25 +0,0 @@
-# encoding: utf-8
-require 'shellwords'
-
-module Cliver
-  module Which
-    # Windows-specific implementation of Which
-    # Required and mixed into Cliver::Which in windows environments
-    module Windows
-      # Windows-specific implementation of `which`
-      # @param executable [String]
-      # @return [nil,String] - path to found executable
-      def which(executable)
-        # `where` returns newline-separated files found on path, but doesn't
-        # ensure that they are executable as commands.
-        where = `where #{Shellwords.escape executable} 2>&1`
-        where.lines.map(&:chomp).find do |found|
-          next if found.empty?
-          File.executable?(found)
-        end
-      rescue Errno::ENOENT
-        raise '"where" must be on your path to use Cliver on Windows.'
-      end
-    end
-  end
-end

data/spec/cliver/assertion_spec.rb

@@ -1,156 +0,0 @@
-# encoding: utf-8
-require 'cliver'
-
-describe Cliver::Assertion do
-  let(:mismatch_exception) { Cliver::Assertion::DependencyVersionMismatch }
-  let(:missing_exception) { Cliver::Assertion::DependencyNotFound }
-  let(:requirements) { ['6.8'] }
-  let(:executable) { 'fubar' }
-  let(:detector) { nil }
-  let(:assertion) do
-    Cliver::Assertion.new(executable, *requirements, &detector)
-  end
-
-  context 'when dependency found' do
-    before(:each) { assertion.stub(:installed_version) { version } }
-
-    # sampling of requirements; actual implementation
-    # is supplied by rubygems/requirement and well-tested there.
-    context '~>' do
-      let(:requirements) { ['~> 6.8'] }
-      context 'when version matches exactly' do
-        let(:version) { '6.8' }
-        it 'should not raise' do
-          expect { assertion.assert! }.to_not raise_exception
-        end
-      end
-      context 'when major matches, and minor too low' do
-        let(:version) { '6.7' }
-        it 'should raise' do
-          expect { assertion.assert! }.to raise_exception mismatch_exception
-        end
-      end
-      context 'when major matches, and minor bumped' do
-        let(:version) { '6.13' }
-        it 'should not raise' do
-          expect { assertion.assert! }.to_not raise_exception
-        end
-      end
-      context 'when major too high' do
-        let(:version) { '7.0' }
-        it 'should raise' do
-          expect { assertion.assert! }.to raise_exception mismatch_exception
-        end
-      end
-      context 'patch version present' do
-        let(:version) { '6.8.1' }
-        it 'should not raise' do
-          expect { assertion.assert! }.to_not raise_exception
-        end
-      end
-      context 'pre-release of version that matches' do
-        let(:version) { '6.8.a' }
-        it 'should raise' do
-          expect { assertion.assert! }.to raise_exception mismatch_exception
-        end
-      end
-    end
-
-    context 'multi [>=,<]' do
-      let(:requirements) { ['>= 1.1.4', '< 3.1'] }
-      context 'matches both' do
-        let(:version)  { '2.0' }
-        it 'should not raise' do
-          expect { assertion.assert! }.to_not raise_exception
-        end
-      end
-      context 'fails one' do
-        let(:version)  { '3.1' }
-        it 'should raise' do
-          expect { assertion.assert! }.to raise_exception mismatch_exception
-        end
-      end
-    end
-
-    context 'none' do
-      let(:requirements) { [] }
-      let(:version) { '3.1' }
-      it 'should not raise' do
-        expect { assertion.assert! }.to_not raise_exception
-      end
-    end
-  end
-
-  context 'when dependency not found' do
-    before(:each) { assertion.stub(:installed_version) { nil } }
-
-    it 'should raise' do
-      expect { assertion.assert! }.to raise_exception missing_exception
-    end
-  end
-
-  context '#installed_version' do
-    before(:each) do
-      if `which #{executable}`.chomp.empty?
-        pending "#{executable} not installed, test will flap."
-      end
-    end
-    let(:detector_touches) { [] }
-    context 'ruby using filter' do
-      let(:requirement) { '~> 1.2.3p112' }
-      let(:executable) { 'ruby' }
-      let(:filter) { proc { |ver| ver.tr('p', '.') } }
-      let(:detector) { proc { '1.2.3p456' } }
-      let(:assertion) do
-        Cliver::Assertion.new(executable, requirement, :filter => filter,
-                                                       :detector => detector)
-      end
-      let(:installed_version) { assertion.installed_version }
-      subject { installed_version }
-
-      it { should eq '1.2.3.456' }
-    end
-    context 'ruby with detector-block returned value' do
-      let(:requirements) { ['~> 10.1.4'] }
-      let(:fake_version) { 'ruby 10.1.5' }
-      let(:executable) { 'ruby' }
-      let(:detector) do
-        proc do |ruby|
-          detector_touches << true
-          fake_version
-        end
-      end
-      it 'should succeed' do
-        expect { assertion.assert! }.to_not raise_exception
-      end
-      context 'the detector' do
-        before(:each) { assertion.assert! }
-        it 'should have been touched' do
-          detector_touches.should_not be_empty
-        end
-      end
-      context 'when block-return doesn\'t meet requirements' do
-        let(:fake_version) { '10.1433.32.alpha' }
-        it 'should raise' do
-          expect { assertion.assert! }.to raise_exception mismatch_exception
-        end
-      end
-    end
-    context 'awk with no requirements' do
-
-      let(:requirements) { [] }
-      let(:executable) { 'awk' }
-      let(:fake_version) { nil }
-
-      it 'should succeed' do
-        expect { assertion.assert! }.to_not raise_exception
-      end
-      context 'the detector' do
-        before(:each) { assertion.assert! }
-        it 'should not have been touched' do
-          detector_touches.should be_empty
-        end
-      end
-    end
-  end
-end