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

Methods included from Arguments

#help_arguments, #main

Methods included from Arguments::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.



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
232
233
234
235
236
237
238
239
 
# File 'lib/command_kit/commands.rb', line 207

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] = if env.eql?(ENV) then env.to_h
                   else                  env.dup
                   end
  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.



271
272
273
274
 
# File 'lib/command_kit/commands.rb', line 271

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.



344
345
346
347
348
 
# File 'lib/command_kit/commands.rb', line 344

def help
  super

  help_commands
end

#help_commands ⇒ Object

Prints the available commands and their summaries.



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/command_kit/commands.rb', line 316

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

    command_aliases = Hash.new { |hash,key| hash[key] = [] }

    self.class.command_aliases.each do |alias_name,name|
      command_aliases[name] << alias_name
    end

    self.class.commands.sort.each do |name,subcommand|
      names = [name, *command_aliases[name]].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.



188
189
190
191
192
193
194
 
# File 'lib/command_kit/commands.rb', line 188

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.



255
256
257
258
259
260
261
 
# File 'lib/command_kit/commands.rb', line 255

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:



291
292
293
 
# File 'lib/command_kit/commands.rb', line 291

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.



302
303
304
305
306
307
308
309
 
# File 'lib/command_kit/commands.rb', line 302

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