aspera-cli 4.25.6 → 4.26.1

data/lib/aspera/cli/formatter.rb

@@ -9,6 +9,7 @@ require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/markdown'
 require 'aspera/dot_container'
+require 'aspera/formatter_interface'
 require 'terminal-table'
 require 'tty-spinner'
 require 'yaml'
@@ -18,6 +19,60 @@ require 'word_wrap'
 
 module Aspera
   module Cli
+    # Terminal formatter with ANSI colors and Unicode support
+    # @see FormatterInterface
+    # @see MarkdownFormatter (in build/lib/doc_helper.rb)
+    module TerminalFormatter
+      include FormatterInterface
+
+      # Format boolean with colored symbol (✓/✗ or Y/ )
+      def tick(yes)
+        result =
+          if Environment.terminal_supports_unicode?
+            yes ? "\u2713" : "\u2717"
+          else
+            yes ? 'Y' : ' '
+          end
+        return result.green if yes
+        return result.red
+      end
+
+      # Format special values with colors (dim for empty, reverse for others)
+      def special_format(what)
+        result = "<#{what}>"
+        return %w[null empty].any?{ |s| what.include?(s)} ? result.dim : result.reverse_color
+      end
+
+      # Prepare table row for terminal display (word wrap arrays)
+      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)
+        end
+      end
+
+      # Convert Markdown to terminal format (**bold** -> blue, `code` -> bold)
+      # @param match [MatchData, String]
+      def markdown_text(match)
+        if match.is_a?(String)
+          match = Markdown::FORMATS.match(match)
+          Aspera.assert(match)
+        end
+        Aspera.assert_type(match, MatchData)
+        if match[:entity]
+          Aspera.assert_values(match[:entity], %w[bsol])
+          '\\'
+        elsif match[:bold]
+          match[:bold].to_s.blue
+        elsif match[:code]
+          match[:code].to_s.bold
+        else
+          Aspera.error_unexpected_value(match.to_s)
+        end
+      end
+
+      module_function :tick, :special_format, :check_row, :markdown_text
+    end
+
     # Take care of CLI output on terminal
     class Formatter
       # remove a fields from the list
@@ -28,78 +83,30 @@ 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
-        def tick(yes)
-          result =
-            if Environment.terminal_supports_unicode?
-              yes ? "\u2713" : "\u2717"
-            else
-              yes ? 'Y' : ' '
-            end
-          return result.green if yes
-          return result.red
-        end
-
-        # Highlight special values on terminal
-        # empty values are dim
-        # 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
-        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)
-          end
-        end
-
-        # Give Markdown String, or matched data, return formatted string for terminal
-        # used by spec_doc
-        # @param match [MatchData,String]
-        def markdown_text(match)
-          if match.is_a?(String)
-            match = Markdown::FORMATS.match(match)
-            Aspera.assert(match)
-          end
-          Aspera.assert_type(match, MatchData)
-          if match[:entity]
-            Aspera.assert_values(match[:entity], 'bsol')
-            '\\'
-          elsif match[:bold]
-            match[:bold].to_s.blue
-          elsif match[:code]
-            match[:code].to_s.bold
-          else
-            Aspera.error_unexpected_value(match.to_s)
-          end
-        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
             current.each do |key, value|
               case value
               when NilClass
-                current[key] = special_format('null')
+                current[key] = TerminalFormatter.special_format('null')
               when String
-                current[key] = special_format('empty string') if value.empty?
+                current[key] = TerminalFormatter.special_format('empty string') if value.empty?
               when Proc
-                current[key] = special_format('lambda')
+                current[key] = TerminalFormatter.special_format('lambda')
               when Array
                 if value.empty?
-                  current[key] = special_format('empty list')
+                  current[key] = TerminalFormatter.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)
@@ -107,7 +114,7 @@ module Aspera
                 end
               when Hash
                 if value.empty?
