rodish 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be6ead8f4e3fb70c94b061d779c3f552842d78acb16e3828e37b64d02804772b
-  data.tar.gz: ec3ad13d30478c9048ea2ff74d07da4cd7c8e1d2efe99e3a569bd4fba09274f4
+  metadata.gz: fe9eb4dc1a9f6cc1e7582a9b24dcbc3491f47e3a3aa24def4ff3f94a241d1dbc
+  data.tar.gz: 90748c4035108090d6576a824e6a6e1699079a755bbf405ce0484d238cd6ee1b
 SHA512:
-  metadata.gz: 93555b428ac603ad16d90fde03a0ff26ff2d8ce7097f8b9d32a8d57d1685b7042c1e8cee4842aeba3e2396ba990eb34b47e7d5df0ef3f90135d3892bb53e97f7
-  data.tar.gz: f306a8549e5b70abac451dc0d75add3a4266c2d66d3aa79c2f05b8efde26379505a91cfc5bbc99cfbcd72931942f8f536e91568e18df7f2e970b03dda537a028
+  metadata.gz: 01030a76bc9a5db02ae2b78ddd9bcdb24b18d0b32d9421dffc41f92041700a062a2f2c13260656cce79521f07abccb3ed5da7b4efeb3e93b5de06c246f2dfdfa
+  data.tar.gz: fe7ea63452c88a46dbe528c33b8f2a54d965f93c47ebc9a4984cd985c5a4ec73c777c4f4fc8c08973783ee0f6eb0957fc0b9804485d91d35dc41fee0e51620f3

data/lib/rodish/command.rb

@@ -1,35 +1,22 @@
 # 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.
+  # 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.
@@ -48,31 +35,20 @@ module Rodish
     # 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
+    # A description for the command
+    attr_accessor :desc
+
+    # A usage banner for the command or subcommands.
+    attr_accessor :banner
 
     def initialize(command_path)
       @command_path = command_path
-      @command_name = command_path.join(" ").freeze
+      @command_name = _command_name(command_path)
       @subcommands = {}
-      @post_subcommands = {}
       @num_args = 0
     end
 
@@ -81,92 +57,72 @@ module Rodish
     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
+    # Return a help string for the command.
+    def help
+      help_lines.join("\n")
+    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 ")
+    # Return an array of help strings for the command.
+    def help_lines
+      output = []
+      help_order.each do |type|
+        send(:"_help_#{type}", output)
       end
+      output
+    end
+
+    # Process options for the command using the option key and parser.
+    def process_command_options(context, options, argv)
+      process_options(argv, options, @option_key, @option_parser)
     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)
+      process_command_options(context, options, argv)
 
       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})")
+          raise_invalid_args_failure(argv)
         end
       else
-        process_command_failure(arg, @subcommands, @option_parser, "")
+        process_command_failure(arg, @subcommands, "")
       end
     rescue ::OptionParser::InvalidOption => e
-      if @option_parser || @post_option_parser
-        raise_failure(e.message)
-      else
-        raise
-      end
+      raise_failure(e.message)
     end
 
-    # This yields the current command and all subcommands and
-    # post subcommands, recursively.
+    # This yields the current command and all 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)
+    # Yield each banner string (if any) to the block.
+    def each_banner
+      yield banner if banner
+      nil
     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
+    # Raise a CommandFailure with the given error and the given
+    # option parsers.
+    def raise_failure(message)
+      raise CommandFailure.new(message, self)
     end
 
     # Returns a Command instance for the named subcommand.
@@ -175,19 +131,114 @@ module Rodish
       _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)
+    private
+
+    # The string to use for the usage heading in help output.
+    def help_usage_heading
+      "Usage:"
     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
+    # The string to use for the command heading in help output.
+    def help_command_heading
+      "Commands:"
     end
 
-    private
+    # The string to use for the options heading in help output.
+    def help_options_heading
+      "Options:"
+    end
+
+    # Use default help order by default.
+    def help_order
+      default_help_order
+    end
+
+    # The default order of help sections
+    def default_help_order
+      [:desc, :banner, :commands, :options]
+    end
+
+    # Add description to help output.
+    def _help_desc(output)
+      if desc
+        output << desc << ""
+      end
+    end
+
+    # Add banner to help output.
+    def _help_banner(output)
+      if each_banner{break true}
+        output << help_usage_heading
+        each_banner do |banner|
+          output << "    #{banner}"
+        end
+        output << ""
+      end
+    end
+
+    # Add commands to help output.
+    def _help_commands(output)
+      name_len = 0
+      each_local_subcommand do |name|
+        len = name.length
+        name_len = len if len > name_len
+      end
+
+      __help_command_hashes.each do |heading, hash|
+        next if hash.empty?
+        output << heading
+        command_output = []
+        _each_local_subcommand(hash) do |name, command|
+          command_output << "    #{name.ljust(name_len)}    #{command.desc}" 
+        end
+        command_output.sort!
+        output.concat(command_output)
+        output << ""
+      end
+    end
+
+    # Hash with hash of subcommand values to potentially show help output for.
+    def __help_command_hashes
+      {help_command_heading => @subcommands}
+    end
+
+    # Add options to help output.
+    def _help_options(output)
+      __help_option_parser_hashes.each do |heading, parser|
+        next if omit_option_parser_from_help?(parser)
+        output << heading
+        output << parser.summarize(String.new)
+      end
+    end
+
+    # Hash with option parser values to potentially show help output for.
+    def __help_option_parser_hashes
+      {help_options_heading => @option_parser}
+    end
+
+    # Whether the given option parser should be ommitted from the
+    # command help output.
+    def omit_option_parser_from_help?(parser)
+      parser.nil?
+    end
+
+    # Raise a error when an invalid number of arguments has been provided.
+    def raise_invalid_args_failure(argv)
+      raise_failure(invalid_num_args_failure_error_message(argv))
+    end
+
+    # Yield each local subcommand to the block.  This does not
+    # yield the current command or nested subcommands.
+    def each_local_subcommand(&block)
+      _each_local_subcommand(@subcommands, &block)
+    end
+
+    # Internals of each_local_subcommand.
+    def _each_local_subcommand(subcommands)
+      subcommands.each_key do |name|
+        yield name, _subcommand(subcommands, name)
+      end
+    end
 
     # Yield to the block for each subcommand in the given
     # subcommands.  Internals of #each_subcommand.
