Class: Toys::Utils::Gems

Inherits:
Object
  • Object
show all
Defined in:
core-docs/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 in the toys-core gem

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, default_confirm: nil, terminal: nil, input: nil, output: 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)



143
144
145
146
147
148
149
150
 
# File 'core-docs/toys/utils/gems.rb', line 143

def initialize(on_missing: nil,
               on_conflict: nil,
               default_confirm: nil,
               terminal: nil,
               input: nil,
               output: 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:



114
115
116
 
# File 'core-docs/toys/utils/gems.rb', line 114

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:



177
178
179
 
# File 'core-docs/toys/utils/gems.rb', line 177

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



207
208
209
210
211
212
213
 
# File 'core-docs/toys/utils/gems.rb', line 207

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

#with(**overrides) ⇒ Toys::Utils::Gems

Return a gem activator with the same settings as this one, except for the provided overrides. See the constructor for argument docs. If no non-nil overrides are provided, self is returned.

Parameters:

  • overrides (Hash) —

    Overrides. See the constructor for details.

Returns:



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

def with(**overrides)
  # Source available in the toys-core gem
end