run_kit 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d199e66b4f3d3fc9d3316baed91dc47ee182dde5d7cc229b4522069cc11de05a
-  data.tar.gz: f80d68b84e9d02d450d95a78282e1b7785defe8ebf50a951d2e95e606349bd56
+  metadata.gz: 88bb49c39cde1b38476bad542e725026bf1709aecd58ed4ffd676a1367a87faf
+  data.tar.gz: 016eed022444cb2aa2fbfeaf213eceee7259fabdf920bde34a7500d60f79ff46
 SHA512:
-  metadata.gz: 66a535125d24e6a1b5c609c096e525d14a5c43c35a35a5011439a4edc8ed68b45860ed955ad242bbf4cb2642e060dc3d41d042cc7d9cb5528cf445c9ecb2ce71
-  data.tar.gz: a4d76419621604a84efbaf0d99cf84591b181a9a04398773ecc29905b8856b87e74032b7d6c03dc68ba47d657cdd5aa5e6c11e3dfaa4c3f8e6910874e0ac48d2
+  metadata.gz: 82159e72865bd71a9d6d696e2c7276e3b5051b82217093e68381ebbd051ef8faeaff9f53debefd09c4b71f4c77c20f335e20ab489aef6e3785a756d7bbfe9b1e
+  data.tar.gz: 5a38d4bb77f1e2a7440c69ebdf435a55e58a772c401f0756c1fea0cdbc9a8aaf8d429e739a846213927b4d300825c8e0ee13347e7ed325883ea8355e955449ca

data/README.md

@@ -58,10 +58,15 @@ o.cmd "test", "Run tests" do |c|
   c.bool "--verbose"
 end
 
