Class: Toys::Utils::Gems

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/utils/gems.rb

Overview

Defined in the toys-core gem

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, 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.



137
138
139
140
141
142
143
144
145
 
# File 'core-docs/toys/utils/gems.rb', line 137

def initialize(on_missing: nil,
               on_conflict: nil,
               terminal: nil,
               input: nil,
               output: nil,
               suppress_confirm: nil,
               default_confirm: nil)
  # Source available in the toys-core gem
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:



105
106
107
 
# File 'core-docs/toys/utils/gems.rb', line 105

def self.activate(name, *requirements)
  # Source available in the toys-core gem
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:



160
161
162
 
# File 'core-docs/toys/utils/gems.rb', line 160

def activate(name, *requirements)
  # Source available in the toys-core gem
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.

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



187
188
189
190
191
192
193
 
# File 'core-docs/toys/utils/gems.rb', line 187

def bundle(groups: nil,
           gemfile_path: nil,
           search_dirs: nil,
           gemfile_names: nil,
           retries: nil)
  # Source available in the toys-core gem
end