aspera-cli 4.14.0 → 4.15.0

data/lib/aspera/cli/manager.rb

@@ -1,42 +1,41 @@
 # frozen_string_literal: true
 
+require 'aspera/cli/extended_value'
+require 'aspera/cli/error'
 require 'aspera/colors'
-require 'aspera/log'
 require 'aspera/secret_hider'
-require 'aspera/cli/extended_value'
-require 'optparse'
+require 'aspera/log'
 require 'io/console'
+require 'optparse'
 
 module Aspera
   module Cli
-    # raised by cli on error conditions
-    class CliError < StandardError; end
-
-    # raised when an unexpected argument is provided
-    class CliBadArgument < Aspera::Cli::CliError; end
-
-    class CliNoSuchId < Aspera::Cli::CliError
-      def initialize(res_type, res_id)
-        msg = "No such #{res_type} identifier: #{res_id}"
-        super(msg)
-      end
-    end
-
     # option is retrieved from another object using accessor
     class AttrAccessor
       # attr_accessor :object
-      # attr_accessor :attr_symb
-      def initialize(object, attr_symb)
+      # attr_accessor :method_name
+      def initialize(object, method_name, option_name)
         @object = object
-        @attr_symb = attr_symb
+        @method = method_name
+        @option_name = option_name
+        @has_writer = @object.respond_to?(writer_method)
+        Log.log.debug{"AttrAccessor: #{@option_name}: #{@object.class}.#{@method}: writer=#{@has_writer}"}
+        raise "internal error: #{object} does not respond to #{method_name}" unless @object.respond_to?(@method)
       end
 
       def value
-        return @object.send(@attr_symb)
+        return @object.send(@method) if @has_writer
+        return @object.send(@method, @option_name, :get)
       end
 
       def value=(val)
-        @object.send("#{@attr_symb}=", val)
+        Log.log.trace1{"AttrAccessor: = #{@method} #{@option_name} :set #{val}, writer=#{@has_writer}"}
+        return @object.send(writer_method, val) if @has_writer
+        return @object.send(@method, @option_name, :set, val)
+      end
+
+      def writer_method
+        return "#{@method}="
       end
     end
 
@@ -53,9 +52,10 @@ module Aspera
       # option name separator on command line
       OPTION_SEP_LINE = '-'
       # option name separator in code (symbol)
-      OPTION_SEP_SYMB = '_'
+      OPTION_SEP_SYMBOL = '_'
+      SOURCE_USER = 'cmdline' # cspell:disable-line
 
-      private_constant :FALSE_VALUES, :TRUE_VALUES, :BOOLEAN_VALUES, :OPTION_SEP_LINE, :OPTION_SEP_SYMB
+      private_constant :FALSE_VALUES, :TRUE_VALUES, :BOOLEAN_VALUES, :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :SOURCE_USER
 
       class << self
         def enum_to_bool(enum)
@@ -68,13 +68,13 @@ module Aspera
         end
 
         # find shortened string value in allowed symbol list
-        def get_from_list(shortval, descr, allowed_values)
+        def get_from_list(short_value, descr, allowed_values)
           # we accept shortcuts
-          matching_exact = allowed_values.select{|i| i.to_s.eql?(shortval)}
+          matching_exact = allowed_values.select{|i| i.to_s.eql?(short_value)}
           return matching_exact.first if matching_exact.length == 1
-          matching = allowed_values.select{|i| i.to_s.start_with?(shortval)}
-          raise CliBadArgument, bad_arg_message_multi("unknown value for #{descr}: #{shortval}", allowed_values) if matching.empty?
-          raise CliBadArgument, bad_arg_message_multi("ambiguous shortcut for #{descr}: #{shortval}", matching) unless matching.length.eql?(1)
+          matching = allowed_values.select{|i| i.to_s.start_with?(short_value)}
+          raise Cli::BadArgument, bad_arg_message_multi("unknown value for #{descr}: #{short_value}", allowed_values) if matching.empty?
+          raise Cli::BadArgument, bad_arg_message_multi("ambiguous shortcut for #{descr}: #{short_value}", matching) unless matching.length.eql?(1)
           return enum_to_bool(matching.first) if allowed_values.eql?(BOOLEAN_VALUES)
           return matching.first
         end
