class SubOptParser

An adaptation of Ruby’s default OptionParser to support sub-commands.

rubocop:disable Metrics/ClassLength

Attributes

When non-nil the cmdpath of this command and a sub-command will be used to automatically ‘require` the Ruby file to register the command.

cmdparent [RW]

The parent command, or nil? if this is the root command.

cmdpath [RW]

The path of parent commands to this command. This is automatically set by cmdadd().

description [RW]

The description of this command.

shared_state [RW]

Arbitrary user data that is shared with all child objects. If the user does not change this, all child commands get the same state assigned when created with cmdadd().

NOTE: This must be set before calling cmdadd().

This may be any object, but the SubOptParse::ShareState class is a useful helper.

Public Class Methods

new (banner = nil, width = 32, indent = " " * 4, **args) { |self| ... }

Source

# File lib/suboptparse.rb, line 58
def initialize(banner = nil, width = 32, indent = " " * 4, **args) # :yields: self
  autorequire_init
  @op = OptionParser.new(banner, width, indent)
  self.raise_unknown = false
  @banner = @op.banner
  @pre_parse_blk = nil
  @post_parse_blk = nil
  @cmdpath = [File.basename($PROGRAM_NAME)]

  # This command's body.
  @cmd = proc { raise StandardError, "No command defined." }

  # Sub-command which are SubOptParser objects.
  @cmds = {}

  @cmdparent = args.delete(:parent)

  yield(self) if block_given?
end

Initialize a new SubOptParser.

If block is given, this object is passed to allow for further initialization.

banner: Passed to OptionParser.new.
width: Passed to OptionParser.new.
indent: Passed to OptionParser.new.
:parent => parent: Defines the parent command to this one.

rubocop:disable Metrics/MethodLength

Public Instance Methods

[] (name)

Source

# File lib/suboptparse.rb, line 109
def [](name)
  @cmds[name]
end

Users may override how to lookup a command or return “nil” if none is found.

[]= (name, subcmd)

Source

# File lib/suboptparse.rb, line 103
def []=(name, subcmd)
  @cmds[name] = subcmd
  @op.banner = @banner + cmdhelp
end

Add a sub command as the given name. No automatic initializtion is done. Prefer using cmdadd().

parser["sub_parser"] = SubOptParser.new do { |sub| ... }

addcmd (name, description = nil, *args)

Alias for: cmdadd

after_parse (&blk)

Source

# File lib/suboptparse.rb, line 133
def after_parse(&blk)
  @post_parse_blk = blk
end

Similar to on_parse but happens after parsing.

Also aliased as: post_parse

call (*argv, into: nil)

Source

# File lib/suboptparse.rb, line 195
def call(*argv, into: nil)
  cmd, rest = _parse!(argv, into: into)

  # Explode if we have arguments left but should not.
  raise StandardError, "Unconsumed arguments: #{argv.join(",")}" if raise_unknown && !rest.empty?

  cmd.call(rest)
end

Parse the arguments in *argv and execute call() on the returned command. Any unparsed values are passed to the invocation of call().

This is equivalent to

cmd = parser.parse!(args)
cmd.call(args)

cmd (prc = nil) { |unconsumed_arguments| ... }

Source

# File lib/suboptparse.rb, line 153
def cmd(prc = nil, &blk) # :yields: unconsumed_arguments
  @cmd = prc unless prc.nil?
  @cmd = blk unless blk.nil?
end

cmdadd (name, description = nil, *args) { |self| ... }

Source

# File lib/suboptparse.rb, line 141
def cmdadd(name, description = nil, *args) # :yields: self
  o = _create_sub_command(name, description, *args)

  # Add default "help" sub-job (unless we are the help job).
  _add_default_help_cmd(o) if name != "help"

  @cmds[name] = o
  yield(o) if block_given?
  @op.banner = @banner + cmdhelp
  o
end

Add a command (and return the resulting command).

Also aliased as: addcmd

cmdhelp ()

Source

# File lib/suboptparse.rb, line 168
def cmdhelp
  cmds = _build_cmd_doc_map
  cmds = _build_cmddocs_doc_map(cmds)
  h = _build_help_body(cmds)

  # Append extra line.
  "#{h}\n"
end

get_subcommand (name)

Source

# File lib/suboptparse.rb, line 206
def get_subcommand(name)
  if (cmd = self[name])
    cmd
  elsif autorequire_root && (cmd = autorequire(name))
    cmd
  end
end

How sub-commands are loaded. If no sub-command can be loaded for the name, nil is returned.

help ()

Source

# File lib/suboptparse.rb, line 160
def help
  if @cmdparent.nil?
    @op.help
  else
    "#{@cmdparent.help}\n#{@op.help}"
  end
end

Put the parent help text at the start of this command’s help. This allows for building recursive help.

method_missing (name, *args, &block)

Source

# File lib/suboptparse.rb, line 81
def method_missing(name, *args, &block)
  @op.__send__(name, *args, &block)
end

rubocop:enable Metrics/MethodLength

on_parse () { |sub_opt_parser, arguments| ... }

Source

# File lib/suboptparse.rb, line 128
def on_parse(&blk) # :yields: sub_opt_parser, arguments
  @pre_parse_blk = blk
end

A callable that is invoked when this SubOptParser starts parsing arguments. This is primarily here to allow for lazy-populating of commands instead of requiring them to be defined at program invokation or to allow filtering or manipulating the command line arguments before parsing.

The proc takes 2 arguments, this SubOptParse object and the current command line options array. Whatever is returned by this call is assigned to the command line options array value and is parsed. Eg:

parser = SubOptParser.new
parser.on_parse { |p,args| p["subcmd"] = SubOptParser.new ; args}

Be careful to not create infinite recursion by adding commands that call themselves and then add themselves.

Also aliased as: pre_parse

parse (*argv, into: nil)

Source

# File lib/suboptparse.rb, line 184
def parse(*argv, into: nil)
  _parse!(argv, into: into)
end

Calls parse!.

parse! (argv, into: nil)

Source

# File lib/suboptparse.rb, line 179
def parse!(argv, into: nil)
  _parse!(argv, into: into)
end

post_parse (&blk)

Alias for: after_parse

pre_parse ()

Alias for: on_parse

raise_unknown ()

Source

# File lib/suboptparse.rb, line 90
def raise_unknown
  @op.raise_unknown
end

If true, an exception will be thrown when an unknown argument is given.

raise_unknown= (value)

Source

# File lib/suboptparse.rb, line 95
def raise_unknown=(value)
  @op.raise_unknown = value
end

If true, an exception will be thrown when an unknown argument is given.

respond_to_missing? (_name, _include_private = false)

Source

# File lib/suboptparse.rb, line 85
def respond_to_missing?(_name, _include_private = false)
  true
end