cliver 0.1.2 → 0.1.3

data/.travis.yml

@@ -1,6 +1,5 @@
 ---
 language: ruby
-before_install: "gem install bundler"
 script: "bundle exec rake spec"
 rvm:
   - 2.0.0
@@ -14,3 +13,4 @@ branches:
     - /^release\/-.*$/
     - /^support\/-.*$/
     - /^hotfix\/-.*$/
+    - /^feature\/-.*$/

data/cliver.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
   spec.require_paths = ['lib']
+  spec.has_rdoc      = 'yard'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake'

data/lib/cliver.rb

@@ -5,9 +5,32 @@ require 'cliver/assertion'
 require 'cliver/detector'
 require 'cliver/detector/default'
 
+# Cliver is tool for making dependency assertions against
+# command-line executables.
 module Cliver
-  # See Cliver::Assertion#assert
+  # @see Cliver::Assertion
+  # @overload (see Cliver::Assertion#initialize)
+  # @param (see Cliver::Assertion#initialize)
+  # @raise (see Cliver::Assertion#assert!)
+  # @return (see Cliver::Assertion#assert!)
   def self.assert(*args, &block)
-    Assertion.assert!(*args, &block)
+    Assertion.new(*args, &block).assert!
+  end
+
+  extend self
+
+  # Wraps Cliver::assert and returns truthy/false instead of raising
+  # @see Cliver::assert
+  # @overload (see Cliver::Assertion#initialize)
+  # @param (see Cliver::Assertion#initialize)
+  # @return [False,String] either returns false or the reason why the
+  #                        assertion was unmet.
+  def dependency_unmet?(*args, &block)
+    Cliver.assert(*args, &block)
+    false
+  rescue Assertion::DependencyNotMet => error
+    # Cliver::Assertion::VersionMismatch -> 'Version Mismatch'
+    reason = error.class.name.split('::').last.gsub(/(?<!\A)[A-Z]/, ' \\0')
+    "#{reason}: #{error.message}"
   end
 end

data/lib/cliver/assertion.rb

@@ -9,17 +9,14 @@ module Cliver
 
     include Which # platform-specific implementation of `which`
 
+    # An exception class raised when assertion is not met
     DependencyNotMet = Class.new(ArgumentError)
-    DependencyVersionMismatch = Class.new(DependencyNotMet)
-    DependencyNotFound = Class.new(DependencyNotMet)
 
-    EXECUTABLE_PATTERN = /\A[a-z][a-zA-Z0-9\-_]*\z/.freeze
+    # An exception that is raised when executable present is the wrong version
+    DependencyVersionMismatch = Class.new(DependencyNotMet)
 
-    # Creates a new instance with the args and calls #assert.
-    # @see #assert
-    def self.assert!(*args, &block)
-      new(*args, &block).assert!
-    end
+    # An exception that is raised when executable is not present
+    DependencyNotFound = Class.new(DependencyNotMet)
 
     # @overload initialize(executable, *requirements, options = {})
     # @param executable [String]
@@ -29,15 +26,13 @@ module Cliver
     #   Where <operator> is optional (default '='') and in the set
     #     '=', '!=', '>', '<', '>=', '<=', or '~>'
     #   And <version> is dot-separated integers with optional
-    #   alphanumeric pre-release suffix
-    #   @see Gem::Requirement::new
+    #   alphanumeric pre-release suffix. See also
+    #   {http://docs.rubygems.org/read/chapter/16 Specifying Versions}
     # @param options [Hash<Symbol,Object>]
-    # @options options [Cliver::Detector, #to_proc] :detector
+    # @option 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
@@ -49,14 +44,17 @@ module Cliver
     # @raise [DependencyNotFound] if no installed version on your path
     def assert!
       version = installed_version
-      raise(DependencyNotFound, "#{@executable} missing.") unless version
+      raise(DependencyNotFound, "'#{@executable}' missing.") unless version
 
       if @requirement && !@requirement.satisfied_by?(Gem::Version.new(version))
         raise DependencyVersionMismatch,
-              "expected #{@executable} to be #{@requirement}, got #{version}"
+              "expected '#{@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

