aspera-cli 4.25.6 → 4.26.1

data/lib/aspera/preview/options.rb

@@ -10,6 +10,8 @@ module Aspera
       # types of generation for video files
       VIDEO_CONVERSION_METHODS = %i[reencode blend clips].freeze
       VIDEO_THUMBNAIL_METHODS = %i[fixed animated].freeze
+      # methods for office document conversion
+      OFFICE_CONVERSION_METHODS = %i[soffice unoconv].freeze
       # options used in generator
       # for scaling see: https://trac.ffmpeg.org/wiki/Scaling
       # iw/ih : input width or height
@@ -20,11 +22,12 @@ module Aspera
         {name: :thumb_vid_fraction,   default: 0.1,                description: 'png: video: time percent position of snapshot'},
         {name: :thumb_img_size,       default: 800,                description: 'png: non-video: height (and width)'},
         {name: :thumb_text_font,      default: 'Courier',          description: 'png: plaintext: font for text rendering: `magick identify -list font`'},
+        {name: :office_conversion,    default: :soffice,           description: 'office: method for office document conversion', values: OFFICE_CONVERSION_METHODS},
         {name: :video_conversion,     default: :reencode,          description: 'mp4: method for preview generation', values: VIDEO_CONVERSION_METHODS},
         {name: :video_png_conv,       default: :fixed,             description: 'mp4: method for thumbnail generation', values: VIDEO_THUMBNAIL_METHODS},
         {name: :video_scale,          default: "'min(iw,360)':-2", description: 'mp4: all: video scale (ffmpeg scale argument)'},
         {name: :video_start_sec,      default: 10,                 description: 'mp4: all: start offset (seconds) of video preview'},
-        {name: :reencode_ffmpeg,      default: {},                 description: 'mp4: reencode: options to ffmpeg'},
+        {name: :reencode_ffmpeg,      default: {},                 description: 'mp4: reencode: options to ffmpeg, keys: `in`, `out`'},
         {name: :blend_keyframes,      default: 30,                 description: 'mp4: blend: # key frames'},
         {name: :blend_pauseframes,    default: 3,                  description: 'mp4: blend: # pause frames'},
         {name: :blend_transframes,    default: 5,                  description: 'mp4: blend: # transition blend frames'},

data/lib/aspera/preview/terminal.rb

@@ -11,15 +11,22 @@ require 'aspera/environment'
 module Aspera
   module Preview
     module Backend
-      # provides image pixels scaled to terminal
+      # Base decoder that rescales image data to the current terminal geometry.
       class Base
+        # @param reserve [Integer] number of terminal rows reserved for non-image output
+        # @param double [Boolean] when `true`, render two image rows in one terminal row
+        # @param font_ratio [Float] terminal font aspect ratio: height divided by width
         def initialize(reserve:, double:, font_ratio:)
           @reserve = reserve
           @height_ratio = double ? 2.0 : 1.0
           @font_ratio = font_ratio
         end
         Aspera.require_method!(:terminal_pixels)
-        # compute scaling to fit terminal
+        # Compute output dimensions that fit inside the terminal while preserving aspect ratio.
+        #
+        # @param rows [Integer] source image height in pixels
+        # @param columns [Integer] source image width in pixels
+        # @return [Array<Integer>] scaled width and height for terminal rendering
         def terminal_scaling(rows, columns)
           (term_rows, term_columns) = IO.console.winsize || [24, 80]
           term_rows = [term_rows - @reserve, 2].max
@@ -29,22 +36,30 @@ module Aspera
       end
 
       class RMagick < Base
+        # Initialize the RMagick-backed decoder for a binary image payload.
+        #
+        # @param blob [String] encoded image binary content
+        # @param kwargs [Hash] forwarding options accepted by [`initialize`](lib/aspera/preview/terminal.rb:16)
         def initialize(blob, **kwargs)
           super(**kwargs)
-          # do not require statically, as the package is optional
+          # Load lazily because this dependency is optional.
           require 'rmagick' # https://rmagick.github.io/index.html
           @image = Magick::ImageList.new.from_blob(blob)
         end
 
+        # Decode the image and return RGB pixels scaled for terminal rendering.
+        #
+        # @return [Array<Array<Array<Integer>>>] rows of `[red, green, blue]` pixel triplets
         def terminal_pixels
-          # quantum depth is 8 or 16, see: `magick xc: -format "%q" info:`
+          # ImageMagick channel depth is typically 8 or 16 bits.
+          # See: `magick xc: -format "%q" info:`
           shift_for_8_bit = Magick::MAGICKCORE_QUANTUM_DEPTH - 8