@@ -85,11 +85,19 @@ module Aspera
 
         # change option name with dash to name with underscore
         def option_line_to_name(name)
-          return name.gsub(OPTION_SEP_LINE, OPTION_SEP_SYMB)
+          return name.gsub(OPTION_SEP_LINE, OPTION_SEP_SYMBOL)
         end
 
         def option_name_to_line(name)
-          return "--#{name.to_s.gsub(OPTION_SEP_SYMB, OPTION_SEP_LINE)}"
+          return "--#{name.to_s.gsub(OPTION_SEP_SYMBOL, OPTION_SEP_LINE)}"
+        end
+
+        def validate_type(what, descr, value, type_list)
+          return nil if type_list.nil?
+          raise 'internal error: types must be a Class Array' unless type_list.is_a?(Array) && type_list.all?(Class)
+          raise Cli::BadArgument,
+            "#{what.to_s.capitalize} #{descr} is a #{value.class} but must be #{type_list.length > 1 ? 'one of ' : ''}#{type_list.map(&:name).join(',')}" unless \
+            type_list.any?{|t|value.is_a?(t)}
         end
       end
 
@@ -97,7 +105,7 @@ module Aspera
       attr_accessor :ask_missing_mandatory, :ask_missing_optional
       attr_writer :fail_on_missing_mandatory
 
-      def initialize(program_name, argv: nil)
+      def initialize(program_name)
         # command line values not starting with '-'
         @unprocessed_cmd_line_arguments = []
         # command line values starting with '-'
@@ -118,7 +126,7 @@ module Aspera
         @parser = OptionParser.new
         @parser.program_name = program_name
         # options can also be provided by env vars : --param-name -> ASCLI_PARAM_NAME
-        env_prefix = program_name.upcase + OPTION_SEP_SYMB
+        env_prefix = program_name.upcase + OPTION_SEP_SYMBOL
         ENV.each do |k, v|
           if k.start_with?(env_prefix)
             @unprocessed_env.push([k[env_prefix.length..-1].downcase.to_sym, v])
@@ -127,71 +135,81 @@ module Aspera
         Log.log.debug{"env=#{@unprocessed_env}".red}
         @unprocessed_cmd_line_options = []
         @unprocessed_cmd_line_arguments = []
-        # argv is nil when help is generated for every plugin
-        unless argv.nil?
-          @parser.separator('')
-          @parser.separator('OPTIONS: global')
-          declare(:interactive, 'Use interactive input of missing params', values: :bool, handler: {o: self, m: :ask_missing_mandatory})
-          declare(:ask_options, 'Ask even optional options', values: :bool, handler: {o: self, m: :ask_missing_optional})
-          parse_options!
-          process_options = true
-          until argv.empty?
-            value = argv.shift
-            if process_options && value.start_with?('-')
-              if value.eql?('--')
-                process_options = false
-              else
-                @unprocessed_cmd_line_options.push(value)
-              end
+      end
+
+      def parse_command_line(argv)
+        @parser.separator('')
+        @parser.separator('OPTIONS: global')
+        declare(:interactive, 'Use interactive input of missing params', values: :bool, handler: {o: self, m: :ask_missing_mandatory})
+        declare(:ask_options, 'Ask even optional options', values: :bool, handler: {o: self, m: :ask_missing_optional})
+        parse_options!
+        process_options = true
+        until argv.empty?
+          value = argv.shift
+          if process_options && value.start_with?('-')
+            if value.eql?('--')
+              process_options = false
             else
-              @unprocessed_cmd_line_arguments.push(value)
+              @unprocessed_cmd_line_options.push(value)
             end
+          else
+            @unprocessed_cmd_line_arguments.push(value)
           end
         end
         @initial_cli_options = @unprocessed_cmd_line_options.dup
