Module: Toys::Mixin
- Included in:
- StandardMixins::Bundler, StandardMixins::Exec, StandardMixins::Fileutils, StandardMixins::Gems, StandardMixins::GitCache, StandardMixins::Highline, StandardMixins::Terminal, StandardMixins::XDG
- 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 Context#get.
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 an initializer block and/or an inclusion block. These can be specified by calling the module methods defined in ModuleMethods.
The initializer block is called when the tool context is instantiated
in preparation for execution. It has access to context methods such as
Context#get, and can perform setup for the tool execution itself,
such as initializing some persistent state and storing it in the tool using
Context#set. The initializer block is passed any extra arguments
that were provided to the include
directive. Define the initializer by
calling ModuleMethods#on_initialize.
The inclusion 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 to define
tools or other objects in the DSL, or even enhance the DSL by defining DSL
methods specific to the mixin. Define the inclusion block by calling
ModuleMethods#on_include.
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. Notice that the initializer is evaluated
# in the context of the runtime context, so has access to the runtime
# context state.
on_initialize do |start = 0|
set(:counter_value, start)
end
# Mixin methods are evaluated in the runtime context and so have
# access to the runtime context state, just as if you had defined
# them in your tool.
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
Class Method Summary collapse
-
.create(&block) ⇒ Class
Create a mixin module with the given block.