rubycli 0.1.7 → 0.2.0

data/lib/rubycli/cli.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'set'
 
 module Rubycli
@@ -76,6 +78,15 @@ module Rubycli
       command_catalog(target)
     end
 
+    # True when the method can be exposed as a CLI command. Rubycli::Runner uses
+    # this to lint the same methods the CLI would expose.
+    def exposable_method?(method_obj)
+      return false unless method_obj&.source_location
+      return false if accessor_generated_method?(method_obj)
+
+      true
+    end
+
     private
 
     def debug_log(message)
@@ -101,13 +112,12 @@ module Rubycli
 
     def handle_missing_method(target, catalog, command, args, cli_mode)
       if target.respond_to?(:call)
-        debug_log "Target is callable, treating as lambda/proc"
+        debug_log 'Target is callable, treating as lambda/proc'
         args.unshift(command)
         execute_callable(target, args, command, cli_mode)
       else
-        error_msg = "Command '#{command}' is not available."
-        puts error_msg
-        @help_renderer.print_help(target, catalog)
+        warn "Command '#{command}' is not available."
+        @help_renderer.print_help(target, catalog, io: $stderr)
         1
       end
     end
@@ -134,22 +144,15 @@ module Rubycli
       end
     end
 
-    def execute_parameterless_method(method_obj, command, args, cli_mode)
+    def execute_parameterless_method(method_obj, command, args, _cli_mode)
       if help_requested_for_parameterless?(args)
         puts usage_for_method(command, method_obj)
         return 0
       end
 
-      begin
-        result = method_obj.call
-        debug_log "Parameterless method returned: #{result.inspect}"
-        if result
-          return run(result, args, false)
-        end
-        0
-      rescue StandardError => e
-        handle_execution_error(e, command, method_obj, [], {}, cli_mode)
-      end
+      warn "Command '#{command}' does not accept arguments."
+      warn usage_for_method(command, method_obj)
+      1
     end
 
     def execute_method_with_params(method_obj, command, args, cli_mode)
@@ -185,13 +188,11 @@ module Rubycli
     end
 
     def handle_execution_error(error, command, method_obj, pos_args, kw_args, cli_mode)
-      if cli_mode && !arguments_match?(method_obj, pos_args, kw_args) && usage_error?(error)
-        puts "Error: #{error.message}"
-        puts usage_for_method(command, method_obj)
-        1
-      else
-        raise error
-      end
+      raise error unless cli_mode && !arguments_match?(method_obj, pos_args, kw_args) && usage_error?(error)
+
+      warn "Error: #{error.message}"
+      warn usage_for_method(command, method_obj)
+      1
     end
 
     def usage_error?(error)
@@ -284,7 +285,9 @@ module Rubycli
 
     def collect_class_methods(target)
       klass = target.class
-      collect_method_map(klass.singleton_class.public_instance_methods(false)) { |name| safe_method_lookup(klass, name) }
+      collect_method_map(klass.singleton_class.public_instance_methods(false)) do |name|
+        safe_method_lookup(klass, name)
+      end
     end
 
     def collect_method_map(method_names)
@@ -302,13 +305,6 @@ module Rubycli
       nil
     end
 
-    def exposable_method?(method_obj)
-      return false unless method_obj&.source_location
-      return false if accessor_generated_method?(method_obj)
-
-      true
-    end
-
     def build_alias_map(entries)
       entries.each_with_object({}) do |entry, memo|
         entry.all_commands.each do |command|

data/lib/rubycli/command_line.rb

@@ -6,20 +6,22 @@ module Rubycli
       Usage: rubycli [--new|-n[=<value>]] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] [--strict] [--check|-c] <target-path> [<class-or-module>] [-- <cli-args>...]
 
       Examples:
-        rubycli scripts/sample_runner.rb echo --message hello
-        rubycli scripts/sample_runner.rb AlternateRunner greet --name Ruby
-        rubycli --new lib/akiya_fetcher.rb fetch_simplified_html https://example.com
-        rubycli --json-args --new='["a","b"]' examples/new_mode_runner.rb run --mode summary --options '{"source":"json"}'
+        rubycli path/to/greeter.rb greet Hanako
+        rubycli path/to/multi_runner.rb AlternateRunner greet --name Ruby
+        rubycli --auto-target path/to/mismatched_runner.rb greet Hanako
+        rubycli --new='["a","b"]' path/to/collection_runner.rb run --mode summary
+        rubycli --json-args --new='["a","b"]' path/to/collection_runner.rb run --mode '"summary"'
 
       Options:
-        --new, -n [<value>]  Instantiate the class/module before invoking CLI commands; optional constructor arguments can follow (array/hash recommended; respects --json-args/--eval-args/--eval-lax)
+        --new, -n [<value>]  Instantiate the class/module before invoking CLI commands; one optional literal can follow and is bound to the constructor's first parameter (respects --json-args/--eval-args/--eval-lax; use --pre-script for several or keyword arguments)
         --pre-script=<src>   Evaluate Ruby code and use its result as the exposed target (--init alias; also accepts space-separated form)
