Class: Toys::CLI
- Inherits:
-
Object
- Object
- Toys::CLI
- Defined in:
- core-docs/toys/cli.rb
Overview
Defined in the toys-core gem
A Toys-based CLI.
This is the entry point for command line execution. It includes the set of tool definitions (and/or information on how to load them from the file system), configuration parameters such as logging and error handling, and a method to call to invoke a command.
This is the class to instantiate to create a Toys-based command line executable. For example:
#!/usr/bin/env ruby
require "toys-core"
cli = Toys::CLI.new
cli.add_config_block do
def run
puts "Hello, world!"
end
end
exit(cli.run(*ARGV))
The currently running CLI is also available at runtime, and can be used by tools that want to invoke other tools. For example:
# My .toys.rb
tool "foo" do
def run
puts "in foo"
end
end
tool "bar" do
def run
puts "in bar"
cli.run "foo"
end
end
Direct Known Subclasses
Defined Under Namespace
Classes: DefaultCompletion, DefaultErrorHandler
Instance Attribute Summary collapse
-
#base_level ⇒ Integer?
readonly
The initial logger level in this CLI, used as the level for verbosity 0.
-
#completion ⇒ Toys::Completion::Base, Proc
readonly
The overall completion strategy for this CLI.
-
#executable_name ⇒ String
readonly
The effective executable name used for usage text in this CLI.
-
#extra_delimiters ⇒ String
readonly
The string of tool name delimiter characters (besides space).
-
#loader ⇒ Toys::Loader
readonly
The current loader for this CLI.
-
#logger ⇒ Logger?
readonly
The global logger, if any.
-
#logger_factory ⇒ Proc
readonly
The logger factory.
Class Method Summary collapse
-
.default_logger_factory ⇒ Proc
Returns a logger factory that generates loggers that write to stderr.
-
.default_middleware_lookup ⇒ Toys::ModuleLookup
Returns a default ModuleLookup for middleware that points at the StandardMiddleware module.
-
.default_middleware_stack ⇒ Array<Toys::Middleware::Spec>
Returns a default set of middleware that may be used as a starting point for a typical CLI.
-
.default_mixin_lookup ⇒ Toys::ModuleLookup
Returns a default ModuleLookup for mixins that points at the StandardMixins module.
-
.default_template_lookup ⇒ Toys::ModuleLookup
Returns a default empty ModuleLookup for templates.
Instance Method Summary collapse
-
#add_config_block(high_priority: false, source_name: nil, context_directory: nil, &block) ⇒ self
Add a configuration block to the loader.
-
#add_config_path(path, high_priority: false, source_name: nil, context_directory: :parent) ⇒ self
Add a specific configuration file or directory to the loader.
-
#add_search_path(search_path, high_priority: false, context_directory: :path) ⇒ self
Checks the given directory path.
-
#add_search_path_hierarchy(start: nil, terminate: [], high_priority: false) ⇒ self
Walk up the directory hierarchy from the given start location, and add to the loader any config files and directories found.
-
#child(**opts) {|cli| ... } ⇒ Toys::CLI
Make a clone with the same settings but no no config blocks and no paths in the loader.
-
#initialize(executable_name: nil, middleware_stack: nil, extra_delimiters: "", config_dir_name: nil, config_file_name: nil, index_file_name: nil, preload_file_name: nil, preload_dir_name: nil, data_dir_name: nil, lib_dir_name: nil, mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil, logger_factory: nil, logger: nil, base_level: nil, error_handler: nil, completion: nil) ⇒ CLI
constructor
Create a CLI.
-
#load_tool(*args) {|context| ... } ⇒ Object
Prepare a tool to be run, but just execute the given block rather than performing a full run of the tool.
-
#run(*args, verbosity: 0, delegated_from: nil) ⇒ Integer
Run the CLI with the given command line arguments.
Constructor Details
#initialize(executable_name: nil, middleware_stack: nil, extra_delimiters: "", config_dir_name: nil, config_file_name: nil, index_file_name: nil, preload_file_name: nil, preload_dir_name: nil, data_dir_name: nil, lib_dir_name: nil, mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil, logger_factory: nil, logger: nil, base_level: nil, error_handler: nil, completion: nil) ⇒ CLI
Create a CLI.
Most configuration parameters (besides tool definitions and tool lookup paths) are set as options passed to the constructor. These options fall roughly into four categories:
- Options affecting output behavior:
-
logger
: A global logger for all tools to use -
logger_factory
: A proc that returns a logger to use -
base_level
: The default log level -
error_handler
: Callback for handling exceptions -
executable_name
: The name of the executable
-
- Options affecting tool specification
-
extra_delimibers
: Tool name delimiters besides space -
completion
: Tab completion handler
-
- Options affecting tool definition
-
middleware_stack
: The middleware applied to all tools -
mixin_lookup
: Where to find well-known mixins -
middleware_lookup
: Where to find well-known middleware -
template_lookup
: Where to find well-known templates
-
- Options affecting tool files and directories
-
config_dir_name
: Directory name containing tool files -
config_file_name
: File name for tools -
index_file_name
: Name of index files in tool directories -
preload_file_name
: Name of preload files in tool directories -
preload_dir_name
: Name of preload directories in tool directories -
data_dir_name
: Name of data directories in tool directories
-
174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 |
# File 'core-docs/toys/cli.rb', line 174 def initialize(executable_name: nil, # rubocop:disable Metrics/MethodLength middleware_stack: nil, extra_delimiters: "", config_dir_name: nil, config_file_name: nil, index_file_name: nil, preload_file_name: nil, preload_dir_name: nil, data_dir_name: nil, lib_dir_name: nil, mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil, logger_factory: nil, logger: nil, base_level: nil, error_handler: nil, completion: nil) # Source available in the toys-core gem end |
Instance Attribute Details
#base_level ⇒ Integer? (readonly)
The initial logger level in this CLI, used as the level for verbosity 0.
May be nil
, indicating it will use the initial logger setting.
246 247 248 |
# File 'core-docs/toys/cli.rb', line 246 def base_level @base_level end |
#completion ⇒ Toys::Completion::Base, Proc (readonly)
The overall completion strategy for this CLI.
252 253 254 |
# File 'core-docs/toys/cli.rb', line 252 def completion @completion end |
#executable_name ⇒ String (readonly)
The effective executable name used for usage text in this CLI.
221 222 223 |
# File 'core-docs/toys/cli.rb', line 221 def executable_name @executable_name end |
#extra_delimiters ⇒ String (readonly)
The string of tool name delimiter characters (besides space).
227 228 229 |
# File 'core-docs/toys/cli.rb', line 227 def extra_delimiters @extra_delimiters end |
#loader ⇒ Toys::Loader (readonly)
The current loader for this CLI.
215 216 217 |
# File 'core-docs/toys/cli.rb', line 215 def loader @loader end |
#logger ⇒ Logger? (readonly)
The global logger, if any.
233 234 235 |
# File 'core-docs/toys/cli.rb', line 233 def logger @logger end |
#logger_factory ⇒ Proc (readonly)
The logger factory.
239 240 241 |
# File 'core-docs/toys/cli.rb', line 239 def logger_factory @logger_factory end |
Class Method Details
.default_logger_factory ⇒ Proc
Returns a logger factory that generates loggers that write to stderr. All loggers generated by this factory share a single Utils::Terminal, so log entries may interleave but will not interrupt one another.
488 489 490 |
# File 'core-docs/toys/cli.rb', line 488 def default_logger_factory # Source available in the toys-core gem end |
.default_middleware_lookup ⇒ Toys::ModuleLookup
Returns a default ModuleLookup for middleware that points at the StandardMiddleware module.
467 468 469 |
# File 'core-docs/toys/cli.rb', line 467 def default_middleware_lookup # Source available in the toys-core gem end |
.default_middleware_stack ⇒ Array<Toys::Middleware::Spec>
Returns a default set of middleware that may be used as a starting point for a typical CLI. This set includes the following in order:
- StandardMiddleware::SetDefaultDescriptions providing defaults for description fields.
- StandardMiddleware::ShowHelp adding the
--help
flag and providing default behavior for namespaces. - StandardMiddleware::HandleUsageErrors
- StandardMiddleware::AddVerbosityFlags adding the
--verbose
and--quiet
flags for managing the logger level.
447 448 449 |
# File 'core-docs/toys/cli.rb', line 447 def default_middleware_stack # Source available in the toys-core gem end |
.default_mixin_lookup ⇒ Toys::ModuleLookup
Returns a default ModuleLookup for mixins that points at the StandardMixins module.
457 458 459 |
# File 'core-docs/toys/cli.rb', line 457 def default_mixin_lookup # Source available in the toys-core gem end |
.default_template_lookup ⇒ Toys::ModuleLookup
Returns a default empty ModuleLookup for templates.
476 477 478 |
# File 'core-docs/toys/cli.rb', line 476 def default_template_lookup # Source available in the toys-core gem end |
Instance Method Details
#add_config_block(high_priority: false, source_name: nil, context_directory: nil, &block) ⇒ self
Add a configuration block to the loader.
This is used to create tools "inline", and is useful for simple command line executables based on Toys.
300 301 302 303 304 305 |
# File 'core-docs/toys/cli.rb', line 300 def add_config_block(high_priority: false, source_name: nil, context_directory: nil, &block) # Source available in the toys-core gem end |
#add_config_path(path, high_priority: false, source_name: nil, context_directory: :parent) ⇒ self
Add a specific configuration file or directory to the loader.
This is generally used to load a static or "built-in" set of tools, either for a standalone command line executable based on Toys, or to provide a "default" set of tools for a dynamic executable. For example, the main Toys executable uses this to load the builtin tools from its "builtins" directory.
275 276 277 278 279 280 |
# File 'core-docs/toys/cli.rb', line 275 def add_config_path(path, high_priority: false, source_name: nil, context_directory: :parent) # Source available in the toys-core gem end |
#add_search_path(search_path, high_priority: false, context_directory: :path) ⇒ self
Checks the given directory path. If it contains a config file and/or config directory, those are added to the loader.
The main Toys executable uses this method to load tools from directories
in the TOYS_PATH
.
324 325 326 327 328 |
# File 'core-docs/toys/cli.rb', line 324 def add_search_path(search_path, high_priority: false, context_directory: :path) # Source available in the toys-core gem end |
#add_search_path_hierarchy(start: nil, terminate: [], high_priority: false) ⇒ self
Walk up the directory hierarchy from the given start location, and add to the loader any config files and directories found.
The main Toys executable uses this method to load tools from the current directory and its ancestors.
347 348 349 |
# File 'core-docs/toys/cli.rb', line 347 def add_search_path_hierarchy(start: nil, terminate: [], high_priority: false) # Source available in the toys-core gem end |
#child(**opts) {|cli| ... } ⇒ Toys::CLI
Make a clone with the same settings but no no config blocks and no paths in the loader. This is sometimes useful for calling another tool that has to be loaded from a different configuration.
207 208 209 |
# File 'core-docs/toys/cli.rb', line 207 def child(**opts) # Source available in the toys-core gem end |
#load_tool(*args) {|context| ... } ⇒ Object
Prepare a tool to be run, but just execute the given block rather than performing a full run of the tool. This is intended for testing tools. Unlike #run, this does not catch errors and perform error handling.
381 382 383 |
# File 'core-docs/toys/cli.rb', line 381 def load_tool(*args) # Source available in the toys-core gem end |
#run(*args, verbosity: 0, delegated_from: nil) ⇒ Integer
Run the CLI with the given command line arguments. Handles exceptions using the error handler.
365 366 367 |
# File 'core-docs/toys/cli.rb', line 365 def run(*args, verbosity: 0, delegated_from: nil) # Source available in the toys-core gem end |