aspera-cli 4.25.6 → 4.26.0

data/lib/aspera/cli/formatter.rb

@@ -28,12 +28,14 @@ module Aspera
       DISPLAY_LEVELS = %i[info data error].freeze
       # column names for single object display in table
       SINGLE_OBJECT_COLUMN_NAMES = %i[field value].freeze
+      # Terminal: vertical separator for list of strings.
+      STR_LST_SEP_VERT = "\n"
 
-      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES
+      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT
 
       class << self
         # nicer display for boolean
-        # used by spec_doc
+        # used by `spec_doc`
         def tick(yes)
           result =
             if Environment.terminal_supports_unicode?
@@ -47,14 +49,14 @@ module Aspera
 
         # Highlight special values on terminal
         # empty values are dim
-        # used by spec_doc
+        # used by `spec_doc`
         def special_format(what)
           result = "<#{what}>"
           return %w[null empty].any?{ |s| what.include?(s)} ? result.dim : result.reverse_color
         end
 
-        # for transfer spec table, build line for display in terminal
-        # used by spec_doc
+        # For transfer spec table, build line for display in terminal
+        # used by `spec_doc`
         def check_row(row)
           row.each_key do |k|
             row[k] = row[k].map{ |i| WordWrap.ww(i.to_s, 120).chomp}.join("\n") if row[k].is_a?(Array)
@@ -62,7 +64,7 @@ module Aspera
         end
 
         # Give Markdown String, or matched data, return formatted string for terminal
-        # used by spec_doc
+        # used by `spec_doc`
         # @param match [MatchData,String]
         def markdown_text(match)
           if match.is_a?(String)
@@ -83,7 +85,7 @@ module Aspera
         end
 
         # Replace special values with a readable version on terminal
-        def replace_specific_for_terminal(input_hash)
+        def replace_specific_for_terminal(input_hash, string_list_separator)
           hash_to_process = [input_hash]
           until hash_to_process.empty?
             current = hash_to_process.pop
@@ -99,7 +101,7 @@ module Aspera
                 if value.empty?
                   current[key] = special_format('empty list')
                 elsif value.all?(String)
-                  current[key] = value.join(',')
+                  current[key] = value.join(string_list_separator)
                 else
                   value.each do |item|
                     hash_to_process.push(item) if item.is_a?(Hash)
@@ -117,8 +119,7 @@ module Aspera
         end
 
         def all_but(list)
-          list = [list] unless list.is_a?(Array)
-          return list.map{ |i| "#{FIELDS_LESS}#{i}"}.unshift(SpecialValues::ALL)
+          Array(list).map{ |i| "#{FIELDS_LESS}#{i}"}.unshift(SpecialValues::ALL)
         end
       end
 
@@ -159,11 +160,6 @@ module Aspera
       end
 
       def declare_options(options)
-        default_table_style = if Environment.terminal_supports_unicode?
-          {border: :unicode_round}
-        else
-          {}
-        end
         options.declare(:display, 'Output only some information', allowed: DISPLAY_LEVELS, handler: {o: self, m: :option_handler}, default: :data)
         options.declare(:format, 'Output format', allowed: DISPLAY_FORMATS, handler: {o: self, m: :option_handler}, default: :table)
         options.declare(:output, 'Destination for results', handler: {o: self, m: :option_handler})
@@ -173,7 +169,7 @@ module Aspera
           default: SpecialValues::DEF
         )
         options.declare(:select, 'Select only some items in lists: column, value', allowed: [Hash, Proc], handler: {o: self, m: :option_handler})