-        --json-args, -j      Parse all following arguments strictly as JSON (no YAML literals)
-        --eval-args, -e      Evaluate following arguments as Ruby code
+        --json-args, -j      Parse all following arguments strictly as JSON (no YAML literals; even plain words need quoting)
+        --eval-args, -e      Evaluate following arguments as Ruby code (every argument must be valid Ruby)
         --eval-lax, -E       Evaluate as Ruby but fall back to raw strings when parsing fails
         --auto-target, -a    Auto-select the only callable constant when names don't match
         --strict             Enforce documented input types/choices (invalid values abort)
         --check, -c          Validate documentation/comments without executing commands
+        --help, -h           Show this message (the bare word `help` works too)
         (Note: --json-args cannot be combined with --eval-args or --eval-lax)
         (Note: Every option that accepts a value understands both --flag=value and --flag value forms.)
 
@@ -29,90 +31,104 @@ module Rubycli
       <cli-args> are forwarded to Rubycli unchanged.
     USAGE
 
+    # Flags collected before the target path; forwarded to Rubycli::Runner.
+    Options = Struct.new(
+      :new_flag,
+      :new_args,
+      :json_mode,
+      :eval_mode,
+      :eval_lax,
+      :constant_mode,
+      :check_mode,
+      :pre_scripts,
+      keyword_init: true
+    ) do
+      def self.defaults
+        new(
+          new_flag: false,
+          new_args: nil,
+          json_mode: false,
+          eval_mode: false,
+          eval_lax: false,
+          constant_mode: nil,
+          check_mode: false,
+          pre_scripts: []
+        )
+      end
+    end
+
     module_function
 
     def run(argv = ARGV)
+      previous_state = environment_state
       args = Array(argv).dup
       Rubycli.environment.enable_print_result!
+      return print_usage(1) if args.empty?
 
-      if args.empty?
-        $stdout.puts(USAGE)
-        return 1
-      end
+      options = Options.defaults
+      status = parse_flags!(args, options)
+      return status if status
+      return print_usage(1) if args.empty?
 
-      new_flag = false
-      new_args_expr = nil
-      json_mode = false
-      eval_mode = false
-      eval_lax_mode = false
-      constant_mode = nil
-      check_mode = false
-      pre_script_sources = []
+      target_path, class_or_module = extract_target!(args)
+      status = reject_conflicting_flags(options, args)
+      return status if status
 
-      loop do
-        arg = args.first
-        break unless arg
+      Rubycli.environment.clear_documentation_issues!
+      dispatch(target_path, class_or_module, args, options)
+    rescue Rubycli::Runner::Error => e
+      warn "[ERROR] #{e.message}"
+      1
+    ensure
+      restore_environment(previous_state)
+    end
 
-        case arg
+    # Consumes leading flags from +args+ and fills +options+.
+    # Returns an exit status when the CLI should stop, otherwise nil.
+    def parse_flags!(args, options)
+      until args.empty?
+        case args.first
         when '-h', '--help', 'help'
-          $stdout.puts(USAGE)
-          return 0
+          return print_usage(0)
         when /\A--new(?:=(.+))?\z/
-          new_flag = true
-          new_args_expr = Regexp.last_match(1)
+          inline_value = Regexp.last_match(1)
           args.shift
-          if new_args_expr.nil?
-            possible = args.first
-            if possible && !possible.start_with?('-') && likely_new_args_value?(possible)
-              new_args_expr = args.shift
-            end
-          end
+          consume_new_arguments!(args, options, inline_value)
         when '-n'
-          new_flag = true
           args.shift
-          possible = args.first
-          if possible && !possible.start_with?('-') && likely_new_args_value?(possible)
-            new_args_expr = args.shift
-          end
+          consume_new_arguments!(args, options, nil)
         when /\A--pre-script=(.+)\z/, /\A--init=(.+)\z/
-          label = Regexp.last_match(0).start_with?('--pre-script') ? '--pre-script' : '--init'
-          expr = Regexp.last_match(1)
-          pre_script_sources << { value: expr, context: "(inline #{label})" }
+          flag = Regexp.last_match(0).start_with?('--pre-script') ? '--pre-script' : '--init'
+          options.pre_scripts << { value: Regexp.last_match(1), context: "(inline #{flag})" }
           args.shift
         when '--pre-script', '--init'
-          flag = args.shift
-          src = args.shift
-          unless src
-            warn "[ERROR] #{flag} requires a file path or inline Ruby code"
-            return 1
-          end
-          context = File.file?(src) ? File.expand_path(src) : "(inline #{flag})"
-          pre_script_sources << { value: src, context: context }
+          status = consume_pre_script_source!(args, options)
+          return status if status
         when '--json-args', '-j'
-          json_mode = true
+          options.json_mode = true
           args.shift
         when '--eval-args', '-e'
-          eval_mode = true
+          options.eval_mode = true
           args.shift
         when '--eval-lax', '-E'
-          eval_mode = true
-          eval_lax_mode = true
+          options.eval_mode = true
+          options.eval_lax = true
           args.shift
         when '--strict'
           Rubycli.environment.enable_strict_input!
           args.shift
         when '--check', '-c'