-                  current[key] = special_format('empty dict')
+                  current[key] = TerminalFormatter.special_format('empty dict')
                 else
                   hash_to_process.push(value)
                 end
@@ -117,8 +124,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 +165,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 +174,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],
@@ -244,20 +245,21 @@ module Aspera
         !@options[:show_secrets] && !@options[:display].eql?(:data)
       end
 
-      # hides secrets in Hash or Array
+      # Hides secrets in Hash or Array
       def hide_secrets(data)
         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,9 +319,9 @@ 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'))
+              display_message(:data, TerminalFormatter.special_format('empty dict'))
             else
               data = DotContainer.new(data).to_dotted if @options[:flat_hash]
               display_table([data], compute_fields([data], fields), single: true)
@@ -337,7 +339,7 @@ module Aspera
               Log.log.debug('no result expected')
               return
             end
-            display_message(:info, self.class.special_format(data.to_s))
+            display_message(:info, TerminalFormatter.special_format(data.to_s))
             return
           when :status # no table
             # :status displays a simple message
@@ -364,6 +366,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,13 +377,14 @@ 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
           removal = false
           if item[0].eql?(FIELDS_LESS)
             removal = true
-            item = item[1..-1]
+            item = item.delete_prefix(FIELDS_LESS)
           end
           case item
           when SpecialValues::ALL
