rubycli 0.1.7 → 0.2.0

data/examples/documentation_style_showcase.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Compact examples that highlight how Rubycli parses different documentation styles.
+module DocumentationStyleShowcase
+  module_function
+
+  # Canonical uppercase placeholders covering required, optional, and repeated forms.
+  #
+  # NAME [String] Name to display
+  # COUNT [Integer] Repetition count
+  # --prefix PREFIX [String] Descriptor printed before the subject
+  # --tags TAG... [String[]] Comma-separated or JSON list of tags (repeatable)
+  # --quiet [Boolean] Suppress the trailing newline marker
+  def canonical(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:canonical, subject, count, prefix, tags, quiet)
+  end
+
+  # Minimal uppercase form – same signature, but placeholders omit type hints entirely.
+  #
+  # NAME Name to display
+  # COUNT Repetition count
+  # --prefix PREFIX Descriptor printed before the subject
+  # --tags TAG... JSON/YAML array or comma-separated list
+  # --quiet
+  def canonical_min(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:canonical_min, subject, count, prefix, tags, quiet)
+  end
+
+  # Angle-bracket placeholders with parenthesized type hints.
+  # <subject> [String] Subject text to render
+  # <count> [Integer] Repetition count
+  # --prefix=<prefix> [String] Prefix that appears before the subject
+  # --tags <tag>... [String[]] JSON/YAML array or comma-separated tags (repeatable)
+  # --quiet [Boolean] Suppress the trailing newline marker
+  def angled(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:angled, subject, count, prefix, tags, quiet)
+  end
+
+  # Minimal angle-bracket form without explicit types.
+  #
+  # <subject> Subject text to render
+  # <count> Repetition count
+  # --prefix=<prefix> Prefix shown before the subject
+  # --tags <tag>... JSON/YAML array or comma-separated list
+  # --quiet
+  def angled_min(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:angled_min, subject, count, prefix, tags, quiet)
+  end
+
+  # Bracketed type hints combined with ellipsis for repeated values.
+  #
+  # <subject> [String] Subject identifier to capture
+  # <count> [Integer, nil] Repetition count (accepts nil)
+  # --prefix PREFIX [String, nil] Heading for the entry
+  # --tags <tag>... [String[]] JSON/YAML array or comma-separated tags (repeatable)
+  # --quiet [Boolean] Suppress the trailing newline marker
+  # => [Hash] Summary of captured attributes
+  def typed(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:typed, subject, count, prefix, tags, quiet)
+  end
+
+  # Minimal typed variant using compact notation.
+  #
+  # <subject> [String] Subject identifier
+  # <count> [Integer] Repetition count
+  # --prefix PREFIX [String] Title prefix
+  # --tags <tag>... [String[]] JSON/YAML array or comma-separated list
+  # --quiet [Boolean]
+  def typed_min(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:typed_min, subject, count, prefix, tags, quiet)
+  end
+
+  # YARD-style annotations without inline option metadata.
+  #
+  # @param subject [String] Subject to process
+  # @param count [Integer] Number of repetitions when composing the label
+  # @param prefix [String, nil] Descriptor printed before the subject
+  # @param tags [Array<String>, nil] Additional tags (JSON/YAML array or comma-separated, repeatable)
+  # @param quiet [Boolean] Suppress the trailing newline marker
+  # @return [Hash] Normalized configuration summary
+  def yard(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:yard, subject, count, prefix, tags, quiet)
+  end
+
+  # Minimal YARD-style form with the shortest acceptable annotations.
+  #
+  # @param subject Subject to process
+  # @param count Repetition count
+  # @param prefix Descriptor printed before the subject
+  # @param tags Tags list (JSON/YAML array or comma-separated)
+  # @param quiet Quiet flag
+  def yard_min(subject, count = 1, prefix: nil, tags: nil, quiet: false)
+    build_payload(:yard_min, subject, count, prefix, tags, quiet)
+  end
+
+  class << self
+    private
+
+    def build_payload(style, subject, count, prefix, tags, quiet)
+      {
+        style: style,
+        subject: subject,
+        count: count,
+        prefix: prefix,
+        tags: tags,
+        quiet: quiet
+      }
+    end
+  end
+end