-          check_mode = true
+          options.check_mode = true
           Rubycli.environment.enable_doc_check!
           args.shift
         when '--print-result'
           args.shift
         when '--debug'
           args.shift
-          warn "[ERROR] --debug flag has been removed; set RUBYCLI_DEBUG=true instead."
+          warn '[ERROR] --debug flag has been removed; set RUBYCLI_DEBUG=true instead.'
           return 1
         when '--auto-target', '-a'
-          constant_mode = :auto
+          options.constant_mode = :auto
           args.shift
         when '--'
           args.shift
@@ -122,67 +138,116 @@ module Rubycli
         end
       end
 
-      if args.empty?
-        $stdout.puts(USAGE)
+      nil
+    end
+
+    def consume_new_arguments!(args, options, inline_value)
+      options.new_flag = true
+      options.new_args = inline_value
+      return unless inline_value.nil?
+
+      candidate = args.first
+      return unless candidate && !candidate.start_with?('-') && likely_new_args_value?(candidate)
+
+      options.new_args = args.shift
+    end
+
+    def consume_pre_script_source!(args, options)
+      flag = args.shift
+      source = args.shift
+      unless source
+        warn "[ERROR] #{flag} requires a file path or inline Ruby code"
         return 1
       end
 
+      context = File.file?(source) ? File.expand_path(source) : "(inline #{flag})"
+      options.pre_scripts << { value: source, context: context }
+      nil
+    end
+
+    # Removes the target path and the optional explicit constant from +args+.
+    def extract_target!(args)
       target_path = args.shift
       class_or_module = nil
-      possible_class = args.first
-      if possible_class && possible_class != '--' && possible_class.match?(/\A[A-Z]/)
-        class_or_module = args.shift
-      end
+      candidate = args.first
+      class_or_module = args.shift if candidate && candidate != '--' && candidate.match?(/\A[A-Z]/)
       args.shift if args.first == '--'
+      [target_path, class_or_module]
+    end
 
-      if json_mode && eval_mode
+    # Returns an exit status when the flag combination is unusable, otherwise nil.
+    def reject_conflicting_flags(options, args)
+      if options.json_mode && options.eval_mode
         warn '[ERROR] --json-args cannot be combined with --eval-args or --eval-lax'
         return 1
       end
 
-      if check_mode && (json_mode || eval_mode)
+      return nil unless options.check_mode
+
+      if options.json_mode || options.eval_mode
         warn '[ERROR] --check cannot be combined with --json-args or --eval-args'
         return 1
       end
 
-      if check_mode && !args.empty?
+      unless args.empty?
         warn '[ERROR] --check does not accept command arguments'
         return 1
       end
 
-      Rubycli.environment.clear_documentation_issues!
+      nil
+    end
 
-      if check_mode
+    def dispatch(target_path, class_or_module, args, options)
+      if options.check_mode
         return Rubycli::Runner.check(
           target_path,
           class_or_module,
-          new: new_flag,
-          new_args: new_args_expr,
-          pre_scripts: pre_script_sources,
-          constant_mode: constant_mode
+          new: options.new_flag,
+          new_args: options.new_args,
+          pre_scripts: options.pre_scripts,
+          constant_mode: options.constant_mode
         )
       end
 
-      Rubycli::Runner.execute(
+      status = Rubycli::Runner.execute(
         target_path,
         class_or_module,
         args,
-        new: new_flag,
-        new_args: new_args_expr,
-        json: json_mode,
-        eval_args: eval_mode,
-        eval_lax: eval_lax_mode,
-        pre_scripts: pre_script_sources,
-        constant_mode: constant_mode
+        new: options.new_flag,
+        new_args: options.new_args,
+        json: options.json_mode,
+        eval_args: options.eval_mode,
+        eval_lax: options.eval_lax,
+        pre_scripts: options.pre_scripts,
+        constant_mode: options.constant_mode
       )
 
-      0
-    rescue Rubycli::Runner::PreScriptError => e
-      warn "[ERROR] #{e.message}"
-      1
-    rescue Rubycli::Runner::Error => e
-      warn "[ERROR] #{e.message}"
-      1
+      # The runner reports the CLI status; treat anything else as success so the
+      # process always exits with a defined status.
+      status.is_a?(Integer) ? status : 0
+    end
+
+    # Usage requested with --help goes to stdout; usage shown because the
+    # invocation was wrong is a diagnostic and belongs on stderr.
+    def print_usage(status)
+      (status.zero? ? $stdout : $stderr).puts(USAGE)
+      status
+    end
+
+    def environment_state
+      environment = Rubycli.environment
+      {
+        doc_check: environment.doc_check_mode?,
+        strict_input: environment.strict_input?,
+        print_result: environment.print_result?
+      }
+    end
+
+    def restore_environment(state)
+      environment = Rubycli.environment
+      state[:doc_check] ? environment.enable_doc_check! : environment.disable_doc_check!
+      state[:strict_input] ? environment.enable_strict_input! : environment.disable_strict_input!
+      state[:print_result] ? environment.enable_print_result! : environment.disable_print_result!
     end
 
     def likely_new_args_value?(token)