-          # get all pixel colors, adjusted for Rainbow
+          # Extract RGB values and normalize them to 8-bit channels for Rainbow.
           pixel_colors = []
           @image.scale(*terminal_scaling(@image.rows, @image.columns)).each_pixel do |pixel, col, row|
             pixel_rgb = [pixel.red, pixel.green, pixel.blue]
             pixel_rgb = pixel_rgb.map{ |color| color >> shift_for_8_bit} unless shift_for_8_bit.eql?(0)
-            # init 2-dim array
+            # Initialize the destination 2D pixel matrix row by row.
             pixel_colors[row] ||= []
             pixel_colors[row][col] = pixel_rgb
           end
@@ -53,12 +68,19 @@ module Aspera
       end
 
       class ChunkyPNG < Base
+        # Initialize the ChunkyPNG-backed decoder for a PNG payload.
+        #
+        # @param blob [String] PNG binary content
+        # @param kwargs [Hash] forwarding options accepted by [`initialize`](lib/aspera/preview/terminal.rb:16)
         def initialize(blob, **kwargs)
           super(**kwargs)
           require 'chunky_png'
           @png = ::ChunkyPNG::Image.from_blob(blob)
         end
 
+        # Resize the PNG using nearest-neighbor sampling and return RGB pixel rows.
+        #
+        # @return [Array<Array<Array<Integer>>>] rows of `[red, green, blue]` pixel triplets
         def terminal_pixels
           src_w = @png.width
           src_h = @png.height
@@ -75,7 +97,7 @@ module Aspera
               sx = (dx * x_ratio).floor
               sx = src_w - 1 if sx >= src_w
               rgba = @png.get_pixel(sx, sy)
-              # ChunkyPNG stores as 0xRRGGBBAA; extract 8-bit channels
+              # ChunkyPNG stores pixels as 0xRRGGBBAA; extract 8-bit RGB channels.
               pixel_colors[dy][dx] = %i[r g b].map{ |i| ::ChunkyPNG::Color.send(i, rgba)}
             end
           end
@@ -84,19 +106,21 @@ module Aspera
       end
     end
 
-    # Display a picture in the terminal.
-    # Either use coloured characters or iTerm2 protocol.
+    # Render an image for terminal output.
+    # Uses either colored text blocks or the iTerm2 inline-image protocol when available.
     class Terminal
-      # Rainbow only supports 8-bit colors
-      # env vars to detect terminal type
+      # Rainbow only supports 8-bit color values.
+      # Environment variables inspected to detect compatible terminal implementations.
       TERM_ENV_VARS = %w[TERM_PROGRAM LC_TERMINAL].freeze
-      # terminal names that support iTerm2 image display
+      # Terminal identifiers known to support the iTerm2 inline-image protocol.
       ITERM_NAMES = %w[iTerm WezTerm mintty].freeze
-      # TODO: retrieve terminal font ratio using some termcap ?
-      # ratio = font height / font width
+      # Fallback font aspect ratio used to estimate how many image pixels fit in a character cell.
+      # Ratio = font height / font width.
       DEFAULT_FONT_RATIO = 32.0 / 14.0
       private_constant :TERM_ENV_VARS, :ITERM_NAMES, :DEFAULT_FONT_RATIO
       class << self
+        # Render an image blob for display in the current terminal.
+        #
         # @param blob       [String]  The image as a binary string
         # @param text       [Boolean] `true` to display the image as text, `false` to use iTerm2 if supported
         # @param reserve    [Integer] Number of lines to reserve for other text than the image
@@ -124,7 +148,7 @@ module Aspera
             return iterm_display_image(blob) if iterm_supported?
             raise 'Cannot decode picture.'
           end
-          # now generate text
+          # Convert decoded pixels into terminal glyphs.
           text_pixels = []
           pixel_colors.each_with_index do |row_data, row|
             next if double && (row.odd? || row.eql?(pixel_colors.length - 1))
@@ -140,11 +164,14 @@ module Aspera
           return text_pixels.join
         end
 
-        # display image in iTerm2
+        # Build the iTerm2 inline-image escape sequence.
         # https://iterm2.com/documentation-images.html
+        #
+        # @param blob [String] image binary content
+        # @return [String] escape sequence that displays the image inline
         def iterm_display_image(blob)
           # image = Magick::ImageList.new.from_blob(blob)
-          # parameters for iTerm2 image display
+          # Parameters accepted by the iTerm2 inline-image protocol.
           arguments = {
             inline:              1,
             preserveAspectRatio: 1,
@@ -152,12 +179,15 @@ module Aspera
             # width:               image.columns,
             # height:              image.rows
           }.map{ |k, v| "#{k}=#{v}"}.join(';')