data/examples/fallback_example.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Example showcasing inference when documentation is incomplete.
+module FallbackExample
+  module_function
+
+  # AMOUNT [Integer] Base amount to process
+  def scale(amount, factor = 2, clamp: nil, notify: false)
+    result = amount * factor
+    result = [result, clamp].min if clamp
+    puts "Scaled to #{result}" if notify
+    result
+  end
+end

data/examples/fallback_example_with_extra_docs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Example showing how comments beyond the live signature are treated.
+module FallbackExampleWithExtraDocs
+  module_function
+
+  # AMOUNT [Integer] Base amount to process
+  # CLAMP [Integer] (unused placeholder)
+  # --ghost [Boolean] Imaginary toggle that is not implemented
+  def scale(amount)
+    amount * 2
+  end
+end

data/examples/hello_app.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Example CLI target without doc comments; see README section 1.
+module HelloApp
+  module_function
+
+  def greet(name)
+    puts "Hello, #{name}!"
+  end
+end

data/examples/hello_app_with_docs.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Example CLI target with documentation-driven options; see README section 2.
+module HelloApp
+  module_function
+
+  # NAME [String] Name to greet
+  # --shout [Boolean] Print in uppercase
+  def greet(name, shout: false)
+    message = "Hello, #{name}!"
+    message = message.upcase if shout
+    puts message
+  end
+end
+
+# Provide a constant that matches the file name so Rubycli infers it automatically.
+HelloAppWithDocs = HelloApp

data/examples/hello_app_with_require.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rubycli'
+
+module HelloApp
+  module_function
+
+  # NAME [String] Name to greet
+  # --shout [Boolean] Print in uppercase
+  # => [String] Printed message
+  def greet(name, shout: false)
+    message = "Hello, #{name}!"
+    message = message.upcase if shout
+    puts message
+    message
+  end
+end
+
+Rubycli.run(HelloApp)

data/examples/mismatched_constant_runner.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Demonstrates a file whose constant does not match the file name. By default
+# Rubycli will ask you to call out the constant explicitly:
+#   rubycli examples/mismatched_constant_runner.rb FriendlyGreeter greet --message "Hello"
+# To auto-select it, pass --auto-target (or set RUBYCLI_AUTO_TARGET=auto).
+class FriendlyGreeter
+  # NAME [String] Text to display
+  # --message MESSAGE [String] Greeting to print (defaults to "Hello")
+  # --quiet [Boolean] Skip the stdout line (the return value is still printed)
+  def self.greet(name = 'friend', message: 'Hello', quiet: false)
+    output = "#{message}, #{name}!"
+    puts(output) unless quiet
+    output
+  end
+end

data/examples/multi_constant_runner.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Demonstrates how Rubycli behaves when a file defines multiple constants.
+# By default Rubycli will prefer the constant whose name matches the file
+# (MultiConstantRunner). To invoke HelperRunner instead, specify it explicitly:
+#   rubycli examples/multi_constant_runner.rb HelperRunner inspect
+class HelperRunner
+  def self.inspect
+    puts('Helper invoked')
+    :helper
+  end
+end
+
+class MultiConstantRunner
+  # TEXT [String] Message to display
+  def self.echo(text = 'hello')
+    puts(text)
+    text
+  end
+end

