philiprehberger-cli_kit 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b81a21c1714aef7854a2d71fa19dfda96b549e63d76a235afe555fa491ddf3a
-  data.tar.gz: 86c9be91443b2d34502557bbefcbca284f9141a0f28d263125b207356f9c184e
+  metadata.gz: c09f7a9f76769c7ecf089942c9594ba1f6d09ce3a992c4def928fe68551eeee3
+  data.tar.gz: c9cf6608c8fb9da1ea27ea7d8afa19654f1323ea0a4ed97f6a31ed18c4a49e6b
 SHA512:
-  metadata.gz: ae7fd1b9fcbe52efea0db053243c449b2eee5f23875cd5f7d5ea61a8b5614bf46535575b82af11376f3f91e11b56057cbe131a367fccac218997155627b24c63
-  data.tar.gz: 9d81fa407958b8cb11b565634c2995366f43bae342dd32229dc8b9f06035aea4164cab743c0c8c281025cd49397796db5da287b5d7f15bad6d742450bd546749
+  metadata.gz: 3c8fd3284baffd888ab79d3c39264e2e7cb742e51ab5de8411526e21dbc282321d1f2c937e58646a2230b24cfb4cc4219f4fbb9ff10755a4de6a3980c02a00ac
+  data.tar.gz: 7029600e08a0001ca9ca5b0fed28150ce33cf09bfbbe799685d736d92f30695ba23095a86a9e06458e16c0a842bfc10a0690c08faf08797568f3bf74b8828c3b

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-30
+
+### Added
+- Subcommands with isolated flags and options via `command(:name) { ... }` DSL
+- `result.command` returns matched subcommand name as symbol or nil
+- Auto-generated help text with `desc:` parameter on flags and options
+- `--help` / `-h` prints formatted usage and exits
+- `result.help_text` returns formatted help string without printing
+- `result.help_requested?` indicates whether help was requested
+- Menu/selection prompt via `CliKit.select(message, choices)` with numbered options
+- `default:` option for pre-selected menu choice
+- `input:` and `output:` IO parameters on `select` for testability
+
 ## [0.1.2] - 2026-03-22
 
 ### Added

data/README.md

