Module: CommandKit::Commands

Extended by:
ModuleMethods
Includes:
CommandName, Env, Options, Stdio, Usage
Defined in:
lib/command_kit/commands.rb,
lib/command_kit/commands/help.rb,
lib/command_kit/commands/command.rb,
lib/command_kit/commands/auto_load.rb,
lib/command_kit/commands/subcommand.rb,
lib/command_kit/commands/auto_require.rb,
lib/command_kit/commands/parent_command.rb,
lib/command_kit/commands/auto_load/subcommand.rb

Overview

Adds sub-commands to a command.

Examples

class CLI

  include CommandKit::Commands

  command_name :foo

  class Foo < CommandKit::Command
    # ...
  end

  class FooBar < CommandKit::Command
    # ...
  end

  command Foo
  command 'foo-bar', FooBar

end

Defined Under Namespace

Modules: ClassMethods, ModuleMethods, ParentCommand Classes: AutoLoad, AutoRequire, Command, Help, Subcommand

Constant Summary

Constants included from Printing

Printing::EOL

Instance Attribute Summary

Attributes included from Env

#env

Attributes included from Options

#options

Attributes included from Options::Parser

#option_parser

Attributes included from CommandName

#command_name

Instance Method Summary collapse

Methods included from ModuleMethods

included

Methods included from Stdio

#abort, #gets, #print, #printf, #putc, #puts, #readline, #readlines, #stderr, #stdin, #stdout

Methods included from Options::ModuleMethods

#included

Methods included from Options::Parser

#help_options, #main, #on_ambiguous_argument, #on_ambiguous_option, #on_invalid_argument, #on_invalid_option, #on_missing_argument, #on_needless_argument, #on_parse_error, #parse_options

Methods included from Options::Parser::ModuleMethods

#included

Methods included from Printing

#print_error, #print_exception

Methods included from Main

#main

Methods included from Main::ModuleMethods

#included

Methods included from Usage

#help_usage, #usage

Methods included from Usage::ModuleMethods

#included

Methods included from Help::ModuleMethods

#included

Methods included from CommandKit::CommandName::ModuleMethods

#included

Instance Method Details

#command(name) ⇒ Object#main?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Looks up the given command name and initializes a subcommand.

Parameters:

  • name (#to_s) —

    The given command name.

Returns:

  • (Object#main, nil) —

    The initialized subcommand.



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
231
 
# File 'lib/command_kit/commands.rb', line 201

def command(name)
  unless (command_class = self.class.get_command(name))
    return
  end

  kwargs = {}

  if command_class.include?(ParentCommand)
    kwargs[:parent_command] = self
  end

  if command_class.include?(CommandName)
    kwargs[:command_name] = "#{command_name} #{command_class.command_name}"
  end

  if command_class.include?(Stdio)
    kwargs[:stdin]  = stdin
    kwargs[:stdout] = stdout
    kwargs[:stderr] = stderr
  end

  if command_class.include?(Env)
    kwargs[:env] = env.dup
  end

  if command_class.include?(Options)
    kwargs[:options] = options.dup
  end

  return command_class.new(**kwargs)
end

#command_not_found(name) ⇒ Object

Prints an error about an unknown command and exits with an error code.

Parameters:

  • name (String) —

    The command name.



263
264
265
266
 
# File 'lib/command_kit/commands.rb', line 263

def command_not_found(name)
  print_error "'#{name}' is not a #{command_name} command. See `#{command_name} help`"
  exit(1)
end

#help ⇒ Object

Prints help information and available commands.



329
330
331
332
333
 
# File 'lib/command_kit/commands.rb', line 329

def help
  super

  help_commands
end

#help_commands ⇒ Object

Prints the available commands and their summaries.



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/command_kit/commands.rb', line 307

def help_commands
  unless self.class.commands.empty?
    puts
    puts "Commands:"

    self.class.commands.sort.each do |name,subcommand|
      names = [name, *subcommand.aliases].join(', ')

      if subcommand.summary
        puts "    #{names}\t#{subcommand.summary}"
      else
        puts "    #{names}"
      end
    end
  end
end

#initialize(**kwargs) ⇒ Object

Note:

Adds a special rule to the #option_parser to

Initializes the command.

stop parsing options when the first non-option is encountered.



182
183
184
185
186
187
188
 
# File 'lib/command_kit/commands.rb', line 182

def initialize(**kwargs)
  super(**kwargs)

  @option_parser.on(/^[^-].*$/) do |command|
    OptionParser.terminate(command)
  end
end

#invoke(name, *argv) ⇒ Integer

Invokes the command with the given argv.

Parameters:

  • name (String) —

    The name of the command to invoke.

  • argv (Array<String>) —

    The additional arguments to pass to the command.

Returns:

  • (Integer) —

    The exit status of the command.



247
248
249
250
251
252
253
 
# File 'lib/command_kit/commands.rb', line 247

def invoke(name,*argv)
  if (command = command(name))
    command.main(argv)
  else
    on_unknown_command(name,argv)
  end
end

#on_unknown_command(name, argv = []) ⇒ Object

This method is abstract.

Place-holder method that is called when the subcommand is not known.

Parameters:

  • name (String) —

    The given sub-command name.

  • argv (Array<String>) (defaults to: []) —

    Additional argv.

See Also:



283
284
285
 
# File 'lib/command_kit/commands.rb', line 283

def on_unknown_command(name,argv=[])
  command_not_found(name)
end

#run(command = nil, *argv) ⇒ Object

Note:

If no subcommand is given, #help will be called.

Runs the command or specified subcommand.



294
295
296
297
298
299
300
 
# File 'lib/command_kit/commands.rb', line 294

def run(command=nil,*argv)
  if command
    exit invoke(command,*argv)
  else
    help
  end
end