Module: Toys::StandardMixins::Gems

Includes:
Mixin
Defined in:
core-docs/toys/standard_mixins/gems.rb

Overview

Defined in the toys-core gem

Provides methods for installing and activating third-party gems. When this mixin is included, it provides a gem method that has the same effect as Utils::Gems#activate, so you can ensure a gem is present when running a tool. A gem directive is likewise added to the tool DSL itself, so you can also ensure a gem is present when defining a tool.

Usage

Make these methods available to your tool by including this mixin in your tool:

include :gems

You can then call the mixin method #gem to ensure that a gem is installed and in the load path. For example:

tool "my_tool" do
  include :gems
  def run
    gem "nokogiri", "~> 1.15"
    # Do stuff with Nokogiri
  end
end

If you pass additional options to the include directive, those are used to initialize settings for the gem install process. For example:

include :gems, on_missing: :error

You can also pass options to the #gem mixin method itself:

tool "my_tool" do
  include :gems
  def run
    # If the gem is not installed, error out instead of asking to
    # install it.
    gem "nokogiri", "~> 1.15", on_missing: :error
    # Do stuff with Nokogiri
  end
end

See Utils::Gems#initialize for a list of supported options.

Defined Under Namespace

Modules: ClassMethods

Constant Summary collapse

KEY =

Context key for the tool-wide Utils::Gems object.

Returns:

  • (Object) 
::Object.new.freeze

Instance Method Summary collapse

Methods included from Mixin

create

Instance Method Details

#gem(name, *requirements, **options) ⇒ :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

  • options (keywords) —

    Additional options to pass to the Utils::Gems constructor

Returns:

  • (:activated) —

    if the gem was activated

  • (:installed) —

    if the gem was installed and activated

  • (false) —

    if the gem had already been activated

Raises:

  • (ActivationFailedError) —

    if activation or install failed



82
83
84
 
# File 'core-docs/toys/standard_mixins/gems.rb', line 82

def gem(name, *requirements, **options)
  # Source available in the toys-core gem
end

#gems ⇒ Toys::Utils::Gems

Returns a tool-wide instance of Utils::Gems.

Returns:



63
64
65
 
# File 'core-docs/toys/standard_mixins/gems.rb', line 63

def gems
  # Source available in the toys-core gem
end