ruby_jard 0.1.0 → 0.3.0

data/lib/ruby_jard/control_flow.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyJard
+  ##
+  # A helper to standardize control instruction passed around via
+  # throw and catch mechanism.
+  class ControlFlow
+    THROW_KEYWORD = :jard_control_flow
+    ALLOW_LIST = {
+      continue: [],                 # lib/ruby_jard/commands/continue_command.rb
+      exit: [],                     # lib/ruby_jard/commands/exit_command.rb
+      frame: [:frame],              # lib/ruby_jard/commands/frame_command.rb
+      up: [:times],                 # lib/ruby_jard/commands/up_command.rb
+      down: [:times],               # lib/ruby_jard/commands/down_command.rb
+      next: [:times],               # lib/ruby_jard/commands/next_command.rb
+      step: [:times],               # lib/ruby_jard/commands/step_command.rb
+      step_out: [:times],           # lib/ruby_jard/commands/step_out_command.rb
+      key_binding: [:action],       # lib/ruby_jard/commands/step_command.rb
+      list: []                      # lib/ruby_jard/commands/list_command.rb
+    }.freeze
+
+    attr_reader :command, :arguments
+
+    def initialize(command, arguments)
+      @command = command
+      @arguments = arguments
+
+      validate!
+    end
+
+    def validate!
+      if command.to_s.empty?
+        raise RubyJard::Error, 'Control command is empty'
+      end
+
+      unless ALLOW_LIST.key?(command)
+        raise RubyJard::Error,
+              "Control command `#{command}` is not registered in the allow list."
+      end
+
+      invalid_keys = arguments.keys - ALLOW_LIST[command]
+      unless invalid_keys.empty?
+        raise RubyJard::Error,
+              "Control command `#{command}` is attached with unregister arguments: #{invalid_keys}"
+      end
+    end
+
+    class << self
+      def dispatch(command, arguments = {})
+        if command.is_a?(RubyJard::ControlFlow)
+          throw THROW_KEYWORD, command
+        else
+          throw THROW_KEYWORD, new(command, arguments)
+        end
+      end
+
+      def listen
+        raise RubyJard::Error, 'This method requires a block' unless block_given?
+
+        flow = catch(THROW_KEYWORD) do
+          yield
+          nil
+        end
+
+        if flow.nil? || flow.is_a?(RubyJard::ControlFlow)
+          flow
+        else
+          raise RubyJard::Error, 'Control flow misused!'
+        end
+      end
+    end
+  end
+end

