philiprehberger-cli_kit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c09f7a9f76769c7ecf089942c9594ba1f6d09ce3a992c4def928fe68551eeee3
-  data.tar.gz: c9cf6608c8fb9da1ea27ea7d8afa19654f1323ea0a4ed97f6a31ed18c4a49e6b
+  metadata.gz: 15240e9c9eb6ad374dafd6457c91e3d1514b34031ccb57f00b4283b266bf3575
+  data.tar.gz: 77fd549d9211ab095433cebe4938db8fd1188e1cffb124c19c91a77e5ce428a8
 SHA512:
-  metadata.gz: 3c8fd3284baffd888ab79d3c39264e2e7cb742e51ab5de8411526e21dbc282321d1f2c937e58646a2230b24cfb4cc4219f4fbb9ff10755a4de6a3980c02a00ac
-  data.tar.gz: 7029600e08a0001ca9ca5b0fed28150ce33cf09bfbbe799685d736d92f30695ba23095a86a9e06458e16c0a842bfc10a0690c08faf08797568f3bf74b8828c3b
+  metadata.gz: b18bf81377d13116b703b5938d8e0b6c84e18272570d1f0eb2b598f125d80d0f603298735445873445882e073d504c25694313c7604157b907817c908b71417f
+  data.tar.gz: 636957466367093c8cdd87305abcffb8523633182e513223f50898d876e3c93e2d3dab4c0a1290350c344d8f6d04d53f66cce5b097b609990e4907f10a54d931

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-15
+
+### Added
+- Repeatable options via `option :name, multi: true` — collects each occurrence into an array
+- `CliKit.password(message)` — prompt that reads input without echoing when stdin is a TTY (falls back to plain `gets` otherwise)
+- `CliKit.ask(message)` — prompt that re-asks until a validator block returns truthy (defaults to any non-empty answer)
+- `CliKit.multi_select(message, choices, defaults:)` — numbered menu supporting comma- or space-separated multi-selection
+- Help text now shows `VALUE (repeatable)` for `multi: true` options
+
+### Changed
+- VERSION spec no longer hardcodes the version string; asserts semver format instead
+
+## [0.2.1] - 2026-03-31
+
+### Changed
+- Standardize README badges, support section, and license format
+
 ## [0.2.0] - 2026-03-30
 
 ### Added
@@ -40,3 +57,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Yes/no confirmation prompt
 - Animated spinner for long-running operations
 - Positional argument collection
+
+[Unreleased]: https://github.com/philiprehberger/rb-cli-kit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/philiprehberger/rb-cli-kit/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/philiprehberger/rb-cli-kit/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/philiprehberger/rb-cli-kit/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/philiprehberger/rb-cli-kit/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/philiprehberger/rb-cli-kit/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/philiprehberger/rb-cli-kit/releases/tag/v0.1.0

data/README.md

