run_kit 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1edf6020353f3bdcf0062314c7ff6d6fef8c9277ba77f8210b3bc89c0bf921f8
-  data.tar.gz: a25aab76b2d20c109d2c3422744f7c7294a9efbe88590a0a59a1517767de6bed
+  metadata.gz: 1876301102a9221f5207f024bcd108a95d3547cf96d270f475700959d8209cb6
+  data.tar.gz: b21d96ce661cbe5e45f2de8b6bf9cb1718d2bb7305bce4e15773aa7a9c4882e2
 SHA512:
-  metadata.gz: 16ad6826101160c4f469210857e4194f282a8ad79316a3a993f26d7b02ca00ff49eb067458896eb08aba242edeeab48ee3574660b9d871449b0d44715d61b008
-  data.tar.gz: cdf3e9157ea53b4ba2734224bdaab4bcc15f707e07d76ffc50516b3c2f1f4d80d5f3891247eadfdf82d3056a39f850822952a41906f08ce01269ee99645db165
+  metadata.gz: a82974e7beaa687457ff4b8555e8d1b38a284c89d4ef756755bbccc92c16ff857cdfe9d5083620bb53265d6b04de43d7fdca168559c4bef25ef99c052e98fbae
+  data.tar.gz: 43946b37bb5f6a155b5eb2d27220afa96df7705827db9e0a7ddb4aa5b86f6234629908436cdd288ed20cc8b751c48c413f3441d265cf4c8925de373629f7e99f

data/.rubocop.yml

@@ -35,7 +35,6 @@ Naming/MemoizedInstanceVariableName: { Enabled: true } # clean memo ivars
 Naming/MethodName: { Enabled: true } # keep method names conventional
 Performance/MapCompact: { Enabled: true } # filter_map-ish style
 Performance/RegexpMatch: { Enabled: false } # local style is fine
-Performance/SelectMap: { Enabled: true } # filter_map-ish style
 Style/BlockDelimiters: { Enabled: true } # do/end vs braces
 Style/ClassAndModuleChildren: { Enabled: true, EnforcedStyle: nested } # explicit nesting
 Style/ClassMethodsDefinitions: { Enabled: true } # avoid "class << self"

data/Gemfile

@@ -1,4 +1,4 @@
-source "https://rubygems.org"
+source "https://rubygems.org", cooldown: 7
 gemspec
 
 group :development, :test do

data/README.md

@@ -30,6 +30,15 @@ Automatic `--help` for the above. Uses color and wraps to terminal:
 
 <img width="379" height="108" alt="image" src="https://github.com/user-attachments/assets/3d11c8ca-6b57-4dec-9c11-28bf23162ded" />
 