@@ -2,7 +2,12 @@
 
 [![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
 
@@ -39,6 +44,42 @@ result.options[:output]   # => 'out.txt' or user-provided value
 result.arguments          # => remaining positional args
 ```
 
+### Subcommands
+
+```ruby
+result = Philiprehberger::CliKit.parse(ARGV) do
+  command(:deploy) do
+    flag :force, short: :f
+    option :env, short: :e
+  end
+  command(:test) do
+    flag :coverage
+  end
+end
+
+result.command            # => :deploy or :test or nil
+result.flags[:force]      # => true/false (within matched command)
+result.options[:env]      # => user-provided value
+```
+
+### Auto-generated Help
+
+```ruby
+result = Philiprehberger::CliKit.parse(ARGV) do
+  flag :verbose, short: :v, desc: 'Enable verbose output'
+  option :output, short: :o, desc: 'Output file path'
+end
+
+# Passing --help or -h prints formatted usage and exits:
+#   Usage: command [options]
+#
+#   Options:
+#     -v, --verbose           Enable verbose output
+#     -o, --output VALUE      Output file path
+
+result.help_text          # => formatted help string without printing
+```
+
 ### Prompts
 
 ```ruby
@@ -49,40 +90,48 @@ confirmed = Philiprehberger::CliKit.confirm('Continue?')
 # Continue? [y/n] _
 ```
 
-### Spinners
+### Menu Selection
 
 ```ruby
-data = Philiprehberger::CliKit.spinner('Loading data...') do
-  # long-running operation
-  fetch_remote_data
-end
+env = Philiprehberger::CliKit.select('Choose env:', %w[dev staging prod])
+#   Choose env:
+#     1) dev
+#     2) staging
+#     3) prod
+#   Choose: _
+
+env = Philiprehberger::CliKit.select('Choose env:', %w[dev staging prod], default: 'staging')
+#   Choose env:
+#       1) dev
+#     * 2) staging
+#       3) prod
+#   Choose [2]: _
 ```
 
-### Argument Parsing Details
+### Spinners
 
 ```ruby
-# Given: mytool --verbose -o report.csv input.txt
-result = Philiprehberger::CliKit.parse(%w[--verbose -o report.csv input.txt]) do
-  flag :verbose, short: :v
-  option :output, short: :o, default: 'out.txt'
+data = Philiprehberger::CliKit.spinner('Loading data...') do
+  # long-running operation
+  fetch_remote_data
 end
-
-result.flags[:verbose]    # => true
-result.options[:output]   # => 'report.csv'
-result.arguments          # => ['input.txt']
 ```
 
 ## API
 
 | Method | Description |
 |--------|-------------|
-| `.parse(args) { ... }` | Parse arguments with flag/option DSL |
+| `.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 |
 | `.spinner(message) { ... }` | Show spinner during block execution |
 | `Parser#flags` | Hash of boolean flag values |
 | `Parser#options` | Hash of option values |
 | `Parser#arguments` | Array of positional arguments |
+| `Parser#command` | Matched subcommand name or nil |
+| `Parser#help_text` | Formatted help string |
+| `Parser#help_requested?` | Whether --help or -h was passed |
 
 ## Development
 
@@ -92,6 +141,13 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.
+
+[![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)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/cli_kit/menu.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CliKit
+    # Numbered menu selection for CLI applications.
+    module Menu
+      # Present a numbered menu and return the selected value.
+      #
+      # @param message [String] the prompt message
+      # @param choices [Array<String>] the list of choices
+      # @param default [String, nil] pre-selected default choice
+      # @param input [IO] input stream (default: $stdin)
+      # @param output [IO] output stream (default: $stdout)
+      # @return [String] the selected value
+      # @raise [ArgumentError] if choices is empty
+      def self.select(message, choices, default: nil, input: $stdin, output: $stdout)
+        raise ArgumentError, 'choices must not be empty' if choices.empty?
+
+        default_index = default ? choices.index(default) : nil
+
+        output.puts message
+        choices.each_with_index do |choice, idx|
+          marker = default_index == idx ? '*' : ' '
+          output.puts "  #{marker} #{idx + 1}) #{choice}"
+        end
+
+        prompt_text = default ? "Choose [#{default_index + 1}]: " : 'Choose: '
+        output.print prompt_text
+        output.flush
+
+        answer = input.gets&.strip || ''
+
+        if answer.empty? && default
+          return default
+        end
+
+        index = answer.to_i - 1
+        if index >= 0 && index < choices.length
+          choices[index]
+        elsif default
+          default
+        else
+          choices.first
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/cli_kit/parser.rb

@@ -9,18 +9,22 @@ module Philiprehberger
       def initialize
         @flag_definitions = {}
         @option_definitions = {}
+        @command_definitions = {}
         @flags = {}
         @options = {}
         @arguments = []
+        @command_name = nil
+        @program_name = nil
       end
 
       # Define a boolean flag.
       #
       # @param name [Symbol] the flag name
       # @param short [Symbol, nil] short alias (single character)
+      # @param desc [String, nil] description for help text
       # @return [void]
-      def flag(name, short: nil)
-        @flag_definitions[name] = { short: short }
+      def flag(name, short: nil, desc: nil)
+        @flag_definitions[name] = { short: short, desc: desc }
         @flags[name] = false
       end
 
@@ -29,18 +33,93 @@ module Philiprehberger
       # @param name [Symbol] the option name
       # @param short [Symbol, nil] short alias (single character)
       # @param default [Object, nil] default value
+      # @param desc [String, nil] description for help text
       # @return [void]
-      def option(name, short: nil, default: nil)
-        @option_definitions[name] = { short: short, default: default }
+      def option(name, short: nil, default: nil, desc: nil)
+        @option_definitions[name] = { short: short, default: default, desc: desc }
         @options[name] = default
       end
 
+      # Define a subcommand or return the matched command name.
+      #
+      # When called with a name and block, defines a subcommand.
+      # When called with no arguments, returns the matched command name.
+      #
+      # @param name [Symbol, nil] the command name (nil to query)
+      # @yield [Parser] the command parser for defining command-specific flags and options
+      # @return [Symbol, nil, void]
+      def command(name = nil, &block)
+        if name.nil?
+          @command_name
+        else
+          cmd_parser = Parser.new
+          cmd_parser.instance_eval(&block) if block
+          @command_definitions[name] = cmd_parser
+        end
+      end
+
+      # Return the matched command name, or nil if no command matched.
+      #
+      # @return [Symbol, nil]
+      attr_reader :command_name
+
+      # Return the formatted help text without printing.
+      #
+      # @return [String]
+      def help_text
+        lines = []
+        lines << "Usage: #{@program_name || 'command'} [options]"
+        lines << ''
+
+        unless @flag_definitions.empty? && @option_definitions.empty?
+          lines << 'Options:'
+          @flag_definitions.each do |name, defn|
+            lines << format_flag_help(name, defn)
+          end
+          @option_definitions.each do |name, defn|
+            lines << format_option_help(name, defn)
+          end
+        end
+
+        unless @command_definitions.empty?
+          lines << '' unless @flag_definitions.empty? && @option_definitions.empty?
+          lines << 'Commands:'
+          @command_definitions.each_key do |name|
+            lines << "  #{name}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
       # Parse the given argument array.
       #
       # @param args [Array<String>] command-line arguments
       # @return [self]
       def parse(args)
         args = args.dup
+
+        # Check for --help / -h before anything else
+        if args.include?('--help') || args.include?('-h')
+          @help_requested = true
+          return self
+        end
+
+        # Try to match a subcommand
+        if @command_definitions.any? && args.any?
+          potential_cmd = args.first.to_sym
+          if @command_definitions.key?(potential_cmd)
+            @command_name = potential_cmd
+            cmd_parser = @command_definitions[potential_cmd]
+            args.shift
+            cmd_parser.parse(args)
+            @flags = cmd_parser.flags
+            @options = cmd_parser.options
+            @arguments = cmd_parser.arguments
+            return self
+          end
+        end
+
         while args.any?
           arg = args.shift
           if arg.start_with?('--')
@@ -54,6 +133,13 @@ module Philiprehberger
         self
       end
 
+      # Check if help was requested.
+      #
+      # @return [Boolean]
+      def help_requested?
+        @help_requested || false
+      end
+
       private
 
       def parse_long(arg, args)
@@ -82,6 +168,36 @@ module Philiprehberger
           end
         end
       end
+
+      def format_flag_help(name, defn)
+        long = "--#{name.to_s.tr('_', '-')}"
+        if defn[:short]
+          short = "-#{defn[:short]}"
+          label = "  #{short}, #{long}"
+        else
+          label = "      #{long}"
+        end
+        if defn[:desc]
+          "#{label.ljust(24)}#{defn[:desc]}"
+        else
+          label
+        end
+      end
+
+      def format_option_help(name, defn)
+        long = "--#{name.to_s.tr('_', '-')} VALUE"
+        if defn[:short]
+          short = "-#{defn[:short]}"
+          label = "  #{short}, #{long}"
+        else
+          label = "      #{long}"
+        end
+        if defn[:desc]
+          "#{label.ljust(24)}#{defn[:desc]}"
+        else
+          label
+        end
+      end
     end
   end
 end

data/lib/philiprehberger/cli_kit/version.rb

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

data/lib/philiprehberger/cli_kit.rb

@@ -4,6 +4,7 @@ require_relative 'cli_kit/version'
 require_relative 'cli_kit/parser'
 require_relative 'cli_kit/prompt'
 require_relative 'cli_kit/spinner'
+require_relative 'cli_kit/menu'
 
 module Philiprehberger
   module CliKit
@@ -12,12 +13,20 @@ module Philiprehberger
     # Parse command-line arguments using a DSL block.
     #
     # @param args [Array<String>] command-line arguments
-    # @yield [Parser] the parser for defining flags and options
+    # @param output [IO] output stream for help text (default: $stdout)
+    # @yield [Parser] the parser for defining flags, options, and commands
     # @return [Parser] the parsed result with flags, options, and arguments
-    def self.parse(args, &block)
+    def self.parse(args, output: $stdout, &)
       parser = Parser.new
-      parser.instance_eval(&block)
+      parser.instance_eval(&)
       parser.parse(args)
+
+      if parser.help_requested?
+        output.puts parser.help_text
+        exit 0 unless output.is_a?(StringIO)
+      end
+
+      parser
     end
 
     # Display a prompt and read user input.
@@ -49,5 +58,17 @@ module Philiprehberger
     def self.spinner(message, output: $stderr, &block)
       Spinner.spinner(message, output: output, &block)
     end
+
+    # Present a numbered menu and return the selected value.
+    #
+    # @param message [String] the prompt message
+    # @param choices [Array<String>] the list of choices
+    # @param default [String, nil] pre-selected default choice
+    # @param input [IO] input stream
+    # @param output [IO] output stream
+    # @return [String] the selected value
+    def self.select(message, choices, default: nil, input: $stdin, output: $stdout)
+      Menu.select(message, choices, default: default, 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.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-03-30 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.
@@ -22,6 +22,7 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/cli_kit.rb
+- lib/philiprehberger/cli_kit/menu.rb
 - lib/philiprehberger/cli_kit/parser.rb
 - lib/philiprehberger/cli_kit/prompt.rb
 - lib/philiprehberger/cli_kit/spinner.rb