-        Log.log.debug{"add_cmd_line_options:commands/args=#{@unprocessed_cmd_line_arguments},options=#{@unprocessed_cmd_line_options}".red}
+        Log.log.debug{"add_cmd_line_options:commands/arguments=#{@unprocessed_cmd_line_arguments},options=#{@unprocessed_cmd_line_options}".red}
       end
 
+      # @param descr [String] description for help
       # @param expected is
-      #    - Array of allowed value (single value)
-      #    - :multiple for remaining values
-      #    - :single for a single unconstrained value
-      # @param mandatory true/false
-      # @param type expected class for result
-      # @param aliases list of aliases for the value
+      #   - Array of allowed value (single value)
+      #   - :multiple for remaining values
+      #   - :single for a single unconstrained value
+      #   - :integer for a single integer value
+      # @param mandatory [Boolean] if true, raise error if option not set
+      # @param type [Class, Array] accepted value type(s)
+      # @param aliases [Hash] map of aliases: key = alias, value = real value
+      # @param default [Object] default value
       # @return value, list or nil
       def get_next_argument(descr, expected: :single, mandatory: true, type: nil, aliases: nil, default: nil)
         unless type.nil?
-          raise 'internal: type must be a Class' unless type.is_a?(Class)
+          type = [type] unless type.is_a?(Array)
+          raise "INTERNAL ERROR: type must be Array of Class: #{type}" unless type.all?(Class)
           descr = "#{descr} (#{type})"
         end
-        result = default
-        if !@unprocessed_cmd_line_arguments.empty?
-          # there are values
-          case expected
-          when :single
-            result = ExtendedValue.instance.evaluate(@unprocessed_cmd_line_arguments.shift)
-          when :multiple
-            result = @unprocessed_cmd_line_arguments.shift(@unprocessed_cmd_line_arguments.length).map{|v|ExtendedValue.instance.evaluate(v)}
-            # if expecting list and only one arg of type array : it is the list
-            if result.length.eql?(1) && result.first.is_a?(Array)
-              result = result.first
+        result =
+          if !@unprocessed_cmd_line_arguments.empty?
+            # there are values
+            case expected
+            when :single
+              ExtendedValue.instance.evaluate(@unprocessed_cmd_line_arguments.shift)
+            when :multiple
+              value = @unprocessed_cmd_line_arguments.shift(@unprocessed_cmd_line_arguments.length).map{|v|ExtendedValue.instance.evaluate(v)}
+              # if expecting list and only one arg of type array : it is the list
+              if value.length.eql?(1) && value.first.is_a?(Array)
+                value = value.first
+              end
+              value
+            when Array
+              allowed_values = [].concat(expected)
+              allowed_values.concat(aliases.keys) unless aliases.nil?
+              raise "internal error: only symbols allowed: #{allowed_values}" unless allowed_values.all?(Symbol)
+              self.class.get_from_list(@unprocessed_cmd_line_arguments.shift, descr, allowed_values)
+            else
+              raise 'Internal error: expected: must be single, multiple, or value array'
             end
-          when Array
-            allowed_values = [].concat(expected)
-            allowed_values.concat(aliases.keys) unless aliases.nil?
-            raise "internal error: only symbols allowed: #{allowed_values}" unless allowed_values.all?(Symbol)
-            result = self.class.get_from_list(@unprocessed_cmd_line_arguments.shift, descr, allowed_values)
-          else
-            raise 'internal error'
+          elsif !default.nil? then default
+            # no value provided, either get value interactively, or exception
+          elsif mandatory then get_interactive(:argument, descr, expected: expected)
           end
-        elsif mandatory
-          # no value provided
-          result = get_interactive(:argument, descr, expected: expected)
+        if result.is_a?(String) && type.eql?([Integer])
+          str_result = result
+          result = Integer(str_result, exception: false)
+          raise Cli::BadArgument, "Invalid integer: #{str_result}" if result.nil?
         end
         Log.log.debug{"#{descr}=#{result}"}
         result = aliases[result] if !aliases.nil? && aliases.key?(result)
-        raise "argument shall be #{type.name}" unless type.nil? || result.is_a?(type)
+        self.class.validate_type(:argument, descr, result, type) unless result.nil? && !mandatory
         return result
       end
 
