aspera-cli 4.13.0 → 4.14.0

data/lib/aspera/cli/manager.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/colors'
 require 'aspera/log'
+require 'aspera/secret_hider'
 require 'aspera/cli/extended_value'
 require 'optparse'
 require 'io/console'
@@ -103,7 +104,7 @@ module Aspera
         @unprocessed_cmd_line_options = []
         # a copy of all initial options
         @initial_cli_options = []
-        # option description: key = option symbol, value=hash, :type, :accessor, :value, :accepted
+        # option description: key = option symbol, value=hash, :read_write, :accessor, :value, :accepted
         @declared_options = {}
         # do we ask missing options and arguments to user ?
         @ask_missing_mandatory = false # STDIN.isatty
@@ -130,10 +131,8 @@ module Aspera
         unless argv.nil?
           @parser.separator('')
           @parser.separator('OPTIONS: global')
-          set_obj_attr(:interactive, self, :ask_missing_mandatory)
-          set_obj_attr(:ask_options, self, :ask_missing_optional)
-          add_opt_boolean(:interactive, 'use interactive input of missing params')
-          add_opt_boolean(:ask_options, 'ask even optional options')
+          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?
@@ -153,21 +152,20 @@ module Aspera
         Log.log.debug{"add_cmd_line_options:commands/args=#{@unprocessed_cmd_line_arguments},options=#{@unprocessed_cmd_line_options}".red}
       end
 
-      def get_next_command(command_list); return get_next_argument('command', expected: command_list); end
-
       # @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
       # @return value, list or nil
-      def get_next_argument(descr, expected: :single, mandatory: true, type: 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)
           descr = "#{descr} (#{type})"
         end
-        result = nil
+        result = default
         if !@unprocessed_cmd_line_arguments.empty?
           # there are values
           case expected
@@ -179,66 +177,37 @@ module Aspera
             if result.length.eql?(1) && result.first.is_a?(Array)
               result = result.first
             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
-            result = self.class.get_from_list(@unprocessed_cmd_line_arguments.shift, descr, expected)
+            raise 'internal error'
           end
         elsif mandatory
           # no value provided
           result = get_interactive(:argument, descr, expected: expected)
         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)
         return result
       end
 
-      # declare option of type :accessor, or :value
-      def declare_option(option_symbol, type)
-        Log.log.debug{"declare_option: #{option_symbol}: #{type}: skip=#{@declared_options.key?(option_symbol)}".green}
-        if @declared_options.key?(option_symbol)
-          raise "INTERNAL ERROR: option #{option_symbol} already declared. only accessor can be re-declared and ignored" \
-          unless @declared_options[option_symbol][:type].eql?(:accessor)
-          return
-        end
-        @declared_options[option_symbol] = {type: type}
-        # by default passwords and secrets are sensitive, else specify when declaring the option
-        @declared_options[option_symbol][:sensitive] = true if !%w[password secret key].select{|i| option_symbol.to_s.end_with?(i)}.empty?
-      end
-
-      # define option with handler
-      def set_obj_attr(option_symbol, object, attr_symb, default_value=nil)
-        Log.log.debug{"set attr obj #{option_symbol} (#{object},#{attr_symb})"}
-        declare_option(option_symbol, :accessor)
-        @declared_options[option_symbol][:accessor] = AttrAccessor.new(object, attr_symb)
-        set_option(option_symbol, default_value, 'default obj attr') if !default_value.nil?
-      end
-
-      # set an option value by name, either store value or call handler
-      def set_option(option_symbol, value, where='default')
-        if !@declared_options.key?(option_symbol)
-          Log.log.debug{"set unknown option: #{option_symbol}"}
-          raise 'ERROR: cannot set undeclared option'
-          # declare_option(option_symbol)
-        end
-        value = ExtendedValue.instance.evaluate(value)
-        value = Manager.enum_to_bool(value) if @declared_options[option_symbol][:values].eql?(BOOLEAN_VALUES)
-        Log.log.debug{"(#{@declared_options[option_symbol][:type]}/#{where}) set #{option_symbol}=#{value}"}
-        case @declared_options[option_symbol][:type]
-        when :accessor
-          @declared_options[option_symbol][:accessor].value = value
-        when :value
-          @declared_options[option_symbol][:value] = value
-        else # nil or other
-          raise 'error'
-        end
-      end
+      def get_next_command(command_list, aliases: nil); return get_next_argument('command', expected: command_list, aliases: aliases); end
 
       # Get an option value by name