data/lib/ruby_jard/decorators/array_decorator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RubyJard
+  module Decorators
+    ##
+    # Decorate Array data structure, supports singleline and multiline form.
+    class ArrayDecorator
+      def initialize(generic_decorator)
+        @generic_decorator = generic_decorator
+        @attributes_decorator = RubyJard::Decorators::AttributesDecorator.new(generic_decorator)
+      end
+
+      def match?(variable)
+        RubyJard::Reflection.call_is_a?(variable, Array)
+      end
+
+      def decorate_singleline(variable, line_limit:, depth: 0)
+        spans = []
+        spans << RubyJard::Span.new(content: '[', styles: :text_primary)
+        spans += @attributes_decorator.inline_values(
+          variable.each_with_index, total: variable.length, line_limit: line_limit - 2, depth: depth + 1
+        )
+        spans << RubyJard::Span.new(content: ']', styles: :text_primary)
+
+        spans
+      end
+
+      def decorate_multiline(variable, first_line_limit:, lines:, line_limit:, depth: 0)
+        if variable.length > lines * 2
+          return do_decorate_multiline(variable, lines: lines, line_limit: line_limit, depth: depth)
+        end
+
+        singleline = decorate_singleline(variable, line_limit: first_line_limit, depth: depth)
+        if (singleline.map(&:content_length).sum < line_limit && same_type?(variable, lines)) || variable.length <= 1
+          [singleline]
+        else
+          do_decorate_multiline(variable, lines: lines, line_limit: line_limit, depth: depth)
+        end
+      end
+
+      private
+
+      def same_type?(variable, sample)
+        variable.first(sample).map { |item| RubyJard::Reflection.call_class(item) }.uniq.length <= 1
+      end
+
+      def do_decorate_multiline(variable, lines:, line_limit:, depth: 0)
+        spans = [[RubyJard::Span.new(content: '[', styles: :text_primary)]]
+
+        item_count = 0
+        variable.each_with_index do |value, index|
+          spans << @attributes_decorator.value(value, line_limit: line_limit, depth: depth + 1)
+
+          item_count += 1
+          break if index >= lines - 2
+        end
+
+        spans << last_line(variable.length, item_count)
+      end
+
+      def last_line(total, item_count)
+        if total > item_count
+          [
+            RubyJard::Span.new(
+              content: "▸ #{total - item_count} more...",
+              margin_left: 2, styles: :text_dim
+            ),
+            RubyJard::Span.new(
+              content: ']',
+              styles: :text_primary
+            )
+          ]
+        else
+          [RubyJard::Span.new(content: ']', styles: :text_primary)]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_jard/decorators/attributes_decorator.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module RubyJard
+  module Decorators
+    TYPICAL_DEPTH = 3
+    MAX_DEPTH = 5
+    DO_NOT_WASTE_LENGTH = 40
+    ##
+    # Decorate collection data structure. Support:
+    # - Collection of values
+    # - Collection of key-value pairs
+    # - Individual value
+    # - Individual pair
+    # This decorator should not be used directly.
+    class AttributesDecorator
+      def initialize(generic_decorator)
+        @generic_decorator = generic_decorator
+      end
+
+      def inline_pairs(enum, total:, line_limit:, process_key:, value_proc: nil, depth: 0)
+        return [ellipsis_span] if too_deep?(depth, line_limit)
+
+        spans = []
+        width = 1
+        item_limit = total == 0 ? 0 : [line_limit / total, pair_limit(depth)].max
+
+        enum.each do |(key, value), index|
+          key_inspection = inspect_key(key, item_limit, process_key: process_key, depth: depth)
+          key_inspection_length = key_inspection.map(&:content_length).sum
+
+          value_inspection = @generic_decorator.decorate_singleline(
+            value_proc.nil? ? value : value_proc.call(key),
+            line_limit: [item_limit - key_inspection_length, pair_limit(depth)].max, depth: depth
+          )
+          value_inspection_length = value_inspection.map(&:content_length).sum
+
+          if index > 0
+            spans << separator_span
+            width += 2
+          end
+
+          if width + key_inspection_length + value_inspection_length + 5 > line_limit
+            spans << ellipsis_span
+            break
+          end
+
+          spans += key_inspection
+          width += key_inspection_length
+
+          spans << arrow_span
+          width += 3
+
+          spans += value_inspection
+          width += value_inspection_length
+        end
+
+        spans
+      end
+
+      def pair(key, value, line_limit:, process_key:, depth: 0)
+        return [ellipsis_span] if too_deep?(depth, line_limit)
+
+        spans = []
+        spans << indent_span
+        width = indent_span.content_length
+
+        key_inspection = inspect_key(key, line_limit - width, process_key: process_key, depth: depth)
+        key_inspection_length = key_inspection.map(&:content_length).sum
+
+        spans += key_inspection
+        width += key_inspection_length
+
+        spans << arrow_span
+        width += 3
+
+        value_inspection = @generic_decorator.decorate_singleline(
+          value, line_limit: [line_limit - width, pair_limit(depth)].max, depth: depth
+        )
+
+        spans + value_inspection
+      end
+
+      def inline_values(enum, total:, line_limit:, depth: 0)
+        return [ellipsis_span] if too_deep?(depth, line_limit)
+
+        spans = []
+        width = 1
+        item_limit = total == 0 ? 0 : [line_limit / total, value_limit(depth)].max
+
+        enum.each do |value, index|
+          value_inspection = @generic_decorator.decorate_singleline(
+            value, line_limit: [item_limit, value_limit(depth)].max, depth: depth
+          )
+          value_inspection_length = value_inspection.map(&:content_length).sum
+
+          if index > 0
+            spans << separator_span
+            width += 2
+          end
+
+          if width + value_inspection_length + 2 > line_limit
+            spans << ellipsis_span
+            break
+          end
+
+          spans += value_inspection
+          width += value_inspection_length
+        end
+
+        spans
+      end
+
+      def value(value, line_limit:, depth: 0)
+        return [ellipsis_span] if too_deep?(depth, line_limit)
+
+        spans = []
+        spans << indent_span
+        width = indent_span.content_length
+
+        value_inspection = @generic_decorator.decorate_singleline(
+          value, line_limit: [line_limit - width, value_limit(depth)].max, depth: depth
+        )
+
+        spans + value_inspection
+      end
+
+      private
+
+      def inspect_key(key, item_limit, process_key:, depth: 0)
+        if process_key
+          @generic_decorator.decorate_singleline(
+            key, line_limit: item_limit, depth: depth
+          )
+        else
+          [RubyJard::Span.new(content: key.to_s, styles: :text_primary)]
+        end
+      end
+
+      def arrow_span
+        RubyJard::Span.new(content: '→', margin_left: 1, margin_right: 1, styles: :text_highlighted)
+      end
+
+      def separator_span
+        RubyJard::Span.new(content: ',', margin_right: 1, styles: :text_primary)
+      end
+
+      def ellipsis_span
+        RubyJard::Span.new(content: '…', styles: :text_dim)
+      end
+
+      def indent_span
+        RubyJard::Span.new(content: '▸', margin_right: 1, margin_left: 2, styles: :text_dim)
+      end
+
+      def too_deep?(depth, line_limit)
+        return true if depth > MAX_DEPTH
+        return false if line_limit > DO_NOT_WASTE_LENGTH
+
+        depth > TYPICAL_DEPTH
+      end
+
+      def pair_limit(depth)
+        # The deeper structure, the less meaningful the actual data is
+        30 - depth * 5
+      end
+
+      def value_limit(_depth)
+        30
+      end
+    end
+  end
+end