data/lib/cliver/detector.rb

@@ -6,15 +6,19 @@ module Cliver
   # @see Cliver::Detector::Default for reference implementation
   module Detector
     # Forward to default implementation
+    # @see Cliver::Detector::Default
+    # @overload (see Cliver::Detector::Default#initialize)
+    # @param (see Cliver::Detector::Default#initialize)
+    # @raise (see Cliver::Detector::Default#initialize)
+    # @return (see Cliver::Detector::Default#initialize)
     def self.new(*args, &block)
       Default.new(*args, &block)
     end
 
-    # @param executable [String] the executable to test
+    # @param executable_path [String] the executable to test
     # @return [Array<String>]
-    def version_command(executable)
-      raise NotImplementedError unless defined? super
-      super
+    def version_command(executable_path)
+      raise NotImplementedError
     end
 
     # @return [Regexp] - the pattern used against the output
@@ -25,19 +29,18 @@ module Cliver
       super
     end
 
-    # @param executable [String] - the path to the executable to test
+    # @param executable_path [String] - the path to the executable to test
     # @return [String] - should be Gem::Version-parsable.
-    def detect_version(executable)
-      command_parts = version_command(executable)
-      escaped_command_parts = command_parts.map(&Shellwords.method(:escape))
-      output = `#{escaped_command_parts.join(' ')} 2>&1`
+    def detect_version(executable_path)
+      output = `#{version_command(executable_path).shelljoin} 2>&1`
       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]
+    # If not overridden, returns a proc that wraps #detect_version
+    # @see #detect_version
+    # @return [Proc] following method signature of {#detect_version}
     def to_proc
       method(:detect_version).to_proc
     end

data/lib/cliver/detector/default.rb

@@ -8,7 +8,11 @@ module Cliver
   class Detector::Default < Struct.new(:command_arg, :version_pattern)
     include Detector
 
+    # Default pattern to use when searching {#version_command} output
     DEFAULT_VERSION_PATTERN = /(?<=version )[0-9][.0-9a-z]+/i.freeze
+
+    # Default command argument to use against the executable to get
+    # version output
     DEFAULT_COMMAND_ARG = '--version'.freeze
 
     # Forgiving input, allows either argument if only one supplied.
@@ -24,16 +28,25 @@ module Cliver
       super(command_arg, version_pattern)
     end
 
+    # The pattern to match the version in {#version_command}'s output.
+    # Defaults to {DEFAULT_VERSION_PATTERN}
+    # @overload (see Cliver::Detector#version_pattern)
+    # @return (see Cliver::Detector#version_pattern)
     def version_pattern
       super || DEFAULT_VERSION_PATTERN
     end
 
+    # The argument to pass to the executable to get current version
+    # Defaults to {DEFAULT_COMMAND_ARG}
+    # @return [String]
     def command_arg
       super || DEFAULT_COMMAND_ARG
     end
 
-    def version_command(executable)
-      [executable, command_arg]
+    # @overload (see Cliver::Detector#version_command)
+    # @return (see Cliver::Detector#version_command)
+    def version_command(executable_path)
+      [executable_path, command_arg]
     end
   end
 end

data/lib/cliver/version.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
 module Cliver
-  VERSION = '0.1.2'
+  # Cliver follows {http://semver.org SemVer}
+  VERSION = '0.1.3'
 end

data/lib/cliver/which/posix.rb

@@ -6,6 +6,7 @@ module Cliver
     # 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)

data/lib/cliver/which/windows.rb

@@ -6,13 +6,14 @@ module Cliver
     # 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.split("\n").find do |found|
+        where.lines.map(&:chomp).find do |found|
           next if found.empty?
           File.executable?(found)
         end

data/spec/cliver_spec.rb

@@ -3,4 +3,29 @@ require 'cliver'
 
 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' }
+      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}' missing" }
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cliver
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-19 00:00:00.000000000 Z
+date: 2013-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -163,4 +163,4 @@ test_files:
 - spec/cliver/assertion_spec.rb
 - spec/cliver/detector_spec.rb
 - spec/cliver_spec.rb
-has_rdoc: 
+has_rdoc: yard