-      # either return value or call handler, can return nil
+      # either return value or calls handler, can return nil
       # ask interactively if requested/required
-      def get_option(option_symbol, is_type: :optional)
+      # @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)
         result = nil
         if @declared_options.key?(option_symbol)
-          case @declared_options[option_symbol][:type]
+          case @declared_options[option_symbol][:read_write]
           when :accessor
             result = @declared_options[option_symbol][:accessor].value
           when :value
@@ -246,15 +215,15 @@ module Aspera
           else
             raise 'unknown type'
           end
-          Log.log.debug{"(#{@declared_options[option_symbol][:type]}) get #{option_symbol}=#{result}"}
+          Log.log.debug{"(#{@declared_options[option_symbol][:read_write]}) get #{option_symbol}=#{result}"}
         end
         # do not fail for manual generation if option mandatory but not set
-        result = '' if result.nil? && is_type.eql?(:mandatory) && !@fail_on_missing_mandatory
+        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 is_type.eql?(:mandatory)
-          elsif @ask_missing_optional || is_type.eql?(:mandatory)
+            raise CliBadArgument, "Missing mandatory option: #{option_symbol}" if mandatory
+          elsif @ask_missing_optional || mandatory
             # ask_missing_mandatory
             expected = :single
             # print "please enter: #{option_symbol.to_s}"
@@ -265,72 +234,117 @@ module Aspera
             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)}
         return result
       end
 
-      # param must be hash
-      def add_option_preset(preset_hash, op: :push)
-        Log.log.debug{"add_option_preset=#{preset_hash}"}
-        raise "internal error: setting default with no hash: #{preset_hash.class}" if !preset_hash.is_a?(Hash)
-        # incremental override
-        preset_hash.each{|k, v|@unprocessed_defaults.send(op, [k.to_sym, v])}
-      end
-
-      # define an option with restricted values
-      def add_opt_list(option_symbol, values, help, *on_args)
-        declare_option(option_symbol, :value)
-        Log.log.debug{"add_opt_list #{option_symbol}"}
-        on_args.unshift(symbol_to_option(option_symbol, 'ENUM'))
-        # this option value must be a symbol
-        @declared_options[option_symbol][:values] = values
-        value = get_option(option_symbol)
-        help_values = values.map{|i|i.eql?(value) ? highlight_current(i) : i}.join(', ')
-        if values.eql?(BOOLEAN_VALUES)
-          help_values = BOOLEAN_SIMPLE.map{|i|(i.eql?(:yes) && value) || (i.eql?(:no) && !value) ? highlight_current(i) : i}.join(', ')
+      # 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)
+        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}"}
+        case attributes[:read_write]
+        when :accessor
+          attributes[:accessor].value = value
+        when :value
+          attributes[:value] = value
+        else # nil or other
+          raise 'error'
         end
-        on_args.push(values)
-        on_args.push("#{help}: #{help_values}")
-        Log.log.debug{"on_args=#{on_args}"}
-        @parser.on(*on_args){|v|set_option(option_symbol, self.class.get_from_list(v.to_s, help, values), 'cmdline')}
       end
 
