rodish 1.1.0 → 2.0.0

data/lib/rodish/plugins/run_is.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# The run_is plugin adds a +run_is+ method that is similar to +is+,
+# but adds a post subcommand instead of a regular subcommand.
+#
+# This does not allow you to set a command description or usage, so it is
+# not recommended in new code.
+#
+# This plugin depends on the is and post_commands plugins.
+
+#
+module Rodish
+  module Plugins
+    module RunIs
+      def self.before_load(app)
+        app.plugin :is
+        app.plugin :post_commands
+      end
+
+      module DSLMethods
+        # Similar to +is+, but for post subcommands instead of normal
+        # subcommands.
+        def run_is(command_name, args: 0, &block)
+          _is(:run_on, command_name, args:, &block)
+        end
+      end
+    end
+
+    register(:run_is, RunIs)
+  end
+end
+

data/lib/rodish/plugins/skip_option_parsing.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# The skip_option_parsing plugin allows skipping option parsing
+# for a command, treating all elements of argv as arguments instead
+# of options. This is different than the default behavior, where
+# all options use will fail by default (as no options are supported
+# by default.
+#
+# After loading the plugin, when configuring the command, you can
+# call skip_options_parsing with the usage banner:
+#
+#   skip_options_parsing("usage banner")
+
+#
+module Rodish
+  module Plugins
+    module SkipOptionParsing
+      module DSLMethods
+        # 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.banner = banner
+          @command.option_parser = :skip
+        end
+      end
+
+      module CommandMethods
+        private
+
+        # Do not process options if the option parser is set to skip.
+        def process_options(argv, options, option_key, option_parser)
+          super unless option_parser == :skip
+        end
+
+        # Whether the given option parser should be ommitted from the
+        # command help output.
+        def omit_option_parser_from_help?(parser)
+          super || parser == :skip
+        end
+      end
+    end
+
+    register(:skip_option_parsing, SkipOptionParsing)
+  end
+end

data/lib/rodish/plugins/usages.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# The usages plugin adds the #usages method to the Rodish processor.
+# This returns a hash for the command help for all commands and subcommands
+# of the processor.
+
+#
+module Rodish
+  module Plugins
+    module Usages
+      module ProcessorMethods
+        # 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 help for the command.
+        def usages
+          usages = {}
+
+          command.each_subcommand do |names, command|
+            usages[names.join(" ")] = command.help
+          end
+
+          usages
+        end
+      end
+    end
+
+    register(:usages, Usages)
+  end
+end

data/lib/rodish/plugins/wrapped_options_separator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# The wrapped_options_separator plugin adds wrap to the option
+# parser, which includes a separator with wrapped content.
+
+require_relative "_wrap"
+
+#
+module Rodish
+  module Plugins
+    module WrappedOptionsSeparator
+      module OptionParserMethods
+        include Wrap_
+
+        # 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)
+          super.each do |line|
+            separator line
+          end
+        end
+      end
+    end
+
+    register(:wrapped_options_separator, WrappedOptionsSeparator)
+  end
+end

data/lib/rodish/plugins.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rodish
+  MUTEX = Mutex.new
+  private_constant :MUTEX
+
+  # Hash of symbol keys to module values for registered rodish plugins.
+  PLUGINS = {}
+  private_constant :PLUGINS
+
+  # Namespace for Rodish plugins.  Plugins do not have to be in this
+  # namespace, but this is what plugins that ship with Rodish use.
+  module Plugins
+    # Load a Rodish plugin.  +name+ should be a symbol.
+    def self.fetch(name)
+      MUTEX.synchronize{PLUGINS[name]}
+    end
+
+    # Register a Rodish plugin.  +name+ should be a symbol, and +mod+
+    # should be a module.
+    def self.register(name, mod)
+      MUTEX.synchronize{PLUGINS[name] = mod}
+    end
+  end
+end

data/lib/rodish/processor.rb

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
 require_relative "dsl"
+require_relative "plugins"
 
 module Rodish
   module Processor
+    # The root command for the processor.
     attr_reader :command
 
+    # Load a plugin into the current processor.
+    def plugin(name, ...)
+      mod = load_plugin(name)
+
+      unless mod.respond_to?(:before_load) || mod.respond_to?(:after_load)
+        _plugin_without_before_or_after_load_check(...)
+      end
+
+      mod.before_load(self, ...) if mod.respond_to?(:before_load)
+      extend(mod::ProcessorMethods) if defined?(mod::ProcessorMethods)
+      self::DSL.include(mod::DSLMethods) if defined?(mod::DSLMethods)
+      self::DSL::Command.include(mod::CommandMethods) if defined?(mod::CommandMethods)
+      self::DSL::OptionParser.include(mod::OptionParserMethods) if defined?(mod::OptionParserMethods)
+      mod.after_load(self, ...) if mod.respond_to?(:after_load)
+      nil
+    end
+
     # 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.
@@ -16,8 +35,6 @@ module Rodish
       # 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