-# myapp build --target debug
-# => #<data command="build", dry_run=false, target="debug", _args=[]>
+# myapp build --dry-run --target debug
+# => #<data command="build", dry_run=true, target="debug", _args=[]>
 ```
 
+Put the command first, then global or command flags in any order. If the first
+argument isn't a command, a `default: true` command receives all arguments.
+Root positionals aren't supported with subcommands; global and command flags
+must have distinct switches and keys.
+
 ## RunKit::Shell
 
 `RunKit::Shell` is a mixin with many helpers for bin scripts:
@@ -74,7 +79,9 @@ end
 | `jsonl_read` / `jsonl_write`   | Atomic read/write jsonl (add .gz for gzip)          |
 |                                |
 | `csv_write_stdout`             | Write CSV to stdout                                 |
+| `csv_write_to_s`               | Generate CSV string                                 |
 | `gunzip` / `gzip`              | (De)compress a string                               |
+|                                |
 | `atomic_write`                 | Atomically replace a file                           |
 | `cache_fetch`                  | Populate/fetch from file cache w/ block             |
 | `cp_metadata`                  | Copy file metadata from src to dst                  |
@@ -132,8 +139,19 @@ RunKit also installs a small set of core extensions to assist with bin scripts.
 
 Note: There has been some effort to get the Pathname helpers into Ruby itself, without much success.
 
+### Future Work
+
+- argv? ask nak for ideas
+
 ### Changelog
 
+#### 0.1.6 (Sep 2026)
+
+- default subcommands with `default: true`
+- `<url...>` positionals for 1+ values
+- remove `naked` and just do the right thing
+- add `csv_write_to_s` for CSV string output
+
 #### 0.1.5 (Sep 2026)
 
 - after some investigation, decided that naked should default to false

data/demo.rb

@@ -6,18 +6,23 @@ options = RunKit.parse do |o|
   o.version = "1.0"
   o.bool "--dry-run", "Preview without making changes"
   o.desc = "this is made up"
+  o.str "--gub"
 
-  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"
+  o.cmd("sub", default: true) do
+    _1.pos "<pos...>"
   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
+  # 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,12 +6,11 @@
 module RunKit
   module Options
     class Config
-      attr_accessor :banner, :color, :desc, :exit, :help, :naked, :root, :validate, :version
-      attr_reader :help_flag, :name, :version_flag
-      alias_method :naked?, :naked
+      attr_accessor :banner, :color, :default, :desc, :exit, :help, :root, :validate, :version
+      attr_reader(*%i[help_flag name version_flag])
+      alias_method :default?, :default
 
       def initialize(name: nil)
-        @naked = false
         self.name = name || Shell.program_name
       end
 
@@ -21,6 +20,10 @@ module RunKit
 
       # Add a positional param declared as `<url>`.
       def pos(meta, help = "")
+        check_inside!
+        if positionals.last&.variadic?
+          raise ArgumentError, "no positional arguments are allowed after #{positionals.last.meta}"
+        end
         Positional.new(meta:, help:).tap do
           raise ArgumentError, "duplicate positional #{_1.key}" if key?(_1.key)
           positionals << _1
@@ -29,19 +32,22 @@ module RunKit
       end
 
       # Add a subcommand with its own nested Config, eg `myapp build`.
-      def cmd(name, desc = nil)
+      def cmd(name, desc = nil, default: false)
+        check_inside!
         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
+        raise ArgumentError, "default command already set" if default && default_command
+        Config.new(name:).tap do |child|
+          child.default, child.desc, child.root = default, desc, self
+          with_inside(name) { yield child } if block_given?
+          raise ArgumentError, "nested commands are not supported" if child.commands.any?
+          commands[name] = child
         end
       end
 
       # Add separator text at the current point in generated help.
       def sep(text = "")
+        check_inside!
         [flags.length, text].tap do
           separators << _1
         end
@@ -95,11 +101,9 @@ module RunKit
       end
 
       # one-liners
-      def flag(switch) = lookup[switch]
-      def flag?(switch) = lookup.key?(switch)
+      def default_command = commands.values.find(&:default?)
       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 ||= {}
@@ -111,6 +115,9 @@ module RunKit
       # Complete one-time setup after the caller has declared overrides.
       def prepare!
         return if @prepared
+        if commands.any? && positionals.any?
+          raise ArgumentError, "a command with subcommands cannot also take positional arguments; add them to a subcommand instead"
+        end
         @prepared = true
 
         # Children inherit shared settings before adding builtins.
@@ -123,18 +130,38 @@ module RunKit
         @help_flag = bool("-h", "--help", "Show this message")
         @version_flag = bool("-v", "--version", "Show version") if version
 
+        # Global and command flags share one parser; only builtins may overlap.
+        if root
+          keys = lookup.keys - [help_flag, version_flag].compact.flat_map { [_1.key, *_1.switches] }
+          collisions = keys & root.lookup.keys
+          raise ArgumentError, "command #{name} conflicts with global options: #{collisions.join(", ")}" if collisions.any?
+        end
+
         # setup subcommands
         commands.each_value(&:prepare!)
       end
 
       protected
 
+      # Catch accidental use of the outer config while defining a command.
+      def with_inside(name)
+        @inside = name
+        yield
+      ensure
+        @inside = nil
+      end
+
+      def check_inside!
+        raise ArgumentError, "you're adding a root option inside #{@inside.inspect} command" if @inside
+      end
+
       def add_flag(flag)
+        check_inside!
         # dup check
         raise ArgumentError, "reserved flag key: _args" if flag.key == :_args
         raise ArgumentError, "dup flag key: #{flag.key}" if key?(flag.key)
         flag.switches.each do
-          raise ArgumentError, "dup flag switch: #{_1}" if flag?(_1)
+          raise ArgumentError, "dup flag switch: #{_1}" if key?(_1)
         end
 
         # append

data/lib/run_kit/options/flag.rb

@@ -9,8 +9,6 @@ module RunKit
       SWITCH_RE = /\A-(\w|-\w[\w-]*)\z/
       # --foo=bar
       INLINE_RE = /\A-(\w|-\w[\w-]*)=(.*)\z/m
-      # --no-foo
-      NEGATE_RE = /\A--no-(\w[\w-]*)\z/
 
       TRUE_ENV = %w[1 true yes on]
       FALSE_ENV = ["", "0", "false", "no", "off"]
@@ -30,6 +28,7 @@ module RunKit
 
         # Extract meta from the final switch, if written as `--port <int>`.
         @meta = build_meta
+        validate_switches!
         @env = (env == true) ? key.to_s.upcase : env
 
         # default, with some special handling for bool
@@ -39,6 +38,9 @@ module RunKit
         end
 
         validate
+      rescue ArgumentError => ex
+        ctx = reconstruct(kind, opts, default:, required:, choices:, env:)
+        raise ArgumentError, "#{ctx} - #{ex.message}", cause: nil
       end
 
       #
@@ -83,15 +85,16 @@ module RunKit
       # validation
       #
 
-      def validate
-        # switches
-        raise ArgumentError, "at least one switch is required" if switches.empty?
+      def validate_switches!
         switches.each do
           raise ArgumentError, "invalid switch: #{_1}" unless _1.is_a?(String)
           raise ArgumentError, "invalid switch: #{_1}" unless _1.match?(SWITCH_RE)
         end
+        raise ArgumentError, 'flag must start with "-" or "--"' if switches.empty?
         raise ArgumentError, "duplicate switch" unless switches.uniq.length == switches.length
+      end
 
+      def validate
         # params
         raise ArgumentError, "invalid flag kind: #{kind}" unless KINDS.include?(kind)
         raise ArgumentError, "boolean flags do not accept meta" if bool? && meta
@@ -114,6 +117,12 @@ module RunKit
       # helpers
       #
 
+      # Use the original declaration, before metadata and ENV normalization.
+      def reconstruct(kind, opts, **settings)
+        args = opts.map(&:inspect) + settings.filter_map { "#{_1}: #{_2.inspect}" if _2 }
+        ["opt.#{kind}", args.join(", ")].reject(&:empty?).join(" ")
+      end
+
       def build_meta
         # Only the final spelling may carry an inferred `<meta>`.
         if (m = /\A(\S+) <([^>]+)>\z/.match(switch))

data/lib/run_kit/options/help.rb

@@ -18,12 +18,13 @@ module RunKit
       # Render generated help, unless the caller supplied complete help text.
       def to_s
         return config.help if config.help
+        options = flags_text(config, "Options:", builtins: !config.root)
         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
+          _1 << options
+          _1 << flags_text(config.root, options ? "Other options:" : "Options:") if config.root
         end.compact.join("\n\n")
         "#{help}\n"
       end
@@ -67,19 +68,22 @@ module RunKit
       # Build the usage line from the command's full name and positionals.
       def banner
         text = config.banner
-        text ||= [color.blue("Usage:"), color.green(config.full_name), "[options]"].tap do
-          _1.push(*config.positionals.map(&:meta))
+        text ||= [color.blue("Usage:"), color.green(config.full_name)].tap do
           _1.push(color.yellow("<command>")) if config.commands.any?
+          _1.push("[options]", *config.positionals.map { |pos| color.yellow(pos.meta) })
         end.join(" ")
         Term.wrap(text, width)
       end
 
       # Render the list of subcommands, aligned like the flag list above.
       def commands_text
+        commands = config.commands.map do |name, child|
+          [child.default? ? "#{name} (default)" : name, child]
+        end
         [].tap do |lines|
           lines << color.blue("Commands:")
-          label_width = config.commands.keys.map { Term.width(_1) }.max
-          config.commands.each do |name, child|
+          label_width = commands.map { Term.width(_1.first) }.max
+          commands.each do |name, child|
             lines << StringIO.new.tap do |buf|
               buf << " " * INDENT << color.green(name)
               if child.desc

data/lib/run_kit/options/main.rb

@@ -39,7 +39,7 @@ module RunKit
           options = root.commands.empty? ? parse_with_ctx(root, argv) : subcommand(argv)
           klass = Data.define(*options.keys)
           klass.new(**options).tap { validate(_1) }
-        rescue Error, NakedRequested => ex
+        rescue Error, HelpRequested => ex
           handle_error(ex)
         end
       end
@@ -59,21 +59,23 @@ module RunKit
         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.
+      # Select from the first argument, then parse global and command flags 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)
+        rest = argv
+        if (child = root.commands[rest.first])
+          rest = rest.drop(1)
+          infer_help = false
+        else
+          child = root.default_command
+          infer_help = true
+        end
+        raise HelpRequested if !child && rest.empty?
+        if !child
+          switch = rest.first.start_with?("--") ? rest.first.split("=", 2).first : rest.first[0, 2]
+          raise Error, "global options must follow the command" if root.key?(switch)
+          raise Error, "unknown command '#{rest.first}'"
+        end
+        parse_with_ctx(child, rest, infer_help:).merge(command: child.name)
       end
 
       # Validate the final options, root first.
@@ -93,7 +95,8 @@ module RunKit
           return exit_fn(1, error: ex.message)
         end
 
-        puts Help.new(ctx)
+        # Inferred help on a bare invocation introduces the whole app.
+        puts Help.new(root)
         exit_fn(0)
       end
 
@@ -116,9 +119,9 @@ module RunKit
         yield
       end
 
-      def parse_with_ctx(ctx, argv, passthru: false)
+      def parse_with_ctx(ctx, argv, infer_help: true)
         with_ctx(ctx) do
-          Parser.new(ctx).parse(argv, passthru:)
+          Parser.new(ctx).parse(argv, infer_help:)
         end
       end
 
@@ -130,7 +133,7 @@ module RunKit
     end
 
     class Error < StandardError; end
-    class NakedRequested < Exception; end # rubocop:disable Lint/InheritException
+    class HelpRequested < Exception; end # rubocop:disable Lint/InheritException
 
     # main entry point
     def self.parse(argv = ARGV)

data/lib/run_kit/options/parser.rb

@@ -6,29 +6,27 @@
 module RunKit
   module Options
     class Parser
-      attr_reader :config
+      attr_reader(*%i[config flags lookup])
 
       def initialize(config)
         @config = config
+        @flags = config.root ? (config.root.flags - [config.root.help_flag, config.root.version_flag]) + config.flags : config.flags
+        @lookup = (config.root&.lookup || {}).merge(config.lookup)
       end
 
-      # 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?
+      # Parse global and command flags together, then assemble the result.
+      def parse(argv, infer_help: true)
+        # 1. Parse argv.
+        argv_options = parse_argv(argv)
 
-        # 2. Parse argv.
-        argv_options = parse_argv(argv, passthru:)
+        # 2. defaults => ENV => ARGV
+        options = {}.merge(config.root&.defaults || {}, config.defaults, parse_env, argv_options)
 
-        # 3. defaults => ENV => ARGV
-        options = {}.merge(config.defaults, parse_env, argv_options)
-
-        # 4. validate final options
-        validate!(options)
+        # 3. Validate requirements after ENV resolution; bare missing inputs show help.
+        validate!(options, infer_help: infer_help && argv.empty?)
 
         # success! add predicate? keys
-        config.flags.select(&:bool?).map(&:key).each do
+        flags.select(&:bool?).map(&:key).each do
           options[:"#{_1}?"] = options[_1] if options.key?(_1)
         end
 
@@ -41,10 +39,10 @@ module RunKit
       # main parser
       #
 
-      def parse_argv(argv, passthru: false)
+      def parse_argv(argv)
         {}.tap do |result|
           # any non-flags we find below
-          operands = []
+          args = []
 
           # process argv as queue
           queue = argv.dup
@@ -53,45 +51,37 @@ module RunKit
             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[^-]/
-              operands << item
-              if passthru
-                operands.concat(queue)
-                break
-              end
-            when "--" then break operands.concat(queue)
+              args << item
+            when "--" then break args.concat(queue)
             else; raise Error, "unexpected argument '#{item}' found"
             end
           end
 
           # positionals
-          config.positionals.each { result[_1.key] = operands.shift }
+          config.positionals.each { result[_1.key] = _1.variadic? ? args.shift(args.length) : args.shift }
+          if config.positionals.any? && args.any?
+            raise Error, "unexpected argument '#{args.first}' found"
+          end
 
           # _args
-          result[:_args] = operands
+          result[:_args] = args
         end
       end
 
       #
-      # -x or -x=123 or --xyz or --xyz=123 or --no-xyz
+      # -x or -x=123 or --xyz or --xyz=123
       #
 
       def parse_switch(item, match, queue)
         switch = "-#{match[1]}"
         param = match[2]
-        separator = param ? "=" : ""
 
         # -x or --xyz?
-        if (flag = config.flag(switch))
-          param = queue.shift if flag.takes_param? && separator.empty?
+        if (flag = lookup[switch])
+          param = queue.shift if flag.takes_param? && !param
           return {flag.key => flag.parse(switch, param)}
         end
 
-        # --no-xyz?
-        if (neg = find_negated_flag(switch))
-          raise Error, "option '#{item}' does not take a value" if separator == "="
-          return {neg.key => false}
-        end
-
         raise Error, "unexpected argument '#{item}' found"
       end
 
@@ -105,7 +95,7 @@ module RunKit
         result = {}
         (1...group.length).each do |idx|
           switch = "-#{group[idx]}"
-          flag = config.flag(switch)
+          flag = lookup[switch]
           raise Error, "unexpected argument '#{group}' found" unless flag
 
           # For `-qnLee`, `Lee` belongs to `-n`; for `-qn Lee`, shift the queue.
@@ -130,7 +120,7 @@ module RunKit
       #
 
       def parse_env
-        config.flags.select { _1.env && ENV.key?(_1.env) }.map do |flag|
+        flags.select { _1.env && ENV.key?(_1.env) }.map do |flag|
           [flag.key, flag.parse_env(ENV[flag.env])]
         end.to_h
       end
@@ -139,19 +129,17 @@ module RunKit
       # helpers
       #
 
-      def find_negated_flag(switch)
-        if (m = Flag::NEGATE_RE.match(switch))
-          flag = config.flag("--#{m[1]}")
-          flag if flag&.bool?
-        end
-      end
-
-      def validate!(options)
-        config.required.each do
-          raise Error, "required option '#{_1.switch}' is missing" if !options.key?(_1.key)
+      def validate!(options, infer_help: false)
+        # Infer help only for missing inputs, after ENV has been resolved.
+        flags.select(&:required?).each do
+          next if options.key?(_1.key)
+          raise HelpRequested if infer_help
+          raise Error, "required option '#{_1.switch}' is missing"
         end
         config.positionals.each do
-          raise Error, "required argument '#{_1.meta}' is missing" if !options[_1.key]
+          next if _1.variadic? ? options[_1.key].any? : options[_1.key]
+          raise HelpRequested if infer_help
+          raise Error, "required argument '#{_1.meta}' is missing"
         end
       end
     end

data/lib/run_kit/options/positional.rb

@@ -1,11 +1,11 @@
 #
-# A required positional param like `<url>`.
+# A required positional param like `<url>` or `<url...>`.
 #
 
 module RunKit
   module Options
     class Positional
-      POSITIONAL_RE = /\A<([A-Z]\w*)>\z/i
+      POSITIONAL_RE = /\A<([A-Z]\w*)(\.\.\.)?>\z/i
 
       attr_reader :help, :meta
 
@@ -13,11 +13,14 @@ module RunKit
         @help, @meta = help, meta
         raise ArgumentError, "positional help must be a string" unless help.is_a?(String)
         raise ArgumentError, "positional meta must be a string" unless meta.is_a?(String)
-        raise ArgumentError, "positional must use <meta>" unless POSITIONAL_RE.match?(meta)
+        unless POSITIONAL_RE.match?(meta)
+          raise ArgumentError, "invalid positional #{meta.inspect}; wrap the argument name in angle brackets, e.g. o.pos(\"<url>\", \"URL to fetch\")"
+        end
       end
 
       # one-liners
       def key = @key ||= POSITIONAL_RE.match(meta)[1].to_sym
+      def variadic? = meta.end_with?("...>")
     end
   end
 end

data/lib/run_kit/shell.rb

@@ -78,6 +78,10 @@ module RunKit
       CSV($stdout) { _csv_write0(_1, rows, headers:) }
     end
 
+    def csv_write_to_s(rows, headers: nil)
+      CSV.generate { _csv_write0(_1, rows, headers:) }
+    end
+
     #
     # shell/shell!
     #

data/run_kit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "run_kit"
-  s.version = "0.1.5"
+  s.version = "0.1.6"
   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.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Adam Doppelt
@@ -88,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Run kit.
 test_files: []