-      def add_opt_boolean(option_symbol, help, *on_args)
-        add_opt_list(option_symbol, BOOLEAN_VALUES, help, *on_args)
-        # if default was defined for obj, it may still be enum (yes/no) instead of boolean
-        default_value = get_option(option_symbol)
-        set_option(option_symbol, default_value, 'opt boolean') unless default_value.nil?
-      end
-
-      # define an option with open values
-      def add_opt_simple(option_symbol, *on_args)
-        declare_option(option_symbol, :value)
-        Log.log.debug{"add_opt_simple #{option_symbol}"}
-        on_args.unshift(symbol_to_option(option_symbol, 'VALUE'))
-        Log.log.debug{"on_args=#{on_args}"}
-        @parser.on(*on_args) { |v| set_option(option_symbol, v, 'cmdline') }
-      end
-
-      # define an option with date format
-      def add_opt_date(option_symbol, *on_args)
-        declare_option(option_symbol, :value)
-        Log.log.debug{"add_opt_date #{option_symbol}"}
-        on_args.unshift(symbol_to_option(option_symbol, 'DATE'))
-        Log.log.debug{"on_args=#{on_args}"}
-        @parser.on(*on_args) do |v|
-          case v
-          when 'now' then set_option(option_symbol, Manager.time_to_string(Time.now), 'cmdline')
-          when /^-([0-9]+)h/ then set_option(option_symbol, Manager.time_to_string(Time.now - (Regexp.last_match(1).to_i * 3600)), 'cmdline')
-          else set_option(option_symbol, v, 'cmdline')
+      # declare an option
+      # @param option_symbol [Symbol] option name
+      # @param description [String] description for help
+      # @param handler [Hash] handler for option value: keys: o (object) and m (method)
+      # @param default [Object] default value
+      # @param values [nil, Array, :bool, :date, :none] list of allowed values, :bool for true/false, :date for dates, :none for on/off switch
+      # @param short [String] short option name
+      # @param coerce [Class] one of the coerce types accepted par option parser
+      # @param types [Class, Array] accepted value type(s)
+      # @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} 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')
+        opt = @declared_options[option_symbol] = {
+          read_write: handler.nil? ? :value : :accessor,
+          # by default passwords and secrets are sensitive, else specify when declaring the option
+          sensitive:  SecretHider.secret?(option_symbol, '')
+        }
+        if !types.nil?
+          types = [types] unless types.is_a?(Array)
+          raise "INTERNAL ERROR: types must be classes: #{types}" unless types.all?(Class)
+          opt[:types] = types
+          description = "#{description} (#{types.map(&:name).join(', ')})"
+        end
+        if deprecation
+          opt[:deprecation] = deprecation
+          description = "#{description} (#{'deprecated'.blue}: #{deprecation})"
+        end
+        Log.log.debug{"declare: #{option_symbol}: #{opt[:read_write]}".green}
+        if opt[:read_write].eql?(:accessor)
+          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])
+        end
+        set_option(option_symbol, default, 'default') unless default.nil?
+        on_args = [description]
+        case values
+        when nil
+          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') }
+        when Array, :bool
+          if values.eql?(:bool)
+            values = BOOLEAN_VALUES
+            set_option(option_symbol, Manager.enum_to_bool(default), 'default') unless default.nil?
+          end
+          # this option value must be a symbol
+          opt[:values] = values
+          value = get_option(option_symbol)
+          help_values = values.map{|i|i.eql?(value) ? highlight_current(i) : i}.join(', ')
+          if values.eql?(BOOLEAN_VALUES)
+            help_values = BOOLEAN_SIMPLE.map{|i|(i.eql?(:yes) && value) || (i.eql?(:no) && !value) ? highlight_current(i) : i}.join(', ')
+          end
+          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')}
+        when :date
+          on_args.push(symbol_to_option(option_symbol, 'DATE'))
+          @parser.on(*on_args) do |v|
+            time_string = case v
+            when 'now' then Manager.time_to_string(Time.now)
+            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')
           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'
         end
+        Log.log.debug{"on_args=#{on_args}"}
       end
 
-      # define an option without value
-      def add_opt_switch(option_symbol, *on_args, &block)
-        Log.log.debug{"add_opt_on #{option_symbol}"}
-        on_args.unshift(symbol_to_option(option_symbol, nil))
-        Log.log.debug{"on_args=#{on_args}"}
-        @parser.on(*on_args, &block)
+      # Adds each of the keys of specified hash as an option
+      # @param preset_hash [Hash] hash of options to add
+      def add_option_preset(preset_hash, op: :push)
+        Log.log.debug{"add_option_preset=#{preset_hash}"}
+        raise "internal error: default expects Hash: #{preset_hash.class}" unless preset_hash.is_a?(Hash)
+        # incremental override
+        preset_hash.each{|k, v|@unprocessed_defaults.send(op, [k.to_sym, v])}
       end
 
       # check if there were unprocessed values to generate error