@@ -201,52 +219,50 @@ module Aspera
       # either return value or calls handler, can return nil
       # ask interactively if requested/required
       # @param mandatory [Boolean] if true, raise error if option not set
-      # @param allowed_types [Array] list of allowed types
-      def get_option(option_symbol, mandatory: false, allowed_types: nil)
-        allowed_types = [allowed_types] if allowed_types.is_a?(Class)
-        raise 'Internal Error: allowed_types must be an Array of Class or a Class' unless allowed_types.nil? || allowed_types.is_a?(Array)
+      def get_option(option_symbol, mandatory: false, default: nil)
+        attributes = @declared_options[option_symbol]
+        raise "INTERNAL ERROR: option not declared: #{option_symbol}" unless attributes
         result = nil
-        if @declared_options.key?(option_symbol)
-          case @declared_options[option_symbol][:read_write]
-          when :accessor
-            result = @declared_options[option_symbol][:accessor].value
-          when :value
-            result = @declared_options[option_symbol][:value]
-          else
-            raise 'unknown type'
-          end
-          Log.log.debug{"(#{@declared_options[option_symbol][:read_write]}) get #{option_symbol}=#{result}"}
+        case attributes[:read_write]
+        when :accessor
+          result = attributes[:accessor].value
+        when :value
+          result = attributes[:value]
+        else
+          raise 'unknown type'
         end
+        Log.log.debug{"(#{attributes[:read_write]}) get #{option_symbol}=#{result}"}
+        result = default if result.nil?
         # do not fail for manual generation if option mandatory but not set
         result = '' if result.nil? && mandatory && !@fail_on_missing_mandatory
         # Log.log.debug{"interactive=#{@ask_missing_mandatory}"}
         if result.nil?
           if !@ask_missing_mandatory
-            raise CliBadArgument, "Missing mandatory option: #{option_symbol}" if mandatory
+            raise Cli::BadArgument, "Missing mandatory option: #{option_symbol}" if mandatory
           elsif @ask_missing_optional || mandatory
             # ask_missing_mandatory
             expected = :single
             # print "please enter: #{option_symbol.to_s}"
-            if @declared_options.key?(option_symbol) && @declared_options[option_symbol].key?(:values)
-              expected = @declared_options[option_symbol][:values]
+            if @declared_options.key?(option_symbol) && attributes.key?(:values)
+              expected = attributes[:values]
             end
             result = get_interactive(:option, option_symbol.to_s, expected: expected)
             set_option(option_symbol, result, 'interactive')
           end
         end
-        raise "option #{option_symbol} is #{result.class} but must be one of #{allowed_types}" unless \
-          !mandatory || allowed_types.nil? || allowed_types.any? { |t|result.is_a?(t)}
+        self.class.validate_type(:option, option_symbol, result, attributes[:types]) unless result.nil? && !mandatory
         return result
       end
 
       # set an option value by name, either store value or call handler
       def set_option(option_symbol, value, where='code override')
-        raise CliBadArgument, "Unknown option: #{option_symbol}" unless @declared_options.key?(option_symbol)
+        raise Cli::BadArgument, "Unknown option: #{option_symbol}" unless @declared_options.key?(option_symbol)
         attributes = @declared_options[option_symbol]
         Log.log.warn("#{option_symbol}: Option is deprecated: #{attributes[:deprecation]}") if attributes[:deprecation]
         value = ExtendedValue.instance.evaluate(value)
         value = Manager.enum_to_bool(value) if attributes[:values].eql?(BOOLEAN_VALUES)
         Log.log.debug{"(#{attributes[:read_write]}/#{where}) set #{option_symbol}=#{value}"}
+        self.class.validate_type(:option, option_symbol, value, attributes[:types])
         case attributes[:read_write]
         when :accessor
           attributes[:accessor].value = value
@@ -269,9 +285,11 @@ module Aspera
       # @param block [Proc] block to execute when option is found
       def declare(option_symbol, description, handler: nil, default: nil, values: nil, short: nil, coerce: nil, types: nil, deprecation: nil, &block)
         raise "INTERNAL ERROR: #{option_symbol} already declared" if @declared_options.key?(option_symbol)
