Class: Toys::CLI
- Inherits:
-
Object
- Object
- Toys::CLI
- Defined in:
- toys-core/lib/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.
-
#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
-
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 |
# File 'toys-core/lib/toys/cli.rb', line 180 def initialize( # rubocop:disable Metrics/MethodLength 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 ) @executable_name = executable_name || ::File.basename($PROGRAM_NAME) @middleware_stack = middleware_stack || CLI.default_middleware_stack @mixin_lookup = mixin_lookup || CLI.default_mixin_lookup @middleware_lookup = middleware_lookup || CLI.default_middleware_lookup @template_lookup = template_lookup || CLI.default_template_lookup @error_handler = error_handler || DefaultErrorHandler.new @completion = completion || DefaultCompletion.new @logger = logger @logger_factory = logger ? proc { logger } : logger_factory || CLI.default_logger_factory @base_level = base_level @extra_delimiters = extra_delimiters @config_dir_name = config_dir_name @config_file_name = config_file_name @index_file_name = index_file_name @preload_file_name = preload_file_name @preload_dir_name = preload_dir_name @data_dir_name = data_dir_name @lib_dir_name = lib_dir_name @loader = Loader.new( index_file_name: @index_file_name, preload_dir_name: @preload_dir_name, preload_file_name: @preload_file_name, data_dir_name: @data_dir_name, lib_dir_name: @lib_dir_name, middleware_stack: @middleware_stack, extra_delimiters: @extra_delimiters, mixin_lookup: @mixin_lookup, template_lookup: @template_lookup, middleware_lookup: @middleware_lookup ) 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.
305 306 307 |
# File 'toys-core/lib/toys/cli.rb', line 305 def base_level @base_level end |
#completion ⇒ Toys::Completion::Base, Proc (readonly)
The overall completion strategy for this CLI.
311 312 313 |
# File 'toys-core/lib/toys/cli.rb', line 311 def completion @completion end |
#executable_name ⇒ String (readonly)
The effective executable name used for usage text in this CLI.
280 281 282 |
# File 'toys-core/lib/toys/cli.rb', line 280 def executable_name @executable_name end |
#extra_delimiters ⇒ String (readonly)
The string of tool name delimiter characters (besides space).
286 287 288 |
# File 'toys-core/lib/toys/cli.rb', line 286 def extra_delimiters @extra_delimiters end |
#loader ⇒ Toys::Loader (readonly)
The current loader for this CLI.
274 275 276 |
# File 'toys-core/lib/toys/cli.rb', line 274 def loader @loader end |
#logger ⇒ Logger? (readonly)
The global logger, if any.
292 293 294 |
# File 'toys-core/lib/toys/cli.rb', line 292 def logger @logger end |
#logger_factory ⇒ Proc (readonly)
The logger factory.
298 299 300 |
# File 'toys-core/lib/toys/cli.rb', line 298 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.
721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 |
# File 'toys-core/lib/toys/cli.rb', line 721 def default_logger_factory require "toys/utils/terminal" shared_terminal = Utils::Terminal.new(output: $stderr) proc do logger = ::Logger.new(shared_terminal) logger.formatter = proc do |severity, time, _progname, msg| msg_str = case msg when ::String msg when ::Exception "#{msg.} (#{msg.class})\n" << (msg.backtrace || []).join("\n") else msg.inspect end format_log(shared_terminal, time, severity, msg_str) end logger.level = ::Logger::WARN logger end end |
.default_middleware_lookup ⇒ Toys::ModuleLookup
Returns a default ModuleLookup for middleware that points at the StandardMiddleware module.
700 701 702 |
# File 'toys-core/lib/toys/cli.rb', line 700 def default_middleware_lookup ModuleLookup.new.add_path("toys/standard_middleware") 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.
675 676 677 678 679 680 681 682 |
# File 'toys-core/lib/toys/cli.rb', line 675 def default_middleware_stack [ Middleware.spec(:set_default_descriptions), Middleware.spec(:show_help, help_flags: true, fallback_execution: true), Middleware.spec(:handle_usage_errors), Middleware.spec(:add_verbosity_flags), ] end |
.default_mixin_lookup ⇒ Toys::ModuleLookup
Returns a default ModuleLookup for mixins that points at the StandardMixins module.
690 691 692 |
# File 'toys-core/lib/toys/cli.rb', line 690 def default_mixin_lookup ModuleLookup.new.add_path("toys/standard_mixins") end |
.default_template_lookup ⇒ Toys::ModuleLookup
Returns a default empty ModuleLookup for templates.
709 710 711 |
# File 'toys-core/lib/toys/cli.rb', line 709 def default_template_lookup ModuleLookup.new 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.
363 364 365 366 367 368 369 370 371 372 |
# File 'toys-core/lib/toys/cli.rb', line 363 def add_config_block(high_priority: false, source_name: nil, context_directory: nil, &block) @loader.add_block(high_priority: high_priority, source_name: source_name, context_directory: context_directory, &block) self 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.
334 335 336 337 338 339 340 341 342 343 |
# File 'toys-core/lib/toys/cli.rb', line 334 def add_config_path(path, high_priority: false, source_name: nil, context_directory: :parent) @loader.add_path(path, high_priority: high_priority, source_name: source_name, context_directory: context_directory) self 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
.
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 |
# File 'toys-core/lib/toys/cli.rb', line 391 def add_search_path(search_path, high_priority: false, context_directory: :path) paths = [] if @config_file_name file_path = ::File.join(search_path, @config_file_name) paths << @config_file_name if !::File.directory?(file_path) && ::File.readable?(file_path) end if @config_dir_name dir_path = ::File.join(search_path, @config_dir_name) paths << @config_dir_name if ::File.directory?(dir_path) && ::File.readable?(dir_path) end @loader.add_path_set(search_path, paths, high_priority: high_priority, context_directory: context_directory) self 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.
426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 |
# File 'toys-core/lib/toys/cli.rb', line 426 def add_search_path_hierarchy(start: nil, terminate: [], high_priority: false) path = start || ::Dir.pwd paths = [] loop do break if terminate.include?(path) paths << path next_path = ::File.dirname(path) break if next_path == path path = next_path end paths.reverse! if high_priority paths.each do |p| add_search_path(p, high_priority: high_priority) end self 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.
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 |
# File 'toys-core/lib/toys/cli.rb', line 244 def child(**opts) args = { executable_name: @executable_name, config_dir_name: @config_dir_name, config_file_name: @config_file_name, index_file_name: @index_file_name, preload_dir_name: @preload_dir_name, preload_file_name: @preload_file_name, data_dir_name: @data_dir_name, lib_dir_name: @lib_dir_name, middleware_stack: @middleware_stack, extra_delimiters: @extra_delimiters, mixin_lookup: @mixin_lookup, middleware_lookup: @middleware_lookup, template_lookup: @template_lookup, logger: @logger, logger_factory: @logger_factory, base_level: @base_level, error_handler: @error_handler, completion: @completion, }.merge(opts) cli = CLI.new(**args) yield cli if block_given? cli end |
#run(*args, verbosity: 0, delegated_from: nil) ⇒ Integer
Run the CLI with the given command line arguments. Handles exceptions using the error handler.
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 |
# File 'toys-core/lib/toys/cli.rb', line 454 def run(*args, verbosity: 0, delegated_from: nil) tool, remaining = ContextualError.capture("Error finding tool definition") do @loader.lookup(args.flatten) end ContextualError.capture_path( "Error during tool execution!", tool.source_info&.source_path, tool_name: tool.full_name, tool_args: remaining ) do default_data = { Context::Key::VERBOSITY => verbosity, Context::Key::DELEGATED_FROM => delegated_from, } run_tool(tool, remaining, default_data) end rescue ContextualError, ::Interrupt => e @error_handler.call(e).to_i end |