-          # \a is BEL, \e is ESC : https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
-          # escape sequence for iTerm2 image display
+          # `\a` is BEL and `\e` is ESC.
+          # See: https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
+          # Return the full escape sequence expected by iTerm2-compatible terminals.
           return "\e]1337;File=#{arguments}:#{Base64.strict_encode64(blob)}\a"
         end
 
-        # @return [Boolean] true if the terminal supports iTerm2 image display
+        # Detect whether the current terminal supports iTerm2 inline images.
+        #
+        # @return [Boolean] `true` when the current terminal advertises iTerm2 image support
         def iterm_supported?
           TERM_ENV_VARS.each do |env_var|
             return true if ITERM_NAMES.any?{ |term| ENV[env_var]&.include?(term)}

data/lib/aspera/preview/utils.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# cspell:ignore ffprobe optipng unoconv
+# cspell:ignore ffprobe optipng unoconv soffice
 require 'aspera/log'
 require 'aspera/assert'
 require 'English'
@@ -11,32 +11,30 @@ require 'open3'
 module Aspera
   module Preview
     class Utils
-      # from bash manual: meta-character need to be escaped
-      BASH_SPECIAL_CHARACTERS = "|&;()<> \t#\n"
-      # external binaries used
-      EXTERNAL_TOOLS = %i[ffmpeg ffprobe magick optipng unoconv].freeze
+      # External binaries used
+      EXTERNAL_TOOLS = %i[ffmpeg ffprobe magick optipng unoconv soffice].freeze
+      # File name format for temporary files, used by both ffmpeg and ruby(Kernel.format)
       TEMP_FORMAT = 'img%04d.jpg'
+      # default parameters for ffmpeg
       FFMPEG_DEFAULT_PARAMS = [
         '-y', # overwrite output without asking
         '-loglevel', 'error' # show only errors and up
       ].freeze
-      private_constant :BASH_SPECIAL_CHARACTERS, :EXTERNAL_TOOLS, :TEMP_FORMAT
+      private_constant :EXTERNAL_TOOLS, :TEMP_FORMAT, :FFMPEG_DEFAULT_PARAMS
 
       class << self
-        # returns string with single quotes suitable for bash if there is any bash meta-character
-        def shell_quote(argument)
-          return argument unless argument.chars.any?{ |c| BASH_SPECIAL_CHARACTERS.include?(c)}
-          # surround with single quotes, and escape single quotes
-          return %Q{'#{argument.gsub("'"){ |_s| %q{'"'"'}}}'}
-        end
-
-        # check that external tools can be executed
+        # Check that external tools can be executed
+        # @param skip_types [Array<Symbol>] list of tools to skip
+        # @return [nil]
         def check_tools(skip_types = [])
           tools_to_check = EXTERNAL_TOOLS.dup
-          tools_to_check.delete(:unoconv) if skip_types.include?(:office)
+          if skip_types.include?(:office)
+            tools_to_check.delete(:unoconv)
+            tools_to_check.delete(:soffice)
+          end
           # Check for binaries
           tools_to_check.each do |command_sym|
-            external_command(command_sym, ['-h'], out: File::NULL)
+            silent_execute(command_sym, '-h')
           rescue Errno::ENOENT => e
             raise "missing #{command_sym} binary: #{e}"
           rescue
@@ -44,42 +42,47 @@ module Aspera
           end
         end
 
-        # Execute external command
-        # @return [nil]
-        def external_command(command_sym, command_args)
-          Aspera.assert_values(command_sym, EXTERNAL_TOOLS){'command'}
-          Environment.secure_execute(command_sym.to_s, *command_args.map(&:to_s), out: File::NULL, err: File::NULL)
+        # Execute external command, verify it is in the supported list
+        def execute(*args, **kwargs)
+          Aspera.assert_values(args.first, EXTERNAL_TOOLS){'command'}
+          Environment.secure_execute(*args, **kwargs)
         end
 
-        # Execute external command and get stdout
-        # @return [String]
-        def external_capture(command_sym, command_args)
-          Aspera.assert_values(command_sym, EXTERNAL_TOOLS){'command'}
-          Environment.secure_execute(command_sym.to_s, *command_args.map(&:to_s), mode: :capture).first
+        # Execute external command silently
+        # @return [nil]
+        def silent_execute(*args)
+          execute(*args, out: File::NULL, err: File::NULL)
+          nil
         end
 