-        options.declare(:table_style, '(Table) Display style', allowed: [Hash], handler: {o: self, m: :option_handler}, default: default_table_style)
+        options.declare(:table_style, '(Table) Display style', allowed: [Hash], handler: {o: self, m: :option_handler}, default: {})
         options.declare(:flat_hash, '(Table) Display deep values as additional keys', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :option_handler}, default: true)
         options.declare(
           :multi_single, '(Table) Control how object list is displayed as single table, or multiple objects', allowed: %i[no yes single],
@@ -249,15 +245,16 @@ module Aspera
         SecretHider.instance.deep_remove_secret(data) if hide_secrets?
       end
 
-      # this method displays the results, especially the table format
-      # @param type [Symbol] type of data
-      # @param data [Object] data to display
-      # @param total [Integer] total number of items
-      # @param fields [Array<String>] list of fields to display
-      # @param name [String] name of the column to display
-      def display_results(type:, data: nil, total: nil, fields: nil, name: nil)
-        Log.log.debug{"display_results: type=#{type} class=#{data.class}"}
-        Log.log.trace1{"display_results: data=#{data}"}
+      # Display results, especially the table format
+      # @param type [Symbol] Type of data
+      # @param data [Object] Data to display
+      # @param fields [Array<String>] List of fields to display
+      # @param total [Integer] Total number of items
+      # @param name [String] Name of the column to display
+      def display_results(type:, data: nil, fields: nil, total: nil, name: nil)
+        Log.log.debug{"display_results: type=#{type}"}
+        Log.dump(:data, data, level: :trace1)
+        Log.dump(:fields, fields, level: :trace1)
         Aspera.assert_type(type, Symbol){'result must have type'}
         Aspera.assert(!data.nil? || %i[empty nothing].include?(type)){'result must have data'}
         display_item_count(data.length, total) unless total.nil?
@@ -317,7 +314,7 @@ module Aspera
           case type
           when :single_object
             # :single_object is a Hash, where key=column name
-            Aspera.assert_type(data, Hash)
+            Aspera.assert_type(data, Hash){'result'}
             if data.empty?
               display_message(:data, self.class.special_format('empty dict'))
             else
@@ -364,6 +361,7 @@ module Aspera
       # @param default [Array<String>, Proc] list of fields to display by default (may contain special values)
       def compute_fields(data, default)
         Log.log.debug{"compute_fields: data:#{data.class} default:#{default.class} #{default}"}
+        Log.dump(:compute_fields_default, default, level: :trace1)
         # the requested list of fields, but if can contain special values
         request =
           case @options[:fields]
@@ -374,6 +372,7 @@ module Aspera
           when Proc then return all_fields(data).select{ |i| @options[:fields].call(i)}
           else Aspera.error_unexpected_value(@options[:fields])
           end
+        Aspera.assert_array_all(request, String)
         result = []
         until request.empty?
           item = request.shift
@@ -398,11 +397,14 @@ module Aspera
             end
           end
         end
+        Log.dump(:compute_fields, result, level: :trace1)
         return result
       end
 
       # filter the list of items on the fields option
       def filter_list_on_fields(data)
+        # no filter for single element
+        return data unless data.is_a?(Array)
         # by default, keep all data intact
         return data if @options[:fields].eql?(SpecialValues::DEF) && @options[:select].nil?
         Aspera.assert_array_all(data, Hash){'filter or select'}
@@ -428,21 +430,26 @@ module Aspera
         end
       end
 
-      # displays a list of objects
-      # @param object_array  [Array] array of hash
-      # @param fields        [Array] list of column names
+      # Displays a list of objects
+      # @param object_array [Array<Hash>] Array of hash
+      # @param fields [Array<String>] List of column names
+      # @param single [Boolean] Contains a single object to display
       def display_table(object_array, fields, single: false)
-        Aspera.assert(!fields.nil?){'missing fields parameter'}
+        Aspera.assert_array_all(object_array, Hash)
+        Aspera.assert_array_all(fields, String)
         if object_array.empty?
           # no  display for csv
           display_message(:info, self.class.special_format('empty')) if @options[:format].eql?(:table)
           return
         end
         filter_columns_on_select(object_array)
-        object_array.each{ |i| self.class.replace_specific_for_terminal(i)}
+        format_style = @options[:table_style].symbolize_keys
+        string_list_separator = format_style.delete(:str_lst_sep) || STR_LST_SEP_VERT
+        # convert data to string, and keep only display fields
+        object_array.each{ |i| self.class.replace_specific_for_terminal(i, string_list_separator)}
         # if table has only one element, and only one field, display the value
         if object_array.length == 1 && fields.length == 1
-          Log.log.debug("display_table: single element, field: #{fields.first}")
+          Log.log.debug("single element, field: #{fields.first}")
           data = object_array.first[fields.first]
           unless data.is_a?(Array) && data.all?(Hash)
             display_message(:data, data)
@@ -453,6 +460,7 @@ module Aspera
           single = false
         end
         Log.dump(:object_array, object_array)
+        Log.dump(:fields, fields)
         # convert data to string, and keep only display fields
         final_table_rows = object_array.map{ |r| fields.map{ |c| r[c].to_s}}
         # remove empty rows
@@ -460,6 +468,7 @@ module Aspera
         # here : fields : list of column names
         case @options[:format]
         when :table
+          format_style[:border] = :unicode_round if Environment.terminal_supports_unicode?
           if single || @options[:multi_single].eql?(:yes) ||
               (@options[:multi_single].eql?(:single) && final_table_rows.length.eql?(1))
             # display multiple objects as multiple transposed tables
@@ -467,23 +476,20 @@ module Aspera
               display_message(:data, Terminal::Table.new(
                 headings:  SINGLE_OBJECT_COLUMN_NAMES,
                 rows:      fields.zip(row),
-                style:     @options[:table_style].symbolize_keys
+                style:     format_style
               ))
             end
           else
-            # display the table ! as single table
+            # display the table as single table
             display_message(:data, Terminal::Table.new(
               headings:  fields,
               rows:      final_table_rows,
-              style:     @options[:table_style].symbolize_keys
+              style:     format_style
             ))
           end
         when :csv
-          params = @options[:table_style].symbolize_keys
-          # delete default
-          params.delete(:border)
-          add_headers = params.delete(:headers)
-          output = CSV.generate(**params) do |csv|
+          add_headers = format_style.delete(:headers)
+          output = CSV.generate(**format_style) do |csv|
             csv << fields if add_headers
             final_table_rows.each do |row|
               csv << row
@@ -493,6 +499,7 @@ module Aspera
         else
           raise "not expected: #{@options[:format]}"
         end
+        nil
       end
     end
   end

data/lib/aspera/cli/manager.rb

@@ -146,7 +146,7 @@ module Aspera
         new_value = [new_value] if @types.eql?(Allowed::TYPES_STRING_ARRAY) && new_value.is_a?(String)
         # Setting a Hash to null set an empty hash
         new_value = {} if new_value.eql?(nil) && @types&.first.eql?(Hash)
-        # Setting a Array to null set an empty hash
+        # Setting a Array to null set an empty array
         new_value = [] if new_value.eql?(nil) && @types&.first.eql?(Array)
         if @types.eql?(Aspera::Cli::Allowed::TYPES_SYMBOL_ARRAY)
           new_value = [new_value] if new_value.is_a?(String)
@@ -204,6 +204,15 @@ module Aspera
         def option_name_to_line(name)
           return "#{OPTION_PREFIX}#{name.to_s.gsub(OPTION_SEP_SYMBOL, OPTION_SEP_LINE)}"
         end
+
+        # @return [Hash{Symbol => String}, nil] `{field:,value:}` if identifier is a percent selector, else `nil`
+        def percent_selector(identifier)
+          Aspera.assert_type(identifier, String)
+          if (m = identifier.match(REGEX_LOOKUP_ID_BY_FIELD))
+            return {field: m[1], value: ExtendedValue.instance.evaluate(m[2], context: "percent selector: #{m[1]}")}
+          end
+          nil
+        end
       end
 
       attr_reader :parser
@@ -281,7 +290,7 @@ module Aspera
         Aspera.assert(!@declared_options.key?(option_symbol)){"#{option_symbol} already declared"}
         Aspera.assert(description[-1] != '.'){"#{option_symbol} ends with dot"}
         Aspera.assert(description[0] == description[0].upcase){"#{option_symbol} description does not start with an uppercase"}
-        Aspera.assert(!['hash', 'extended value'].any?{ |s| description.downcase.include?(s)}){"#{option_symbol} shall use :allowed"}
+        Aspera.assert(!['hash', 'extended value'].any?{ |s| description.downcase.include?(s)}){"#{option_symbol} shall use :allowed instead of hash/extended value in option description"}
         Aspera.assert_type(handler, Hash) if handler
         Aspera.assert(handler.keys.sort.eql?(%i[m o])) if handler
         option_attrs = @declared_options[option_symbol] = OptionValue.new(
@@ -390,6 +399,21 @@ module Aspera
         return result
       end
 
+      # Resource identifier as positional parameter
+      #
+      # @param description [String] description of the identifier
+      # @param block       [Proc] block to search for identifier based on attribute value
+      # @return   [String, Array] identifier or list of ids
+      def instance_identifier(description: 'identifier', &block)
+        res_id = get_next_argument(description, multiple: get_option(:bulk)) if res_id.nil?
+        # Can be an Array
+        if res_id.is_a?(String) && (m = Manager.percent_selector(res_id))
+          Aspera.assert(block_given?, type: Cli::BadArgument){"Percent syntax for #{description} not supported in this context"}
+          res_id = yield(m[:field], m[:value])
+        end
+        return res_id
+      end
+
       def get_next_command(command_list, aliases: nil); return get_next_argument('command', accept_list: command_list, aliases: aliases); end
 
       # Get an option value by name
@@ -508,7 +532,7 @@ module Aspera
         begin
           # remove known options one by one, exception if unknown
           Log.log.trace1('Before parse')
-          Log.dump(:unprocessed_cmd_line_options, @unprocessed_cmd_line_options)
+          Log.dump(:unprocessed_cmd_line_options, @unprocessed_cmd_line_options, level: :trace1)
           @parser.parse!(@unprocessed_cmd_line_options)
           Log.log.trace1('After parse')
         rescue OptionParser::InvalidOption => e
@@ -678,8 +702,10 @@ module Aspera
       # when this is alone, this stops option processing
       OPTIONS_STOP = '--'
       SOURCE_USER = 'cmdline' # cspell:disable-line
+      # Percent selector: select by this field for this value
+      REGEX_LOOKUP_ID_BY_FIELD = /^%([^:]+):(.*)$/
 
-      private_constant :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :OPTION_VALUE_SEPARATOR, :OPTION_PREFIX, :OPTIONS_STOP, :SOURCE_USER
+      private_constant :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :OPTION_VALUE_SEPARATOR, :OPTION_PREFIX, :OPTIONS_STOP, :SOURCE_USER, :REGEX_LOOKUP_ID_BY_FIELD
     end
   end
 end