@@ -346,7 +360,7 @@ module Aspera
         return result
       end
 
-      # get all original options  on command line used to generate a config in config file
+      # 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|

data/lib/aspera/cli/plugin.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'aspera/cli/extended_value'
+
 module Aspera
   module Cli
     # base class for plugins modules
@@ -8,13 +10,16 @@ module Aspera
       GLOBAL_OPS = %i[create list].freeze
       # operations with id
       INSTANCE_OPS = %i[modify delete show].freeze
+      # all standard operations
       ALL_OPS = [GLOBAL_OPS, INSTANCE_OPS].flatten.freeze
-      # max number of items for list command
+      # special query parameter: max number of items for list command
       MAX_ITEMS = 'max'
-      # max number of pages for list command
+      # special query parameter: max number of pages for list command
       MAX_PAGES = 'pmax'
       # used when all resources are selected
       VAL_ALL = 'ALL'
+      # special identifier format: look for this name to find where supported
+      REGEX_LOOKUP_ID_BY_FIELD = /^%([^:]+):(.*)$/.freeze
 
       # global for inherited classes
       @@options_created = false # rubocop:disable Style/ClassVars
@@ -24,46 +29,54 @@ module Aspera
         # env.each_key {|k| raise "wrong agent key #{k}" unless AGENTS.include?(k)}
         @agents = env
         # check presence in descendant of mandatory method and constant
-        raise StandardError, "missing method 'execute_action' in #{self.class}" unless respond_to?(:execute_action)
+        raise StandardError, "Missing method 'execute_action' in #{self.class}" unless respond_to?(:execute_action)
         raise StandardError, 'ACTIONS shall be redefined by subclass' unless self.class.constants.include?(:ACTIONS)
         options.parser.separator('')
         options.parser.separator("COMMAND: #{self.class.name.split('::').last.downcase}")
         options.parser.separator("SUBCOMMANDS: #{self.class.const_get(:ACTIONS).map(&:to_s).sort.join(' ')}")
         options.parser.separator('OPTIONS:')
         return if @@options_created
-        options.add_opt_simple(:query, 'additional filter for API calls (extended value) (some commands)')
-        options.add_opt_simple(:value, 'extended value for create, update, list filter')
-        options.add_opt_simple(:property, 'name of property to set')
-        options.add_opt_simple(:id, "resource identifier (#{INSTANCE_OPS.join(',')})")
-        options.add_opt_boolean(:bulk, 'Bulk operation (only some)')
-        options.add_opt_boolean(:bfail, 'Bulk operation error handling')
-        options.set_option(:bulk, :no)
-        options.set_option(:bfail, :yes)
+        options.declare(:query, 'Additional filter for for some commands (list/delete)', types: Hash)
+        options.declare(
+          :value, 'Value for create, update, list filter', types: Hash,
+          deprecation: 'Use positional value for create/modify or option: query for list/delete')
+        options.declare(:property, 'Name of property to set (modify operation)')
+        options.declare(:id, 'Resource identifier', deprecation: "Use identifier after verb (#{INSTANCE_OPS.join(',')})")
+        options.declare(:bulk, 'Bulk operation (only some)', values: :bool, default: :no)
+        options.declare(:bfail, 'Bulk operation error handling', values: :bool, default: :yes)
         options.parse_options!
         @@options_created = true # rubocop:disable Style/ClassVars
       end
 
-      # must be called AFTER the instance action
-      def instance_identifier
+      # must be called AFTER the instance action, ... folder browse <call instance_identifier>
+      # @param description [String] description of the identifier
+      # @param block [Proc] block to search for identifier based on attribute value
+      # @return [String] identifier
+      def instance_identifier(description: 'identifier', &block)
         res_id = options.get_option(:id)