data/examples/new_mode_runner.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Demonstrates instance-only CLI with constructor arguments and eval/json modes.
+class NewModeRunner
+  attr_reader :items, :options
+
+  # ITEMS [String[]]  List input (comma-separated or a JSON array)
+  # --options [Hash]  Extra settings (JSON or eval literals)
+  def initialize(items, options: {})
+    @items = items
+    @options = options
+  end
+
+  # --mode MODE [Symbol] Execution mode (summary or reverse)
+  def run(mode: :summary)
+    case mode.to_sym
+    when :summary
+      {
+        count: items.size,
+        uppercased: items.map(&:upcase),
+        options: options
+      }
+    when :reverse
+      items.reverse
+    else
+      warn "unknown mode: #{mode}"
+      nil
+    end
+  end
+end
+
+# Usage examples (from the repository root):
+#   # Instance methods only, so --new is required; the array can be JSON or comma-separated
+#   rubycli --new='["a","b","c"]' examples/new_mode_runner.rb run --mode reverse
+#   rubycli --new a,b,c examples/new_mode_runner.rb run --mode summary
+#
+#   # JSON mode: every following argument is parsed strictly as JSON (bare words are rejected)
+#   rubycli --json-args --new='["a","b"]' examples/new_mode_runner.rb run
+#
+#   # Eval mode: Ruby literals are accepted, but every argument must be valid Ruby
+#   rubycli --eval-args --new='%w[x y]' examples/new_mode_runner.rb run --mode ':reverse'
+#
+#   # --new passes a single value (items), so keyword arguments go through a pre-script,
+#   # which builds the instance on its own and needs no --new
+#   rubycli --pre-script 'NewModeRunner.new(%w[a b c], options: {from: :pre})' \
+#     examples/new_mode_runner.rb run --mode summary

data/examples/strict_choices_demo.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Demonstrates literal enum choices and strict validation.
+module StrictChoicesDemo
+  module_function
+
+  # LEVEL %i[info warn error] Report severity
+  # --format TARGET ["text", "json", "yaml"] Output destination (strings)
+  # --notify [Boolean] Print a notification banner
+  def report(level, format: 'text', notify: false)
+    payload = { level: level, format: format, notify: notify }
+    message = "[#{level.to_s.upcase}] format=#{format}"
+    message = "#{message} (notify enabled)" if notify
+    puts message
+    payload
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  require 'rubycli'
+  Rubycli.run(StrictChoicesDemo)
+end

data/examples/typed_arguments_demo.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+require 'bigdecimal'
+require 'pathname'
+
+# Demonstrates standard library type coercions.
+module TypedArgumentsDemo
+  module_function
+
+  # --date DATE [Date] Planned schedule date
+  # --moment TIME [Time] Execution timestamp
+  # --budget AMOUNT [BigDecimal] Budget amount
+  # --input FILE [Pathname] Path to source file
+  def ingest(
+    date: Date.today,
+    moment: Time.now,
+    budget: BigDecimal('0'),
+    input: Pathname.new('.')
+  )
+    summary = <<~TEXT
+      Date: #{date.iso8601}
+      Moment: #{moment.utc.iso8601}
+      Budget: #{budget.to_s('F')}
+      Input: #{input.expand_path}
+    TEXT
+
+    puts summary
+    {
+      date: date,
+      moment: moment,
+      budget: budget,
+      input: input
+    }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  require 'rubycli'
+  Rubycli.run(TypedArgumentsDemo)
+end

data/lib/rubycli/argument_mode_controller.rb

@@ -29,13 +29,9 @@ module Rubycli
     def apply_argument_coercions(positional_args, keyword_args)
       ensure_modes_compatible!
 
-      if json_mode?
-        coerce_values!(positional_args, keyword_args) { |value| @json_coercer.coerce_json_value(value) }
-      end
+      coerce_values!(positional_args, keyword_args) { |value| @json_coercer.coerce_json_value(value) } if json_mode?
 
-      if eval_mode?
-        coerce_values!(positional_args, keyword_args) { |value| @eval_coercer.coerce_eval_value(value) }
-      end
+      coerce_values!(positional_args, keyword_args) { |value| @eval_coercer.coerce_eval_value(value) } if eval_mode?
     rescue ::ArgumentError => e
       raise Rubycli::ArgumentError, e.message
     end
@@ -54,13 +50,13 @@ module Rubycli
     end
 
     def ensure_modes_compatible!
-      if json_mode? && eval_mode?
-        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax'
-      end
+      return unless json_mode? && eval_mode?
+
+      raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax'
     end
 
-    def coerce_values!(positional_args, keyword_args)
-      positional_args.map! { |value| yield(value) }
+    def coerce_values!(positional_args, keyword_args, &block)
+      positional_args.map!(&block)
       keyword_args.keys.each do |key|
         keyword_args[key] = yield(keyword_args[key])
       end