data/lib/ruby_jard/decorators/color_decorator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyJard
+  module Decorators
+    ##
+    # Manipulate and decorate color for texts.
+    # This class translate colors to corresponding escape sequences.
+    # Support 24-bit color (#51617d format) or 256 colors (https://jonasjacek.github.io/colors/)
+    # Example:
+    # - #fafafa => \e[38;2;250;250;250m
+    # - #aaa => \e[38;2;170;170;170m
+    # - 77 => \e[38;2;170;170;170m
+    class ColorDecorator
+      HEX_PATTERN_6 = /^#([A-Fa-f0-9]{2})([A-Fa-f0-9]{2})([A-Fa-f0-9]{2})$/i.freeze
+      HEX_PATTERN_3 = /^#([A-Fa-f0-9]{1})([A-Fa-f0-9]{1})([A-Fa-f0-9]{1})$/i.freeze
+      XTERM_NUMBER_PATTERN = /^([01]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])$/i.freeze
+
+      CSI_RESET = "\e[0m"
+      CSI_FOREGROUND_24BIT = "\e[38;2;%d;%d;%dm"
+      CSI_BACKGROUND_24BIT = "\e[48;2;%d;%d;%dm"
+      CSI_FOREGROUND_256 = "\e[38;5;%dm"
+      CSI_BACKGROUND_256 = "\e[48;5;%dm"
+
+      CSI_ITALIC = "\e[3m"
+      CSI_UNDERLINE = "\e[4m"
+      CSI_BOLD = "\e[1m"
+
+      STYLES_CSI_MAP = {
+        underline: CSI_UNDERLINE,
+        italic: CSI_ITALIC,
+        bold: CSI_BOLD
+      }.freeze
+
+      def initialize(color_scheme)
+        @color_scheme = color_scheme
+      end
+
+      def decorate(style_names, content)
+        attributes = nil
+        if style_names.is_a?(Symbol)
+          styles = @color_scheme.styles_for(style_names)
+        else
+          attributes = translate_styles(style_names)
+          styles = @color_scheme.styles_for(style_names.shift)
+        end
+        foreground = translate_color(styles.shift, true)
+        background = translate_color(styles.shift, false)
+        "#{foreground}#{background}#{attributes}#{content}#{CSI_RESET}"
+      end
+
+      def translate_color(color, foreground)
+        if (matches = HEX_PATTERN_6.match(color.to_s))
+          red = matches[1].to_i(16)
+          green = matches[2].to_i(16)
+          blue = matches[3].to_i(16)
+          sequence = foreground ? CSI_FOREGROUND_24BIT : CSI_BACKGROUND_24BIT
+          format sequence, red, green, blue
+        elsif (matches = HEX_PATTERN_3.match(color.to_s))
+          red = (matches[1] * 2).to_i(16)
+          green = (matches[2] * 2).to_i(16)
+          blue = (matches[3] * 2).to_i(16)
+          sequence = foreground ? CSI_FOREGROUND_24BIT : CSI_BACKGROUND_24BIT
+          format sequence, red, green, blue
+        elsif (matches = XTERM_NUMBER_PATTERN.match(color.to_s))
+          color = matches[1]
+          sequence = foreground ? CSI_FOREGROUND_256 : CSI_BACKGROUND_256
+          format sequence, color
+        else
+          ''
+        end
+      end
+
+      private
+
+      def translate_styles(styles = [])
+        styles.map { |key| STYLES_CSI_MAP[key] }.compact.join
+      end
+    end
+  end
+end

