Class: Toys::CLI

Inherits:
Object
  • Object
show all
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

StandardCLI

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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


175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'core-docs/toys/cli.rb', line 175

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.



247
248
249
 
# File 'core-docs/toys/cli.rb', line 247

def base_level
  @base_level
end

#completion ⇒ Toys::Completion::Base, Proc (readonly)

The overall completion strategy for this CLI.



253
254
255
 
# File 'core-docs/toys/cli.rb', line 253

def completion
  @completion
end

#executable_name ⇒ String (readonly)

The effective executable name used for usage text in this CLI.



222
223
224
 
# File 'core-docs/toys/cli.rb', line 222

def executable_name
  @executable_name
end

#extra_delimiters ⇒ String (readonly)

The string of tool name delimiter characters (besides space).



228
229
230
 
# File 'core-docs/toys/cli.rb', line 228

def extra_delimiters
  @extra_delimiters
end

#loader ⇒ Toys::Loader (readonly)

The current loader for this CLI.



216
217
218
 
# File 'core-docs/toys/cli.rb', line 216

def loader
  @loader
end

#logger ⇒ Logger? (readonly)

The global logger, if any.



234
235
236
 
# File 'core-docs/toys/cli.rb', line 234

def logger
  @logger
end

#logger_factory ⇒ Proc (readonly)

The logger factory.



240
241
242
 
# File 'core-docs/toys/cli.rb', line 240

def logger_factory
  @logger_factory
end

Class Method Details

.default_completion ⇒ Object

Returns a default Completion that simply uses the tool's completion.



461
462
463
 
# File 'core-docs/toys/cli.rb', line 461

def default_completion
  # Source available in the toys-core gem
end

.default_error_handler ⇒ Proc

Returns a bare-bones error handler that takes simply reraises the error. If the original error (the cause of the Toys::ContextualError) was a SignalException (or a subclass such as Interrupted), that SignalException itself is reraised so that the Ruby VM has a chance to handle it. Otherwise, for any other error, the Toys::ContextualError is reraised.



444
445
446
 
# File 'core-docs/toys/cli.rb', line 444

def default_error_handler
  # Source available in the toys-core gem
end

.default_logger_factory ⇒ Proc

Returns a default logger factory that generates simple loggers that write to STDERR.



454
455
456
 
# File 'core-docs/toys/cli.rb', line 454

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.



421
422
423
 
# File 'core-docs/toys/cli.rb', line 421

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:



401
402
403
 
# File 'core-docs/toys/cli.rb', line 401

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.



411
412
413
 
# File 'core-docs/toys/cli.rb', line 411

def default_mixin_lookup
  # Source available in the toys-core gem
end

.default_template_lookup ⇒ Toys::ModuleLookup

Returns a default empty ModuleLookup for templates.



430
431
432
 
# File 'core-docs/toys/cli.rb', line 430

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.



301
302
303
304
305
306
 
# File 'core-docs/toys/cli.rb', line 301

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.



276
277
278
279
280
281
 
# File 'core-docs/toys/cli.rb', line 276

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.



325
326
327
328
329
 
# File 'core-docs/toys/cli.rb', line 325

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.



348
349
350
 
# File 'core-docs/toys/cli.rb', line 348

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 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.

Yield Parameters:

  • cli (Toys::CLI) —

    If you pass a block, the new CLI is yielded to it so you can add paths and make other modifications.



208
209
210
 
# File 'core-docs/toys/cli.rb', line 208

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.

Yield Parameters:



382
383
384
 
# File 'core-docs/toys/cli.rb', line 382

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.



366
367
368
 
# File 'core-docs/toys/cli.rb', line 366

def run(*args, verbosity: 0, delegated_from: nil)
  # Source available in the toys-core gem
end