+Flags can also read from ENV:
+
+```ruby
+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.
+
 ## RunKit::Shell
 
 `RunKit::Shell` is a mixin with many helpers for bin scripts:
@@ -102,6 +111,14 @@ Note: There has been some effort to get the Pathname helpers into Ruby itself, w
 
 ### Changelog
 
+#### 0.1.3 (Sep 2026)
+
+- move PROGBAR constant into RunKit::
+
+#### 0.1.2 (Sep 2026)
+
+- allow options to read from ENV
+
 #### 0.1.1 Sep 2026
 
 - add title to progressbar default

data/lib/run_kit/core_ext.rb

@@ -34,20 +34,15 @@ module RunKit
     # each.with_progresbar
     module Enumerator
       def with_progressbar(options = {}, &block)
-        defaults = {
-          format: "%t: %j%% %B #{RunKit::Term.paint_ansi("%c/%u %e", RunKit::Term.ansi256_fg(242))}",
-          progress_mark: RunKit::Term.paint_ansi("━", RunKit::Term.ansi256_fg(46)),
-          remainder_mark: RunKit::Term.paint_ansi("━", RunKit::Term.ansi256_fg(237)),
+        options = RunKit::PROGRESSBAR.merge(
           output: $stdout.isatty ? $stdout : $stderr,
-          total: size,
-          length: 72,
-        }
-        options = defaults.merge(options)
+          total: size
+        ).merge(options)
 
         return enum_for(__method__) if !block
 
-        if !options[:hide]
-          bar = ProgressBar.create(options)
+        bar = if !options[:hide]
+          ProgressBar.create(options)
         end
         RunKit::Term.with_hidden_cursor(options[:output]) do
           each do

data/lib/run_kit/options/config.rb

@@ -37,28 +37,28 @@ module RunKit
       # flags
       #
 
-      def bool(*opts, default: nil, required: false)
-        add_flag(Flag.new(:bool, opts, default:, required:))
+      def bool(*opts, default: nil, required: false, env: nil)
+        add_flag(Flag.new(:bool, opts, default:, required:, env:))
       end
 
-      def float(*opts, default: nil, required: false, choices: nil)
-        add_flag(Flag.new(:float, opts, default:, required:, choices:))
+      def float(*opts, default: nil, required: false, choices: nil, env: nil)
+        add_flag(Flag.new(:float, opts, default:, required:, choices:, env:))
       end
 
-      def int(*opts, default: nil, required: false, choices: nil)
-        add_flag(Flag.new(:int, opts, default:, required:, choices:))
+      def int(*opts, default: nil, required: false, choices: nil, env: nil)
+        add_flag(Flag.new(:int, opts, default:, required:, choices:, env:))
       end
 
-      def path(*opts, default: nil, required: false, choices: nil)
-        add_flag(Flag.new(:path, opts, default:, required:, choices:))
+      def path(*opts, default: nil, required: false, choices: nil, env: nil)
+        add_flag(Flag.new(:path, opts, default:, required:, choices:, env:))
       end
 
-      def str(*opts, default: nil, required: false, choices: nil)
-        add_flag(Flag.new(:str, opts, default:, required:, choices:))
+      def str(*opts, default: nil, required: false, choices: nil, env: nil)
+        add_flag(Flag.new(:str, opts, default:, required:, choices:, env:))
       end
 
-      def sym(*opts, default: nil, required: false, choices: nil)
-        add_flag(Flag.new(:sym, opts, default:, required:, choices:))
+      def sym(*opts, default: nil, required: false, choices: nil, env: nil)
+        add_flag(Flag.new(:sym, opts, default:, required:, choices:, env:))
       end
 
       # long-form aliases

data/lib/run_kit/options/flag.rb

@@ -12,12 +12,14 @@ module RunKit
       # --no-foo
       NEGATE_RE = /\A--no-(\w[\w-]*)\z/
 
+      TRUE_ENV = %w[1 true yes on]
+      FALSE_ENV = ["", "0", "false", "no", "off"]
       KINDS = %i[bool float int path str sym]
 
-      attr_reader :choices, :default, :help, :kind, :meta, :required, :switches
+      attr_reader(*%i[choices default env help kind meta required switches])
 
       # ctor
-      def initialize(kind, opts, default: nil, required: false, choices: nil)
+      def initialize(kind, opts, default: nil, required: false, choices: nil, env: nil)
         @choices, @kind, @required = choices, kind, required
 
         # extract @help from last string
@@ -28,6 +30,7 @@ module RunKit
 
         # Extract meta from the final switch, if written as `--port <int>`.
         @meta = build_meta
+        @env = (env == true) ? key.to_s.upcase : env
 
         # default, with some special handling for bool
         @default = default
@@ -50,22 +53,21 @@ module RunKit
         end
 
         raise Error, "option '#{switch}' requires a value" if !param
-        parsed = begin
-          case kind
-          when :float then Float(param)
-          when :int then Integer(param, 10)
-          when :path then Pathname.new(param)
-          when :str then param
-          when :sym then param.to_sym
-          end
-        rescue ArgumentError
-          raise Error, "invalid value '#{param}' for option '#{switch}'"
-        end
+        parse_value(param, "option '#{switch}'")
+      end
 
-        if choices && !choices.include?(parsed)
-          raise Error, "invalid value '#{parsed}' for option '#{switch}', must be one of #{choices.join(", ")}"
+      # Parse a value supplied by ENV[$SOMETHING]
+      def parse_env(param)
+        source = "environment variable '#{env}'"
+
+        # special handling for bools
+        if bool?
+          return true if TRUE_ENV.include?(param.downcase)
+          return false if FALSE_ENV.include?(param.downcase)
+          raise Error, "invalid value '#{param}' for #{source}"
         end
-        parsed
+
+        parse_value(param, source)
       end
 
       # one-liners
@@ -96,6 +98,7 @@ module RunKit
         raise ArgumentError, "required must be true or false" unless required == true || required == false
         raise ArgumentError, "required flags cannot have defaults" if required && default != nil
         raise ArgumentError, "invalid default #{default.inspect} for #{kind}" if default != nil && !allowed?(default)
+        raise ArgumentError, "env must be true or a string" unless env.nil? || env.is_a?(String)
 
         # choices
         if choices
@@ -130,6 +133,25 @@ module RunKit
         when :sym then candidate.is_a?(Symbol)
         end
       end
+
+      def parse_value(param, source)
+        parsed = begin
+          case kind
+          when :float then Float(param)
+          when :int then Integer(param, 10)
+          when :path then Pathname.new(param)
+          when :str then param
+          when :sym then param.to_sym
+          end
+        rescue ArgumentError
+          raise Error, "invalid value '#{param}' for #{source}"
+        end
+
+        if choices && !choices.include?(parsed)
+          raise Error, "invalid value '#{parsed}' for #{source}, must be one of #{choices.join(", ")}"
+        end
+        parsed
+      end
     end
   end
 end

data/lib/run_kit/options/help.rb

@@ -36,10 +36,15 @@ module RunKit
           buf << label
 
           # right
-          if flag.help
+          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(flag.help, width - indent).gsub("\n", "\n#{" " * indent}")
+            buf << Term.wrap(help, width - indent).gsub("\n", "\n#{" " * indent}")
           end
           buf << "\n"
         end

data/lib/run_kit/options/parser.rb

@@ -6,7 +6,7 @@
 module RunKit
   module Options
     class Parser
-      attr_reader :config, :options, :queue
+      attr_reader :config
 
       def initialize(config)
         @config = config
@@ -14,9 +14,24 @@ module RunKit
 
       # Reset transient state, parse argv, and assemble the result.
       def parse(argv)
-        @options, @queue = config.defaults, argv.dup
-        parse_queue
-        validate!
+        # 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)
+
+        # 3. defaults => ENV => ARGV
+        options = {}.merge(config.defaults, parse_env, argv_options)
+
+        # 4. validate final options
+        validate!(options)
+
+        # success! add predicate? keys
+        config.flags.select(&:bool?).map(&:key).each do
+          options[:"#{_1}?"] = options[_1] if options.key?(_1)
+        end
+
         options
       end
 
@@ -26,42 +41,36 @@ module RunKit
       # main parser
       #
 
-      def parse_queue
-        raise NakedRequested if config.naked? && queue.empty?
-
-        # any non-flags we find below
-        operands = []
-
-        # process argv as queue
-        while (item = queue.shift)
-          case item
-          when Flag::SWITCH_RE, Flag::INLINE_RE then parse_switch(item, Regexp.last_match)
-          when /\A-[^-]/ then parse_smashed(item)
-          when "", /\A[^-]/ then operands << item
-          when "--" then break operands.concat(queue)
-          else; raise Error, "unexpected argument '#{item}' found"
+      def parse_argv(argv)
+        {}.tap do |result|
+          # any non-flags we find below
+          operands = []
+
+          # process argv as queue
+          queue = argv.dup
+          while (item = queue.shift)
+            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 "--" then break operands.concat(queue)
+            else; raise Error, "unexpected argument '#{item}' found"
+            end
           end
-        end
 
-        # add pred? for bools
-        config.flags.filter_map { _1.key if _1.bool? }.each do
-          options[:"#{_1}?"] = options[_1] if options.key?(_1)
-        end
+          # positionals
+          config.positionals.each { result[_1.key] = operands.shift }
 
-        # positionals
-        config.positionals.each do
-          options[_1.key] = operands.shift
+          # _args
+          result[:_args] = operands
         end
-
-        # _args
-        options[:_args] = operands
       end
 
       #
       # -x or -x=123 or --xyz or --xyz=123 or --no-xyz
       #
 
-      def parse_switch(item, match)
+      def parse_switch(item, match, queue)
         switch = "-#{match[1]}"
         param = match[2]
         separator = param ? "=" : ""
@@ -70,15 +79,13 @@ module RunKit
         if (flag = config.flag(switch))
           builtin!(flag)
           param = queue.shift if flag.takes_param? && separator.empty?
-          options[flag.key] = flag.parse(switch, param)
-          return
+          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 == "="
-          options[neg.key] = false
-          return
+          return {neg.key => false}
         end
 
         raise Error, "unexpected argument '#{item}' found"
@@ -90,7 +97,8 @@ module RunKit
 
       # Expand short-switch groups such as `-qv`. A parameter-taking switch ends
       # the group and consumes either its attached suffix or the next queue item.
-      def parse_smashed(group)
+      def parse_smashed(group, queue)
+        result = {}
         (1...group.length).each do |idx|
           switch = "-#{group[idx]}"
           flag = config.flag(switch)
@@ -104,13 +112,24 @@ module RunKit
             else
               queue.shift
             end
-            options[flag.key] = flag.parse(switch, param)
-            return
+            result[flag.key] = flag.parse(switch, param)
+            return result
           end
 
           # bool
-          options[flag.key] = true
+          result[flag.key] = true
         end
+        result
+      end
+
+      #
+      # env
+      #
+
+      def parse_env
+        config.flags.select { _1.env && ENV.key?(_1.env) }.map do |flag|
+          [flag.key, flag.parse_env(ENV[flag.env])]
+        end.to_h
       end
 
       #
@@ -129,7 +148,7 @@ module RunKit
         end
       end
 
-      def validate!
+      def validate!(options)
         config.required.each do
           raise Error, "required option '#{_1.switch}' is missing" if !options.key?(_1.key)
         end

data/lib/run_kit.rb

@@ -16,7 +16,14 @@ require_relative "run_kit/term"
 require_relative "run_kit/options"
 require_relative "run_kit/shell"
 
-# handy entry point for RunKit::Options
 module RunKit
+  PROGRESSBAR = {
+    format: "%t: %j%% %B #{Term.paint_ansi("%c/%u %e", Term.ansi256_fg(242))}",
+    progress_mark: Term.paint_ansi("━", Term.ansi256_fg(46)),
+    remainder_mark: Term.paint_ansi("━", Term.ansi256_fg(237)),
+    length: 72,
+  }
+
+  # handy entry point for RunKit::Options
   def self.parse(...) = Options.parse(...)
 end

data/run_kit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "run_kit"
-  s.version = "0.1.1"
+  s.version = "0.1.3"
   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.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Adam Doppelt