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/utils/pager.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/utils/standard_ui.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/pager.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.
Common starting points
Some of the most commonly needed class documentation is listed below:
- For information on the DSL used to write tools, start with DSL::Tool.
- The base class for tool runtime (i.e. that defines the basic methods available to a tool's implementation) is Context.
- For information on writing mixins, see Mixin.
- For information on writing templates, see Template.
- For information on writing acceptors, see Acceptor.
- For information on writing custom shell completions, see Completion.
- Standard mixins are defined under the StandardMixins module.
- Various utilities are defined under Utils. Some of these serve as the implementations of corresponding mixins.
- The main entrypoint for the command line framework is CLI.
Other important internal classes are listed below.
- The definition of a tool is represented by ToolDefinition along the helpers Flag, PositionalArg, and FlagGroup.
- Argument parsing is implemented by ArgParser.
- The process of finding and loading a tool definition given a tool name, is implemented by Loader.
- Text wrapping is handled by WrappableString.
- The settings system is implemented by Settings.
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
-
.executable_path ⇒ String?
Path to the executable.
Class Method Summary collapse
-
.Tool(*args, name: nil, base: nil) ⇒ Object
Create a base class for defining a tool with a given name.
Class Attribute Details
.executable_path ⇒ String?
Path to the executable. This can, for example, be invoked to run a subtool in a clean environment.
114 115 116 |
# File 'lib/toys-core.rb', line 114 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
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 |