run_kit 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1876301102a9221f5207f024bcd108a95d3547cf96d270f475700959d8209cb6
-  data.tar.gz: b21d96ce661cbe5e45f2de8b6bf9cb1718d2bb7305bce4e15773aa7a9c4882e2
+  metadata.gz: 957080dc55365e15529d2077974586f3239ac02d04d8b2ef6f568ca126ed22a5
+  data.tar.gz: 92beadf93985edeac07cc957b66fea237a55f29e4c7db97e43eecfd214eda91e
 SHA512:
-  metadata.gz: a82974e7beaa687457ff4b8555e8d1b38a284c89d4ef756755bbccc92c16ff857cdfe9d5083620bb53265d6b04de43d7fdca168559c4bef25ef99c052e98fbae
-  data.tar.gz: 43946b37bb5f6a155b5eb2d27220afa96df7705827db9e0a7ddb4aa5b86f6234629908436cdd288ed20cc8b751c48c413f3441d265cf4c8925de373629f7e99f
+  metadata.gz: 5ff6d38e709d6412237e499a8df5f3388d133fa56dcd57c66bc89355da4c419273203ae3264acb54dcf569a232d0d8321753821c1b20e599e9480d497d9d0228
+  data.tar.gz: 9999afdfe9bda8cf5903cb695a59b26c387401e5d21732e107977100b0873a35c9c2b6bfdb38fa309fcfa3642922050f5ebd809229d57db22f7d5422b75601a5

data/README.md

@@ -6,10 +6,10 @@ RunKit is a small toolkit for cli. It provides option parsing, shell and file he
 
 ```ruby
 # install gem
-$ gem install run_key
+$ gem install run_kit
 
 # or add to your Gemfile
-gem "run_key"
+gem "run_kit"
 ```
 
 ## RunKit::Options
@@ -37,7 +37,28 @@ o.bool "--force", env: true              # ENV["FORCE"]
 o.str "--token", env: "API_TOKEN"        # ENV["API_TOKEN"]
 ```
 
-Configured variables appear in `--help`. Command-line values override ENV, which overrides defaults. Boolean ENV values accept `true/1/yes/on` and `false/0/no/off/empty`, ignoring case.
+Custom validation:
+
+```ruby
+o.validate = lambda do |options|
+  raise "--count must be positive" if options.count <= 0
+end
+```
+
+Also supports subcommands, `git`-style:
+
+```ruby
+o.bool "-n", "--dry-run"
+o.cmd "build", "Build the project" do |c|
+  c.str "--target <target>", default: "release"
+end
+o.cmd "test", "Run tests" do |c|
+  c.bool "--verbose"
+end
+
+# myapp build --target debug
+# => #<data command="build", dry_run=false, target="debug", _args=[]>
+```
 
 ## RunKit::Shell
 
@@ -48,7 +69,7 @@ Configured variables appear in `--help`. Command-line values override ENV, which
 | `csv_read` / `csv_write`       | Read/write CSV (add .gz for gzip)                   |
 | `file_read` / `file_write`     | Atomic read/write files (add .gz for gzip)          |
 | `json_read` / `json_write`     | Atomic read/write json (add .gz for gzip)           |
-| `jsonl_read / `jsonl_write`    | Atomic read/write jsonl (add .gz for gzip)          |
+| `jsonl_read` / `jsonl_write`   | Atomic read/write jsonl (add .gz for gzip)          |
 |                                |
 | `csv_write_stdout`             | Write CSV to stdout                                 |
 | `gunzip` / `gzip`              | (De)compress a string                               |
@@ -66,7 +87,7 @@ Configured variables appear in `--help`. Command-line values override ENV, which
 |                                |
 | `banner` / `warning` / `fatal` | Pretty banner in green, orange or red (fatal exits) |
 | `program_name`                 | Return executable name                              |
-| `prompt?`                      | Ask use for confirmation                            |
+| `prompt?`                      | Ask user for confirmation                           |
 | `md5` / `sha256`               | Hash strings                                        |
 
 ### RunKit CoreExt
@@ -111,6 +132,11 @@ Note: There has been some effort to get the Pathname helpers into Ruby itself, w
 
 ### Changelog
 
+#### 0.1.4 (Sep 2026)
+
+- add subcommand support (`o.cmd`)
+- add custom validation (`o.validate`)
+
 #### 0.1.3 (Sep 2026)
 
 - move PROGBAR constant into RunKit::

data/demo.rb

@@ -3,9 +3,21 @@
 require_relative "lib/run_kit"
 
 options = RunKit.parse do |o|
