Module: Toys

Defined in:
lib/toys-core.rb,
lib/toys/cli.rb,
lib/toys/core.rb,
lib/toys/flag.rb,
lib/toys/mixin.rb,
lib/toys/compat.rb,
lib/toys/errors.rb,
lib/toys/loader.rb,
lib/toys/context.rb,
lib/toys/acceptor.rb,
lib/toys/dsl/base.rb,
lib/toys/dsl/flag.rb,
lib/toys/dsl/tool.rb,
lib/toys/settings.rb,
lib/toys/template.rb,
lib/toys/utils/xdg.rb,
lib/toys/arg_parser.rb,
lib/toys/completion.rb,
lib/toys/flag_group.rb,
lib/toys/middleware.rb,
lib/toys/utils/exec.rb,
lib/toys/utils/gems.rb,
lib/toys/source_info.rb,
lib/toys/dsl/internal.rb,
lib/toys/module_lookup.rb,
lib/toys/dsl/flag_group.rb,
lib/toys/positional_arg.rb,
lib/toys/utils/terminal.rb,
lib/toys/tool_definition.rb,
lib/toys/utils/git_cache.rb,
lib/toys/utils/help_text.rb,
lib/toys/wrappable_string.rb,
lib/toys/dsl/positional_arg.rb,
lib/toys/standard_mixins/xdg.rb,
lib/toys/standard_mixins/exec.rb,
lib/toys/standard_mixins/gems.rb,
lib/toys/standard_mixins/bundler.rb,
lib/toys/utils/completion_engine.rb,
lib/toys/standard_mixins/highline.rb,
lib/toys/standard_mixins/terminal.rb,
lib/toys/standard_mixins/fileutils.rb,
lib/toys/standard_mixins/git_cache.rb,
lib/toys/standard_middleware/show_help.rb,
lib/toys/standard_middleware/apply_config.rb,
lib/toys/standard_middleware/show_root_version.rb,
lib/toys/standard_middleware/add_verbosity_flags.rb,
lib/toys/standard_middleware/handle_usage_errors.rb,
lib/toys/standard_middleware/set_default_descriptions.rb

Overview

Toys is a configurable command line tool. Write commands in config files using a simple DSL, and Toys will provide the command line executable and take care of all the details such as argument parsing, online help, and error reporting. Toys is designed for software developers, IT professionals, and other power users who want to write and organize scripts to automate their workflows. It can also be used as a Rake replacement, providing a more natural command line interface for your project's build tasks.

This module contains the command line framework underlying Toys. It can be used to create command line executables using the Toys DSL and classes.

Defined Under Namespace

Modules: Acceptor, Completion, Core, DSL, FlagGroup, InputFile, Middleware, Mixin, StandardMiddleware, StandardMixins, Template, Utils Classes: ArgParser, ArgParsingError, CLI, Context, ContextualError, Flag, Loader, LoaderError, ModuleLookup, NotRunnableError, PositionalArg, Settings, SourceInfo, Tool, ToolDefinition, ToolDefinitionError, WrappableString

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.executable_path ⇒ String?

Path to the executable. This can, for example, be invoked to run a subtool in a clean environment.

Returns:

  • (String) —

    if there is an executable

  • (nil) —

    if there is no such executable



66
67
68
 
# File 'lib/toys-core.rb', line 66

def executable_path
  @executable_path
end

Class Method Details

.Tool(*args, name: nil, base: nil) ⇒ Object

Create a base class for defining a tool with a given name.

This method returns a base class for defining a tool with a given name. This is useful if the naming behavior of Tool is not adequate for your tool.

Example

class FooBar < Toys.Tool("Foo_Bar")
  desc "This is a tool called Foo_Bar"

  def run
    puts "Foo_Bar called"
  end
end

Parameters:

  • name (String) (defaults to: nil) —

    Name of the tool. Defaults to a name inferred from the class name. (See Tool.)

  • base (Class) (defaults to: nil) —

    Use this tool class as the base class, and inherit helper methods from it.

  • args (String, Class) —

    Any string-valued positional argument is interpreted as the name. Any class-valued positional argument is interpreted as the base class.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/toys/dsl/base.rb', line 28

def Toys.Tool(*args, name: nil, base: nil) # rubocop:disable Naming/MethodName
  args.each do |arg|
    case arg
    when ::Class
      raise ::ArgumentError, "Both base keyword argument and class-valud argument received" if base
      base = arg
    when ::String, ::Symbol
      raise ::ArgumentError, "Both name keyword argument and string-valud argument received" if name
      name = arg
    else
      raise ::ArgumentError, "Unrecognized argument: #{arg}"
    end
  end
  if base && !base.ancestors.include?(::Toys::Context)
    raise ::ArgumentError, "Base class must itself be a tool"
  end
  return base || ::Toys::Tool if name.nil?
  ::Class.new(base || ::Toys::Context) do
    base_class = self
    define_singleton_method(:inherited) do |tool_class|
      ::Toys::DSL::Internal.configure_class(tool_class, base_class == self ? name.to_s : nil)
      super(tool_class)
      ::Toys::DSL::Internal.setup_class_dsl(tool_class)
    end
  end
end