@@ -398,11 +402,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 +435,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)
+          display_message(:info, TerminalFormatter.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 +465,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 +473,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 +481,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 +504,7 @@ module Aspera
         else
           raise "not expected: #{@options[:format]}"
         end
+        nil
       end
     end
   end

data/lib/aspera/cli/main.rb

@@ -12,6 +12,8 @@ require 'aspera/cli/hints'
 require 'aspera/secret_hider'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/schema/documentation'
+require 'aspera/schema/registry'
 require 'net/ssh/errors'
 require 'openssl'
 
@@ -19,6 +21,8 @@ module Aspera
   module Cli
     # Global objects shared with plugins
     class Context
+      # @type [Array<Symbol>]
+      MEMBERS = %i[options transfer config formatter persistency man_header].freeze
       # @!attribute [rw] options
       #   @return [Manager] the command line options manager
       # @!attribute [rw] transfer
@@ -31,15 +35,17 @@ module Aspera
       #   @return [Object] # whatever the type is
       # @!attribute [rw] man_header
       #   @return [Boolean] whether to display the manual header in plugin help
-      MEMBERS = %i[options transfer config formatter persistency man_header].freeze
       attr_accessor(*MEMBERS)
 
       # Initialize all members to nil, so that they are defined and can be validated later
+      # @return [nil]
       def initialize
         MEMBERS.each{ |i| instance_variable_set(:"@#{i}", nil)}
       end
 
       # Validate that all members are set, raise exception if not
+      # @raise [Aspera::AssertionError] if any member is not set
+      # @return [nil]
       def validate
         MEMBERS.each do |i|
           Aspera.assert(instance_variable_defined?(:"@#{i}"))
@@ -47,10 +53,14 @@ module Aspera
         end
       end
 
+      # Check if the context is in manual-only mode
+      # @return [Boolean] true if in manual-only mode
       def only_manual?
         transfer.eql?(:only_manual)
       end
 
+      # Set the context to manual-only mode
+      # @return [Symbol] :only_manual
       def only_manual!
         @transfer = :only_manual
       end
@@ -69,26 +79,37 @@ module Aspera
       private_constant :COMMAND_CONFIG, :COMMAND_HELP, :SCALAR_TYPES, :USER_INTERFACES
 
       class << self
-        def result_special(how); {type: :special, data: how}; end
+        # Create a special result type (only used internally here)
+        # @param special_sym [Symbol] the special result type
+        # @return [Hash] result hash with type :special
+        def result_special(special_sym); {type: :special, data: special_sym}; end
 
         # Expect some list, but nothing to display
+        # @return [Hash] result hash for empty list
         def result_empty; result_special(:empty); end
 
         # Nothing expected
+        # @return [Hash] result hash for nothing
         def result_nothing; result_special(:nothing); end
 
         # Result is some status, such as "complete", "deleted"...
         # @param status [String] The status
+        # @return [Hash] result hash with type :status
         def result_status(status); return {type: :status, data: status}; end
 
         # Text result coming from command result
+        # @param data [String, Integer, Symbol] the text data to display
+        # @return [Hash] result hash with type :text
         def result_text(data); return {type: :text, data: data}; end
 
+        # Create a success result
+        # @return [Hash] result hash with status 'complete'
         def result_success; return result_status('complete'); end
 
         # Process statuses of finished transfer sessions
-        # @raise exception if there is one error
-        # else returns an empty status
+        # @param statuses [Array] array of transfer session statuses
+        # @raise [Symbol] exception if there is one error
+        # @return [Hash] empty status result if all transfers succeeded
         def result_transfer(statuses)
           worst = TransferAgent.session_status(statuses)
           raise worst unless worst.eql?(:success)
@@ -112,26 +133,33 @@ module Aspera
         end
 
         # Display image for that URL or directly blob
-        #
         # @param url_or_blob [String] URL or blob to display as image
+        # @return [Hash] result hash with type :image
         def result_image(url_or_blob)
           return {type: :image, data: url_or_blob}
         end
 
         # A single object, must be Hash
+        # @param data [Hash] the object data
+        # @param fields [Array<String>, nil] optional list of fields to display
+        # @return [Hash] result hash with type :single_object
         def result_single_object(data, fields: nil)
           return {type: :single_object, data: data, fields: fields}
         end
 
         # An Array of Hash
+        # @param data [Array<Hash>] array of objects
+        # @param fields [Array<String>, nil] optional list of fields to display
+        # @param total [Integer, nil] optional total count
+        # @return [Hash] result hash with type :object_list
         def result_object_list(data, fields: nil, total: nil)
           return {type: :object_list, data: data, fields: fields, total: total}
         end
 
         # A list of values
-        #
         # @param data [Array] The list of values
         # @param name [String] The name of the list (used for display)
+        # @return [Hash] result hash with type :value_list
         def result_value_list(data, name: 'id')
           Aspera.assert_type(data, Array)
           Aspera.assert_type(name, String)
@@ -139,6 +167,8 @@ module Aspera
         end
 
         # Determines type of result based on data
+        # @param data [Object] the data to analyze and format
+        # @return [Hash] result hash with appropriate type based on data
         def result_auto(data)
           case data
           when NilClass
@@ -159,6 +189,8 @@ module Aspera
       end
 
       # Minimum initialization, no exception raised
+      # @param argv [Array<String>] command line arguments
+      # @return [nil]
       def initialize(argv)
         @argv = argv
         Log.dump(:argv, @argv, level: :trace2)
@@ -169,6 +201,8 @@ module Aspera
       end
 
       # This is the main function called by initial script just after constructor
+      # Processes command line arguments, executes commands, and handles exceptions
+      # @return [nil]
       def process_command_line
         # Catch exception information , if any
         exception_info = nil
@@ -239,6 +273,7 @@ module Aspera
         rescue Cli::BadArgument => e;               exception_info = {e: e, t: 'Argument', usage: true}
         rescue Cli::MissingArgument => e;           exception_info = {e: e, t: 'Missing', usage: true}
         rescue Cli::BadIdentifier => e;             exception_info = {e: e, t: 'Identifier'}
+        rescue Cli::SchemaRequest => e;             exception_info = {e: e, t: 'Schema'}
         rescue Cli::Error => e;                     exception_info = {e: e, t: 'Tool', usage: true}
         rescue Transfer::Error => e;                exception_info = {e: e, t: 'Transfer'}
         rescue RestCallError => e;                  exception_info = {e: e, t: 'Rest'}
@@ -251,11 +286,22 @@ module Aspera
         # 1- processing of error condition
         unless exception_info.nil?
           Log.log.warn(exception_info[:e].message) if Log.instance.logger_type.eql?(:syslog) && exception_info[:security]
-          Log.log.error{"#{exception_info[:t]}: #{exception_info[:e].message}"}
+          Log.log.error{"#{exception_info[:t]}: #{exception_info[:e].message}"} unless exception_info[:e].is_a?(Cli::SchemaRequest)
           Log.log.debug{(['Backtrace:'] + exception_info[:e].backtrace).join("\n")} if exception_info[:debug]
           @context.formatter.display_message(:error, 'Use option -h to get help.') if exception_info[:usage]
           # Is that a known error condition with proposal for remediation ?
           Hints.hint_for(exception_info[:e], @context.formatter)
+          # Requested help for a Hash parameter/option ?
+          if exception_info[:e].is_a?(Cli::SchemaRequest)
+            Log.log.info{"#{exception_info[:t]}: #{exception_info[:e].message}"}
+            schema_path = exception_info[:e].path
+            if schema_path.nil?
+              Log.log.warn{'Sorry, no schema provided yet. Please refer to the manual or API.'}
+            else
+              builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(schema_path)).build
+              @context.formatter.display_results(**Main.result_object_list(builder.rows, fields: builder.columns))
+            end
+          end
         end
         # 2- processing of command not processed (due to exception or bad command line)
         if execute_command || @option_show_config
