cliver 0.0.1 → 0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+`Cliver` is [MIT-liennsed](LICENSE.txt) and intends to follow the
+[pull-request-hack][].
+
+## Git-Flow
+
+`Cliver` follows the [git-flow][] branching model, which means that every
+commit on `master` is a release. The default working branch is `develop`, so
+in general please keep feature pull-requests based against the current
+`develop`.
+
+ - fork cliver
+ - use the git-flow model to start your feature or hotfix
+ - make some commits (please include specs)
+ - submit a pull-request
+
+## Bug Reporting
+
+Please include clear steps-to-reproduce. Spec files are especially welcome;
+a failing spec can be contributed as a pull-request against `develop`.
+
+## Ruby Appraiser
+
+`Cliver` uses the [ruby-appraiser][] gem via [pre-commit][] hook, which can be
+activated by installing [icefox/git-hooks][] and running `git-hooks --install`.
+Reek and Rubocop are strong guidelines; use them to reduce defects as much as
+you can, but if you believe clarity will be sacrificed they can be bypassed
+with the `--no-verify` flag.
+
+[git-flow]: http://nvie.com/posts/a-successful-git-branching-model/
+[pre-commit]: .githooks/pre-commit/ruby-appraiser
+[ruby-appraiser]: https://github.com/simplymeasured/ruby-appraiser
+[icefox/git-hooks]: https://github.com/icefox/git-hooks
+[pull-request-hack]: http://felixge.de/2013/03/11/the-pull-request-hack.html

data/README.md

@@ -19,27 +19,45 @@ Cliver.assert('racc', '>= 1.0', '< 1.4.9') # many version requirements
 
 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::VersionMismatch`
-exception is raised.
+reached does not meet the requirements, a `Cliver::Assertion::DependencyVersionMismatch`
+exception is raised; both inherit from `Cliver::Assertion::DependencyNotMet`
 
 ## Advanced Usage:
 
 Some programs don't provide nice 'version 1.2.3' strings in their `--version`
-output; `Cliver` lets you provide your own matcher, whose first group is the
-string version.
+output; `Cliver` lets you provide your own version detector with a pattern.
 
 ```ruby
-Cliver.assert('python', '~> 1.7', version_matcher: /Python ([0-9.]+)/)
+Cliver.assert('python', '~> 1.7',
+              detector: Cliver::Detector.new(/(?<=Python )[0-9][.0-9a-z]+/))
 ```
 
-Other programs don't provide a standard `--version`; `Cliver` allows you to
-provide your own arg:
+Other programs don't provide a standard `--version`; `Cliver::Detector` also
+allows you to provide your own arg to get the version:
 
 ```ruby
-Cliver.assert('janky', '~> 10.1.alpha', version_arg: '--release-version')
+Cliver.assert('janky', '~> 10.1.alpha',
+              detector: Cliver::Detector.new('--release-version'))
 ```
 
-It obeys all the same rules as `Gem::Requirement`, including pre-release
-semantics.
+Alternatively, you can supply your own detector (anything that responds to
+`#to_proc`) in the options hash or as a block, so long as it returns a
+`Gem::Version`-parsable version number; if it returns nil or false when
+version requirements are given, a descriptive `ArgumentError` is raised.
+
+```ruby
+Cliver.assert('oddball', '~> 10.1.alpha') do |oddball_path|
+  File.read(File.expand_path('../VERSION', oddball_path)).chomp
+end
+```
+
+Since `Cliver` uses `Gem::Requirement` for version comparrisons, it obeys all
+the same rules including pre-release semantics.
+
+## See Also:
+
+ - [Contributing](CONTRIBUTING.md)
+ - [License](LICENSE.txt)
+
 
 [rubygems/requirements]: https://github.com/rubygems/rubygems/blob/master/lib/rubygems/requirement.rb

data/lib/cliver.rb

@@ -1,6 +1,8 @@
 # encoding: utf-8
 require 'cliver/version'
 require 'cliver/assertion'
+require 'cliver/detector'
+require 'cliver/detector/default'
 
 module Cliver
   # See Cliver::Assertion#assert

data/lib/cliver/assertion.rb

@@ -6,15 +6,16 @@ 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
-    VersionMismatch = Class.new(ArgumentError)
-    DependencyNotFound = Class.new(ArgumentError)
+    DependencyNotMet = Class.new(ArgumentError)
+    DependencyVersionMismatch = Class.new(DependencyNotMet)
+    DependencyNotFound = Class.new(DependencyNotMet)
 
     EXECUTABLE_PATTERN = /\A[a-z][a-zA-Z0-9\-_]*\z/.freeze
 
     # Creates a new instance with the args and calls #assert.
     # @see #assert
-    def self.assert!(*args)
-      new(*args).assert!
+    def self.assert!(*args, &block)
+      new(*args, &block).assert!
     end
 
     # @overload initialize(executable, *requirements, options = {})