-  o.int "-n", "--count <n>", "How many times to run", default: 1
-  o.str "--mode <mode>", "Run quickly, or not", choices: %w[fast slow]
-  o.positional "<url>", "url to fetch"
+  o.version = "1.0"
+  o.bool "--dry-run", "Preview without making changes"
+  o.desc = "this is made up"
+
+  o.cmd "fetch", "Fetch a URL" do |c|
+    c.int "-n", "--count <n>", "How many times to run", default: 1
+    c.str "--mode <mode>", "Run quickly, or not", choices: %w[fast slow]
+    c.positional "<url>", "URL to fetch"
+  end
+
+  o.cmd "build", "Build the project" do |c|
+    c.naked = false
+    c.str "--target <target>", "Build target", choices: %w[debug release], default: "release"
+    c.bool "--force", "Force a rebuild", env: "DEMO_FORCE"
+  end
 end
 
 p options

data/lib/run_kit/options/config.rb

@@ -6,15 +6,17 @@
 module RunKit
   module Options
     class Config
-      attr_accessor :app_name, :banner, :color, :exit, :help, :naked, :version
-      attr_reader :flags, :help_flag, :lookup, :positionals, :separators, :version_flag
+      attr_accessor :banner, :color, :desc, :exit, :help, :naked, :root, :validate, :version
+      attr_reader :help_flag, :name, :version_flag
       alias_method :naked?, :naked
 
-      def initialize
-        @app_name = File.basename($PROGRAM_NAME)
+      def initialize(name: nil)
         @naked = true
-        @lookup = {}
-        @flags, @positionals, @separators = [], [], []
+        self.name = name || Shell.program_name
+      end
+
+      def name=(name)
+        @name = name.to_s
       end
 
       # Add a positional param declared as `<url>`.
@@ -26,6 +28,18 @@ module RunKit
         end
       end
 
+      # Add a subcommand with its own nested Config, eg `myapp build`.
+      def cmd(name, desc = nil)
+        name = name.to_s
+        raise ArgumentError, "duplicate command #{name}" if commands.key?(name)
+        Config.new(name:).tap do
+          _1.desc, _1.root = desc, self
+          yield _1 if block_given?
+          raise ArgumentError, "nested commands are not supported" if _1.commands.any?
+          commands[name] = _1
+        end
+      end
+
       # Add separator text at the current point in generated help.
       def sep(text = "")
         [flags.length, text].tap do
@@ -62,7 +76,9 @@ module RunKit
       end
 
       # long-form aliases
+      alias_method :app_name=, :name=
       alias_method :boolean, :bool
+      alias_method :command, :cmd
       alias_method :integer, :int
       alias_method :pathname, :path
       alias_method :positional, :pos
@@ -81,27 +97,38 @@ module RunKit
       # one-liners
       def flag(switch) = lookup[switch]
       def flag?(switch) = lookup.key?(switch)
+      def full_name = root ? "#{root.full_name} #{name}" : name
       def key?(key) = lookup.key?(key)
       def required = flags.select(&:required?)
 
+      # memoized accessors
+      def commands = @commands ||= {}
+      def flags = @flags ||= []
+      def lookup = @lookup ||= {}
+      def positionals = @positionals ||= []
+      def separators = @separators ||= []
+
       # Complete one-time setup after the caller has declared overrides.
       def prepare!
         return if @prepared
         @prepared = true
+
+        # Children inherit shared settings before adding builtins.
+        if root
+          self.color, self.exit, self.version = root.color, root.exit, root.version
+        end
+
+        # now defaults
         @exit ||= lambda { |status| Kernel.exit(status) }
-        @help_flag = add_builtin(["-h", "--help"], "Show this message")
-        @version_flag = add_builtin(["-v", "--version"], "Show version") if version
+        @help_flag = bool("-h", "--help", "Show this message")
+        @version_flag = bool("-v", "--version", "Show version") if version
+
+        # setup subcommands
+        commands.each_value(&:prepare!)
       end
 
       protected
 
-      # Add help/version flags, but only for switches the user did not override.
-      def add_builtin(switches, help_text)
-        unused = switches.select { !flag?(_1) }
-        return if unused.empty?
-        add_flag(Flag.new(:bool, unused + [help_text]))
-      end
-
       def add_flag(flag)
         # dup check
         raise ArgumentError, "reserved flag key: _args" if flag.key == :_args

data/lib/run_kit/options/help.rb

@@ -18,65 +18,88 @@ module RunKit
       # Render generated help, unless the caller supplied complete help text.
       def to_s
         return config.help if config.help
