scryglass 0.1.0

data/lib/hexes.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+## Hexes takes care of some console/view/IO work for Scryglass
+module Hexes
+  using ClipStringRefinement
+  using AnsilessStringRefinement
+  using ConstantDefinedStringRefinement
+
+  def self.simple_screen_slice(screen_string)
+    screen_height, screen_width = $stdout.winsize
+
+    split_lines = screen_string.split("\n")
+
+    ## Here we cut down the (rectangular if opacified) display array in both
+    ##   dimensions (into a smaller rectangle), as needed, to fit the view.
+    sliced_lines = split_lines.map do |string|
+      ansi_length = string.length - string.ansiless_length
+      slice_length = screen_width + ansi_length
+      string[0, slice_length]
+    end
+    sliced_list = sliced_lines[0, screen_height]
+
+    sliced_list.join("\n")
+  end
+
+  def self.opacify_screen_string(screen_string)
+    screen_height, screen_width = $stdout.winsize
+
+    split_lines = screen_string.split("\n")
+    rows_filled = split_lines.count
+
+    blank_rows_at_bottom = [screen_height - rows_filled, 0].max
+
+    # This takes all the unfilled spaces left after a newline, and makes them
+    #   real spaces, so they'll overwrite whatever was there a second ago. Thus
+    #   I don't have to worry about clearing the screen all the time, which was
+    #   seemingly causing console chaff and some flickering.
+    side_filled_string = split_lines.map do |line|
+      margin_to_fill = screen_width - line.ansiless.length
+      line + (' ' * margin_to_fill)
+    end.join("\e[00m\n") # Also turns off ANSI text formatting at the end of
+    #   each line, in case a formatted string had its "turn off formatting" code
+    #   cut off from the end. (Reducing the need to end with one at all).
+
+    blank_line = "\n" + (' ' * screen_width)
+
+    side_filled_string + (blank_line * blank_rows_at_bottom)
+  end
+
+  def self.stdout_rescue
+    @preserved_stdout_dup = $stdout.dup
+
+    begin
+      yielded_return = yield
+    rescue => e
+      # `e` is raised again in the `ensure` block after stdout is safely reset.
+    ensure
+      $stdout = @preserved_stdout_dup
+      raise e if e
+    end
+
+    yielded_return
+  end
+
+  def self.capture_io(char_limit: nil)
+    stdout_rescue do # Ensures that $stdout is reset no matter what
+      temporary_io_channel = StringIO.new
+      $stdout = temporary_io_channel
+      Thread.abort_on_exception = true # So threads can return error text at all
+
+      if char_limit
+        background_output_thread = Thread.new { yield } # It's assumed that the
+        #   yielded block will be printing something somewhat promptly.
+
+        sleep 0.05 # Give it a head start (Sometimes makes a difference!)
+
+        while temporary_io_channel.size < char_limit
+          io_size = temporary_io_channel.size
+          sleep 0.05
+          new_io_size = temporary_io_channel.size
+          break if new_io_size == io_size
+        end
+        background_output_thread.terminate
+      else
+        yield
+      end
+
+      temporary_io_channel.rewind
+      captured_output = temporary_io_channel.read
+      captured_output = captured_output.clip_at(char_limit) if char_limit
+
+      captured_output
+    end
+  end
+
+  def self.overwrite_screen(screen_string)
+    csi = "\e["
+    $stdout.write "#{csi}s" # Saves terminal cursor position
+    $stdout.write "#{csi}1;1H" # Moves terminal cursor to top left corner
+
+    $stdout.print "\r#{screen_string}"
+    $stdout.write "#{csi}u" # Restores saved terminal cursor position
+  end
+
+  def self.hide_db_outputs
+    necessary_constants = ['Logger', 'ActiveRecord::Base']
+    necessary_constants_defined = necessary_constants.all?(&:constant_defined?)
+    return yield unless necessary_constants_defined
+
+    rails_logger_defined = 'Rails'.constant_defined? && Rails.try(:logger).present?
+
+    ## These are purposefully preserved as global variables so retrieval, in
+    ##   debugging or errored usage, is as easy as possible.
+    $preserved_ar_base_logger = ActiveRecord::Base.logger.dup
+    $preserved_rails_logger = Rails.logger.dup if rails_logger_defined
+
+    begin
+      ## Now we create an unused dump string to serve as the output
+      ignored_output = StringIO.new
+      ignored_log = Logger.new(ignored_output)
+      ActiveRecord::Base.logger = ignored_log
+      Rails.logger = ignored_log if rails_logger_defined
+
+      yielded_return = yield
+    rescue => e
+      # `e` is raised again in the `ensure` after displays are safely reset.
+    ensure
+      ActiveRecord::Base.logger = $preserved_ar_base_logger
+      Rails.logger = $preserved_rails_logger if rails_logger_defined
+      raise e if e
+    end
+
+    yielded_return
+  end
+end

