module SubOptParser::AutoRequire

Methods and logic to support auto-requiring commands that are not found in a sub-command.

This is done by loading files named after the command, as shown in the example. When the ‘.rb` file is loaded, the values # AutoRequire.auto_require_command_parent and

AutoRequire.auto_require_command_name are set to the current parent command and the name

of the command trying to be loaded.

so = SubOptParser.new do |opt|
  opt.autorequire_root = "my_proj/my_commands"
  opt.autorequire_suffix = "_command"
end

# This will require...
# require "my_proj/my_commands/a_command"
# require "my_proj/my_commands/a/b_command"
# require "my_proj/my_commands/a/b/c_command"
so.call("a", "b", "c")

The contents of ‘c_command.rb` might look like this…

require "suboptparse/auto_require"

SubOptParser::AutoRequire.register do |so, name|
  so.addcmd(name, "A command.") do |so|
    so.cmd do
      so.shared_state["x"] = 3
    end
  end
end

Attributes

autorequire_root [RW]

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.

autorequire_suffix [RW]

Appended to the command name to load by a call to ‘require “path/to/cmd_command”`

Public Class Methods

auto_require_command_description ()

Source

# File lib/suboptparse/auto_require.rb, line 49
def auto_require_command_description
  @@auto_require_command_description
end

auto_require_command_name ()

Source

# File lib/suboptparse/auto_require.rb, line 45
def auto_require_command_name
  @@auto_require_command_name
end

auto_require_command_parent ()

Source

# File lib/suboptparse/auto_require.rb, line 41
def auto_require_command_parent
  @@auto_require_command_parent
end

Source

# File lib/suboptparse/auto_require.rb, line 58
def register(&blk) # :yields: sub_command
  @@auto_require_command_parent.cmdadd(@@auto_require_command_name, @@auto_require_command_description, &blk)
end

This registers a command with a description with the current values of @@auto_require_command_name and @@auto_require_command_description and passes the resulting SubOptParser object to the given block.

The calling module should them setup the particulars of the newly registered command.

Public Instance Methods

autorequire (name)

Source

# File lib/suboptparse/auto_require.rb, line 74
def autorequire(name)
  path = generate_require_path(name)

  do_in_autorequire(name) do
    require path
    self[name]
  rescue LoadError => e
    generate_default_command(name, e)
  end
end

Auto-require the command.

The root app name is ignored as it can change by program invocation.

cmddocadd (name, description, req = nil)

Source

# File lib/suboptparse/auto_require.rb, line 107
def cmddocadd(name, description, req = nil)
  @cmddocs[name] = { "name" => name, "description" => description, "require" => req }
  @op.banner = @banner + cmdhelp
end

Add the name and description of a command to be documented in help text. This is for use with autoloaded commands which may not fully document themselves unless called.

name: Name of the command.
description: The description of the command.
req: String you can pass to “require” to load the command.

generate_require_path (name)

Source

# File lib/suboptparse/auto_require.rb, line 90
def generate_require_path(name)
  if @cmddocs.member?(name) && @cmddocs[name]["require"]
    "#{@autorequire_root}/#{@cmddocs[name]["require"]}"
  else
    # Don't consider the root app name.
    cmdpath = @cmdpath[1..] || []

    [@autorequire_root, *cmdpath, "#{name}#{autorequire_suffix}"].join("/")
  end
end

Build a path for the given command name to pass to require.

p = generate_require_path(foo)
require p

Protected Instance Methods

autorequire_init ()

Source

# File lib/suboptparse/auto_require.rb, line 149
def autorequire_init
  @autorequire_root = nil
  @autorequire_suffix = "_command"

  # Documentation for unloaded commands.
  @cmddocs = {}
end