+        # Execute `ffmpeg`
+        # @return [nil]
         def ffmpeg(gl_p: FFMPEG_DEFAULT_PARAMS, in_p: [], in_f:, out_p: [], out_f:)
           Aspera.assert_type(gl_p, Array)
           Aspera.assert_type(in_p, Array)
           Aspera.assert_type(out_p, Array)
-          external_command(:ffmpeg, gl_p +  in_p + ['-i', in_f] + out_p + [out_f])
+          silent_execute(:ffmpeg, *gl_p, *in_p, '-i', in_f, *out_p, out_f)
         end
 
         # @return Float in seconds
         def video_get_duration(input_file)
-          return external_capture(:ffprobe, [
+          return execute(
+            :ffprobe,
             '-loglevel', 'error',
             '-show_entries', 'format=duration',
             '-print_format', 'default=noprint_wrappers=1:nokey=1', # cspell:disable-line
-            input_file
-          ]).to_f
+            input_file,
+            mode: :capture
+          ).first.to_f
         end
 
+        # File output format, including temp folder
         def ffmpeg_fmt(temp_folder)
           return File.join(temp_folder, TEMP_FORMAT)
         end
 
         def get_tmp_num_filepath(temp_folder, file_number)
+          # Format using {Kernel.format}
           return File.join(temp_folder, format(TEMP_FORMAT, file_number))
         end
 
@@ -97,19 +100,58 @@ module Aspera
           1.upto(count) do |i|
             percent = i * 100 / (count + 1)
             filename = get_tmp_num_filepath(temp_folder, index_begin + i)
-            external_command(:magick, ['composite', '-blend', percent, img2, img1, filename])
+            silent_execute(:magick, 'composite', '-blend', percent, img2, img1, filename)
           end
         end
 
-        def video_dump_frame(input_file, offset_seconds, scale, output_file, index = nil)
-          output_file = get_tmp_num_filepath(output_file, index) unless index.nil?
+        # Dump a frame from a video file
+        # @param input_file [String] the input file path
+        # @param offset_seconds [Integer] the offset in seconds
+        # @param scale [String] the scale of the output frame
+        # @param output_file [String] the output file path
+        # @return [nil]
+        def video_dump_frame(input_file, offset_seconds, scale, output_file)
           ffmpeg(
             in_f: input_file,
             in_p: ['-ss', offset_seconds],
             out_f: output_file,
             out_p: ['-frames:v', 1, '-filter:v', "scale=#{scale}"]
           )
-          return output_file
+        end
+
+        # Parse the output of `magick identify -list font` command
+        # @param output [String] the output from `magick -list font`
+        # @return [Hash] with keys :path and :fonts
+        #   :path [String] the path to the type.xml file
+        #   :fonts [Array<Hash>] array of font hashes with keys:
+        #     :name, :family, :style, :stretch, :weight, :metrics, :glyphs, :index
+        def parse_magick_fonts(output)
+          result = {path: nil, fonts: []}
+          current_font = nil
+          output.each_line do |line|
+            line = line.strip
+            # Parse the Path line
+            if line.start_with?('Path:')
+              result[:path] = line.sub(/^Path:\s*/, '')
+            # Parse Font name
+            elsif line.start_with?('Font:')
+              # Save previous font if exists
+              result[:fonts] << current_font if current_font
+              # Start new font
+              current_font = {name: line.sub(/^Font:\s*/, '')}
+            # Parse font properties
+            elsif current_font && line.include?(':')
+              key, value = line.split(':', 2)
+              key = key.strip.gsub(/\s+/, '_').to_sym
+              value = value.strip
+              # Convert numeric values
+              value = value.to_i if key == :weight || key == :index
+              current_font[key] = value
+            end
+          end
+          # Don't forget the last font
+          result[:fonts] << current_font if current_font
+          result
         end
       end
     end

data/lib/aspera/products/transferd.rb

@@ -27,7 +27,7 @@ module Aspera
           sdk_directory
         end
 
-        # @return the path to folder where SDK is installed
+        # @return the path to folder where SDK is or should be installed
         def sdk_directory
           Aspera.assert(!@sdk_dir.nil?){'SDK path was not initialized'}
           @sdk_dir

data/lib/aspera/proxy_auto_config.rb

@@ -10,6 +10,9 @@ module URI
     # save original method that finds proxy in URI::Generic, it uses env var http_proxy
     alias_method :find_proxy_orig, :find_proxy
     class << self
+      # Register a custom proxy finder block
+      # @yieldparam url [String] The URL to find proxy for
+      # @yieldreturn [String, nil] Proxy URL or nil to fallback to original method
       def register_proxy_finder
         Aspera.assert(block_given?)
         # overload the method in URI : call user's provided block and fallback to original method