data/lib/prog.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+## Prog is a simple progress bar for tracking one or more nested or simultaneous
+##   processes. Tasks fit evenly and dynamically into a Pipe, which can then
+##   be displayed at a chosen width.
+module Prog
+  class Pipe
+    attr_accessor :tasks
+    attr_accessor :highest_count
+
+    def initialize
+      self.tasks = []
+      self.highest_count = 0
+    end
+
+    def to_s(length: $stdout.winsize[1])
+      return ' ' * length if tasks.count.zero?
+
+      unused_length = length
+      self.highest_count = [highest_count, tasks.count].max
+
+      ## Set up the first barrier
+      display_string = +'|'
+      unused_length -= 1
+
+      ## Get a first pass at equal task length
+      # first_pass_task_length = unused_length/working_tasks.count
+      first_pass_task_length = unused_length / highest_count
+      if first_pass_task_length < 2
+        raise "Prog::Pipe length (#{length}) too small to " \
+              "fit all tasks (#{tasks.count})"
+      end
+      tasks.each do |task|
+        task.working_length = first_pass_task_length
+      end
+
+      ## Distribute the remaining space evenly among the first n tasks
+      remaining_space = unused_length - (first_pass_task_length * highest_count)
+      tasks[0...remaining_space].each { |task| task.working_length += 1 }
+
+      tasks.each do |task|
+        display_string << task.to_s
+      end
+      display_string.ljust(length, ' ')
+    end
+
+    def <<(task)
+      tasks << task
+      task.pipe = self
+      task.force_finish if task.max_count.zero?
+    end
+  end
+
+  class Task
+    attr_accessor :pipe, :max_count, :current_count
+    attr_accessor :working_length
+
+    def initialize(max_count:)
+      self.max_count = max_count
+      self.current_count = 0
+      self.working_length = nil # (Only set by Prog::Pipe)
+    end
+
+    def tick(number_of_ticks = 1)
+      self.current_count += number_of_ticks
+
+      force_finish if current_count >= max_count
+    end
+
+    def force_finish
+      pipe.tasks.delete(self)
+      pipe.highest_count = 0 if pipe.tasks.empty?
+    end
+
+    def to_s
+      progress_ratio = current_count / max_count.to_f
+
+      unused_length = working_length
+      display_string = +'|' # (not frozen)
+      unused_length -= 1
+
+      filled_cells = (unused_length * progress_ratio).floor
+      fill_bar = ('=' * filled_cells).ljust(unused_length, ' ')
+      display_string.prepend(fill_bar)
+
+      display_string
+    end
+  end
+end

data/lib/refinements/ansiless_string_refinement.rb

