module CommandKit::Commands

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

Public Class Methods

new(**kwargs) click to toggle source

Initializes the command.

@note Adds a special rule to the {Options#option_parser option_parser} to stop parsing options when the first non-option is encountered.

@api public

Calls superclass method CommandKit::Env::new
# File lib/command_kit/commands.rb, line 182
def initialize(**kwargs)
  super(**kwargs)

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

Public Instance Methods

command(name) click to toggle source

Looks up the given command name and initializes a subcommand.

@param [#to_s] name

The given command name.

@return [Object#main, nil]

The initialized subcommand.

@api private

# 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) click to toggle source

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

@param [String] name

The command name.

@api semipublic

# 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() click to toggle source

Prints help information and available commands.

@api public

Calls superclass method CommandKit::Usage#help
# File lib/command_kit/commands.rb, line 329
def help
  super

  help_commands
end
help_commands() click to toggle source

Prints the available commands and their summaries.

@api semipublic

# 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
invoke(name,*argv) click to toggle source

Invokes the command with the given argv.

@param [String] name

The name of the command to invoke.

@param [Array<String>] argv

The additional arguments to pass to the command.

@return [Integer]

The exit status of the command.

@api semipublic

# 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=[]) click to toggle source

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

@param [String] name

The given sub-command name.

@param [Array<String>] argv

Additional argv.

@abstract

@see command_not_found

@api semipublic

# File lib/command_kit/commands.rb, line 283
def on_unknown_command(name,argv=[])
  command_not_found(name)
end
run(command=nil,*argv) click to toggle source

Runs the command or specified subcommand.

@note If no subcommand is given, {#help} will be called.

@api public

# File lib/command_kit/commands.rb, line 294
def run(command=nil,*argv)
  if command
    exit invoke(command,*argv)
  else
    help
  end
end