rodish 1.1.0 → 2.0.0

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:

data/lib/rodish/plugins/_context_sensitive_help.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# _context_sensitive_help is an internal plugin to implement context
+# sensitive help output.
+
+#
+module Rodish
+  module Plugins
+    module ContextSensitiveHelp_
+      # Object that wraps a block, which is instance execed in the provided
+      # context when called.
+      class ContextHelp
+        def initialize(block)
+          @block = block
+        end
+
+        def call(context)
+          context.instance_exec(&@block)
+        end
+      end
+
+      module CommandMethods
+        # Render help with context-sensitive information.
+        def context_help(context)
+          lines = help_lines(include_context_help: true)
+          lines.map! do |line|
+            if line.is_a?(ContextHelp)
+              line.call(context)
+            else
+              line
+            end
+          end
+          lines.flatten!
+          lines.join("\n")
+        end
+
+        # Exclude ContextHelp lines unless they are explicitly requested.
+        def help_lines(include_context_help: false)
+          lines = super()
+          lines.reject!{|l| l.is_a?(ContextHelp)} unless include_context_help
+          lines
+        end
+      end
+    end
+  end
+end

data/lib/rodish/plugins/_wrap.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# _wrap is an an internal plugin module used by other plugins.
+
+#
+module Rodish
+  module Plugins
+    module Wrap_
+      module_function
+
+      # Return an array of strings, each no longer than limit,
+      # showing the prefix and all values.
+      public 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 = value.to_s
+          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.map{|l| l.join}
+      end
+    end
+  end
+end

data/lib/rodish/plugins/after_options_hook.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# The after_options_hook plugin supports an after_options configuration
+# method, specifying a block to execute in context after parsing options,
+# before executing the command or any subcommands.  It is passed the remaining
+# argv and already parsed options:
+#
+#   after_options do |argv, options|
+#     # ...
+#   end
+
+#
+module Rodish
+  module Plugins
+    module AfterOptionsHook
+      module DSLMethods
+        # Sets the after_options block.  This block is executed in the same
+        # context as the run block would be executed, directly after
+        # option parsing.
+        def after_options(&block)
+          @command.after_options = block
+        end
+      end
+
+      module CommandMethods
+        # A hook to execute after parsing options for the command.
+        attr_accessor :after_options
+
+        # Run after_options hook if present after parsing options.
+        def process_command_options(context, options, argv)
+          super
+          context.instance_exec(argv, options, &after_options) if after_options
+        end
+      end
+    end
+
+    register(:after_options_hook, AfterOptionsHook)
+  end
+end

data/lib/rodish/plugins/cache_help_output.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# The cache_help caches help output when the command is frozen, so
+# it is only calculated once.  This is useful if help output for
+# the command does not depend on external state, and help for the
+# command could be requested multiple times during program runtime.
+
+#
+module Rodish
+  module Plugins
+    module CacheHelpOutput
+      module CommandMethods
+        # Cache and help output when freezing the command.
+        def freeze
+          @help = help.freeze
+          super
+        end
+
+        # Return cached help if it is present.
+        def help
+          @help || super
+        end
+      end
+    end
+
+    register(:cache_help_output, CacheHelpOutput)
+  end
+end

data/lib/rodish/plugins/help_examples.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# The help_examples plugin supports showing examples in help output.
+# By default, examples are shown at the end of the help output, but you
+# can change the order using the help_order method.
+
+#
+module Rodish
+  module Plugins
+    module HelpExamples
+      module DSLMethods
+        # Add an example to show in the help output for the command.
+        def help_example(example)
+          (@command.help_examples ||= []) << example
+        end
+      end
+
+      module CommandMethods
+        # An array of strings for any examples to display in the help.
+        attr_accessor :help_examples
+
+        private
+
+        # The string to use for the examples heading in help output.
+        def help_examples_heading
+          "Examples:"
+        end
+
+        # Include examples at the end of the help text by default.
+        def default_help_order
+          super << :examples
+        end
+
+        def _help_examples(output)
+          if help_examples
+            output << help_examples_heading
+            help_examples.each  do |example|
+              output << "    #{example}"
+            end
+            output << ""
+          end
+        end
+      end
+    end
+
+    register(:help_examples, HelpExamples)
+  end
+end