@@ -276,6 +322,10 @@ module Aspera
         return
       end
 
+      # Display usage information and help
+      # @param all [Boolean] if true, show help for all plugins; if false, show only current plugin
+      # @param exit [Boolean] if true, exit the process after displaying help
+      # @return [nil]
       def show_usage(all: true, exit: true)
         # Display main plugin options (+config)
         @context.formatter.display_message(:error, @context.options.parser)
@@ -298,7 +348,10 @@ module Aspera
 
       private
 
+      # Initialize agents and options
       # This can throw exception if there is a problem with the environment, needs to be caught by execute method
+      # @raise [StandardError] if there is a problem with the environment
+      # @return [nil]
       def init_agents_and_options
         @context.man_header = true
         # Create formatter, in case there is an exception, it is used to display.
@@ -328,6 +381,8 @@ module Aspera
         @context.options.parser.banner = app_banner
       end
 
+      # Generate the application banner for help display
+      # @return [String] formatted banner text
       def app_banner
         t = ' ' * 8
         return <<~END_OF_BANNER
@@ -362,7 +417,8 @@ module Aspera
         END_OF_BANNER
       end
 
-      # Define header for manual
+      # Define header for manual and declare all global options
+      # @return [nil]
       def declare_global_options
         Log.log.debug('declare_global_options')
         @context.options.declare(:help, 'Show this message', allowed: Allowed::TYPES_NONE, short: 'h'){@option_help = true}
@@ -397,9 +453,10 @@ module Aspera
         @context.options.parse_options!
       end
 
-      # @return the plugin instance, based on name
+      # Get the plugin instance based on name
       # Also loads the plugin options, and default values from conf file
-      # @param plugin_name_sym : symbol for plugin name
+      # @param plugin_name_sym [Symbol] symbol for plugin name
+      # @return [Plugins::Base] the plugin instance
       def get_plugin_instance_with_options(plugin_name_sym)
         Log.log.debug{"get_plugin_instance_with_options(#{plugin_name_sym})"}
         # Load default params only if no param already loaded before plugin instantiation
@@ -408,6 +465,8 @@ module Aspera
         return command_plugin
       end
 
+      # Generate bash completion suggestions
+      # @return [nil]
       def generate_bash_completion
         if @context.options.get_next_argument('', multiple: true, mandatory: false).nil?
           Plugins::Factory.instance.plugin_list.each{ |p| puts p}