@@ -214,32 +265,37 @@ module Rodish
       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)
+    # Handle command failures for subcommands.
+    def process_command_failure(arg, subcommands, 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)
+        raise_failure(invalid_subcommand_error_message(arg, subcommands, prefix))
       else
-        raise_failure("no #{prefix}subcommand provided", option_parser)
+        raise_failure(no_subcommand_provided_error_message(arg, subcommands, prefix))
       end
     end
 
+    # The error message to use when an invalid number of arguments is provided.
+    def invalid_num_args_failure_error_message(argv)
+      "invalid number of arguments#{subcommand_name} (requires: #{@num_args}, given: #{argv.length})"
+    end
+
+    # Error message for cases where an invalid subcommand is provided.
+    def invalid_subcommand_error_message(arg, subcommands, prefix)
+      "invalid #{prefix}subcommand: #{arg}"
+    end
+
+    # Error message for cases where a subcommand is required and not provided.
+    def no_subcommand_provided_error_message(arg, subcommands, prefix)
+      "no #{prefix}subcommand provided"
+    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
+      if option_parser
         command_options = option_key ? {} : options
 
         option_parser.order!(argv, into: command_options)
@@ -247,6 +303,8 @@ module Rodish
         if option_key
           options[option_key] = command_options
         end
+      else
+        self.class::DEFAULT_OPTION_PARSER.order!(argv)
       end
     end
 
@@ -255,7 +313,6 @@ module Rodish
     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
 
@@ -268,6 +325,12 @@ module Rodish
       end
     end
 
+    # Set the command name for the command.  The command name is used
+    # in error messages.
+    def _command_name(command_path)
+      command_path.join(" ").freeze
+    end
+
     # Return whether the given argv has a valid number of arguments.
     def valid_args?(argv)
       if @num_args.is_a?(Integer)

data/lib/rodish/dsl.rb

@@ -2,7 +2,6 @@
 
 require_relative "command"
 require_relative "option_parser"
-require_relative "skip_option_parser"
 
 module Rodish
   # The Rodish::DSL class implements Rodish's DSL.  Blocks
@@ -18,8 +17,8 @@ module Rodish
     # 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 = self::Command.new(command_path)
+      new(command).instance_exec(&block) if block
       command
     end
 
@@ -27,16 +26,14 @@ module Rodish
       @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)
+    # Set the description for the command.
+    def desc(description)
+      @command.desc = description
+    end
+
+    # Set the banner for the command execution and subcommand usage.
+    def banner(banner)
+      @command.banner = banner
     end
 
     # Set the option parser for the command to based on the
@@ -49,38 +46,18 @@ module Rodish
     #
     # 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.banner = banner
       @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
+      @command.option_parser = create_option_parser(&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)
+    # pass a Range.
+    def args(args)
       @command.num_args = args
-      @command.invalid_args_message = invalid_args_message
     end
 
     # Autoload subcommands from the given directory. Filenames
@@ -93,24 +70,12 @@ module Rodish
       _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.
@@ -118,38 +83,9 @@ module Rodish
       @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.
+    # Internals of autoloading of 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.
@@ -159,30 +95,17 @@ module Rodish
       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+.
+    # Internals of +on+.
     def _on(hash, command_name, &block)
       command_path = @command.command_path + [command_name]
-      hash[command_name] = DSL.command(command_path.freeze, &block)
+      hash[command_name] = self.class.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
+    # Internals of +options+.
+    def create_option_parser(&block)
+      option_parser = self.class::OptionParser.new
+      option_parser.banner = "" # Avoids issues when parser is frozen
+      option_parser.instance_exec(&block)
       option_parser
     end
   end

data/lib/rodish/errors.rb

@@ -26,9 +26,10 @@ module Rodish
   # * 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
+    attr_reader :command
+
+    def initialize(message, command=nil)
+      @command = command
       super(message)
     end
 
@@ -41,10 +42,11 @@ module Rodish
     # 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?
+      help = @command&.help || ''
+      if help.empty?
         message
       else
-        "#{message}\n\n#{@option_parsers.join("\n\n")}"
+        "#{message}\n\n#{help}"
       end
     end
   end

data/lib/rodish/option_parser.rb

@@ -7,58 +7,11 @@ 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: