Module: Fuelcell

Defined in:
lib/fuelcell.rb,
lib/fuelcell/cli.rb,
lib/fuelcell/help.rb,
lib/fuelcell/shell.rb,
lib/fuelcell/version.rb,
lib/fuelcell/action/root.rb,
lib/fuelcell/help/builder.rb,
lib/fuelcell/action/command.rb,
lib/fuelcell/action/callable.rb,
lib/fuelcell/action/not_found.rb,
lib/fuelcell/action/arg_results.rb,
lib/fuelcell/action/opt_results.rb,
lib/fuelcell/action/subcommands.rb,
lib/fuelcell/parser/arg_handler.rb,
lib/fuelcell/parser/opt_handler.rb,
lib/fuelcell/action/args_manager.rb,
lib/fuelcell/action/opts_manager.rb,
lib/fuelcell/help/base_formatter.rb,
lib/fuelcell/help/cmds_formatter.rb,
lib/fuelcell/help/desc_formatter.rb,
lib/fuelcell/help/opts_formatter.rb,
lib/fuelcell/parser/base_handler.rb,
lib/fuelcell/help/usage_formatter.rb,
lib/fuelcell/action/arg_definition.rb,
lib/fuelcell/action/opt_definition.rb,
lib/fuelcell/parser/ignore_handler.rb,
lib/fuelcell/parser/opt_name_handler.rb,
lib/fuelcell/parser/parsing_strategy.rb,
lib/fuelcell/parser/cmd_args_strategy.rb,
lib/fuelcell/parser/opt_value_equal_handler.rb,
lib/fuelcell/parser/short_opt_no_space_handler.rb

Overview

Exposes Fuelcell’s main interface. You can describe a complete command heirarchy, and start the processing/execution of a command all at the same time using Fuelcell.start. Fuelcell.define allows you to describe a command heirarchy using separate files. The cli interfaces are needed when :start & :define are used togather, allowing :define to access the root command

Defined Under Namespace

Modules: Action, Help, Parser Classes: Cli, Shell

Constant Summary collapse

VERSION = 
"0.2.4"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.cli ⇒ Object

Assigning the cli represents the current execution context for which commandline processing takes place. This is triggered by the :start method and is needed to allow the :define method to work in a separate file the was required by the script using :start

The alias :make_cli_available_for_definitions is ment to describe the intent of the :start method



20
21
22
 
# File 'lib/fuelcell.rb', line 20

def cli
  @cli
end

Class Method Details

.cli? ⇒ Boolean

Returns:

  • (Boolean) 


23
24
25
 
# File 'lib/fuelcell.rb', line 23

def cli?
  ! @cli.nil?
end

.create_cli(settings = {}) ⇒ Fuelcell::Cli

Allows for the configuration of the Cli object which controls command line processing.

Parameters:

  • settings (Hash) (defaults to: {}) —

    root_name: used to override the default script name root_cmd: override the RootCommand object with your own shell: override the Shell object with your own backtrace: causes backtraces to be printed to error stream output_stream: override $stdout as the output stream input_stream: override $stdin as the input stream error_stream: override $stderr as the error stream exit: cause fuelcell not to explicitly exit, use false parser: override opt & args parsing cmd_args_extractor: override command extraction strategy

Returns:



84
85
86
87
88
89
 
# File 'lib/fuelcell.rb', line 84

def create_cli(settings = {})
  root_name = settings[:root_name]
  root_cmd  = settings.fetch(:root_cmd) { Action::Root.new(root_name) }
  shell     = settings.fetch(:shell) { Shell.new(settings) }
  Cli.new(root: root_cmd, shell: shell)
end

.define(name) { ... } ⇒ Object

Allows definitions to be created in a separate file and have them included by load/require in the start block.

Parameters:

  • name (String) —

    name of the command to be defined

Yields:

  • instance_eval into the root command



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/fuelcell.rb', line 50

def define(name, &block)
  name = name.to_s
  if name.empty?
    fail ArgumentError, 'command name can not be empty'
  end

  unless cli?
    fail RuntimeError, 'cli interface does not exist, please use ' \
                       'Fuelcell.start before Fuelcell.define'
  end

  root = cli.root
  cmd_args = name.split(' ')
  root.ensure_command_hierarchy(cmd_args)
  cmd = root[name]
  cmd.instance_eval(&block)
end

.remove_cli ⇒ Nil Also known as: remove_cli_availability

Remove the cli object & replace it with nil. The general case for this is in the :start method when no more command definition will be processed. Since we don’t know for sure how long we will be in memory we clean up whats not used

The alias :remove_cli_availability is an attempt to improve intent of the :start method

Returns:

  • (Nil) 


40
41
42
 
# File 'lib/fuelcell.rb', line 40

def remove_cli
  @cli = nil
end

.start(args = [], settings = {}) { ... } ⇒ Int

Entry point for executing a command which was defined through the the fuelcell dsl. The executable command should return an exit code, used to exit the program.

Parameters:

  • args (Array) (defaults to: []) —

    command line args to be processed

  • settings (Hash) (defaults to: {}) —

    allows for overriding parts of fuelcell

Yields:

  • optional block, will instance_eval on the root command

Returns:

  • (Int) 


99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/fuelcell.rb', line 99

def start(args = [], settings = {}, &block)
  cli  = settings[:cli] || create_cli(settings)
  root = cli.root

  make_cli_available_for_definitions(cli)

  # expose the command dsl
  root.instance_eval(&block) if block_given?
  context = cli.parse(args)

  remove_cli_availability
  code = cli.execute(context)
  cli.handle_exit code
end