Module: Cliver

Extended by:
Cliver
Included in:
Cliver
Defined in:
lib/cliver.rb,
lib/cliver/filter.rb,
lib/cliver/version.rb,
lib/cliver/detector.rb,
lib/cliver/dependency.rb

Overview

Cliver is tool for making dependency assertions against command-line executables.

Defined Under Namespace

Modules: Filter Classes: Dependency, Detector

Constant Summary

VERSION =

Cliver follows SemVer

'0.2.1'

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

- (Dependency) initialize(executables, *requirements, options = {}) {|executable_path| ... }

A legacy interface for detect with the option strict: true, ensures that the first executable on your path matches the requirements.

Parameters:

  • executables (String, Array<String>) —

    api-compatible executable names e.g, ['python2','python']

  • requirements (Array<String>, String) —

    splat of strings whose elements follow the pattern [] Where is optional (default '='') and in the set '=', '!=', '>', '<', '>=', '<=', or '~>' And is dot-separated integers with optional alphanumeric pre-release suffix. See also Specifying Versions

  • options (Hash<Symbol,Object>) (defaults to: {})

Options Hash (options):

  • :detector (Cliver::Detector) — default: Detector.new
  • :detector (#to_proc, Object) — default: see Detector::generate
  • :filter (#to_proc) — default: {Cliver::Filter::IDENTITY}
  • :strict (Boolean) — default: 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.

  • :path (String) — default: '*' —

    the path on which to search for executables. If an asterisk (*) is included in the supplied string, it is replaced with ENV['PATH']

Yield Parameters:

  • executable_path (String) —

    (see Detector#detect_version)

Yield Returns:

  • (String) —

    containing a version that, once filtered, can be used for comparrison.

Parameters:

  • options (Hash) —

    a customizable set of options

Returns:

  • (String) —

    path to an executable that meets the requirements

Raises:

See Also:



45
46
47
48
49
 
# File 'lib/cliver.rb', line 45

def self.assert(*args, &block)
  options = args.last.kind_of?(Hash) ? args.pop : {}
  args << options.merge(:strict => true)
  Dependency::new(*args, &block).detect!
end

- (Dependency) initialize(executables, *requirements, options = {}) {|executable_path| ... }

A non-raising variant of detect!, simply returns false if dependency cannot be found.

Parameters:

  • executables (String, Array<String>) —

    api-compatible executable names e.g, ['python2','python']

  • requirements (Array<String>, String) —

    splat of strings whose elements follow the pattern [] Where is optional (default '='') and in the set '=', '!=', '>', '<', '>=', '<=', or '~>' And is dot-separated integers with optional alphanumeric pre-release suffix. See also Specifying Versions

  • options (Hash<Symbol,Object>) (defaults to: {})

Options Hash (options):

  • :detector (Cliver::Detector) — default: Detector.new
  • :detector (#to_proc, Object) — default: see Detector::generate
  • :filter (#to_proc) — default: {Cliver::Filter::IDENTITY}
  • :strict (Boolean) — default: 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.

  • :path (String) — default: '*' —

    the path on which to search for executables. If an asterisk (*) is included in the supplied string, it is replaced with ENV['PATH']

Yield Parameters:

  • executable_path (String) —

    (see Detector#detect_version)

Yield Returns:

  • (String) —

    containing a version that, once filtered, can be used for comparrison.

Returns:

  • (see #detect!) —

    or nil if no match found.

See Also:



33
34
35
 
# File 'lib/cliver.rb', line 33

def self.detect(*args, &block)
  Dependency::new(*args, &block).detect
end

- (Dependency) initialize(executables, *requirements, options = {}) {|executable_path| ... }

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.

Parameters:

  • executables (String, Array<String>) —

    api-compatible executable names e.g, ['python2','python']

  • requirements (Array<String>, String) —

    splat of strings whose elements follow the pattern [] Where is optional (default '='') and in the set '=', '!=', '>', '<', '>=', '<=', or '~>' And is dot-separated integers with optional alphanumeric pre-release suffix. See also Specifying Versions

  • options (Hash<Symbol,Object>) (defaults to: {})

Options Hash (options):

  • :detector (Cliver::Detector) — default: Detector.new
  • :detector (#to_proc, Object) — default: see Detector::generate
  • :filter (#to_proc) — default: {Cliver::Filter::IDENTITY}
  • :strict (Boolean) — default: 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.

  • :path (String) — default: '*' —

    the path on which to search for executables. If an asterisk (*) is included in the supplied string, it is replaced with ENV['PATH']

Yield Parameters:

  • executable_path (String) —

    (see Detector#detect_version)

Yield Returns:

  • (String) —

    containing a version that, once filtered, can be used for comparrison.

Returns:

  • (String) —

    path to an executable that meets the requirements

Raises:

See Also:



22
23
24
 
# File 'lib/cliver.rb', line 22

def self.detect!(*args, &block)
  Dependency::new(*args, &block).detect!
end

+ (String) verify!(executable, *requirements, options = {})

Verify an absolute-path to an executable.

Path to an executable that meets the requirements

Parameters:

  • executable (String) —

    absolute path to an executable

Returns:

  • (String) —

    path to an executable that meets the requirements

Raises:



58
59
60
61
62
63
64
 
# File 'lib/cliver.rb', line 58

def self.verify!(executable, *args, &block)
  unless File.absolute_path?(executable)
    raise ArgumentError, "executable path must be absolute, " +
                         "got '#{executable.inspect}'."
  end
  Dependency::new(executable, *args, &block).detect!
end

Instance Method Details

- (False, String) dependency_unmet?(*args, &block)

Wraps Cliver::assert and returns truthy/false instead of raising

Returns:

  • (False, String) —

    either returns false or the reason why the assertion was unmet.

See Also:

  • assert


74
75
76
77
78
79
80
81
 
# File 'lib/cliver.rb', line 74

def dependency_unmet?(*args, &block)
  Cliver.assert(*args, &block)
  false
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}"
end