@@ -28,36 +29,48 @@ module Cliver
     #   alphanumeric pre-release suffix
     #   @see Gem::Requirement::new
     # @param options [Hash<Symbol,Object>]
-    # @options options [#match] :version_matcher
-    # @options options [String] :version_arg
-    def initialize(executable, *args)
-      options = args.last.kind_of?(Hash) ? args.pop : {}
+    # @options options [Cliver::Detector, #to_proc] :detector
+    # @yieldparam [String] full path to executable
+    # @yieldreturn [String] Gem::Version-parsable string version
+    def initialize(executable, *args, &detector)
       raise ArgumentError, 'executable' unless executable[EXECUTABLE_PATTERN]
 
+      options = args.last.kind_of?(Hash) ? args.pop : {}
+
       @executable = executable.dup.freeze
-      @requirement = Gem::Requirement.new(args)
-      @version_arg = options.fetch(:version_arg, '--version')
-      @version_matcher = options.fetch(:version_matcher,
-                                       /version ([0-9][.0-9a-z]+)/i)
+      @requirement = Gem::Requirement.new(args) unless args.empty?
+      @detector = detector || options.fetch(:detector) { Detector.new }
     end
 
-    # @raise [VersionMismatch] if installed version does not match requirement
+    # @raise [DependencyVersionMismatch] if installed version does not match
     # @raise [DependencyNotFound] if no installed version on your path
     def assert!
       version = installed_version
-      version || raise(DependencyNotFound, "#{@executable} missing.")
-      unless @requirement.satisfied_by?(version)
-        raise VersionMismatch,
-              "got #{version}, expected #{@requirement}"
+      raise(DependencyNotFound, "#{@executable} missing.") unless version
+
+      if @requirement && !@requirement.satisfied_by?(Gem::Version.new(version))
+        raise DependencyVersionMismatch,
+              "expected #{@executable} to be #{@requirement}, got #{version}"
       end
     end
 
     # @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
-      command = "which #{@executable} && #{@executable} #{@version_arg}"
-      command_out, _ = Open3.capture2e(command)
-      match = @version_matcher.match(command_out)
-      match && Gem::Version.new(match[1])
+      which, _ = Open3.capture2e("which #{@executable}")
+      executable_path = which.chomp
+      return nil if executable_path.empty?
+      return true unless @requirement
+
+      @detector.to_proc.call(executable_path).tap do |version|
+        unless version
+          raise ArgumentError,
+                "found #{@executable} at '#{executable_path}' " +
+                'but could not detect its version.'
+        end
+      end
     end
   end
 end

data/lib/cliver/detector.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+require 'open3'
+
+module Cliver
+  # The interface for Cliver::Detector classes.
+  # @see Cliver::Detector::Default for reference implementation
+  module Detector
+    # Forward to default implementation
+    def self.new(*args, &block)
+      Default.new(*args, &block)
+    end
+
+    # @param executable [String] the executable to test
+    # @return [Array<String>]
+    def version_command(executable)
+      raise NotImplementedError unless defined? super
+      super
+    end
+
+    # @return [Regexp] - the pattern used against the output
+    #                    of the #version_command, which should
+    #                    typically be Gem::Version-parsable.
+    def version_pattern
+      raise NotImplementedError unless defined? super
+      super
+    end
+
+    # @param executable [String] - the path to the executable to test
+    # @return [String] - should be Gem::Version-parsable.
+    def detect_version(executable)
+      output, _ = Open3.capture2e(*version_command(executable))
+      ver = output.scan(version_pattern)
+      ver && ver.first
+    end
+
+    # This is the interface that any detector must have.
+    # @see #detect_version for the returned proc's method signature.
+    # @return [Proc]
+    def to_proc
+      method(:detect_version).to_proc
+    end
+  end
+end

data/lib/cliver/detector/default.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+require 'open3'
+
+module Cliver
+  # Default implementation of Cliver::Detector
+  # Requires a command argument (default '--version')
+  # and a pattern-matcher Regexp with sensible default.
+  class Detector::Default < Struct.new(:command_arg, :version_pattern)
+    include Detector
+
+    DEFAULT_VERSION_PATTERN = /(?<=version )[0-9][.0-9a-z]+/i.freeze
+    DEFAULT_COMMAND_ARG = '--version'.freeze
+
+    # Forgiving input, allows either argument if only one supplied.
+    #
+    # @overload initialize(command_arg)
+    # @overload initialize(version_pattern)
+    # @overload initialize(command_arg, version_pattern)
+    # @param command_arg [String] ('--version')
+    # @param version_pattern [Regexp] (/(?<=version )[0-9][.0-9a-z]+/i)
+    def initialize(*args)
+      command_arg = args.shift if args.first.kind_of?(String)
+      version_pattern = args.shift
+      super(command_arg, version_pattern)
+    end
+
+    def version_pattern
+      super || DEFAULT_VERSION_PATTERN
+    end
+
+    def command_arg
+      super || DEFAULT_COMMAND_ARG
+    end
+
+    def version_command(executable)
+      [executable, command_arg]
+    end
+  end
+end