data/lib/ruby_jard/decorators/hash_decorator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RubyJard
+  module Decorators
+    ##
+    # Decorate Hash data structure, supports singleline and multiline form.
+    class HashDecorator
+      def initialize(generic_decorator)
+        @generic_decorator = generic_decorator
+        @attributes_decorator = RubyJard::Decorators::AttributesDecorator.new(generic_decorator)
+      end
+
+      def decorate_singleline(variable, line_limit:, depth: 0)
+        spans = []
+        spans << RubyJard::Span.new(content: '{', styles: :text_primary)
+        spans += @attributes_decorator.inline_pairs(
+          variable.each_with_index,
+          total: variable.length, line_limit: line_limit - 2, process_key: true, depth: depth + 1
+        )
+        spans << RubyJard::Span.new(content: '}', styles: :text_primary)
+      end
+
+      def decorate_multiline(variable, first_line_limit:, lines:, line_limit:, depth: 0)
+        if variable.size > lines * 1.5
+          return do_decorate_multiline(variable, lines: lines, line_limit: line_limit, depth: depth)
+        end
+
+        singleline = decorate_singleline(variable, line_limit: first_line_limit)
+        if singleline.map(&:content_length).sum < line_limit || variable.length <= 1
+          [singleline]
+        else
+          do_decorate_multiline(variable, lines: lines, line_limit: line_limit, depth: depth)
+        end
+      end
+
+      def match?(variable)
+        RubyJard::Reflection.call_is_a?(variable, Hash)
+      end
+
+      private
+
+      def do_decorate_multiline(variable, lines:, line_limit:, depth: 0)
+        spans = [[RubyJard::Span.new(content: '{', styles: :text_primary)]]
+
+        item_count = 0
+        variable.each_with_index do |(key, value), index|
+          spans << @attributes_decorator.pair(
+            key, value, line_limit: line_limit, process_key: true, depth: depth + 1
+          )
+          item_count += 1
+          break if index >= lines - 2
+        end
+        spans << last_line(variable.length, item_count)
+      end
+
+      def last_line(total, item_count)
+        if total > item_count
+          [
+            RubyJard::Span.new(
+              content: "▸ #{total - item_count} more...",
+              margin_left: 2, styles: :text_dim
+            ),
+            RubyJard::Span.new(
+              content: '}',
+              styles: :text_primary
+            )
+          ]
+        else
+          [RubyJard::Span.new(content: '}', styles: :text_primary)]
+        end
+      end
+    end
+  end
+end