@@ -2,12 +2,7 @@
 
 [![Tests](https://github.com/philiprehberger/rb-cli-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-cli-kit/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-cli_kit.svg)](https://rubygems.org/gems/philiprehberger-cli_kit)
-[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-cli-kit)](https://github.com/philiprehberger/rb-cli-kit/releases)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-cli-kit)](https://github.com/philiprehberger/rb-cli-kit/commits/main)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-cli-kit)](LICENSE)
-[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-cli-kit/bug)](https://github.com/philiprehberger/rb-cli-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
-[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-cli-kit/enhancement)](https://github.com/philiprehberger/rb-cli-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
-[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 All-in-one CLI toolkit with argument parsing, prompts, and spinners
 
@@ -90,6 +85,37 @@ confirmed = Philiprehberger::CliKit.confirm('Continue?')
 # Continue? [y/n] _
 ```
 
+### Password Prompt
+
+```ruby
+secret = Philiprehberger::CliKit.password('Enter password:')
+# Enter password: _
+# Input is read without echoing to the terminal when stdin is a TTY.
+```
+
+### Validated Ask
+
+```ruby
+# Without a block, any non-empty answer is accepted.
+name = Philiprehberger::CliKit.ask('Name:')
+
+# With a block, the prompt repeats until the block returns a truthy value.
+port = Philiprehberger::CliKit.ask('Port:', error: 'Must be a number') do |answer|
+  answer.match?(/\A\d+\z/)
+end
+```
+
+### Repeatable Options
+
+```ruby
+result = Philiprehberger::CliKit.parse(ARGV) do
+  option :tag, short: :t, multi: true, desc: 'Add a tag (repeatable)'
+end
+
+# Invoked as: mycli --tag ruby --tag cli -t kit
+result.options[:tag]   # => ["ruby", "cli", "kit"]
+```
+
 ### Menu Selection
 
 ```ruby
@@ -108,6 +134,26 @@ env = Philiprehberger::CliKit.select('Choose env:', %w[dev staging prod], defaul
 #   Choose [2]: _
 ```
 
+### Multi-Select Menu
+
+```ruby
+tags = Philiprehberger::CliKit.multi_select('Pick tags:', %w[ruby cli dsl testing])
+#   Pick tags:
+#       1) ruby
+#       2) cli
+#       3) dsl
+#       4) testing
+#   Choose (comma-separated): 1,3
+# => ["ruby", "dsl"]
+
+tags = Philiprehberger::CliKit.multi_select('Pick tags:', %w[ruby cli dsl], defaults: %w[ruby dsl])
+#   Pick tags:
+#     * 1) ruby
+#       2) cli
+#     * 3) dsl
+#   Choose (comma-separated): _   # empty answer => defaults
+```
+
 ### Spinners
 
 ```ruby
@@ -124,10 +170,14 @@ end
 | `.parse(args) { ... }` | Parse arguments with flag/option/command DSL |
 | `.prompt(message)` | Display prompt and read input |
 | `.confirm(message)` | Display yes/no confirmation |
-| `.select(message, choices)` | Present numbered menu and return selection |
+| `.password(message)` | Read input without echoing to the terminal |
+| `.ask(message) { \|answer\| ... }` | Prompt until block returns truthy (defaults to non-empty) |
+| `.select(message, choices)` | Present numbered menu and return one selection |
+| `.multi_select(message, choices, defaults:)` | Present numbered menu and return multiple selections |
 | `.spinner(message) { ... }` | Show spinner during block execution |
+| `Parser#option(name, multi: true)` | Collect repeated option values into an array |
 | `Parser#flags` | Hash of boolean flag values |
-| `Parser#options` | Hash of option values |
+| `Parser#options` | Hash of option values (arrays when `multi: true`) |
 | `Parser#arguments` | Array of positional arguments |
 | `Parser#command` | Matched subcommand name or nil |
 | `Parser#help_text` | Formatted help string |
@@ -143,10 +193,21 @@ bundle exec rubocop
 
 ## Support
 
-If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-cli-kit)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-cli-kit/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-cli-kit/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
 
-[![LinkedIn](https://img.shields.io/badge/Philip%20Rehberger-LinkedIn-0A66C2?logo=linkedin)](https://www.linkedin.com/in/philiprehberger)
-[![More packages](https://img.shields.io/badge/more-open%20source%20packages-blue)](https://philiprehberger.com/open-source-packages)
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
 
 ## License
 

data/lib/philiprehberger/cli_kit/menu.rb

@@ -43,6 +43,47 @@ module Philiprehberger
           choices.first
         end
       end
+
+      # Present a numbered menu and allow multiple selections.
+      #
+      # The user enters a comma- or space-separated list of numbers (e.g.
+      # "1,3" or "1 3"). Unknown or out-of-range entries are ignored, and
+      # duplicates are collapsed. An empty answer returns +defaults+ or an
+      # empty array if no defaults are given.
+      #
+      # @param message [String] the prompt message
+      # @param choices [Array<String>] the list of choices
+      # @param defaults [Array<String>] choices pre-selected by default
+      # @param input [IO] input stream (default: $stdin)
+      # @param output [IO] output stream (default: $stdout)
+      # @return [Array<String>] the selected values in choice order
+      # @raise [ArgumentError] if choices is empty
+      def self.multi_select(message, choices, defaults: [], input: $stdin, output: $stdout)
+        raise ArgumentError, 'choices must not be empty' if choices.empty?
+
+        default_indexes = defaults.map { |d| choices.index(d) }.compact
+
+        output.puts message
+        choices.each_with_index do |choice, idx|
+          marker = default_indexes.include?(idx) ? '*' : ' '
+          output.puts "  #{marker} #{idx + 1}) #{choice}"
+        end
+
+        output.print 'Choose (comma-separated): '
+        output.flush
+
+        answer = input.gets&.strip || ''
+        return defaults.dup if answer.empty?
+
+        picks = answer.split(/[,\s]+/).filter_map do |token|
+          idx = Integer(token, 10) - 1
+          idx if idx >= 0 && idx < choices.length
+        rescue ArgumentError
+          nil
+        end
+
+        picks.uniq.sort.map { |i| choices[i] }
+      end
     end
   end
 end

data/lib/philiprehberger/cli_kit/parser.rb

@@ -34,10 +34,11 @@ module Philiprehberger
       # @param short [Symbol, nil] short alias (single character)
       # @param default [Object, nil] default value
       # @param desc [String, nil] description for help text
+      # @param multi [Boolean] when true, collect repeated values into an array
       # @return [void]
-      def option(name, short: nil, default: nil, desc: nil)
-        @option_definitions[name] = { short: short, default: default, desc: desc }
-        @options[name] = default
+      def option(name, short: nil, default: nil, desc: nil, multi: false)
+        @option_definitions[name] = { short: short, default: default, desc: desc, multi: multi }
+        @options[name] = multi ? [] : default
       end
 
       # Define a subcommand or return the matched command name.
@@ -147,7 +148,7 @@ module Philiprehberger
         if @flag_definitions.key?(name)
           @flags[name] = true
         elsif @option_definitions.key?(name)
-          @options[name] = args.shift
+          assign_option(name, args.shift)
         end
       end
 
@@ -163,12 +164,22 @@ module Philiprehberger
 
         @option_definitions.each do |name, defn|
           if defn[:short] == char
-            @options[name] = args.shift
+            assign_option(name, args.shift)
             return
           end
         end
       end
 
+      def assign_option(name, value)
+        defn = @option_definitions[name]
+        if defn && defn[:multi]
+          @options[name] = [] unless @options[name].is_a?(Array)
+          @options[name] << value unless value.nil?
+        else
+          @options[name] = value
+        end
+      end
+
       def format_flag_help(name, defn)
         long = "--#{name.to_s.tr('_', '-')}"
         if defn[:short]
@@ -185,7 +196,8 @@ module Philiprehberger
       end
 
       def format_option_help(name, defn)
-        long = "--#{name.to_s.tr('_', '-')} VALUE"
+        placeholder = defn[:multi] ? 'VALUE (repeatable)' : 'VALUE'
+        long = "--#{name.to_s.tr('_', '-')} #{placeholder}"
         if defn[:short]
           short = "-#{defn[:short]}"
           label = "  #{short}, #{long}"

data/lib/philiprehberger/cli_kit/prompt.rb

@@ -28,6 +28,66 @@ module Philiprehberger
         answer = input.gets&.strip&.downcase || ''
         %w[y yes].include?(answer)
       end
+
+      # Display a prompt and read input without echoing characters to the terminal.
+      #
+      # When the input stream responds to +noecho+ (a real TTY), echo is disabled
+      # for the duration of the read. When it does not (e.g. a +StringIO+ during
+      # tests), input is read normally. A trailing newline is printed to the
+      # output after the read so the next prompt starts on its own line.
+      #
+      # @param message [String] the prompt message
+      # @param input [IO] input stream (default: $stdin)
+      # @param output [IO] output stream (default: $stdout)
+      # @return [String] the user's input, stripped of whitespace
+      def self.password(message, input: $stdin, output: $stdout)
+        output.print "#{message} "
+        output.flush
+
+        raw = if input.respond_to?(:noecho)
+                begin
+                  input.noecho(&:gets)
+                rescue IOError, Errno::ENOTTY
+                  input.gets
+                end
+              else
+                input.gets
+              end
+
+        output.print "\n"
+        output.flush
+        raw&.strip || ''
+      end
+
+      # Display a prompt and read input, repeating until it passes validation.
+      #
+      # The block is called with the stripped input; when it returns a truthy
+      # value the input is accepted and returned. When it returns a falsy value
+      # an optional +error+ message is printed and the user is prompted again.
+      # When no block is given, any non-empty input is accepted.
+      #
+      # @param message [String] the prompt message
+      # @param error [String] the message shown on invalid input
+      # @param input [IO] input stream (default: $stdin)
+      # @param output [IO] output stream (default: $stdout)
+      # @yieldparam answer [String] the stripped user input
+      # @yieldreturn [Boolean] whether the answer is acceptable
+      # @return [String] the accepted user input
+      def self.ask(message, error: 'Invalid input, please try again.', input: $stdin, output: $stdout, &block)
+        validator = block || ->(answer) { !answer.empty? }
+
+        loop do
+          output.print "#{message} "
+          output.flush
+          raw = input.gets
+          return '' if raw.nil?
+
+          answer = raw.strip
+          return answer if validator.call(answer)
+
+          output.puts error
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/cli_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CliKit
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/cli_kit.rb

@@ -49,6 +49,29 @@ module Philiprehberger
       Prompt.confirm(message, input: input, output: output)
     end
 
+    # Display a prompt and read input without echoing to the terminal.
+    #
+    # @param message [String] the prompt message
+    # @param input [IO] input stream
+    # @param output [IO] output stream
+    # @return [String] the user's input
+    def self.password(message, input: $stdin, output: $stdout)
+      Prompt.password(message, input: input, output: output)
+    end
+
+    # Display a prompt, re-asking until the answer satisfies the given block.
+    #
+    # @param message [String] the prompt message
+    # @param error [String] error message shown on invalid input
+    # @param input [IO] input stream
+    # @param output [IO] output stream
+    # @yieldparam answer [String] the stripped user input
+    # @yieldreturn [Boolean] whether the answer is acceptable
+    # @return [String] the accepted user input
+    def self.ask(message, error: 'Invalid input, please try again.', input: $stdin, output: $stdout, &block)
+      Prompt.ask(message, error: error, input: input, output: output, &block)
+    end
+
     # Display a spinner while executing a block.
     #
     # @param message [String] the spinner message
@@ -70,5 +93,17 @@ module Philiprehberger
     def self.select(message, choices, default: nil, input: $stdin, output: $stdout)
       Menu.select(message, choices, default: default, input: input, output: output)
     end
+
+    # Present a numbered menu allowing multiple selections and return the selected values.
+    #
+    # @param message [String] the prompt message
+    # @param choices [Array<String>] the list of choices
+    # @param defaults [Array<String>] pre-selected default choices
+    # @param input [IO] input stream
+    # @param output [IO] output stream
+    # @return [Array<String>] the selected values
+    def self.multi_select(message, choices, defaults: [], input: $stdin, output: $stdout)
+      Menu.multi_select(message, choices, defaults: defaults, input: input, output: output)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cli_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-15 00:00:00.000000000 Z
 dependencies: []
 description: Lightweight CLI toolkit combining argument parsing with flags and options,
   interactive prompts with confirmation, and animated spinners for long-running operations.
@@ -27,11 +27,11 @@ files:
 - lib/philiprehberger/cli_kit/prompt.rb
 - lib/philiprehberger/cli_kit/spinner.rb
 - lib/philiprehberger/cli_kit/version.rb
-homepage: https://github.com/philiprehberger/rb-cli-kit
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-cli_kit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-cli-kit
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-cli_kit
   source_code_uri: https://github.com/philiprehberger/rb-cli-kit
   changelog_uri: https://github.com/philiprehberger/rb-cli-kit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-cli-kit/issues