data/lib/aspera/rest.rb

@@ -78,6 +78,7 @@ module Aspera
 
       # Indicate that the given Hash query uses php style for array parameters
       # @param query [Hash] A key can have Array value and result will use PHP format: a[]=1&a[]=2
+      # @return [Hash] The query parameters.
       def php_style(query)
         Aspera.assert_type(query, Hash){'query'}
         query[:x_array_php_style] = true
@@ -165,7 +166,7 @@ module Aspera
           next unless url_match
           url = url_match[1]
           # Extract parameters after the URL
-          params_str = link_part[url_match.end(0)..-1]
+          params_str = link_part[url_match.end(0)..]
           # Check if this link has the specified rel (with or without quotes, case insensitive)
           next unless /;\s*rel\s*=\s*"?#{Regexp.escape(rel)}"?/i.match?(params_str)
           return url

data/lib/aspera/rest_list.rb

@@ -11,33 +11,39 @@ module Aspera
 
     # Query entity by general search (read with parameter `q`)
     #
-    # @param subpath     [String] Path of entity in API
-    # @param search_name [String] Name of searched entity
-    # @param query       [Hash]   Optional additional search query parameters
+    # @param entity [String] Path of entity in API
+    # @param value [String] Value of field of searched entity
+    # @param field [String] Field of searched entity
+    # @param query [Hash] Optional additional search query parameters
     # @returns [Hash] A single entity matching the search, or an exception if not found or multiple found
-    def lookup_by_name(subpath, search_name, query: nil)
-      query = {} if query.nil?
+    def lookup_with_q(entity, value:, field: 'name', query: {})
+      Aspera.assert_type(query, Hash){'query'}
+      Aspera.assert_type(field, String){'field'}
       # returns entities matching the query (it matches against several fields in case insensitive way)
-      matching_items = read(subpath, query.merge({'q' => search_name}))
-      # API style: {totalcount:, ...} cspell: disable-line
-      matching_items = matching_items[subpath] if matching_items.is_a?(Hash)
+      # We don't do paging, as anyway, we look for only one match
+      matching_items = read(entity, query.merge({'q' => value}))
+      # API style: {totalcount:, ...} cspell: disable-line: TODO: is that total_count ?
+      # @type [Array<Hash{String => String}>]
+      matching_items = matching_items[entity] if matching_items.is_a?(Hash)
       Aspera.assert_type(matching_items, Array)
       case matching_items.length
       when 1 then return matching_items.first
-      when 0 then raise EntityNotFound, %Q{No such #{subpath}: "#{search_name}"}
+      when 0 then raise EntityNotFound, %Q{No such #{entity}: "#{value}"}
       else
         # multiple case insensitive partial matches, try case insensitive full match
-        # (anyway AoC does not allow creation of 2 entities with same case insensitive name)
-        name_matches = matching_items.select{ |i| i['name'].casecmp?(search_name)}
-        case name_matches.length
-        when 1 then return name_matches.first
-        when 0 then raise %Q(#{subpath}: Multiple case insensitive partial match for: "#{search_name}": #{matching_items.map{ |i| i['name']}} but no case insensitive full match. Please be more specific or give exact name.)
-        else raise "Two entities cannot have the same case insensitive name: #{name_matches.map{ |i| i['name']}}"
+        # (anyway AoC does not allow creation of 2 entities with same case insensitive field value)
+        value_matches = matching_items.select{ |i| i[field].casecmp?(value)}
+        case value_matches.length
+        when 1 then return value_matches.first
+        when 0 then raise %Q(#{entity}: Multiple case insensitive partial match for: "#{value}" in #{matching_items.map{ |i| i[field]}.join(', ')} but no case insensitive full match. Please be more specific or give exact #{field}.)
+        else raise "Two entities cannot have the same case insensitive #{field}: #{value_matches.map{ |i| i[field]}}"
         end
       end
     end
 
-    # Get a (full or partial) list of all entities of a given type with query: offset/limit
+    # Get a (full or partial) list of all entities of a given type.
+    # Using query: `offset` + `limit`
+    # And response `total_count`
     # @param entity    [String,Symbol] API endpoint of entity to list
     # @param items_key [String]        Key in the result to get the list of items (Default: same as `entity`)
     # @param query     [Hash,nil]      Additional query parameters
@@ -114,6 +120,7 @@ module Aspera
       return found.first if found.length.eql?(1)
       raise Cli::BadIdentifier.new(entity, value, field: field, count: found.length)
     end
+
     PER_PAGE_DEFAULT = 1000
     private_constant :PER_PAGE_DEFAULT
     module_function :lookup_entity_generic