Module: Toys::Mixin

Included in:

StandardMixins::Exec, StandardMixins::Fileutils, StandardMixins::Gems, StandardMixins::Highline, StandardMixins::Terminal

Defined in:

lib/toys/mixin.rb

Overview

A mixin definition. Mixin modules should include this module.

A mixin is a collection of methods that are available to be called from a tool implementation (i.e. its run method). The mixin is added to the tool class, so it has access to the same methods that can be called by the tool, such as Tool#option.

Usage

To create a mixin, define a module, and include this module. Then define the methods you want to be available.

If you want to perform some initialization specific to the mixin, you can provide a to_initialize block and/or a to_include block.

The to_initialize block is called when the tool itself is instantiated. It has access to tool methods such as Tool#option, and can perform setup for the tool execution itself, often involving initializing some persistent state and storing it in the tool using Tool#set. The to_initialize block is passed any extra arguments that were provided to the include directive.

The to_include block is called in the context of your tool class when your mixin is included. It is also passed any extra arguments that were provided to the include directive. It can be used to issue directives or define methods on the DSL, specific to the mixin.

Example

This is an example that implements a simple counter. Whenever the counter is incremented, a log message is emitted. The tool can also retrieve the final counter value.

# Define a mixin by creating a module that includes Toys::Mixin
module MyCounterMixin
  include Toys::Mixin

  # Initialize the counter. Called with self set to the tool so it can
  # affect the tool state.
  to_initialize do |start = 0|
    set(:counter_value, start)
  end

  # Mixin methods are called with self set to the tool and can affect
  # the tool state.
  def counter_value
    get(:counter_value)
  end

  def increment
    set(:counter_value, counter_value + 1)
    logger.info("Incremented counter")
  end
end

Now we can use it from a tool:

tool "count-up" do
  # Pass 1 as an extra argument to the mixin initializer
  include MyCounterMixin, 1

  def run
    # Mixin methods can be called.
    5.times { increment }
    puts "Final value is #{counter_value}"
  end
end

Defined Under Namespace

Modules: ModuleMethods