+        # raise "INTERNAL ERROR: #{option_symbol} clash with another option" if
+        # @declared_options.keys.map(&:to_s).any?{|k|k.start_with?(option_symbol.to_s) || option_symbol.to_s.start_with?(k)}
         raise "INTERNAL ERROR: #{option_symbol} ends with dot" unless description[-1] != '.'
-        raise "INTERNAL ERROR: #{option_symbol} does not start with capital" unless description[0] == description[0].upcase
-        raise "INTERNAL ERROR: #{option_symbol} shall use :types" if description.downcase.include?('hash') || description.downcase.include?('extended value')
+        raise "INTERNAL ERROR: #{option_symbol} description does not start with capital" unless description[0] == description[0].upcase
+        raise "INTERNAL ERROR: #{option_symbol} shall use :types" if ['hash', 'extended value'].any?{|s|description.downcase.include?(s) }
         opt = @declared_options[option_symbol] = {
           read_write: handler.nil? ? :value : :accessor,
           # by default passwords and secrets are sensitive, else specify when declaring the option
@@ -279,7 +297,7 @@ module Aspera
         }
         if !types.nil?
           types = [types] unless types.is_a?(Array)
-          raise "INTERNAL ERROR: types must be classes: #{types}" unless types.all?(Class)
+          raise "INTERNAL ERROR: types must be Array of Class: #{types}" unless types.all?(Class)
           opt[:types] = types
           description = "#{description} (#{types.map(&:name).join(', ')})"
         end
@@ -292,7 +310,7 @@ module Aspera
           raise 'internal error' unless handler.is_a?(Hash)
           raise 'internal error' unless handler.keys.sort.eql?(%i[m o])
           Log.log.debug{"set attr obj #{option_symbol} (#{handler[:o]},#{handler[:m]})"}
-          opt[:accessor] = AttrAccessor.new(handler[:o], handler[:m])
+          opt[:accessor] = AttrAccessor.new(handler[:o], handler[:m], option_symbol)
         end
         set_option(option_symbol, default, 'default') unless default.nil?
         on_args = [description]
@@ -301,7 +319,7 @@ module Aspera
           on_args.push(symbol_to_option(option_symbol, 'VALUE'))
           on_args.push("-#{short}VALUE") unless short.nil?
           on_args.push(coerce) unless coerce.nil?
-          @parser.on(*on_args) { |v| set_option(option_symbol, v, 'cmdline') }
+          @parser.on(*on_args) { |v| set_option(option_symbol, v, SOURCE_USER) }
         when Array, :bool
           if values.eql?(:bool)
             values = BOOLEAN_VALUES
@@ -317,7 +335,7 @@ module Aspera
           on_args[0] = "#{description}: #{help_values}"
           on_args.push(symbol_to_option(option_symbol, 'ENUM'))
           on_args.push(values)
-          @parser.on(*on_args){|v|set_option(option_symbol, self.class.get_from_list(v.to_s, description, values), 'cmdline')}
+          @parser.on(*on_args){|v|set_option(option_symbol, self.class.get_from_list(v.to_s, description, values), SOURCE_USER)}
         when :date
           on_args.push(symbol_to_option(option_symbol, 'DATE'))
           @parser.on(*on_args) do |v|
@@ -326,14 +344,14 @@ module Aspera
             when /^-([0-9]+)h/ then Manager.time_to_string(Time.now - (Regexp.last_match(1).to_i * 3600))
             else v
             end
-            set_option(option_symbol, time_string, 'cmdline')
+            set_option(option_symbol, time_string, SOURCE_USER)
           end
         when :none
           raise "internal error: missing block for #{option_symbol}" if block.nil?
           on_args.push(symbol_to_option(option_symbol, nil))
           on_args.push("-#{short}") if short.is_a?(String)
           @parser.on(*on_args, &block)
-        else raise 'internal error'
+        else raise "internal error: Unknown type for values: #{values} / #{values.class}"
         end
         Log.log.debug{"on_args=#{on_args}"}
       end