data/lib/rodish/plugins/help_option_values.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Support showing allowed option values in help output.  The allowed
+# options are wrapped.  The also allows for context-sensitive allowed
+# options, where the allowed options may vary per-call.
+
+require_relative "_context_sensitive_help"
+require_relative "_wrap"
+
+#
+module Rodish
+  module Plugins
+    module HelpOptionValues
+      def self.before_load(app)
+        app.plugin(ContextSensitiveHelp_)
+      end
+
+      # Used to wrap context sensitive option values, when the allowed options
+      # differ depending on the context.
+      class ContextWrappedOptionValues < ContextSensitiveHelp_::ContextHelp
+        def initialize(name, block)
+          @name = name
+          super(block)
+        end
+
+        # Get the allowed values using the provided context, then wrap the values.
+        def call(context)
+          Wrap_.wrap("    #{@name}", super)
+        end
+      end
+
+      module DSLMethods
+        # Add allowed option values to show in help output.
+        def help_option_values(option_name, values=nil, &block)
+          values ||= ContextWrappedOptionValues.new(option_name, block)
+          (@command.help_option_values ||= {})[option_name] = values
+        end
+      end
+
+      module CommandMethods
+        # An hash with option name string keys, and keys that are either
+        # arrays of strings or ContextWrappedOptionValues instances.
+        attr_accessor :help_option_values
+
+        private
+
+        # The string to use for the allowed option values heading in help output.
+        def help_allowed_option_values_heading
+          "Allowed Option Values:"
+        end
+
+        # Include option values after options.
+        def default_help_order
+          order = super
+          index = order.index(:options) || -2
+          order.insert(index+1, :option_values)
+          order
+        end
+
+        # Include allowed options in the help output, if there are any
+        # option values for this command.
+        def _help_option_values(output)
+          if help_option_values
+            output << help_allowed_option_values_heading
+            help_option_values.each do |name, values|
+              if values.is_a?(ContextWrappedOptionValues)
+                output << values
+              else
+                output.concat(Wrap_.wrap("    #{name}", values))
+              end
+            end
+            output << ""
+          end
+        end
+      end
+    end
+
+    register(:help_option_values, HelpOptionValues)
+  end
+end

data/lib/rodish/plugins/help_order.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# The help_order plugin allows overriding the order of help sections in
+# commands:
+#
+#   help_order(:desc, :options)
+#
+# You can provide the default order for help sections using the
+# +default_help_order+ keyword argument:
+#
+#   plugin :help_order, default_help_order: [:usage, :options]
+
+#
+module Rodish
+  module Plugins
+    module HelpOrder
+      def self.after_load(app, default_help_order: nil)
+        if default_help_order
+          app::DSL::Command.class_exec do
+            define_method(:default_help_order){default_help_order.dup}
+            alias_method(:default_help_order, :default_help_order)
+            private(:default_help_order)
+          end
+        end
+      end
+
+      module DSLMethods
+        # Override the order of help sections for the command.
+        def help_order(*sections)
+          @command.help_order = sections
+        end
+      end
+
+      module CommandMethods
+        # The order of sections in returned help. If not set for the
+        # command, uses the default order
+        attr_writer :help_order
+
+        private
+
+        def help_order
+          @help_order || super
+        end
+      end
+    end
+
+    register(:help_order, HelpOrder)
+  end
+end

data/lib/rodish/plugins/invalid_args_message.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# The invalid_args_message plugin allows for using a specific
+# error message when an invalid number of arguments has been
+# passed to a command.
+#
+# You can pass the invalid_args_message keyword argument to the
+# following configuration methods:
+#
+# * args
+# * is
+# * run_is
+
+#
+module Rodish
+  module Plugins
+    module InvalidArgsMessage
+      module DSLMethods
+        # Support setting +invalid_args_message+ when calling +args+.
+        def args(args, **kw)
+          _set_invalid_args_message(kw) do
+            super
+            @command
+          end
+        end
+
+        # Support setting +invalid_args_message+ when calling +is+.
+        def is(command_name, **kw, &block)
+          _set_invalid_args_message(kw) do
+            super
+          end
+        end
+
+        # Support setting +invalid_args_message+ when calling +run_is+.
+        def run_is(command_name, **kw, &block)
+          _set_invalid_args_message(kw) do
+            super
+          end
+        end
+
+        private
+
+        # Remove invalid_args_message from keyword hash, yield to get
+        # the command, then set the invalid_args_message on the command
+        # if it was set.
+        def _set_invalid_args_message(kw)
+          message = kw.delete(:invalid_args_message)
+          command = yield
+          command.invalid_args_message = message if message
+          command
+        end
+      end
+
+      module CommandMethods
+        # The error message to use if an invalid number of
+        # arguments is provided.
+        attr_accessor :invalid_args_message
+
+        private
+
+        # Use invalid_args_message if it has been set.
+        def invalid_num_args_failure_error_message(argv)
+          if @invalid_args_message
+            "invalid arguments#{subcommand_name} (#{@invalid_args_message})"
+          else
+            super
+          end
+        end
+      end
+    end
+
+    register(:invalid_args_message, InvalidArgsMessage)
+  end
+end