+        help = [].tap do
+          _1 << desc if config.desc
+          _1 << banner
+          _1 << commands_text if config.commands.any?
+          _1 << flags_text(config, "Options:", builtins: !config.root)
+          _1 << flags_text(config.root, "Other options:") if config.root
+        end.compact.join("\n\n")
+        "#{help}\n"
+      end
 
-        # usage: xyz (banner)
-        buf = StringIO.new
-        buf << banner
-        buf << "\n"
-        buf << "\n" if config.separators.any? { _1.first.zero? }
+      # Render a heading and aligned flags, preserving explicit separator lines.
+      def flags_text(source, title, builtins: true)
+        # gather flags
+        flags = source.flags
+        flags -= [source.help_flag, source.version_flag] unless builtins
+        return if flags.empty? && source.separators.empty?
 
-        # Render each flag with aligned switch labels and wrapped help text.
-        label_width = widest_label
-        config.flags.each.with_index do |flag, idx|
-          buf << separator_text(idx) # sep
+        [].tap do |lines|
+          lines << color.blue(title)
+          label_width = flags.map { Term.width(flag_label(_1)) }.max
+          flags.each.with_index do |flag, idx|
+            lines.concat(separator_lines(source, idx))
+            buf = StringIO.new
 
-          # left
-          label = flag_label(flag)
-          buf << " " * INDENT
-          buf << label
+            # left
+            label = flag_label(flag)
+            buf << " " * INDENT
+            buf << label
 
-          # right
-          help = flag.help
-          if flag.env
-            env_help = "[env: #{flag.env}]"
-            help = help ? "#{help} #{env_help}" : env_help
-          end
-          if help
-            buf << " " * (label_width - Term.width(label) + 2)
-            indent = INDENT + label_width + 2
-            buf << Term.wrap(help, width - indent).gsub("\n", "\n#{" " * indent}")
+            # right
+            help = flag.help
+            if flag.env
+              env_help = "[env: #{flag.env}]"
+              help = help ? "#{help} #{env_help}" : env_help
+            end
+            if help
+              buf << " " * (label_width - Term.width(label) + 2)
+              indent = INDENT + label_width + 2
+              buf << Term.wrap(help, width - indent).gsub("\n", "\n#{" " * indent}")
+            end
+            lines << buf.string
           end
-          buf << "\n"
-        end
-        buf << separator_text(config.flags.length)
-
-        buf.string
+          lines.concat(separator_lines(source, flags.length))
+        end.join("\n")
       end
 
-      # Build the usage line from the configured app name and positionals.
+      # Build the usage line from the command's full name and positionals.
       def banner
         text = config.banner
-        text ||= [color.blue("Usage:"), color.green(config.app_name), "[options]"].tap do
+        text ||= [color.blue("Usage:"), color.green(config.full_name), "[options]"].tap do
           _1.push(*config.positionals.map(&:meta))
+          _1.push(color.yellow("<command>")) if config.commands.any?
         end.join(" ")
         Term.wrap(text, width)
       end
 
-      # Render separator text at its recorded position between flags.
-      def separator_text(position)
-        StringIO.new.tap do |buf|
-          config.separators.each do |(pos, str)|
-            if pos == position
-              buf << color.blue(str)
-              buf << "\n"
-            end
+      # Render the list of subcommands, aligned like the flag list above.
+      def commands_text
+        [].tap do |lines|
+          lines << color.blue("Commands:")
+          label_width = config.commands.keys.map { Term.width(_1) }.max
+          config.commands.each do |name, child|
+            lines << StringIO.new.tap do |buf|
+              buf << " " * INDENT << color.green(name)
+              if child.desc
+                buf << " " * (label_width - Term.width(name) + 2)
+                indent = INDENT + label_width + 2
+                buf << Term.wrap(child.desc, width - indent).gsub("\n", "\n#{" " * indent}")
+              end
+            end.string
           end
-        end.string
+        end.join("\n")
+      end
+
+      # Keep blank and multiline separators exactly as supplied.
+      def separator_lines(source, position)
+        source.separators.filter_map { |pos, str| color.blue(str) if pos == position }
       end
 
       # one-liners
       def color = @color ||= Color.new(config.color)
-      def widest_label = config.flags.map { Term.width(flag_label(_1)) }.max
+      def desc = Term.wrap(config.desc, width)
 
       protected
 

data/lib/run_kit/options/main.rb

@@ -16,67 +16,125 @@
 # | meta       | placeholder shown for a param      | <xxx> from `--port <xxx>` |
 # | positional | configured required param slot     | o.positional "<url>"      |
 # | separator  | help section heading               | "Network:"                |