@@ -363,31 +381,32 @@ module Aspera
       # get all original options on command line used to generate a config in config file
       def get_options_table(remove_from_remaining: true)
         result = {}
-        @initial_cli_options.each do |optionval|
-          case optionval
+        @initial_cli_options.each do |option_value|
+          case option_value
           when /^--([^=]+)$/
             # ignore
           when /^--([^=]+)=(.*)$/
             name = Regexp.last_match(1)
             value = Regexp.last_match(2)
-            name.gsub!(OPTION_SEP_LINE, OPTION_SEP_SYMB)
+            name.gsub!(OPTION_SEP_LINE, OPTION_SEP_SYMBOL)
             value = ExtendedValue.instance.evaluate(value)
             Log.log.debug{"option #{name}=#{value}"}
             result[name] = value
-            @unprocessed_cmd_line_options.delete(optionval) if remove_from_remaining
+            @unprocessed_cmd_line_options.delete(option_value) if remove_from_remaining
           else
-            raise CliBadArgument, "wrong option format: #{optionval}"
+            raise Cli::BadArgument, "wrong option format: #{option_value}"
           end
         end
         return result
       end
 
-      # return options as taken from config file and command line just before command execution
-      def declared_options(only_defined: false)
+      # @param only_defined [Boolean] if true, only return options that were defined
+      # @return [Hash] options as taken from config file and command line just before command execution
+      def known_options(only_defined: false)
         result = {}
-        @declared_options.each_key do |option_symb|
-          v = get_option(option_symb)
-          result[option_symb.to_s] = v unless only_defined && v.nil?
+        @declared_options.each_key do |option_symbol|
+          v = get_option(option_symbol)
+          result[option_symbol] = v unless only_defined && v.nil?
         end
         return result
       end
@@ -416,21 +435,36 @@ module Aspera
         @unprocessed_cmd_line_options = unknown_options
       end
 
-      private
-
       def prompt_user_input(prompt, sensitive)
         return $stdin.getpass("#{prompt}> ") if sensitive
         print("#{prompt}> ")
-        return $stdin.gets.chomp
+        line = $stdin.gets
+        raise 'Unexpected end of standard input' if line.nil?
+        return line.chomp
+      end
+
+      # prompt user for input in a list of symbols
+      # @param prompt [String] prompt to display
+      # @param sym_list [Array] list of symbols to select from
+      # @return [Symbol] selected symbol
+      def prompt_user_input_in_list(prompt, sym_list)
+        loop do
+          input = prompt_user_input(prompt, false).to_sym
+          if sym_list.any?{|a|a.eql?(input)}
+            return input
+          else
+            $stderr.puts("No such #{prompt}: #{input}, select one of: #{sym_list.join(', ')}")
+          end
+        end
       end
 
       def get_interactive(type, descr, expected: :single)
         if !@ask_missing_mandatory
-          raise CliBadArgument, self.class.bad_arg_message_multi("missing: #{descr}", expected) if expected.is_a?(Array)
-          raise CliBadArgument, "missing argument (#{expected}): #{descr}"
+          raise Cli::BadArgument, self.class.bad_arg_message_multi("missing: #{descr}", expected) if expected.is_a?(Array)
+          raise Cli::BadArgument, "missing argument (#{expected}): #{descr}"
         end
         result = nil
-        sensitive = type.eql?(:option) && @declared_options[descr.to_sym][:sensitive]
+        sensitive = type.eql?(:option) && @declared_options[descr.to_sym].is_a?(Hash) && @declared_options[descr.to_sym][:sensitive]
         default_prompt = "#{type}: #{descr}"
         # ask interactively
         case expected
@@ -450,9 +484,11 @@ module Aspera
         return result
       end
 
+      private
+
       # generate command line option from option symbol
       def symbol_to_option(symbol, opt_val)
-        result = '--' + symbol.to_s.gsub(OPTION_SEP_SYMB, OPTION_SEP_LINE)
+        result = '--' + symbol.to_s.gsub(OPTION_SEP_SYMBOL, OPTION_SEP_LINE)
         result = result + '=' + opt_val unless opt_val.nil?
         return result
       end