@@ -28,8 +45,11 @@ module Rodish
     # block.
     def on(*command_names, &block)
       if block
-        command_name = command_names.pop
-        dsl(command_names).on(command_name, &block)
+        if command_name = command_names.pop
+          dsl(command_names).on(command_name, &block)
+        else
+          dsl(command_names).instance_exec(&block)
+        end
       else
         dsl(command_names)
       end
@@ -37,43 +57,55 @@ module Rodish
 
     # 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)
+    def is(*command_names, command_name, **kw, &block)
+      dsl(command_names).is(command_name, **kw, &block)
     end
 
-    # Freeze the command when freezing the object.
+    # Freeze the command and classes related to the processor when freezing the processor.
     def freeze
       command.freeze
+      self::DSL.freeze
+      self::DSL::Command.freeze
+      self::DSL::OptionParser.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 = {}
+    private
+
+    def _plugin_without_before_or_after_load_check
+      raise ArgumentError, "plugin doesn't support block" if defined?(yield)
+    end
 
-      command.each_subcommand do |names, command|
-        option_parsers = command.option_parsers
-        unless option_parsers.empty?
-          usages[names.join(" ")] = command.option_parsers.join("\n\n")
+    # Load the rodish plugin with the given name, which can be either a module
+    # (used directly), or a symbol (which will load a registered plugin), requiring
+    # the related plugin file if it is not already registered.
+    def load_plugin(name)
+      case name
+      when Module
+        name
+      when Symbol
+        unless mod = Rodish::Plugins.fetch(name)
+          require "rodish/plugins/#{name}"
+          unless mod = Rodish::Plugins.fetch(name)
+            raise RuntimeError, "rodish plugin did not properly register itself: #{name.inspect}"
+          end
         end
-      end
 
-      usages
+        mod
+      else
+        raise ArgumentError, "invalid argument to plugin: #{name.inspect}"
+      end
     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)
+        command = command.subcommand(name)
       end
-      DSL.new(command)
+      self::DSL.new(command)
     end
   end
 end

data/lib/rodish.rb

@@ -9,7 +9,22 @@ module Rodish
   # using Rodish::DSL.
   def self.processor(klass, &block)
     klass.extend(Processor)
-    klass.instance_variable_set(:@command, DSL.command([].freeze, &block))
+
+    dsl_class = Class.new(DSL)
+    klass.const_set(:DSL, dsl_class)
+
+    command_class = Class.new(Command)
+    dsl_class.const_set(:Command, command_class)
+
+    option_parser_class = Class.new(OptionParser)
+    dsl_class.const_set(:OptionParser, option_parser_class)
+
+    option_parser = option_parser_class.new
+    option_parser.set_banner("")
+    option_parser.freeze
+    command_class.const_set(:DEFAULT_OPTION_PARSER, option_parser)
+
+    klass.instance_variable_set(:@command, dsl_class.command([].freeze, &block))
     klass
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rodish
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jeremy Evans
 bindir: bin
 cert_chain: []
-date: 2025-03-04 00:00:00.000000000 Z
+date: 2025-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: optparse
@@ -60,21 +60,31 @@ 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/plugins.rb
+- lib/rodish/plugins/_context_sensitive_help.rb
+- lib/rodish/plugins/_wrap.rb
+- lib/rodish/plugins/after_options_hook.rb
+- lib/rodish/plugins/cache_help_output.rb
+- lib/rodish/plugins/help_examples.rb
+- lib/rodish/plugins/help_option_values.rb
+- lib/rodish/plugins/help_order.rb
+- lib/rodish/plugins/invalid_args_message.rb
+- lib/rodish/plugins/is.rb
+- lib/rodish/plugins/post_commands.rb
+- lib/rodish/plugins/run_is.rb
+- lib/rodish/plugins/skip_option_parsing.rb
+- lib/rodish/plugins/usages.rb
+- lib/rodish/plugins/wrapped_options_separator.rb
 - lib/rodish/processor.rb
-- lib/rodish/skip_option_parser.rb
-homepage: http://github.com/jeremyevans/rodish
+homepage: https://rodish.jeremyevans.net/
 licenses:
 - MIT
 metadata:
@@ -87,8 +97,6 @@ rdoc_options:
 - "--inline-source"
 - "--title"
 - 'Rodish: Routing tree argv parser'
-- "--main"
-- README.rdoc
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement

data/CHANGELOG

@@ -1,7 +0,0 @@
-=== 1.1.0 (2025-03-03)
-
-* Support after_options method for a block called after options processing (jeremyevans)
-
-=== 1.0.0 (2025-02-27)
-
-* Initial Public Release

data/README.rdoc

@@ -1,265 +0,0 @@
-= 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. This is not called if an invalid subcommand is requested and there
-is no run block for the command.
-
-== +after_options+
-
-The +after_options+ method takes a block, and this block is executed
-directly after options parsing, 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/skip_option_parser.rb

@@ -1,19 +0,0 @@
-# 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