-        res_id = options.get_next_argument('identifier') if res_id.nil?
+        res_id = options.get_next_argument(description) if res_id.nil?
+        # cab be an Array
+        if res_id.is_a?(String) && (m = res_id.match(REGEX_LOOKUP_ID_BY_FIELD))
+          if block
+            res_id = yield(m[1], ExtendedValue.instance.evaluate(m[2]))
+          else
+            raise CliBadArgument, "Percent syntax for #{description} not supported in this context"
+          end
+        end
         return res_id
       end
 
-      # TODO
-      # def get_next_id_command(instance_ops: INSTANCE_OPS,global_ops: GLOBAL_OPS)
-      #  return get_next_argument('command',expected: command_list)
-      # end
-
       # For create and delete operations: execute one actin or multiple if bulk is yes
-      # @param params either single id or hash, or array for bulk
+      # @param single_or_array [Object] single hash, or array of hash for bulk
       # @param success_msg deleted or created
+      # @param id_result [String] key in result hash to use as identifier
+      # @param fields [Array] fields to display
       def do_bulk_operation(single_or_array, success_msg, id_result: 'id', fields: :default)
         raise 'programming error: missing block' unless block_given?
         params = options.get_option(:bulk) ? single_or_array : [single_or_array]
         raise 'expecting Array for bulk operation' unless params.is_a?(Array)
         Log.log.warn('Empty list given for bulk operation') if params.empty?
-        Log.dump(:bulk_create, params)
+        Log.dump(:bulk_operation, params)
         result_list = []
         params.each do |param|
           # init for delete
@@ -96,11 +109,14 @@ module Aspera
       # @param id_default [String] default identifier to use for existing entity commands (show, modify)
       # @param item_list_key [String] result is in a sub key of the json
       # @param id_as_arg [String] if set, the id is provided as url argument ?<id_as_arg>=<id>
+      # @param is_singleton [Boolean] if true, res_class_path is the full path to the resource
       # @return result suitable for CLI result
-      def entity_command(command, rest_api, res_class_path, display_fields: nil, id_default: nil, item_list_key: false, id_as_arg: false)
-        if INSTANCE_OPS.include?(command)
+      def entity_command(command, rest_api, res_class_path, display_fields: nil, id_default: nil, item_list_key: false, id_as_arg: false, is_singleton: false, &block)
+        if is_singleton
+          one_res_path = res_class_path
+        elsif INSTANCE_OPS.include?(command)
           begin
-            one_res_id = instance_identifier
+            one_res_id = instance_identifier(&block)
           rescue StandardError => e
             raise e if id_default.nil?
             one_res_id = id_default
@@ -108,29 +124,24 @@ module Aspera
           one_res_path = "#{res_class_path}/#{one_res_id}"
           one_res_path = "#{res_class_path}?#{id_as_arg}=#{one_res_id}" if id_as_arg
         end
-        # parameters mandatory for create/modify
-        if %i[create modify].include?(command)
-          parameters = options.get_option(:value, is_type: :mandatory)
-        end
-        # parameters optional for list
-        if %i[list delete].include?(command)
-          parameters = options.get_option(:value)
-        end
+
         case command
         when :create
-          return do_bulk_operation(parameters, 'created', fields: display_fields) do |params|
+          raise 'cannot create singleton' if is_singleton
+          return do_bulk_operation(value_create_modify(command: command, type: :bulk_hash), 'created', fields: display_fields) do |params|
             raise 'expecting Hash' unless params.is_a?(Hash)
             rest_api.create(res_class_path, params)[:data]
           end
         when :delete
+          raise 'cannot delete singleton' if is_singleton
           return do_bulk_operation(one_res_id, 'deleted') do |one_id|
-            rest_api.delete("#{res_class_path}/#{one_id}", parameters)
+            rest_api.delete("#{res_class_path}/#{one_id}", old_query_read_delete)
             {'id' => one_id}
           end
         when :show
           return {type: :single_object, data: rest_api.read(one_res_path)[:data], fields: display_fields}
         when :list