+# | command    | subcommand with its own Config     | o.cmd "build" { ... }     |
 #
 
 module RunKit
   module Options
     class Main
-      attr_reader :config
+      # root is the top-level config; ctx is the active parser or validator's config.
+      attr_reader :ctx, :root
 
-      def initialize = @config = Config.new
-      def app_name = config.app_name
+      def initialize = @root = Config.new
 
       # Parse argv and turn internal parser outcomes into CLI behavior.
       def parse(argv)
-        config.prepare!
+        @ctx = root
+        root.prepare!
+
+        # handle --help and --version
+        return exit_fn(0) if early_exit?(argv)
 
         begin
-          options = Parser.new(config).parse(argv)
+          options = root.commands.empty? ? parse_with_ctx(root, argv) : subcommand(argv)
           klass = Data.define(*options.keys)
-          klass.new(**options)
-        rescue Error => ex
-          warn "#{app_name}: #{ex.message}"
-          warn "#{app_name}: try '#{app_name} --help' for more information"
-          exit_fn(1, error: ex.message)
-        rescue HelpRequested, NakedRequested, VersionRequested => ex
-          early_exit(ex)
-          exit_fn(0)
+          klass.new(**options).tap { validate(_1) }
+        rescue Error, NakedRequested => ex
+          handle_error(ex)
         end
       end
 
       protected
 
-      def early_exit(ex)
-        case ex
-        when HelpRequested
-          puts Help.new(config)
-        when NakedRequested
-          puts "#{app_name}: try '#{app_name} --help' for more information"
-        when VersionRequested
-          puts "#{app_name} #{config.version}"
+      # Handle --help or --version
+      def early_exit?(argv)
+        if argv.include?("--help") || argv.include?("-h")
+          selected = root.commands[argv.first] || root
+          puts Help.new(selected)
+          return true
+        end
+        if root.version && (argv.include?("--version") || argv.include?("-v"))
+          puts "#{root.name} #{root.version}"
+          return true
+        end
+      end
+
+      # Peek at the first bare argument to pick a subcommand, then parse the
+      # rest with its own Config and merge the two option hashes together.
+      def subcommand(argv)
+        # Parse root options before the subcommand.
+        root_options = parse_with_ctx(root, argv, passthru: true)
+        name, *rest = root_options[:_args]
+        raise NakedRequested if !name
+
+        # Find and parse the child.
+        child = root.commands[name]
+        raise Error, "unknown command '#{name}'" if !child
+        child_options = parse_with_ctx(child, rest)
+
+        # merge
+        root_options.merge(child_options).merge(command: name)
+      end
+
+      # Validate the final options, root first.
+      def validate(options)
+        [ctx.root, ctx].compact.each do
+          validate_with_ctx(_1, options)
+        rescue RuntimeError => ex
+          raise Error, ex.message
         end
       end
 
+      # Render the outcome using the active context.
+      def handle_error(ex)
+        if ex.is_a?(Error)
+          warn "#{ctx.full_name}: #{ex.message}"
+          warn "#{ctx.full_name}: try '#{ctx.full_name} --help' for more information"
+          return exit_fn(1, error: ex.message)
+        end
+
+        puts Help.new(ctx)
+        exit_fn(0)
+      end
+
       def exit_fn(status, error: nil)
         args = [].tap do
           _1 << status
-          _1 << error if config.exit.arity == 2
+          _1 << error if root.exit.arity == 2
         end
-        config.exit.call(*args)
+        root.exit.call(*args)
         nil
       end
+
+      #
+      # Keep the active config after a failure so the outer rescue can use it.
+      # This is error context, not a push/pop command stack.
+      #
+
+      def with_ctx(ctx)
+        @ctx = ctx
+        yield
+      end
+
+      def parse_with_ctx(ctx, argv, passthru: false)
+        with_ctx(ctx) do
+          Parser.new(ctx).parse(argv, passthru:)
+        end
+      end
+
+      def validate_with_ctx(ctx, options)
+        with_ctx(ctx) do
+          ctx.validate&.call(options)
+        end
+      end
     end
 
     class Error < StandardError; end
-
-    # early exits
-    class HelpRequested < Exception; end # rubocop:disable Lint/InheritException
     class NakedRequested < Exception; end # rubocop:disable Lint/InheritException
-    class VersionRequested < Exception; end # rubocop:disable Lint/InheritException
 
     # main entry point
     def self.parse(argv = ARGV)