data/lib/rodish/plugins/is.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# The is plugin adds an +is+ method as 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+ keyword arguments to specify the number
+# of arguments.
+#
+# This does not allow you to set a command description or usage, so it is
+# not recommended in new code.
+
+#
+module Rodish
+  module Plugins
+    module Is
+      module DSLMethods
+        # 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.
+        def is(command_name, args: 0, &block)
+          _is(:on, command_name, args:, &block)
+        end
+
+        private
+
+        # Internals of +is+.
+        def _is(meth, command_name, args:, &block)
+          public_send(meth, command_name) do
+            args(args)
+            run(&block)
+          end
+        end
+      end
+    end
+
+    register(:is, Is)
+  end
+end

data/lib/rodish/plugins/post_commands.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# The post_commands plugin supports subcommands after arguments,
+# instead of requiring subcommands before arguments.  You can
+# use Command#run to dispatch to post subcommands inside the
+# Command's run block.
+#
+#   run do |argv, opts, command|
+#     @something = argv.shift
+#     command.run(self, opts, argv)
+#   end
+
+#
+module Rodish
+  module Plugins
+    module PostCommands
+      def self.after_load(app)
+        app.command.instance_exec do
+          @post_subcommands ||= {}
+        end
+      end
+
+      module DSLMethods
+        # Set the banner for post subcommand usage.
+        def post_banner(banner)
+          @command.post_banner = banner
+        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_banner = banner
+          @command.post_option_key = key
+          @command.post_option_parser = create_option_parser(&block)
+        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
+
+        # 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
+      end
+
+      module CommandMethods
+        # A hash of post subcommands for the command.  Keys are
+        # post subcommand name strings.
+        attr_reader :post_subcommands
+
+        # 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 usage banner for any post subcommands.
+        attr_accessor :post_banner
+
+        def initialize(command_path)
+          super
+          @post_subcommands = {}
+        end
+
+        # Freeze all post subcommands and the post option parsers in
+        # addition to the command itself.
+        def freeze
+          @post_subcommands.each_value(&:freeze)
+          @post_subcommands.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, self)
+          end
+
+          arg = argv[0]
+          if arg && @post_subcommands[arg]
+            process_subcommand(@post_subcommands, context, options, argv)
+          else
+            process_command_failure(arg, @post_subcommands, "post ")
+          end
+        end
+        alias run_post_subcommand run
+
+        # Also yield each post subcommand, recursively.
+        def each_subcommand(names = [].freeze, &block)
+          super
+          _each_subcommand(names, @post_subcommands, &block)
+        end
+
+        # Also yield the post banner
+        def each_banner
+          super
+          yield post_banner if post_banner
+          nil
+        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
+
+        private
+
+        # The string to use for the post commands heading in help output.
+        def help_post_commands_heading
+          "Post Commands:"
+        end
+
+        # The string to use for the post options heading in help output.
+        def help_post_options_heading
+          "Post Options:"
+        end
+
+        # Include post subcommands as separate help section.
+        def __help_command_hashes
+          hash = super
+          hash[help_post_commands_heading] = @post_subcommands
+          hash
+        end
+
+        # Include post option parser as separate help section.
+        def __help_option_parser_hashes
+          hash = super
+          hash[help_post_options_heading] = @post_option_parser
+          hash
+        end
+
+        # Also yield each local post subcommand to the block.
+        def each_local_subcommand(&block)
+          super
+          _each_local_subcommand(@post_subcommands, &block)
+        end
+      end
+    end
+
+    register(:post_commands, PostCommands)
+  end
+end