suboptparse 0.1.24

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24db536b0fc85771658568b756c7989ee2c8d3ff8e09bca9d5276e3a03c38967
+  data.tar.gz: e4350502b4931b3a8b353adfda993fdfb56c18c85889b924d9d8e6ef7d443d8f
+SHA512:
+  metadata.gz: a79c1a8d07d00ad44cfae635e26c65709b0676be125e5437ce1c1d1a31c949d9cf882a439644d6d1005274b5fc41231935eee8772745268e7490aa5c09eb4056
+  data.tar.gz: 9ce6eec459229b9f3d56f42790523c55d66021769187dbca616ae62315ddc75019571a765940ca334c68f270c7e46fd13ef257628c7c8e88a30438328838e48f

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Lint/ShadowingOuterLocalVariable:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,86 @@
+## [0.1.24]
+
+- RDoc updates.
+- GitHub build updates.
+
+## [0.1.14]
+
+- Support post_parse and after_parse.
+- Alias on_parse to pre_parse.
+
+## [0.1.13] - 2025-02-04
+
+- Throw the LoadError what prevents an command from being auto-required
+  if that command is ever executed.
+
+## [0.1.12] - 2025-02-03
+
+- Adjust SubOptParse::AutoRequire.require to automatically add the sub-command
+  and pass the created SubOptParse object to the callback for further 
+  configuration.
+- Improve help output to remove duplicate commands and sort the commands by
+  command name. Duplicates could appear when a command was registered by
+  cmdadd() and cmddocsadd().
+
+## [0.1.11] - 2025-02-03
+
+- Extend cmddocadd() to also support dynamic autloading of commands
+  defined in this way. This allows cmd documentation to exist when
+  autoloading is defined.
+
+## [0.1.10] - 2025-02-03
+
+- Add recurisve help. Help is printed from the root command down to the 
+  last called child command.
+
+## [0.1.9] - 2025-02-02
+
+- Add sub-command documentation when there is no loaded command.
+- Allow auto-loading of files if an autorequire_root path is defined.
+- Migrate cmdpath to a list of command names rather than a single string.
+
+## [0.1.8] - 2025-01-31
+
+- Update changelog and readme to match new release process.
+
+## [0.1.7] - 2025-01-31
+
+- *No Change* - Configuring GitHub actions to release code.
+
+## [0.1.6] - 2025-01-31
+
+- *No Change* - Configuring GitHub actions to release code.
+
+## [0.1.5] - 2025-01-30
+
+- Update project meta data.
+- Update project rdoc documentation.
+- Add RDoc::Task to Rakefile. Output to ./rdoc.
+
+## [0.1.4] - 2025-01-30
+
+- Set @cmdpath in the command ussage. This is the path in the command tree
+  that leads to the executing command.
+- Add SubOptParse::Util.merge_recursive() to assist in merging
+  configurations loaded into Ruby Hash objects.
+- Add SubOptParse::SharedState to help use shared_state correctly
+  in instances of SubOptParsers.
+
+## [0.1.3] - 2025-01-28
+
+- Set banner correctly on sub-commands.
+
+## [0.1.2] - 2025-01-28
+
+- Update usage on sub-commands.
+- Allow an optional description to be included when calling .cmdadd().
+
+## [0.1.1] - 2025-01-28
+
+- Add default "help" sub-command to all commands.
+- Allow for custom command lookups by overriding SubOptParser#[].
+- Allow for adding commands are parse time with .on_parse { |so| ... }
+
+## [0.1.0] - 2025-01-21
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Sam Baskinger <basking2@yahoo.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+# SubOptParse
+
+[![Gem Version](https://badge.fury.io/rb/suboptparse.svg)](https://badge.fury.io/rb/suboptparse)
+[![Known Vulnerabilities](https://snyk.io/test/github/basking2/suboptparse/badge.svg)](https://snyk.io/test/github/basking2/suboptparse)
+
+
+[SubOptParse](https://basking2.github.io/suboptparse) is a collection of classes and utilities to extend Ruby's 
+[OptionParser](https://ruby-doc.org/current/optparse/tutorial_rdoc.html) with some understanding of sub-commands.
+
+Sub-commands maybe thought of as a traditional CLI command but with 
+a single parent command as the entry poiont. As an example, consider
+a CLI application that buys things from a store. We'll call the command
+`./buy`. You can have a sub-command `./buy apples --count=3` that
+knows how to buy apples. Now, purchasing from the deli is different
+and so we isolate that into a different sub-command, `deli`.
+You could run `./buy deli potato_salad`.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add suboptparse
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install suboptparse
+
+## Usage
+
+### Looks Like OptionParser
+
+```ruby
+require "suboptparse"
+
+# Looks like OptionParser.
+parser = SubOptParser.new do |sop|
+  # Normal OptionParser calls.
+  sop.on("--my-option=foo", "-m", "Sets a value") do |v|
+    # Record value somewhere.
+  end
+end
+
+# Still looks like OptionParser, but a command to execute is returned.
+cmd = parser.parse!
+
+# If you don't specify a command, don't call this! It throws an exception.
+cmd.call()
+```
+
+### Define A Root Command
+
+This is like the previous example, but we define a command to call.
+
+```ruby
+require "suboptparse"
+
+# Looks like OptionParser.
+parser = SubOptParser.new do |sop|
+  # Normal OptionParser calls.
+  sop.on("--my-option=foo", "-m", "Sets a value") do |v|
+    # Record value somewhere.
+  end
+
+  sop.cmd do |args|
+    puts "Root command run."
+  end
+end
+
+# Still looks like OptionParser, but a command to execute is returned.
+cmd = parser.parse!
+
+# Now this prints, "Root command run."
+cmd.call()
+```
+
+### Sub Command Example
+
+This example shows a sub-command and a few features.
+
+You can raise an exception if arguments are not consumed during parsing
+using `raise_unknown=true`. 
+
+You can share state between commands so they can parse into a common location.
+This makes parent commands sharing common values with child commands
+easier.
+
+Finally, if you set `raise_unknown=false` (the default value), then
+unparsed command line options are passed to the called command.
+
+```ruby
+require "suboptparse"
+
+# Looks like OptionParser.
+parser = SubOptParser.new do |sop|
+
+  # Set shared state. All sub-commands may add values to this.
+  # This is set at command creation time and should not be changed after.
+  sop.shared_state = SubOptParse::SharedState.new
+
+  # This command should raise an error if it executes with unconsumed options.
+  # Default is false.
+  sop.raise_unknown = true
+
+  # Normal OptionParser calls.
+  sop.on("--my-option=foo", "-m", "Sets a value") do |v|
+    # Record value somewhere.
+  end
+
+  sop.cmd do |args|
+    puts "Root command run."
+  end
+
+  sop.cmdadd("subcommand", "This is a sub-command.") do |sop|
+    sop.on("--sub-command-option=value", "A sub-command option.") do |v|
+      sop.shared_state["sub-command-option"] = v
+    end
+
+    sop.cmd do |unconsumed_arguments|
+      sop.shared_state["sub-command-option"]
+    end
+  end
+end
+
+# Parse and call the command in 1 call.
+ret = parser.call("subcommand", "--sub-command-option=foo", "--my-option=bar")
+
+# The returns "foo".
+puts "Calling subcommand returned #{ret}."
+```
+
+## How Tos
+
+### Intercept -h
+
+Calling `-h` normally has the effect of terminating parsing and printing the
+help of the parent command. You can register an `on_parse` handler to 
+remove `-h` and append `help` to the end of the command line arguemnts.
+This will cause the default help function of the child command to be called
+when `-h` is on the command line.
+
+```ruby
+require "suboptparse"
+
+# Looks like OptionParser.
+parser = SubOptParser.new do |sop|
+
+  sop.on_parse do |op, argv|
+    if argv.include? "-h" or argv.include? "--help"
+        argv.delete("-h")
+        argv.delete("--help")
+        argv.push('help')
+    end
+    argv
+  end
+
+  sop.shared_state = SubOptParse::SharedState.new
+
+  # Normal OptionParser calls.
+  sop.on("--my-option=foo", "-m", "Sets a value") do |v|
+    # Record value somewhere.
+  end
+
+  sop.cmd do |args|
+    puts "Root command run."
+  end
+
+  sop.cmdadd("subcommand", "This is a sub-command.") do |sop|
+    sop.on("--sub-command-option=value", "A sub-command option.") do |v|
+      sop.shared_state["sub-command-option"] = v
+    end
+
+    sop.cmd do
+      sop.shared_state["sub-command-option"]
+    end
+  end
+end
+
+# Parse and call the command in 1 call.
+ret = parser.call("-h", "subcommand")
+
+puts "Calling subcommand returned #{ret}."
+```
+
+### Auto Requiring Commands
+
+You can configure the SubOptParser to call `require` on files in your
+`$LOAD_PATH` to load and define sub-commands dynamically. There
+are two approaches, implicit and explicit. Both methods require that the
+loading class define itself when loading.
+
+This may be done by using class variables or class methods that capture
+the current command name being loaded and the current SubOptParse instance
+doing the loading.
+
+A dynamically loaded command might look like this:
+
+```ruby
+# frozen_string_literal: true
+
+require "suboptparse/auto_require"
+
+SubOptParser::AutoRequire.register do |so, name|
+  so.addcmd(name, "A command.") do |so|
+    # Define the command...
+    so.cmd { puts so.help }
+  end
+end
+```
+
+The `register` method is just a conveneint way to access the class
+variables
+`SubOptParse::AutoRequire::auto_require_command_parent`
+and
+`SubOptParse::AutoRequire::auto_require_command_name`.
+You may access them directly, though, that is a lot of typing.
+
+### Implicit Auto Requiring
+
+First, to enable the feature, you must define an `autorequire_root`.
+This path will be prefixed to any file attempted to be loaded with a call
+to `require`.
+
+```ruby
+so = SubOptParser.new do |opt|
+  opt.autorequire_root = "suboptparse/autoreqtest"
+  opt.autorequire_suffix = "_command"
+end
+
+# This calls require "suboptparse/autoreqtest/a_command"
+so.get_subcommand("a").help
+
+# This calls require "suboptparse/autoreqtest/a/b/c_command"
+so.get_subcommand("a", "b", "c").help
+```
+
+There is a problem with this approache. Because the commands are not
+loaded, calling `help` on the parent command will not show the child
+commands. Calling `help` on the child commands will recursively
+print the help from the root command.
+
+You can define documentation for a child command by calling
+`cmddocadd()` as shown here.
+
+```ruby
+so = SubOptParser.new do |opt|
+  opt.autorequire_root = "suboptparse/autoreqtest"
+  opt.autorequire_suffix = "_command"
+  opt.cmddocadd("a", "This is the A command")
+end
+```
+
+Now the help text for the root command will include a listing for the
+sub-command, "a".
+
+### Explicit Auto Requiring
+
+Like with implicit loading, to enable the feature, you must define
+an `autorequire_root`.  This path will be prefixed to any file attempted to
+be loaded with a call to `require`.
+
+To define a sub-command to be loaded, again, `cmddocadd()` is used, but
+included is a 3rd argument which is the `require` path
+*relative to the `autorequire_root`.*
+
+```ruby
+so = SubOptParser.new do |opt|
+  opt.shared_state = {}
+  opt.autorequire_root = "suboptparse/autoreqtest2"
+  opt.cmddocadd("a", "A", "a_command")
+  opt.cmddocadd("b", "B", "a/b_command")
+  opt.cmddocadd("c", "C", "a/b/c_command")
+end
+
+# Calls `require "suboptparse/autoreqtest2/a_command"`.
+so.get_subcommand("a")
+
+# Calls `require "suboptparse/autoreqtest2/a/b/c_command"`.
+so.call("a", "b", "c")
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Releasing
+
+```shell
+# Tag with a 3 digit tag prefixed with a "v".
+git tag v0.1.2
+
+# Push the tag. GitHub actions will do the rest.
+git push origin tag v0.1.2
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/basking2/suboptparse.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rdoc/task"
+require "English"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+  rdoc.options << "--format=darkfish"
+  rdoc.title = "SubOptParse"
+  rdoc.rdoc_dir = "rdoc"
+end
+
+task :version, [:val] do |_t, args|
+  raise StandardError.new, "Version must be formatted as v[digit].[digit].[digit]." \
+      unless args[:val] =~ /^v([0-9]+\.[0-9]+\.[0-9]+)$/
+
+  ver = $LAST_MATCH_INFO[1]
+  puts ver
+  vfile = [
+    "# frozen_string_literal: true",
+    "",
+    "module SubOptParse",
+    "  VERSION = \"#{ver}\"",
+    "end",
+    ""
+  ].join("\n")
+  File.open("./lib/suboptparse/version.rb", "wt") do |io|
+    io.write(vfile)
+  end
+end
+
+task default: %i[spec rubocop]

data/lib/suboptparse/auto_require.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+class SubOptParser
+  # 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
+  module AutoRequire
+    # rubocop:disable Style/ClassVars
+    @@auto_require_command_parent = nil
+    @@auto_require_command_name = nil
+    @@auto_require_command_description = nil
+    # rubocop:enable Style/ClassVars
+
+    class << self
+      def auto_require_command_parent
+        @@auto_require_command_parent
+      end
+
+      def auto_require_command_name
+        @@auto_require_command_name
+      end
+
+      def auto_require_command_description
+        @@auto_require_command_description
+      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.
+      def register(&blk) # :yields: sub_command
+        @@auto_require_command_parent.cmdadd(@@auto_require_command_name, @@auto_require_command_description, &blk)
+      end
+    end
+
+    # Appended to the command name to load by a call to `require "path/to/cmd_command"`
+    attr_accessor :autorequire_suffix
+
+    # 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.
+    #
+    attr_accessor :autorequire_root
+
+    # Auto-require the command.
+    #
+    # The root app name is ignored as it can change by program invocation.
+    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
+
+    # Build a path for the given command name to pass to require.
+    #
+    #    p = generate_require_path(foo)
+    #    require p
+    #
+    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
+
+    # 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.
+    def cmddocadd(name, description, req = nil)
+      @cmddocs[name] = { "name" => name, "description" => description, "require" => req }
+      @op.banner = @banner + cmdhelp
+    end
+
+    private
+
+    # Generate a command which, if executed, throws the exception that prevented it from being created.
+    def generate_default_command(name, err)
+      cmdadd(name, "Autogenerated command.") do |so|
+        so.cmd do
+          raise err
+        end
+      end
+    end
+
+    # rubocop:disable Style/ClassVars, Metrics/MethodLength
+    def do_in_autorequire(name)
+      prev_auto_require_command_parent = @@auto_require_command_parent
+      prev_auto_require_command_name = @@auto_require_command_name
+      prev_auto_require_command_description = @@auto_require_command_description
+      @@auto_require_command_parent = self
+      @@auto_require_command_name = name
+      @@auto_require_command_description = get_sub_command_description(name)
+      yield if block_given?
+    ensure
+      @@auto_require_command_parent = prev_auto_require_command_parent
+      @@auto_require_command_name = prev_auto_require_command_name
+      @@auto_require_command_description = prev_auto_require_command_description
+    end
+    # rubocop:enable Style/ClassVars, Metrics/MethodLength:
+
+    def get_sub_command_description(name)
+      if (cmddoc = @cmddocs[name])
+        cmddoc["description"]
+      else
+        ""
+      end
+    end
+
+    protected
+
+    def autorequire_init
+      @autorequire_root = nil
+      @autorequire_suffix = "_command"
+
+      # Documentation for unloaded commands.
+      @cmddocs = {}
+    end
+  end
+end

data/lib/suboptparse/shared_state.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "./util"
+
+module SubOptParse
+  # A helper class that may be used in SubOptParse.shared_state.
+  #
+  # This class wraps a Hash and allows other hash-like objects to be
+  # merged into this hash without creating a new container object.
+  class SharedState
+    # The current state.
+    attr_accessor :curr
+
+    def initialize(initial_state = {})
+      @curr = initial_state
+    end
+
+    def merge!(other)
+      @curr = SubOptParse::Util.recursive_merge(@curr, other)
+    end
+
+    # Convenience function equivalent to shared_state.curr[name] = value.
+    def []=(name, value)
+      @curr[name] = value
+    end
+
+    # Convenience function equivalent to shared_state.curr[name].
+    def [](name)
+      @curr[name]
+    end
+  end
+end

data/lib/suboptparse/util.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SubOptParse
+  # Utility methods that may help in writing commands.
+  module Util
+    # Merge obj2 into obj1, if possible.
+    # Only hashes and lists are mergable.
+    # :stopdoc:
+    # rubocop:disable Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+    # :startdoc:
+    def self.recursive_merge(obj1, obj2)
+      if obj1.nil?
+        obj2
+      elsif obj2.nil?
+        obj1
+      elsif obj1.instance_of?(Hash) && obj2.instance_of?(Hash)
+        obj2.each { |k, v| obj1[k] = recursive_merge(obj1[k], v) }
+        obj1
+      elsif obj1.instance_of?(Array) && obj2.instance_of?(Array)
+        h = {}
+        obj1.each { |v| h[v] = recursive_merge(h[v], v) }
+        obj2.each { |v| h[v] = recursive_merge(h[v], v) }
+        h.values
+      else
+        # Can't merge. Return object 2.
+        obj2
+      end
+    end
+    # :stopdoc:
+    # rubocop:enable Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+    # :startdoc:
+  end
+end

data/lib/suboptparse/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SubOptParse
+  VERSION = "0.1.24"
+end

data/lib/suboptparse.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require_relative "suboptparse/version"
+require_relative "suboptparse/shared_state"
+require_relative "suboptparse/util"
+require_relative "suboptparse/auto_require"
+
+require "optparse"
+
+module SubOptParse
+  class Error < StandardError; end
+end
+
+# An adaptation of Ruby's default OptionParser to support sub-commands.
+# :stopdoc:
+# rubocop:disable Metrics/ClassLength
+# :startdoc:
+class SubOptParser
+  include SubOptParser::AutoRequire
+
+  # The description of this command.
+  attr_accessor :description
+
+  # The path of parent commands to this command.
+  # This is automatically set by #cmdadd().
+  attr_accessor :cmdpath
+
+  # The parent command, or nil? if this is the root command.
+  attr_accessor :cmdparent
+
+  # 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.
+  attr_accessor :shared_state
+
+  # 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.
+  #
+  attr_accessor :autorequire_root
+
+  # 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.
+  #
+  # :stopdoc:
+  # rubocop:disable Metrics/MethodLength
+  # :startdoc:
+  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
+  # :stopdoc:
+  # rubocop:enable Metrics/MethodLength
+  # :startdoc:
+
+  def method_missing(name, *args, &block)
+    @op.__send__(name, *args, &block)
+  end
+
+  def respond_to_missing?(_name, _include_private = false)
+    true
+  end
+
+  # If true, an exception will be thrown when an unknown argument is given.
+  def raise_unknown
+    @op.raise_unknown
+  end
+
+  # If true, an exception will be thrown when an unknown argument is given.
+  def raise_unknown=(value)
+    @op.raise_unknown = value
+  end
+
+  # Add a sub command as the given name.
+  # No automatic initializtion is done. Prefer using #cmdadd().
+  #
+  #     parser["sub_parser"] = SubOptParser.new do { |sub| ... }
+  def []=(name, subcmd)
+    @cmds[name] = subcmd
+    @op.banner = @banner + cmdhelp
+  end
+
+  # Users may override how to lookup a command or return "nil" if none is found.
+  def [](name)
+    @cmds[name]
+  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.
+  def on_parse(&blk) # :yields: sub_opt_parser, arguments
+    @pre_parse_blk = blk
+  end
+
+  # Similar to #on_parse but happens after parsing.
+  def after_parse(&blk)
+    @post_parse_blk = blk
+  end
+
+  alias pre_parse on_parse
+  alias post_parse after_parse
+
+  # Add a command (and return the resulting command).
+  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
+
+  def cmd(prc = nil, &blk) # :yields: unconsumed_arguments
+    @cmd = prc unless prc.nil?
+    @cmd = blk unless blk.nil?
+  end
+
+  # Put the parent help text at the start of this command's help.
+  # This allows for building recursive help.
+  def help
+    if @cmdparent.nil?
+      @op.help
+    else
+      "#{@cmdparent.help}\n#{@op.help}"
+    end
+  end
+
+  def cmdhelp
+    cmds = _build_cmd_doc_map
+    cmds = _build_cmddocs_doc_map(cmds)
+    h = _build_help_body(cmds)
+
+    # Append extra line.
+    "#{h}\n"
+  end
+
+  alias addcmd cmdadd
+
+  def parse!(argv, into: nil)
+    _parse!(argv, into: into)
+  end
+
+  # Calls parse!.
+  def parse(*argv, into: nil)
+    _parse!(argv, into: into)
+  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)
+  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
+
+  # How sub-commands are loaded.
+  # If no sub-command can be loaded for the name, +nil+ is returned.
+  def get_subcommand(name)
+    if (cmd = self[name])
+      cmd
+    elsif autorequire_root && (cmd = autorequire(name))
+      cmd
+    end
+  end
+
+  private
+
+  def _parse!(argv, into: nil)
+    argv = @pre_parse_blk.call(self, argv) if @pre_parse_blk
+
+    # Parse, removing all matching arguments.
+    @op.parse!(argv, into: into)
+
+    argv = @post_parse_blk.call(self, argv) if @post_parse_blk
+
+    if !argv.empty? && (cmd = get_subcommand(argv[0]))
+      argv.shift
+      cmd.parse!(argv, into: into)
+    else
+      [@cmd, argv]
+    end
+  end
+
+  def _add_default_help_cmd(opt_parser)
+    opt_parser.cmdadd("help") do |o2|
+      o2.cmd do
+        puts opt_parser.help
+        exit 0
+      end
+      o2.description = "Print help."
+    end
+  end
+
+  def _create_sub_command(name, description, *args)
+    cmdpath = @cmdpath.dup.append(name)
+    o = SubOptParser.new("Usage: #{cmdpath.join(" ")} [options]", *args, parent: self)
+    o.cmdpath = cmdpath
+    o.description ||= description
+    o.shared_state = @shared_state
+    o.raise_unknown = raise_unknown
+    o.autorequire_root = autorequire_root
+    o
+  end
+
+  # Build a map of command names to documentaton strings from @cmds.
+  def _build_cmd_doc_map
+    # Map of command names to descriptions.
+    @cmds.each_with_object({}) do |arr, h|
+      h[arr[0]] = arr[1].description
+    end
+  end
+
+  # Add to the given +cmds+ map of commands to documentation those
+  # commands in the @cmddocs map.
+  #
+  # If a command was already added by _build_cmd_doc_map, it is not
+  # overwritten.
+  #
+  # The final map is returned of commands to documentation.
+  def _build_cmddocs_doc_map(cmds)
+    # Map of documented command names to descriptions.
+    @cmddocs.each_with_object(cmds) do |arr, h|
+      h[arr[0]] = arr[1]["description"] unless @cmds.member?(arr[0])
+    end
+  end
+
+  # Given a map of command names to documentation strings,
+  # return a string that lists them in sorted order suitable for use in
+  # -h, --help or help output.
+  def _build_help_body(cmds)
+    cmds.keys.sort.inject("\n\n") do |h, key|
+      "#{h}#{key} - #{cmds[key]}\n"
+    end
+  end
+end
+# :stopdoc:
+# rubocop:enable Metrics/ClassLength
+# :startdoc:

data/sig/suboptparse.rbs

@@ -0,0 +1,4 @@
+module Suboptparse
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: suboptparse
+version: !ruby/object:Gem::Version
+  version: 0.1.24
+platform: ruby
+authors:
+- Sam Baskinger
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-02-12 00:00:00.000000000 Z
+dependencies: []
+description: Augment the default optparse OptionParser with some support for sub commands.
+email:
+- basking2@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/suboptparse.rb
+- lib/suboptparse/auto_require.rb
+- lib/suboptparse/shared_state.rb
+- lib/suboptparse/util.rb
+- lib/suboptparse/version.rb
+- sig/suboptparse.rbs
+homepage: https://basking2.github.io/suboptparse/
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://basking2.github.io/suboptparse/
+  source_code_uri: https://github.com/basking2/suboptparse
+  changelog_uri: https://github.com/basking2/suboptparse/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Add subcommands to OptionParser.
+test_files: []