-      Main.new.tap { yield _1.config if block_given? }.parse(argv)
+      Main.new.tap { yield _1.root if block_given? }.parse(argv)
     end
   end
 end

data/lib/run_kit/options/parser.rb

@@ -12,14 +12,14 @@ module RunKit
         @config = config
       end
 
-      # Reset transient state, parse argv, and assemble the result.
-      def parse(argv)
+      # Reset transient state, parse argv, and assemble the result. When
+      # passthru is set, scanning halts at the first bare arg (for subcommands).
+      def parse(argv, passthru: false)
         # 1. naked?
         raise NakedRequested if config.naked? && argv.empty?
 
-        # 2. Parse argv. We do this first, because other things can raise and
-        # --help should trump other issues.
-        argv_options = parse_argv(argv)
+        # 2. Parse argv.
+        argv_options = parse_argv(argv, passthru:)
 
         # 3. defaults => ENV => ARGV
         options = {}.merge(config.defaults, parse_env, argv_options)
@@ -41,7 +41,7 @@ module RunKit
       # main parser
       #
 
-      def parse_argv(argv)
+      def parse_argv(argv, passthru: false)
         {}.tap do |result|
           # any non-flags we find below
           operands = []
@@ -52,7 +52,12 @@ module RunKit
             case item
             when Flag::SWITCH_RE, Flag::INLINE_RE then result.merge!(parse_switch(item, Regexp.last_match, queue))
             when /\A-[^-]/ then result.merge!(parse_smashed(item, queue))
-            when "", /\A[^-]/ then operands << item
+            when "", /\A[^-]/
+              operands << item
+              if passthru
+                operands.concat(queue)
+                break
+              end
             when "--" then break operands.concat(queue)
             else; raise Error, "unexpected argument '#{item}' found"
             end
@@ -77,7 +82,6 @@ module RunKit
 
         # -x or --xyz?
         if (flag = config.flag(switch))
-          builtin!(flag)
           param = queue.shift if flag.takes_param? && separator.empty?
           return {flag.key => flag.parse(switch, param)}
         end
@@ -103,7 +107,6 @@ module RunKit
           switch = "-#{group[idx]}"
           flag = config.flag(switch)
           raise Error, "unexpected argument '#{group}' found" unless flag
-          builtin!(flag)
 
           # For `-qnLee`, `Lee` belongs to `-n`; for `-qn Lee`, shift the queue.
           if flag.takes_param?
@@ -136,11 +139,6 @@ module RunKit
       # helpers
       #
 
-      def builtin!(flag)
-        raise HelpRequested if flag == config.help_flag
-        raise VersionRequested if flag == config.version_flag
-      end
-
       def find_negated_flag(switch)
         if (m = Flag::NEGATE_RE.match(switch))
           flag = config.flag("--#{m[1]}")

data/lib/run_kit/shell.rb

@@ -29,9 +29,9 @@ module RunKit
     # json file read/write, including gz
     #
 
-    def json_read(path, symbolize_names: true) = JSON.parse(file_read(path), symbolize_names:)
+    def json_read(path, symbolize_names: true) = JSON.parse(file_read(path), allow_comments: true, symbolize_names:)
     def json_write(path, json) = file_write(path, JSON.pretty_generate(json))
-    def jsonl_read(path, symbolize_names: true) = file_read(path).split("\n").map { JSON.parse(_1, symbolize_names:) }
+    def jsonl_read(path, symbolize_names: true) = file_read(path).split("\n").map { JSON.parse(_1, allow_comments: true, symbolize_names:) }
     def jsonl_write(path, json) = file_write(path, json.map { JSON.generate(_1) }.join("\n"))
 
     #
@@ -262,8 +262,8 @@ module RunKit
       data = gunzip(data) if compress
       case format
       when :bin then data.force_encoding("ascii-8bit")
-      when :json then JSON.parse(data)
-      when :jsonl then data.split("\n").map { JSON.parse(_1) }
+      when :json then JSON.parse(data, allow_comments: true)
+      when :jsonl then data.split("\n").map { JSON.parse(_1, allow_comments: true) }
       when :marshal then Marshal.load(data)
       when :str, :string then data.force_encoding("utf-8")
       else; raise "unknown format #{format.inspect}"

data/run_kit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "run_kit"
-  s.version = "0.1.3"
+  s.version = "0.1.4"
   s.authors = ["Adam Doppelt"]
   s.email = "amd@gurge.com"
   s.summary = "Run kit."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: run_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Adam Doppelt
@@ -87,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Run kit.
 test_files: []