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,
lib/cliver/shell_capture.rb

Overview

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

Defined Under Namespace

Modules: Filter Classes: Dependency, Detector, ShellCapture

Constant Summary collapse

VERSION =

Cliver follows SemVer

'0.3.2'

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

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

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

    [<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 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`

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:



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

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

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

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

    [<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 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`

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:



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

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

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

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

    [<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 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`

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:



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

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

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

Verify an absolute-path to an executable.

Returns 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:



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

def self.verify!(executable, *args, &block)
  unless File.absolute_path?(executable)
    raise ArgumentError, "executable path must be absolute, " +
                         "got '#{executable.inspect}'."
  end
  options = args.last.kind_of?(Hash) ? args.pop : {}
  args << options.merge(:path => '.') # ensure path non-empty.
  Dependency::new(executable, *args, &block).detect!
end

Instance Method Details

#dependency_unmet?(*args, &block) ⇒ False, String

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


77
78
79
80
81
82
83
84
 
# File 'lib/cliver.rb', line 77

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