rodish 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be6ead8f4e3fb70c94b061d779c3f552842d78acb16e3828e37b64d02804772b
+  data.tar.gz: ec3ad13d30478c9048ea2ff74d07da4cd7c8e1d2efe99e3a569bd4fba09274f4
+SHA512:
+  metadata.gz: 93555b428ac603ad16d90fde03a0ff26ff2d8ce7097f8b9d32a8d57d1685b7042c1e8cee4842aeba3e2396ba990eb34b47e7d5df0ef3f90135d3892bb53e97f7
+  data.tar.gz: f306a8549e5b70abac451dc0d75add3a4266c2d66d3aa79c2f05b8efde26379505a91cfc5bbc99cfbcd72931942f8f536e91568e18df7f2e970b03dda537a028

data/CHANGELOG

@@ -0,0 +1,3 @@
+=== 1.0.0 (2025-02-27)
+
+* Initial Public Release

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2025 Jeremy Evans
+
+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 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.rdoc

@@ -0,0 +1,257 @@
+= Rodish
+
+Rodish parses an argv array using a routing tree approach. It is
+designed to make it easy to implement command line applications
+that support multiple levels of subcommands, with options at each
+level.
+
+= Installation
+
+  gem install rodish
+
+= Source Code
+
+Source code is available on GitHub at https://github.com/jeremyevans/rodish
+
+= Simple Example
+
+Here's a simple commented example with a single subcommand:
+
+  require "rodish"
+
+  # This just creates a normal Ruby class.  For each argv parse, Rodish will
+  # create an instance of this class
+  class CliExample
+
+    # This allows instances of the class to be instantiated with or without
+    # a default person.
+    def initialize(default_person=nil)
+      @default_person = default_person
+    end
+
+    # This installs the Rodish processor into CliExample. It also extends the
+    # CliExample class with the Rodish::Processor module).  The block provided
+    # is evaluated in the context of a Rodish::DSL instance.
+    Rodish.processor(self) do
+
+      # This method call creates a hello subcommand of the current/root command.
+      # If the given argv is for the hello subcommand, the block will be
+      # executed in the context of the CliExample instance.
+      on "hello" do
+
+        # This adds a usage string and a -p options for the hello subcommand.
+        # The block passed is used to set the options via the optparse library.
+        options("cli-example hello [options]") do
+          on("-p", "--person=name", "say hello to specific person")
+        end
+
+        run do |opts|
+          "Hello #{opts[:person] || @default_person || 'World'}"
+        end
+      end
+    end
+  end
+
+  # This requests Rodish to process the provided argv.  Rodish will determine
+  # the related command block to execute and execute it.  The return value of
+  # that block will be returned to the caller.
+  CliExample.process(["hello"])
+  # => "Hello World"
+
+  # Additional arguments passed to .process are passed to .new.  In this
+  # example, this sets the default person.
+  CliExample.process(["hello"], "Adol")
+  # => "Hello Adol"
+
+  # This shows an example of passing an option to a subcommand, and using
+  # the option value when returning a response.
+  CliExample.process(["hello", "-p", "Feena"], "Adol")
+  # => "Hello Feena"
+
+= Rodish DSL
+
+Inside the <tt>Rodish.processor</tt> block, you are in the context of the root
+command. The following methods are available for configuring the processing of
+the command.
+
+== +on+
+
+The +on+ method adds a subcommand of the current command, and yields to the
+block to configure the subcommand.  All of the methods described in the Rodish
+DSL section can be executed inside the +on+ block, and arbitrary levels of
+subcommands are supported.
+
+== +options+
+
+The +options+ method sets up an options parser for the current command.  The
+default options parser disallows any options. Options are parsed into a hash,
+which is yielded to commands (as in the above example).
+
+This method requires a String argument for the usage for the current command.
+You can also provide a +key+ keyword argument, to put parsed options into
+a subhash of the main options hash, which can be useful when options are
+parsed at multiple levels.
+
+If a block is provided, it is executed in the context of a Rodish::OptionParser
+instance.  Rodish::OptionParser is a subclass of Ruby's standard OptionParser
+(from +optparse+), with a few additional methods.
+
+== +args+
+
+The +args+ method sets the number of arguments accepted when running the command.
+The default for +args+ is +0+. You can provide either an Integer to accept a
+fixed number of arguments, or a Range to allow any number of arguments in that
+range.
+
+The method also accepts an +invalid_args_message+ keyword argument for the
+message, to set the message to display if an invalid number of arguments is
+provided.
+
+== +run+
+
+The +run+ method sets the block to run for the current command.  If the
+command accepts a fixed number of arguments, those arguments are yielded
+as the first arguments to the command.  If the command accepts a range of
+argument numbers, then the remaining argv array will be passed as the
+first argument.
+
+The block will be passed two additional arguments, the options already
+parsed, and the current Rodish::Command object.
+
+== +is+
+
+The +is+ method is a shortcut for calling the +on+ method and +run+ method.
+For example:
+
+  is "hello" do
+    :world
+  end
+  
+is equivalent to:
+
+  on "hello" do
+    run do
+      :world
+    end
+  end
+
+The +is+ method also takes +args+ and +invalid_args_message+ keyword arguments.
+
+== +before+
+
+The +before+ method takes a block, and this block is executed before command
+or subcommand execution, in the same context that the +run+ block would be
+executed in.  It is passed the remaining argv array and the already parsed
+options.
+
+== +skip_option_parsing+
+
+The +skip_option_parsing+ method makes the command do no option parsing,
+treating all elements of the remaining argv as options.  It requires a
+usage string for the command, similar to +options+.
+
+== +run_on+
+
+The +run_on+ method is similar to +on+, except it creates a post subcommand
+instead of a normal subcommand.  Post subcommands allow the +run+ block
+to parse part of the remaining argv array, and then call a subcommand with
+the modified (or a new) argv array.  You dispatch to post subcommands
+inside the +run+ block by calling +run+ on the command argument:
+
+  on "hello" do
+    args(2...)
+
+    run do |argv, opts, command|
+      @name = argv.shift
+      command.run(self, opts, argv)
+    end
+
+    run_on "world" do
+      run do
+        "Hello #{@name.upcase} World!"
+      end
+    end
+  end
+
+  # process(%w[hello foo world])
+  # => "Hello FOO World!"
+
+== +run_is+
+
+The +run_is+ method operates similarly to +is+, but adds a post subcommand
+instead of a normal subcommand.
+
+== +post_options+
+
+The +post_options+ method sets an option parser that is used for post
+subcommands. This parses options from the argv array that passed to
++command.run+, before calling the related subcommand. Example:
+
+  on "hello" do
+    args(2...)
+
+    post_options("Usage: hello name [options] subcommand ...") do
+      on("-c", "--cap", "capitalize instead of uppercase")
+    end
+
+    run do |argv, opts, command|
+      @name = argv.shift
+      command.run(self, opts, argv)
+    end
+
+    run_is "world" do |opts|
+      name = opts[:cap] ? @name.capitalize :  @name.upcase
+      "Hello #{name} World!"
+    end
+  end
+
+  # process(%w[hello foo world])
+  # => "Hello FOO World!"
+  # process(%w[hello foo -c world])
+  # => "Hello Foo World!"
+
+== +autoload_subcommand_dir+
+
+The +autoload_subcommand_dir+ takes a directory, and will autoload
+subcommands from the given directory.  Filenames ending in +.rb+ in
+this directory will be treated as subcommands, and requiring the
+file should add the appropriate subcommand.
+
+This allows you to design complex command line programs where only
+the parts of the program needed to handle the given argv are loaded.
+
+== +autoload_post_subcommand_dir+
+
+The +autoload_post_subcommand_dir+ operates the same as
++autoload_subcommand_dir+, but it handles post subcommands instead of
+normal subcommands.
+
+= Examples
+
+The tests that ship with Rodish fully cover all of Rodish's functionality.
+
+If you would like to view a production example using Rodish, which
+uses most of Rodish's features, please see UbiCli, which is part of
+Ubicloud:
+
+* Main class: https://github.com/ubicloud/ubicloud/blob/main/lib/ubi_cli.rb
+* Commands (separate command per file): https://github.com/ubicloud/ubicloud/tree/main/cli-commands
+
+= History
+
+Rodish was extracted from Ubicloud (https://github.com/ubicloud/ubicloud),
+and is the argv processor used in Ubicloud's command line interface.
+
+= Naming
+
+The name Rodish was chosen because Rodish uses an API similar (-ish) to the Roda
+web framework (http://roda.jeremyevans.net), and the library is designed for
+use in applications executed from a shell (sh).
+
+= License
+
+MIT
+
+= Author
+
+Jeremy Evans <code@jeremyevans.net>

data/lib/rodish/command.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require_relative "option_parser"
+require_relative "skip_option_parser"
+require_relative "errors"
+
+module Rodish
+  # Rodish::Command is the main object in Rodish's processing.
+  # It handles a single command, and may have one or more
+  # subcommands and/or post subcommands, forming a tree.
+  #
+  # Rodish's argv processing starts with the root command,
+  # processing options and deleting appropriately to subcommands,
+  # until the requested command or subcommand is located,
+  # which is then executed.
+  class Command
+    option_parser = OptionParser.new
+    option_parser.set_banner("")
+    option_parser.freeze
+
+    # The default option parser if no options are given for
+    # the command.
+    DEFAULT_OPTION_PARSER = option_parser
+
+    # A hash of subcommands for the command.  Keys are
+    # subcommand name strings.
+    attr_reader :subcommands
+
+    # A hash of post subcommands for the command.  Keys are
+    # post subcommand name strings.
+    attr_reader :post_subcommands
+
+    # The block to execute if this command is the requested
+    # subcommand.  May be nil if this subcommand cannot be
+    # executed, and can only dispatch to subcommands.
+    attr_accessor :run_block
+
+    # An array of command names that represent a path to the
+    # current command.  Empty for the root command.
+    attr_accessor :command_path
+
+    # The option parser for the current command.  May be nil,
+    # in which case the default option parser is used.
+    attr_accessor :option_parser
+
+    # If set, places parsed options in a subhash of the options
+    # hash, keyed by the given value.  If nil, parsed options
+    # are placed directly in the options hash.
+    attr_accessor :option_key
+
+    # The post option parser for the current command.  Called
+    # only before dispatching to post subcommands.
+    attr_accessor :post_option_parser
+
+    # Similar to +option_key+, but for post options instead
+    # of normal subcommands.
+    attr_accessor :post_option_key
+
+    # A before hook to execute before executing the current
+    # command or dispatching to subcommands.
+    attr_accessor :before
+
+    # The number of arguments the run block will accept.
+    # Should be either an integer or a range of integers.
+    attr_accessor :num_args
+
+    # The error message to use if an invalid number of
+    # arguments is provided.
+    attr_accessor :invalid_args_message
+
+    def initialize(command_path)
+      @command_path = command_path
+      @command_name = command_path.join(" ").freeze
+      @subcommands = {}
+      @post_subcommands = {}
+      @num_args = 0
+    end
+
+    # Freeze all subcommands and option parsers in
+    # addition to the command itself.
+    def freeze
+      @subcommands.each_value(&:freeze)
+      @subcommands.freeze
+      @post_subcommands.each_value(&:freeze)
+      @post_subcommands.freeze
+      @option_parser.freeze
+      @post_option_parser.freeze
+      super
+    end
+
+    # Run a post subcommand using the given context (generally self),
+    # options, and argv.  Usually called inside a run block, after
+    # shifting one or more values off the given argv:
+    #
+    #   run do |argv, opts, command|
+    #     @name = argv.shift
+    #     command.run(self, opts, argv)
+    #   end
+    def run(context, options, argv)
+      begin
+        process_options(argv, options, @post_option_key, @post_option_parser)
+      rescue ::OptionParser::InvalidOption => e
+        raise CommandFailure.new(e.message, @post_option_parser)
+      end
+
+      arg = argv[0]
+      if arg && @post_subcommands[arg]
+        process_subcommand(@post_subcommands, context, options, argv)
+      else
+        process_command_failure(arg, @post_subcommands, @post_option_parser, "post ")
+      end
+    end
+    alias run_post_subcommand run
+
+    # Process the current command.  This first processes the options.
+    # After processing the options, it checks if the first argument
+    # in the remaining argv is a subcommand.  If so, it dispatches to
+    # that subcommand.  If not, it dispatches to the run block.
+    def process(context, options, argv)
+      process_options(argv, options, @option_key, @option_parser)
+
+      arg = argv[0]
+      if argv && @subcommands[arg]
+        process_subcommand(@subcommands, context, options, argv)
+      elsif run_block
+        if valid_args?(argv)
+          context.instance_exec(argv, options, &before) if before
+
+          if @num_args.is_a?(Integer)
+            context.instance_exec(*argv, options, self, &run_block)
+          else
+            context.instance_exec(argv, options, self, &run_block)
+          end
+        elsif @invalid_args_message
+          raise_failure("invalid arguments#{subcommand_name} (#{@invalid_args_message})")
+        else
+          raise_failure("invalid number of arguments#{subcommand_name} (accepts: #{@num_args}, given: #{argv.length})")
+        end
+      else
+        process_command_failure(arg, @subcommands, @option_parser, "")
+      end
+    rescue ::OptionParser::InvalidOption => e
+      if @option_parser || @post_option_parser
+        raise_failure(e.message)
+      else
+        raise
+      end
+    end
+
+    # This yields the current command and all subcommands and
+    # post subcommands, recursively.
+    def each_subcommand(names = [].freeze, &block)
+      yield names, self
+      _each_subcommand(names, @subcommands, &block)
+      _each_subcommand(names, @post_subcommands, &block)
+    end
+
+    # Raise a CommandFailure with the given error and the given
+    # option parsers.
+    def raise_failure(message, option_parsers = self.option_parsers)
+      raise CommandFailure.new(message, option_parsers)
+    end
+
+    # Returns a string of options text for the command's option parsers.
+    def options_text
+      option_parsers = self.option_parsers
+      unless option_parsers.empty?
+        _options_text(option_parsers)
+      end
+    end
+
+    # Returns a Command instance for the named subcommand.
+    # This will autoload the subcommand if not already loaded.
+    def subcommand(name)
+      _subcommand(@subcommands, name)
+    end
+
+    # Returns a Command instance for the named post subcommand.
+    # This will autoload the post subcommand if not already loaded.
+    def post_subcommand(name)
+      _subcommand(@post_subcommands, name)
+    end
+
+    # An array of option parsers for the command.  May be empty
+    # if the command has no option parsers.
+    def option_parsers
+      [@option_parser, @post_option_parser].compact
+    end
+
+    private
+
+    # Yield to the block for each subcommand in the given
+    # subcommands.  Internals of #each_subcommand.
+    def _each_subcommand(names, subcommands, &block)
+      subcommands.each_key do |name|
+        sc_names = names + [name]
+        _subcommand(subcommands, name).each_subcommand(sc_names.freeze, &block)
+      end
+    end
+
+    # Return the named subcommand from the given subcommands hash,
+    # autoloading it if it is not already loaded.
+    def _subcommand(subcommands, name)
+      subcommand = subcommands[name]
+
+      if subcommand.is_a?(String)
+        require subcommand
+        subcommand = subcommands[name]
+        unless subcommand.is_a?(Command)
+          raise ProgramBug, "program bug, autoload of subcommand #{name} failed"
+        end
+      end
+
+      subcommand
+    end
+
+    # Return a string containing all option parser text.
+    def _options_text(option_parsers)
+      option_parsers.join("\n\n")
+    end
+
+    # Handle command failures for both subcommands and post subcommands.
+    def process_command_failure(arg, subcommands, option_parser, prefix)
+      if subcommands.empty?
+        raise ProgramBug, "program bug, no run block or #{prefix}subcommands defined#{subcommand_name}"
+      elsif arg
+        raise_failure("invalid #{prefix}subcommand: #{arg}", option_parser)
+      else
+        raise_failure("no #{prefix}subcommand provided", option_parser)
+      end
+    end
+
+    # Process options for the given command. If option_key is set,
+    # parsed options are added as a options subhash under the given key.
+    # Otherwise, parsed options placed directly into options.
+    def process_options(argv, options, option_key, option_parser)
+      case option_parser
+      when SkipOptionParser
+        # do nothing
+      when nil
+        DEFAULT_OPTION_PARSER.order!(argv)
+      else
+        command_options = option_key ? {} : options
+
+        option_parser.order!(argv, into: command_options)
+
+        if option_key
+          options[option_key] = command_options
+        end
+      end
+    end
+
+    # Dispatch to the appropriate subcommand using the first entry in
+    # the provided argv.
+    def process_subcommand(subcommands, context, options, argv)
+      subcommand = _subcommand(subcommands, argv[0])
+      argv.shift
+      context.instance_exec(argv, options, &before) if before
+      subcommand.process(context, options, argv)
+    end
+
+    # Helper used for constructing error messages.
+    def subcommand_name
+      if @command_name.empty?
+        " for command"
+      else
+        " for #{@command_name} subcommand"
+      end
+    end
+
+    # Return whether the given argv has a valid number of arguments.
+    def valid_args?(argv)
+      if @num_args.is_a?(Integer)
+        argv.length == @num_args
+      else
+        @num_args.include?(argv.length)
+      end
+    end
+  end
+end

data/lib/rodish/dsl.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "option_parser"
+require_relative "skip_option_parser"
+
+module Rodish
+  # The Rodish::DSL class implements Rodish's DSL.  Blocks
+  # passed to Rodish.processor and on/run_on blocks inside
+  # those blocks evaluated in the context of an instance of
+  # Rodish::DSL.
+  #
+  # Each Rodish::DSL instance is bound to a single
+  # Rodish::Command and allows the DSL to modify the state
+  # of the command.
+  class DSL
+    # Create a new command with the given path and evaluate
+    # the given block in the context of a new instance using
+    # that command.
+    def self.command(command_path, &block)
+      command = Command.new(command_path)
+      new(command).instance_exec(&block)
+      command
+    end
+
+    def initialize(command)
+      @command = command
+    end
+
+    # Skip option parsing for the command.  This is different
+    # then the default option parsing, which will error if any
+    # options are given.  A banner must be provided, setting
+    # the usage for the command.
+    #
+    # The main reason to use this is if you are going to pass
+    # the entire remaining argv as the argv to another
+    # program.
+    def skip_option_parsing(banner)
+      @command.option_parser = SkipOptionParser.new(banner)
+    end
+
+    # Set the option parser for the command to based on the
+    # provided block, which is executed in the context of a new
+    # instance of Rodish::OptionParser. These options are parsed
+    # for execuction of both subcommands and the current command.
+    #
+    # The banner argument is required and sets the usage string
+    # for the command.
+    #
+    # If +key+ is given, parsed options
+    # will be placed in a subhash using that key.
+    #
+    # The block is optional, allowing you to set a usage banner for
+    # commands without allowing any options.
+    def options(banner, key: nil, &block)
+      @command.option_key = key
+      @command.option_parser = create_option_parser(banner, @command.subcommands, &block)
+    end
+
+    # Similar to +options+, but sets the option parser for post
+    # subcommands.  This option parser is only used when the
+    # command is executed and chooses to run a post subcommand.
+    def post_options(banner, key: nil, &block)
+      @command.post_option_key = key
+      @command.post_option_parser = create_option_parser(banner, @command.post_subcommands, &block)
+    end
+
+    # Sets the before block.  This block is executed in the same
+    # context as the run block would be executed, before either
+    # subcommand execution or execution of the current command.
+    def before(&block)
+      @command.before = block
+    end
+
+    # Set the number of arguments supported by this command.
+    # The default is 0.  To support a fixed number of arguments,
+    # pass an Integer.  To support a variable number of arguments,
+    # pass a Range.  The +invalid_args_message+ argument sets the
+    # error message to use if an invalid number of arguments is
+    # passed.
+    def args(args, invalid_args_message: nil)
+      @command.num_args = args
+      @command.invalid_args_message = invalid_args_message
+    end
+
+    # Autoload subcommands from the given directory. Filenames
+    # ending in .rb in this directory should be valid subcommands,
+    # and requiring the related file should load the subcommand.
+    #
+    # You can use this so that your argv parser does not need to
+    # load code not needed to support processing the command.
+    def autoload_subcommand_dir(dir)
+      _autoload_subcommand_dir(@command.subcommands, dir)
+    end
+
+    # Similar to +autoload_subcommand_dir+, but for post
+    # subcommands instead of normal subcommands.
+    def autoload_post_subcommand_dir(dir)
+      _autoload_subcommand_dir(@command.post_subcommands, dir)
+    end
+
+    # Create a new subcommand with the given name and yield to
+    # the block to configure the subcommand.
+    def on(command_name, &block)
+      _on(@command.subcommands, command_name, &block)
+    end
+
+    # Same as +on+, but for post subcommands instead of normal
+    # subcommands.
+    def run_on(command_name, &block)
+      _on(@command.post_subcommands, command_name, &block)
+    end
+
+    # Set the block to run for subcommand execution.  Commands
+    # should have subcommands and/or a run block, otherwise it
+    # is not possible to use the command successfully.
+    def run(&block)
+      @command.run_block = block
+    end
+
+    # A shortcut for calling +on+ and +run+.
+    #
+    #   is "hello" do
+    #     :world
+    #   end
+    #  
+    # is equivalent to:
+    #
+    #   on "hello" do
+    #     run do
+    #       :world
+    #     end
+    #   end
+    #
+    # The +args+ argument sets the number of arguments supported by
+    # the command.
+    #
+    # The +invalid_args_message+ arguments set the error message to
+    # use if an invalid number of arguments is provided.
+    def is(command_name, args: 0, invalid_args_message: nil, &block)
+      _is(:on, command_name, args:, invalid_args_message:, &block)
+    end
+
+    # Similar to +is+, but for post subcommands instead of normal
+    # subcommands.
+    def run_is(command_name, args: 0, invalid_args_message: nil, &block)
+      _is(:run_on, command_name, args:, invalid_args_message:, &block)
+    end
+
+    private
+
+    # Internals of autoloading of normal and post subcommands.
+    # This sets the value of the subcommand as a string instead of a
+    # Command instance, and the Command#_subcommand method recognizes
+    # this and handles the autoloading.
+    def _autoload_subcommand_dir(hash, base)
+      Dir.glob("*.rb", base:).each do |filename|
+        hash[filename.chomp(".rb")] = File.expand_path(File.join(base, filename))
+      end
+    end
+
+    # Internals of +is+ and +run_is+.
+    def _is(meth, command_name, args:, invalid_args_message: nil, &block)
+      public_send(meth, command_name) do
+        args(args, invalid_args_message:)
+        run(&block)
+      end
+    end
+
+    # Internals of +on+ and +run_on+.
+    def _on(hash, command_name, &block)
+      command_path = @command.command_path + [command_name]
+      hash[command_name] = DSL.command(command_path.freeze, &block)
+    end
+
+    # Internals of +options+ and +post_options+.
+    def create_option_parser(banner, subcommands, &block)
+      option_parser = OptionParser.new
+      option_parser.set_banner("Usage: #{banner}")
+      if block
+        option_parser.separator ""
+        option_parser.separator "Options:"
+        option_parser.instance_exec(&block)
+      end
+      option_parser.subcommands = subcommands
+      option_parser
+    end
+  end
+end

data/lib/rodish/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Rodish
+  # Rodish::CommandExit is the base error class for Rodish, signaling
+  # that a command execution finished. Callers of
+  # Rodish::Processor#process should rescue CommandExit to handle
+  # both failures as well as early exits.
+  #
+  # Direct instances represent successful execution. This is
+  # raised when calling halt inside an options parser block (if an
+  # option should result in an early exit).  It can also be raised
+  # manually inside command run blocks to exit early.
+  class CommandExit < StandardError
+    # Whether or not the command failed.  For CommandExit, this always
+    # returns false, since CommandExit represents successful execution
+    # exits.
+    def failure?
+      false
+    end
+  end
+
+  # Rodish::CommandFailure is used for failures of commands, such as:
+  #
+  # * Invalid options
+  # * Invalid number of arguments for a command
+  # * Invalid subcommands
+  # * No subcommand given for a command that only supports subcommands
+  class CommandFailure < CommandExit
+    def initialize(message, option_parsers = [])
+      option_parsers = [option_parsers] unless option_parsers.is_a?(Array)
+      @option_parsers = option_parsers.compact
+      super(message)
+    end
+
+    # Always returns false, since CommandFailure represents failures.
+    def failure?
+      true
+    end
+
+    # Return the message along with the content of any related option
+    # parsers.  This can be used to show usage an options along with
+    # error messages for failing commands.
+    def message_with_usage
+      if @option_parsers.empty?
+        message
+      else
+        "#{message}\n\n#{@option_parsers.join("\n\n")}"
+      end
+    end
+  end
+
+  # Rodish::ProgramBug is a subclass of Rodish::CommandFailure only used
+  # in cases where there is a bug in the program, such as a command with
+  # no subcommands or run block, or when subcommand autoloads do not
+  # result in the subcommand being defined.
+  class ProgramBug < CommandFailure
+  end
+end

data/lib/rodish/option_parser.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "errors"
+
+module Rodish
+  # Rodish::OptionPaser is a subclass of Ruby's standard OptionParser
+  # (from the optparse library).
+  class OptionParser < ::OptionParser
+    # A hash of subcommands for the option parser.  If not empty,
+    # shows available subcommands when showing options.
+    attr_accessor :subcommands
+
+    # Don't add officious, which includes options that call exit.
+    # With Rodish, there are no secret options, only options you define.
+    def add_officious
+    end
+
+    # Add the available subcommands to the returned string if there are
+    # any subcommands.
+    def to_s
+      string = super
+
+      if subcommands.length > 6
+        string += "\nSubcommands:\n  #{subcommands.keys.sort.join("\n  ")}\n"
+      elsif !subcommands.empty?
+        string += "\nSubcommands: #{subcommands.keys.sort.join(" ")}\n"
+      end
+
+      string
+    end
+
+    # Helper method that takes an array of values, wraps them to the given
+    # limit, and adds each line as a separator.  This is useful when you
+    # have a large amount of information you want to display and you want
+    # to wrap if for display to the user when showing options.
+    def wrap(prefix, values, separator: " ", limit: 80)
+      line = [prefix]
+      lines = [line]
+      prefix_length = length = prefix.length
+      sep_length = separator.length
+      indent = " " * prefix_length
+
+      values.each do |value|
+        value_length = value.length
+        new_length = sep_length + length + value_length
+        if new_length > limit
+          line = [indent, separator, value]
+          lines << line
+          length = prefix_length
+        else
+          line << separator << value
+        end
+        length += sep_length + value_length
+      end
+
+      lines.each do |line|
+        separator line.join
+      end
+    end
+
+    # Halt processing with a CommandExit using the given string.
+    # This can be used to implement early exits, by calling this
+    # method in a block:
+    #
+    #   on("--version", "show program version") { halt VERSION }
+    def halt(string)
+      raise CommandExit, string
+    end
+  end
+end

data/lib/rodish/processor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "dsl"
+
+module Rodish
+  module Processor
+    attr_reader :command
+
+    # Process an argv array using a new instance of the class that is
+    # extended with Rodish::Processor.  Additional arguments are passed to
+    # new when creating the instance.
+    #
+    # Callers of this method are encouraged to rescue Rodish::CommandExit,
+    # to handle both early exits and command failures.
+    def process(argv, *a, **kw) 
+      # Deliberately do not pass a block here, to reserve
+      # block handling for future use.
+      @command.process(new(*a, **kw), {}, argv)
+    rescue ::OptionParser::InvalidOption => e
+      @command.raise_failure(e.message)
+    end
+
+    # Without a block, returns the Command instance for related subcommand
+    # (a nested subcommand if multiple command names are given).
+    #
+    # With a block, uses the last command name to create a subcommand under
+    # the other named commands, configuring the created subcommand using the
+    # block.
+    def on(*command_names, &block)
+      if block
+        command_name = command_names.pop
+        dsl(command_names).on(command_name, &block)
+      else
+        dsl(command_names)
+      end
+    end
+
+    # Uses the last command name to create a subcommand under the other
+    # named commands, with the block being the commands
+    def is(*command_names, command_name, args: 0, invalid_args_message: nil, &block)
+      dsl(command_names).is(command_name, args:, invalid_args_message:, &block)
+    end
+
+    # Freeze the command when freezing the object.
+    def freeze
+      command.freeze
+      super
+    end
+
+    # Return a hash of usage strings for the root command and all subcommands,
+    # recursively.  The hash has string keys for the command name, and
+    # string values for the option parser(s) for the command.
+    def usages
+      usages = {}
+
+      command.each_subcommand do |names, command|
+        option_parsers = command.option_parsers
+        unless option_parsers.empty?
+          usages[names.join(" ")] = command.option_parsers.join("\n\n")
+        end
+      end
+
+      usages
+    end
+
+    private
+
+    # Use the array of command names to find the appropriate subcommand
+    # (which may be empty to use the root command), and return a DSL instance
+    # for it.
+    def dsl(command_names)
+      command = self.command
+      command_names.each do |name|
+        command = command.subcommands.fetch(name)
+      end
+      DSL.new(command)
+    end
+  end
+end

data/lib/rodish/skip_option_parser.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rodish
+  # Rodish::SkipOptionParser is used when option parsing should be
+  # skipped, treating all entries in argv as arguments.
+  class SkipOptionParser
+    # A usage banner to use for the related command.
+    attr_reader :banner
+
+    # The same as banner, but ending in a newline, similarly
+    # to how OptionParser#to_s works.
+    attr_reader :to_s
+
+    def initialize(banner)
+      @banner = "Usage: #{banner}".freeze
+      @to_s = (@banner + "\n").freeze
+    end
+  end
+end

data/lib/rodish.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "rodish/processor"
+require_relative "rodish/dsl"
+
+module Rodish
+  # Install a Rodish processor in the given class. This extends the class
+  # with Rodish::Processor, and uses the block to configure the processor
+  # using Rodish::DSL.
+  def self.processor(klass, &block)
+    klass.extend(Processor)
+    klass.instance_variable_set(:@command, DSL.command([].freeze, &block))
+    klass
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: rodish
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jeremy Evans
+bindir: bin
+cert_chain: []
+date: 2025-02-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-global_expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Rodish parses an argv array using a routing tree approach. It is
+  designed to make it easy to implement command line applications
+  that support multiple levels of subcommands, with options at each
+  level.
+email: code@jeremyevans.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+- CHANGELOG
+- MIT-LICENSE
+files:
+- CHANGELOG
+- MIT-LICENSE
+- README.rdoc
+- lib/rodish.rb
+- lib/rodish/command.rb
+- lib/rodish/dsl.rb
+- lib/rodish/errors.rb
+- lib/rodish/option_parser.rb
+- lib/rodish/processor.rb
+- lib/rodish/skip_option_parser.rb
+homepage: http://github.com/jeremyevans/rodish
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/jeremyevans/rodish/issues
+  changelog_uri: https://github.com/jeremyevans/rodish/blob/master/CHANGELOG
+  source_code_uri: https://github.com/jeremyevans/rodish
+rdoc_options:
+- "--quiet"
+- "--line-numbers"
+- "--inline-source"
+- "--title"
+- 'Rodish: Routing tree argv parser'
+- "--main"
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Routing tree argv parser
+test_files: []