@@ -0,0 +1,11 @@
+module AnsilessStringRefinement
+  refine String do
+    def ansiless
+      gsub(/\e\[[\d\;]*m/, '')
+    end
+
+    def ansiless_length
+      ansiless.length
+    end
+  end
+end

data/lib/refinements/array_fit_to_refinement.rb

@@ -0,0 +1,67 @@
+module ArrayFitToRefinement
+  refine Array do
+    using ClipStringRefinement
+    using AnsilessStringRefinement
+    # Warning: Still not going to work nicely if a string ends in an ansi code!
+    def fit_to(string_length_goal, fill: ' ', ignore_ansi_codes: true)
+      string_array = self.map(&:to_s) # This also acts to dup
+      length_method = ignore_ansi_codes ? :ansiless_length : :length
+      length_result = string_array.join('').send(length_method)
+
+
+      if length_result > string_length_goal
+        string_array.compress_to(string_length_goal, ignore_ansi_codes: ignore_ansi_codes)
+      elsif length_result < string_length_goal
+        string_array.expand_to(string_length_goal, ignore_ansi_codes: ignore_ansi_codes, fill: fill)
+      else # If it joins to the right length already, we still want to return the expected number of strings.
+        spacers = [''] * (string_array.count - 1)
+        string_array.zip(spacers).flatten.compact
+      end
+    end
+
+    # Warning: Still not going to work nicely if a string ends in an ansi code!
+    def compress_to(string_length_goal, ignore_ansi_codes:)
+      working_array = self.map(&:to_s)
+      original_string_count = self.count
+      spacers = [''] * (original_string_count - 1)
+      length_method = ignore_ansi_codes ? :ansiless_length : :length
+
+      ## Ensure the strings are short enough to fit:
+      slider = 0
+      while working_array.join('').send(length_method) > string_length_goal
+        longest_string_length = working_array.map { |s| s.send(length_method) }.max
+        slider_index = slider % working_array.count
+        if working_array[slider_index].send(length_method) >= longest_string_length
+          working_array[slider_index] =
+            working_array[slider_index].clip_at(working_array[slider_index].send(length_method) - 1,
+                                                ignore_ansi_codes: ignore_ansi_codes)
+        end
+        slider += 1
+      end
+
+      working_array.zip(spacers).flatten.compact
+    end
+
+    def expand_to(string_length_goal, ignore_ansi_codes:, fill:)
+      original_string_count = self.count
+      working_array = self.map(&:to_s)
+      spacers = [''] * (original_string_count - 1)
+      length_method = ignore_ansi_codes ? :ansiless_length : :length
+
+      ## Ensure the spacers are large enough to fill out to string_length_goal
+      space_to_fill = string_length_goal - working_array.join('').send(length_method)
+      first_pass_spacer_length = space_to_fill / spacers.count
+      spacers.map! { fill * first_pass_spacer_length }
+
+      ## Distribute the remaining space evenly among the last n spacers
+      remaining_space = space_to_fill - spacers.join('').send(length_method)
+      if remaining_space.positive?
+        spacers =
+          spacers[0...-remaining_space] +
+          spacers[-remaining_space..-1].map! { |spacer| spacer + ' ' } #each { |task| task.working_length += 1 }
+      end
+
+      working_array.zip(spacers).flatten.compact
+    end
+  end
+end

data/lib/refinements/clip_string_refinement.rb

@@ -0,0 +1,27 @@
+module ClipStringRefinement
+  refine String do
+    using AnsilessStringRefinement
+
+    # Warning: Still not going to work nicely if a string ends in an ansi code!
+    def clip_at(clip_length, ignore_ansi_codes: false)
+      length_method = ignore_ansi_codes ? :ansiless_length : :length
+      original_length = send(length_method)
+      ansi_length = ignore_ansi_codes ? length - ansiless_length : 0
+      slice_length = clip_length + ansi_length
+      clipped_string = self[0...slice_length]
+      if clipped_string.send(length_method) < original_length
+        clipped_string = clipped_string.mark_as_abbreviated
+      end
+
+      clipped_string
+    end
+
+    # Warning: Still not going to work nicely if a string ends in an ansi code!
+    def mark_as_abbreviated
+      self_dup = dup
+      self_dup[-1] = '…' if self_dup[-1]
+      self_dup[-2] = '…' if self_dup[-2]
+      self_dup
+    end
+  end
+end

data/lib/refinements/constant_defined_string_refinement.rb

@@ -0,0 +1,11 @@
+module ConstantDefinedStringRefinement
+  refine String do
+    def constant_defined?
+      begin
+        !!Object.const_get(self)
+      rescue
+        false # Swallow expected error if not defined
+      end
+    end
+  end
+end

data/lib/scryglass.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+
+## Bookkeeping and external tools:
+require "scryglass/version"
+require 'active_support/core_ext/object/blank' # This gives us `.present?` and `.blank?` # https://stackoverflow.com/questions/4648684/how-to-use-present-in-ruby-projects
+require 'io/console'
+require 'pp'
+
+## Refinements and sub-tools:
+require 'refinements/ansiless_string_refinement'
+require 'refinements/clip_string_refinement'
+require 'refinements/constant_defined_string_refinement'
+require 'refinements/array_fit_to_refinement'
+require 'hexes'
+require 'prog'
+
+## Core gem components:
+require 'scryglass/config'
+require 'scryglass/ro'
+require 'scryglass/ro_builder'
+require 'scryglass/session'
+require 'scryglass/view_wrapper'
+require 'scryglass/view_panel'
+require 'scryglass/tree_panel'
+require 'scryglass/lens_panel'
+
+## Testing and Demoing:
+require 'example_material.rb'
+
+module Scryglass
+  HELP_SCREEN = <<~'HELPSCREENPAGE'
+          q : Quit Scry                               ? : Cycle help panels (1/2)
+
+    BASIC NAVIGATION: · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+      ·                                                                               ·
+      ·   UP / DOWN : Navigate (You can type a number first)                          ·
+      ·   RIGHT     : Expand   current or selected row(s)                             ·
+      ·   LEFT      : Collapse current or selected row(s)                             ·
+      ·                                                                               ·
+      ·   ENTER : Close Scry, returning current or selected object(s) (Key or Value)  ·
+      ·                                                                               ·
+      · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+
+    INSPECTING WITH LENS VIEW:  · · · · · · · · · · · · · ·
+      ·                                                   ·
+      ·   SPACEBAR : Toggle Lens View                     ·
+      ·          l : Cycle through lens types             ·
+      ·          L : Toggle subject  (Key/Value of row)   ·
+      ·                                                   ·
+      · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+
+    MORE NAVIGATION:  · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+      ·                                                                       ·
+      ·      [w]    :  Move view window           0 : Reset view location     ·
+      ·   [a][s][d]   (ALT increases speed)      (Press again: reset cursor)  ·
+      ·                                                                       ·
+      · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+  HELPSCREENPAGE
+
+  HELP_SCREEN_ADVANCED = <<~'HELPSCREENADVANCEDPAGE'
+          q : Quit Scry                               ? : Cycle help panels (2/2)
+
+    ADVANCED: · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+      ·  DIGGING DEEPER:                                                                    ·
+      ·    For current or selected row(s)...                                                ·
+      ·      @ : Build instance variable sub-rows                                           ·
+      ·      . : Build ActiveRecord association sub-rows                                    ·
+      ·      ( : Attempt to smart-build sub-rows, if Enumerable. Usually '@' is preferable. ·
+      ·                                                                                     ·
+      ·  SELECTING ROWS:                                                                    ·
+      ·    * : Select/Deselect ALL rows                                                     ·
+      ·    | : Select/Deselect every sibling row under the same parent row                  ·
+      ·    - : Select/Deselect current row                                                  ·
+      ·                                                                                     ·
+      ·  TEXT SEARCH:                                                                       ·
+      ·    / : Begin a text search (in tree view)                                           ·
+      ·    n : Move to next search result                                                   ·
+      ·                                                                                     ·
+      · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
+  HELPSCREENADVANCEDPAGE
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.reset_config
+    @config = Config.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  def self.load_silently
+    begin
+      add_kernel_methods
+      { success: true, error: nil }
+    rescue => e
+      { success: false, error: e }
+    end
+  end
+
+  def self.load
+    caller_path = caller_locations.first.path
+
+    silent_load_result = Scryglass.load_silently
+
+    if silent_load_result[:success]
+      puts "(Scryglass is loaded, from `#{caller_path}`. Use `Scryglass.help` for help getting started)"
+    else
+      puts "(Scryglass failed to load, from `#{caller_path}` " \
+           "getting `#{silent_load_result[:error].message}`)"
+    end
+
+    silent_load_result
+  end
+
+  def self.help
+    console_help = <<~"CONSOLE_HELP" # Bolded with \e[1m
+      \e[1m
+      |  To prep Scryglass, call `Scryglass.load`
+      |  (Or add it to .irbrc & .pryrc)
+      |
+      |  To start a Scry Session, call:
+      |  >   scry my_object   OR
+      |  >   my_object.scry
+      |
+      |  To resume the previous session:   (in same console session)
+      |  >   scry   OR
+      |  >   scry_resume (if you're in a breakpoint pry)
+      \e[0m
+    CONSOLE_HELP
+
+    puts console_help
+  end
+
+  private
+
+  def self.add_kernel_methods
+    Kernel.module_eval do
+      def scry(arg = nil, actions = nil) # `actions` can't be a keyword arg due
+        #   to this ruby issue: https://bugs.ruby-lang.org/issues/8316
+
+        receiver = self unless to_s == 'main'
+        # As in: `receiver.scry`,
+        #   and no receiver means scry was called on 'main', (unless self is
+        #   different in the because you've pry'd into something!)
+
+        seed_object = arg || receiver
+
+        $scry_session = Scryglass::Session.new(seed_object) if seed_object
+        # If it's been given an arg or receiver, create new session!
+        # The global variable is purposeful, and not accessible outside of
+        #   the one particular console instance.
+
+        scry_resume(actions) # Pick up the new or previous session
+      end
+
+      # For the user, this is mainly just for pry sessions where `self` isn't `main`
+      def scry_resume(actions = nil)
+        Scryglass.config.validate!
+
+        no_previous_session = $scry_session.nil?
+        if no_previous_session
+          raise ArgumentError,
+                '`scry` requires either an argument, a receiver, or a past' \
+                'session to reopen. try `Scryglass.help`'
+        end
+
+        Hexes.stdout_rescue do
+          $scry_session.run_scry_ui(actions: actions)
+        end
+      end
+    end
+  end
+end