data/lib/cliver/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Cliver
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/spec/cliver/assertion_spec.rb

@@ -2,11 +2,14 @@
 require 'cliver/assertion'
 
 describe Cliver::Assertion do
-  let(:mismatch_exception) { Cliver::Assertion::VersionMismatch }
+  let(:mismatch_exception) { Cliver::Assertion::DependencyVersionMismatch }
   let(:missing_exception) { Cliver::Assertion::DependencyNotFound }
   let(:requirements) { ['6.8'] }
   let(:executable) { 'fubar' }
-  let(:assertion) { Cliver::Assertion.new(executable, *requirements) }
+  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 } }
@@ -16,39 +19,38 @@ describe Cliver::Assertion do
     context '~>' do
       let(:requirements) { ['~> 6.8'] }
       context 'when version matches exactly' do
-        let(:version) { Gem::Version.new('6.8') }
+        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) { Gem::Version.new('6.7') }
+        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) { Gem::Version.new('6.13') }
+        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) { Gem::Version.new('7.0') }
+        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) { Gem::Version.new('6.8.1') }
+        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) { Gem::Version.new('6.8.a') }
+        let(:version) { '6.8.a' }
         it 'should raise' do
-          version.should be_prerelease
           expect { assertion.assert! }.to raise_exception mismatch_exception
         end
       end
@@ -57,13 +59,13 @@ describe Cliver::Assertion do
     context 'multi [>=,<]' do
       let(:requirements) { ['>= 1.1.4', '< 3.1'] }
       context 'matches both' do
-        let(:version)  { Gem::Version.new('2.0') }
+        let(:version)  { '2.0' }
         it 'should not raise' do
           expect { assertion.assert! }.to_not raise_exception
         end
       end
       context 'fails one' do
-        let(:version)  { Gem::Version.new('3.1') }
+        let(:version)  { '3.1' }
         it 'should raise' do
           expect { assertion.assert! }.to raise_exception mismatch_exception
         end
@@ -72,7 +74,7 @@ describe Cliver::Assertion do
 
     context 'none' do
       let(:requirements) { [] }
-      let(:version) { Gem::Version.new('3.1') }
+      let(:version) { '3.1' }
       it 'should not raise' do
         expect { assertion.assert! }.to_not raise_exception
       end
@@ -86,4 +88,55 @@ describe Cliver::Assertion 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 with detector-block returned value' do
+      let(:requirements) { ['~> 10.1.4'] }
+      let(:fake_version) { '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.1.3' }
+        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

data/spec/cliver/detector_spec.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+require 'cliver/detector'
+
+describe Cliver::Detector do
+  let(:detector) { Cliver::Detector::Default.new(*args) }
+  let(:defaults) do
+    {
+      version_pattern: Cliver::Detector::Default::DEFAULT_VERSION_PATTERN,
+      command_arg:     Cliver::Detector::Default::DEFAULT_COMMAND_ARG,
+    }
+  end
+  let(:args) { [] }
+  subject { detector }
+
+  it { should respond_to :to_proc }
+
+  its(:command_arg) { should eq defaults[:command_arg] }
+  its(:version_pattern) { should eq defaults[:version_pattern] }
+
+  context 'with one string argument' do
+    let(:version_arg) { '--release-version' }
+    let(:args) { [version_arg] }
+
+    its(:command_arg) { should eq version_arg }
+    its(:version_pattern) { should eq defaults[:version_pattern] }
+  end
+
+  context 'with one regexp argument' do
+    let(:regexp_arg) { /.*/ }
+    let(:args) { [regexp_arg] }
+
+    its(:command_arg) { should eq defaults[:command_arg] }
+    its(:version_pattern) { should eq regexp_arg }
+  end
+
+  context 'with both arguments' do
+    let(:version_arg) { '--release-version' }
+    let(:regexp_arg) { /.*/ }
+    let(:args) { [version_arg, regexp_arg] }
+
+    its(:command_arg) { should eq version_arg }
+    its(:version_pattern) { should eq regexp_arg }
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cliver
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -100,6 +100,7 @@ extra_rdoc_files: []
 files:
 - .githooks/pre-commit/ruby-appraiser
 - .gitignore
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -107,8 +108,11 @@ files:
 - cliver.gemspec
 - lib/cliver.rb
 - lib/cliver/assertion.rb
+- lib/cliver/detector.rb
+- lib/cliver/detector/default.rb
 - lib/cliver/version.rb
 - spec/cliver/assertion_spec.rb
+- spec/cliver/detector_spec.rb
 - spec/cliver_spec.rb
 homepage: https://www.github.com/yaauie/cliver
 licenses:
@@ -137,5 +141,6 @@ 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
 has_rdoc: