Class: Toys::Utils::Gems

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/utils/gems.rb

Overview

A helper class that activates and installs gems and sets up bundler.

This class is not loaded by default. Before using it directly, you should require "toys/utils/gems"

Defined Under Namespace

Classes: ActivationFailedError, AlreadyBundledError, BundleNotInstalledError, BundlerFailedError, GemfileNotFoundError, GemfileUpdateNeededError, IncompatibleGemSourceError, IncompatibleToysError, InstallFailedError

Constant Summary collapse

DEFAULT_GEMFILE_NAMES =

The gemfile names that are searched by default.

Returns:

  • (Array<String>) 
[".gems.rb", "gems.rb", "Gemfile"].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(on_missing: nil, on_conflict: nil, terminal: nil, input: nil, output: nil, suppress_confirm: nil, default_confirm: nil) ⇒ Gems

Create a new gem activator.

Parameters:

  • on_missing (:confirm, :error, :install) (defaults to: nil) —

    What to do if a needed gem is not installed. Possible values:

    • :confirm - prompt the user on whether to install
    • :error - raise an exception
    • :install - just install the gem

    The default is :confirm.

  • on_conflict (:error, :warn, :ignore) (defaults to: nil) —

    What to do if bundler has already been run with a different Gemfile. Possible values:

    • :error - raise an exception
    • :ignore - just silently proceed without bundling again
    • :warn - print a warning and proceed without bundling again

    The default is :error.

  • default_confirm (boolean) (defaults to: nil) —

    The default confirmation result, if on_missing is set to :confirm. Defaults to true.

  • terminal (Toys::Utils::Terminal) (defaults to: nil) —

    Terminal to use (optional)

  • input (IO) (defaults to: nil) —

    Input IO (optional, defaults to STDIN)

  • output (IO) (defaults to: nil) —

    Output IO (optional, defaults to STDOUT)

  • suppress_confirm (boolean) (defaults to: nil) —

    Deprecated. Use on_missing instead.



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/toys/utils/gems.rb', line 180

def initialize(on_missing: nil,
               on_conflict: nil,
               terminal: nil,
               input: nil,
               output: nil,
               suppress_confirm: nil,
               default_confirm: nil)
  require "rubygems"
  unless suppress_confirm.nil?
    warn("The :suppress_confirm argument to Toys::Utils::Gems is deprecated. " \
         "Use :on_missing instead.")
  end
  default_confirm = true if default_confirm.nil?
  @default_confirm = default_confirm ? true : false
  @on_missing = on_missing ||
                if suppress_confirm
                  @default_confirm ? :install : :error
                else
                  :confirm
                end
  @on_conflict = on_conflict || :error
  @terminal = terminal
  @input = input || $stdin
  @output = output || $stdout
end

Class Method Details

.activate(name, *requirements) ⇒ :activated, ...

Activate the given gem. If it is not present, attempt to install it (or inform the user to update the bundle).

Parameters:

  • name (String) —

    Name of the gem

  • requirements (String...) —

    Version requirements

Returns:

  • (:activated) —

    if the gem was activated

  • (:installed) —

    if the gem was installed and activated

  • (false) —

    if the gem had already been activated

Raises:



148
149
150
 
# File 'lib/toys/utils/gems.rb', line 148

def self.activate(name, *requirements)
  new.activate(name, *requirements)
end

Instance Method Details

#activate(name, *requirements) ⇒ :activated, ...

Activate the given gem. If it is not present, attempt to install it (or inform the user to update the bundle).

Parameters:

  • name (String) —

    Name of the gem

  • requirements (String...) —

    Version requirements

Returns:

  • (:activated) —

    if the gem was activated

  • (:installed) —

    if the gem was installed and activated

  • (false) —

    if the gem had already been activated

Raises:



219
220
221
222
223
224
225
 
# File 'lib/toys/utils/gems.rb', line 219

def activate(name, *requirements)
  Gems.synchronize do
    gem(name, *requirements) ? :activated : false
  rescue ::Gem::LoadError => e
    handle_activation_error(e, name, requirements)
  end
end

#bundle(groups: nil, gemfile_path: nil, search_dirs: nil, gemfile_names: nil, retries: nil) ⇒ :setup, ...

Search for an appropriate Gemfile, and set up the bundle.

Parameters:

  • groups (Array<String>) (defaults to: nil) —

    The groups to include in setup. Gems already loaded in this process are always included, whatever groups are requested, because excluding one would remove it from the load path of the running process.

  • gemfile_path (String) (defaults to: nil) —

    The path to the Gemfile to use. If nil or not given, the :search_dirs will be searched for a Gemfile.

  • search_dirs (String, Array<String>) (defaults to: nil) —

    Directories in which to search for a Gemfile, if gemfile_path is not given. You can provide a single directory or an array of directories.

  • gemfile_names (String, Array<String>) (defaults to: nil) —

    File names that are recognized as Gemfiles, when searching because gemfile_path is not given. Defaults to DEFAULT_GEMFILE_NAMES.

  • retries (Integer) (defaults to: nil) —

    Number of times to retry bundler operations. Optional.

Returns:

  • (:setup) —

    if the bundle was set up with no install needed

  • (:installed) —

    if the bundle was installed and set up

  • (:updated) —

    if the bundle was updated and set up

  • (false) —

    on a bundle conflict if configured not to raise an exception

Raises:



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/toys/utils/gems.rb', line 253

def bundle(groups: nil,
           gemfile_path: nil,
           search_dirs: nil,
           gemfile_names: nil,
           retries: nil)
  Array(search_dirs).each do |dir|
    break if gemfile_path
    gemfile_path = Gems.find_gemfile(dir, gemfile_names: gemfile_names)
  end
  raise GemfileNotFoundError, "Gemfile not found" unless gemfile_path
  gemfile_path = ::File.absolute_path(gemfile_path)
  Gems.synchronize do
    setup_bundle(gemfile_path, groups: Array(groups), retries: retries)
  end
end