-          resp = rest_api.read(res_class_path, parameters)
+          resp = rest_api.read(res_class_path, old_query_read_delete)
           data = resp[:data]
           # TODO: not generic : which application is this for ?
           if resp[:http]['Content-Type'].start_with?('application/vnd.api+json')
@@ -153,6 +164,7 @@ module Aspera
             raise "An error occurred: unexpected result type for list: #{data.class}"
           end
         when :modify
+          parameters = value_create_modify(command: command, type: Hash)
           property = options.get_option(:property)
           parameters = {property => parameters} unless property.nil?
           rest_api.update(one_res_path, parameters)
@@ -169,8 +181,8 @@ module Aspera
         return entity_command(command, rest_api, res_class_path, **opts)
       end
 
-      # query for list operation
-      def option_url_query(default)
+      # query parameters in URL suitable for REST list/GET and delete/DELETE
+      def query_read_delete(default: nil)
         query = options.get_option(:query)
         # dup default, as it could be frozen
         query = default.dup if query.nil?
@@ -179,11 +191,48 @@ module Aspera
           # check it is suitable
           URI.encode_www_form(query) unless query.nil?
         rescue StandardError => e
-          raise CliBadArgument, "query must be an extended value which can be encoded with URI.encode_www_form. Refer to manual. (#{e.message})"
+          raise CliBadArgument, "Query must be an extended value which can be encoded with URI.encode_www_form. Refer to manual. (#{e.message})"
         end
         return query
       end
 
+      # TODO: when deprecation of `value` is completed: remove this method, replace with query_read_delete
+      def old_query_read_delete
+        query = options.get_option(:value) # legacy, deprecated, remove, one day...
+        query = query_read_delete if query.nil?
+        return query
+      end
+
+      # TODO: when deprecation of `value` is completed: remove this method, replace with options.get_option(:query)
+      def value_or_query(mandatory: false, allowed_types: nil)
+        value = options.get_option(:value, mandatory: false, allowed_types: allowed_types)
+        value = options.get_option(:query, mandatory: mandatory, allowed_types: allowed_types) if value.nil?
+        return value
+      end
+
+      # Retrieves an extended value from command line, used for creation or modification of entities
+      # @param default [Object] default value if not provided
+      # @param command [String] command name for error message
+      # @param type [Class] expected type of value
+      # TODO: when deprecation of `value` is completed: remove line with :value
+      def value_create_modify(default: nil, command: 'command', type: nil)
+        value = options.get_option(:value)
+        value = options.get_next_argument("parameters for #{command}", mandatory: default.nil?) if value.nil?
+        value = default if value.nil?
+        if type.nil?
+          # nothing to do
+        elsif type.is_a?(Class)
+          raise CliBadArgument, "Value must be a #{type}" unless value.is_a?(type)
+        elsif type.is_a?(Array)
+          raise CliBadArgument, "Value must be one of #{type.join(', ')}" unless type.any?{|t| value.is_a?(t)}
+        elsif type.eql?(:bulk_hash)
+          raise CliBadArgument, 'Value must be a Hash or Array of Hash' unless value.is_a?(Hash) || (value.is_a?(Array) && value.all?(Hash))
+        else
+          raise "Internal error: #{type}"
+        end
+        return value
+      end
+
       # shortcuts helpers for plugin environment
       %i[options transfer config formatter persistency].each do |name|
         define_method(name){@agents[name]}

data/lib/aspera/cli/plugins/alee.rb

@@ -13,8 +13,8 @@ module Aspera
           command = options.get_next_command(ACTIONS)
           case command
           when :entitlement
-            entitlement_id = options.get_option(:username, is_type: :mandatory)
-            customer_id = options.get_option(:password, is_type: :mandatory)
+            entitlement_id = options.get_option(:username, mandatory: true)
+            customer_id = options.get_option(:password, mandatory: true)
             api_metering = AoC.metering_api(entitlement_id, customer_id)
             return {type: :single_object, data: api_metering.read('entitlement')[:data]}
           end