scryglass 1.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e64cacb2e1c0e588ffa8554c9203f73a5aa11f565454f0e7e190328b18acaaa8
-  data.tar.gz: 4435413405197c4dbf03a80bff4632b29cf09d44b0f53de45894ea426c858091
+  metadata.gz: 69ff16003c6e5b4ceb6e93e9c5f9ee8aed269b50954db3869963fdf9ab64215b
+  data.tar.gz: 6d5c2f92d50b86a1e837033646b7793ee08e5115df98c47c2772775132875337
 SHA512:
-  metadata.gz: 2d9081ae5876b542f6c17e792f7a02b12f832a128644e3334c0c6b819dc076fb1a8e60f77e9c02e65032e67e2be52fae38f7ba8b0d38fdfced2bac95469b4ff0
-  data.tar.gz: adbc658b799af3c4167d132de38d3225db3efaba3e95b39251352b0b8360169419db654605fd88314ccbfce80ce3a78d9cb87c02ff55559ce42a483d086848cf
+  metadata.gz: 2f76204b2d6a0e67901e5cee79c5b4a1dcbe7fd08bf03c289cc95268b6e562d86bc49804f215a476e2239a7dfa388e66771c2ad1b1206b23b0b16aeee00607a1
+  data.tar.gz: 25171585025b50992b202bff43a881715a11cb7e48c0cfef522281357ea9d2de0de2b584446ba36d979fce45eba7509b69531118f98ce55d3b02c03c5534129e

data/.irbrc

@@ -0,0 +1,9 @@
+Scryglass.load
+
+def th
+  Scryglass.test_hash
+end
+
+def dh
+  Scryglass.demo_hash
+end

data/CHANGELOG.md

@@ -7,6 +7,109 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## Added
+
+## Changed
+
+## Fixed
+
+## [2.0.2] - 2020-01-14
+
+## Added
+
+## Changed
+
+- Added a default character limit to the method_showcase_for lens to speed it up (Some AR objects have over 1000 methods).
+
+## Fixed
+
+## [2.0.1] - 2020-01-13
+
+## Changed
+
+- The named-an-object message now stays for 3 seconds instead of 2.
+
+## Fixed
+
+- Typo in spec.description in scryglass.gemspec.
+- Negative sign error on method_showcase_for while calculating padding for very long method names.
+
+## [2.0.0] - 2021-01-13
+
+## Added
+
+- Turned on ANSI formatted/colored support with AnsiSliceStringRefinement.
+- Added 'AmazingPrint' lens (colored) and gem.
+- Added color formatting to (beta) method_showcase_for.
+- Added "Smart Open" command 'o', which attempts to create sub-rows of the (next) most helpful type.
+- README and help screen now point out that holding SHIFT will increase up/down step distance.
+- Bottom and right edges of screen now indicate, with dots, when there is more beyond the view's edge.
+- Added the VIM home row keybindings `h`/`j`/`k`/`l` as optional arrow keys.
+- Now if the scry session hits an error, it will first ensure the error and console prompt appear below the present screen.
+- Can now press `=` to give a console instance variable name to current objects without leaving scry session.
+- Added popup messages for when the user attempts to create sub-rows for the current row and no sub-items are found.
+- Added tab functionality to manage multiple scry session tabs for easy reference and comparison.
+- Scryglass version now shows up in top right corner of the tree view when the header has no values to track.
+- Improved and enabled 'Method Showcase' lens by default.
+- Added `[<]`/`[>]` key reminders to Lens View.
+
+## Changed
+
+- Changed user_signal timeout period from 0.1sec to 0.3sec to reduce number of coincidentally dropped inputs.
+- Changed AnsiSliceStringRefinement syntax even closer to 'string'[args] (supporting [i, l] syntax).
+- Changed the keys for switching subject type and lens from `L`/`l` to `<`/`>` (To make room for vim h/j/k/l keybindings)
+- Expanded list of "Patient Actions" which won't beep even if that procedure (sometimes user input) took longer than 4 seconds.
+- Improved popup messages QOL (they now stack properly and don't make the user wait for them to disappear).
+- Removed `scry_resume` command; bare `scry` now always resumes last session even if the current console receiver isn't `main`.
+- Made help screen key text blue.
+
+## Fixed
+
+- Some more fixes to support (BETA) method_showcase_for:
+  - Added method_source gem.
+  - Now requiring lens_helper.
+  - Changed method to be callable externally
+- Extra view margin no longer producible at far end of ANSI strings
+- Escape true newlines returned by objects with unexpected `.inspect` results, which otherwise messes up the display.
+- Cursor indicators ( `(`/`@`/`·` ) can no longer stall or error on exceptional objects; they now show up as `X` if they error or take too long (0.05s).
+- When quitting from the help screen, cursor and prompt are now set all the way at the bottom of the display, rather than where the content ends on the current *non-help* panel.
+
+## [1.1.0] - 2020-09-21
+
+## Added
+
+- Added ability to distinguish genuine escape key presses, and added escape key functionality.
+- Added ability (AnsiSliceStringRefinement) to slice strings while effectively maintaining their ANSI formatting, as our eyes would expect.
+- Added some dynamic header items to Tree View that track the following:
+  - Multiple targets count and message
+  - Last search text (what will be searched again by hitting 'n')
+  - Number-to-move, if digits are typed
+  - ('?' controls reminder now only displays when header is otherwise empty)
+
+## Changed
+
+- Now inputs check and screen redraws every 0.1 seconds even without user keypresses.
+- (ArrayFitToRefinement now allows non-plural array counts)
+
+## Removed
+
+- Temporarily removed record/playback functionality
+- Removed all dependency on activesupport
+
+## Fixed
+
+- Fixed issue where shrinking the console screen size enough would create a visual glitch until one of the boundary-resizing commands was received.
+
+## [1.0.1] - 2020-09-18
+
+### Added
+
+- Added `require 'stringio'` for StringIO
+
+### Removed
+
+- Removed development_dependency 'io-console'
+
 ## [1.0.0] - 2020-09-18
 
 ### Added

data/Gemfile.lock

@@ -1,33 +1,35 @@
 PATH
   remote: .
   specs:
-    scryglass (1.0.0)
+    scryglass (2.0.2)
+      amazing_print
+      binding_of_caller
+      method_source
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.4.4)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    concurrent-ruby (1.1.7)
-    i18n (1.8.5)
-      concurrent-ruby (~> 1.0)
-    io-console (0.5.6)
-    minitest (5.14.2)
+    amazing_print (1.2.1)
+    binding_of_caller (0.8.0)
+      debug_inspector (>= 0.0.1)
+    coderay (1.1.3)
+    debug_inspector (0.0.3)
+    interception (0.5)
+    method_source (1.0.0)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-rescue (1.5.2)
+      interception (>= 0.5)
+      pry (>= 0.12.0)
     rake (12.3.3)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport (~> 5.0)
   bundler (~> 2.1)
-  io-console
+  pry-rescue
   rake (~> 12.0)
   scryglass!
 

data/README.md

@@ -1,3 +1,17 @@
+# 🔮 Scryglass
+
+Scryglass is a ruby console tool for visualizing and actively exploring objects (large, nested, interrelated, or unfamiliar). You can navigate nested arrays, hashes, instance variables, ActiveRecord
+relations, and unknown Enumerable types like an expandable/collapsable file tree in an intuitive UI.
+
+Objects and child objects can also be inspected through a variety of display lenses, returned directly to the console, and more!
+
+`scry` is quick to use and useful for both experienced developers and those very new to ruby, rails, or coding.  
+It facilitates:
+- Debugging/Investigating
+- Education, learning the structure of objects and their relationships
+- Comparing/Scanning sub-items in an Enumerable (e.g. Person.first.library_records.scry)
+
+
 # Table of Contents
 
 [🔮 Scryglass Intro Summary](#-scryglass)
@@ -18,18 +32,6 @@
 - [Miscellaneous Troubleshooting Notes](#miscellaneous-troubleshooting-notes)
 - [Contributing](#contributing)
 
-# 🔮 Scryglass
-
-Scryglass is a ruby console tool for visualizing and actively exploring objects (large, nested, interrelated, or unfamiliar). You can navigate nested arrays, hashes, instance variables, ActiveRecord
-relations, and unknown Enumerable types like an expandable/collapsable file tree in an intuitive UI.
-
-Objects and child objects can also be inspected through a variety of display lenses, returned directly to the console, and more!
-
-`scry` is quick to use and useful for both experienced developers and those very new to ruby, rails, or coding.  
-It facilitates:
-- Debugging/Investigating
-- Education, learning the structure of objects and their relationships
-- Comparing/Scanning sub-items in an Enumerable (e.g. Person.first.library_records.scry)
 
 ## ⚡️ tl;dr SUPER Quick Start
 
@@ -58,7 +60,7 @@ $ gem install scryglass
 ```
 ## Enabling Scryglass
 
-For the `scry` method syntax to work as cleanly as it does, Scryglass needs to add the method to the Kernel module. While this is safe, it was safest to have this only happen on a console session basis. To enable the `scry` method, call `Scryglass.load`. Thus, to automatically enable Scryglass when opening a console, you add one of the following lines to your `./irbrc` (and `./pryrc` for rails or pry sessions):
+For the `scry` method syntax to work as cleanly as it does, Scryglass needs to add the method to the Kernel module. While this is safe, it was safest to have this only happen on a console session basis. To enable the `scry` method, call `Scryglass.load`. Thus, to automatically enable Scryglass when opening a console, you add one of the following lines to your `./.irbrc` (and `./.pryrc` for rails or pry sessions):
 ```ruby
 Scryglass.load
 ```
@@ -85,9 +87,6 @@ To start a Scry Session, call:
 **A note about passing an argument without parentheses:**  
 > The arg syntax (`scry my_object`) will get confused if it's given a hash direcly (`scry {a: [1, 2] }`), thinking you're trying to pass a block, unless you use parentheses (`scry({a: [1, 2] })`).
 
-**A note about using the resume session command, while in a pry:**  
-> The straight resume command, the bare `scry`, relies on the assumption that the method receiver is `main`. When your console is a pry in some other code, `self` is no longer `main`, but some other object, and so you are actually calling `scry` on that, overwriting your previous session. If you still want to resume session in that context, you can use `scry_resume`.
-
 ## Basic Usage
 
 Use the arrow keys to move around and open/close known Enumerable types! Hit `'?'` to view all the controls and learn how to do much much more.
@@ -128,40 +127,47 @@ The cursor, movable by arrow keys, is represented by a straight line (`–––
 | `––––` | ...no secret contents |
 | `(–––` | ...a non-empty Enumerable of an unknown type (openable with `'('`) |
 | `–@––` | ...instance variables on the object (openable with `'@'`) |
-| `(@––` | ...both! ***Generally* instance variables yield more sub-items with more info.** |
+| `––·–` | ...ActiveRecord associations (openable with `'.'`) |
+| `(@·–` | ...all three! (Note: ***Generally* IVs yield more sub-items with more info than using `'('`).** |
 
-ActiveRecord objects are no secret; you can press `'.'` on them to build their AR Association sub-items.
+An `X` in place of any of these characters indicates an error or a timeout (if the "counting" process takes longer than 0.05 seconds)
 
 A single `•` will mark the presence of user-added rows when they are hidden.
 
 ### Waiting!
 Scryglass has two features to make wait time a little easier:
-- If any process takes longer than 4 seconds between you pressing a key and the process completing, it **makes a beep sound!** This means if something seems like it might take a bit, you can switch to another tab or window without worry, and it will tell you when to check back.
+- If any process (with a couple exceptions for user input) takes longer than 4 seconds between you pressing a key and the process completing, it **makes a beep sound!** This means if something seems like it might take a bit, you can switch to another tab or window without worry, and it will tell you when to check back.
 - While there are no time estimates (for a number of reasons), many subprocesses are linked to a **progress bar**, which will display at the bottom of the screen. If multiple nested processes are running one within another, the progress bar will divide itself into parts to show each process. The leftmost bar is the base level iteration task.
 
 ## In-Depth Control Rundown
 
-| Key | Help Screen Snippet | Verbose Description |
+| Key | Help_Screen_Snippet | Verbose Description |
 |:---:|---------------------|---------------------|
 | `?` | Press '?' for controls | `?` will cycle through the help panels, then back to the scry session. |
 | `q` | Quit Scry | Exits the scry session, returning nil. The cursor (and exit message) is then placed below the last line console line with content in order to take up no more space than needed. |
-| `UP`/`DOWN` | Navigate (You can type a number first) | Moves the cursor one step upward or downward in the tree view (this can be done while in lens view). If a number (of any number of digits) is typed out before pressing `UP` or `DOWN`, then the cursor will move that many steps in that direction. If the number of steps goes past the edge of the list, the cursor will sit safely at that edge. |
-| `RIGHT` | Expand current or selected row(s) | If any rows are *selected* this attempts to expand all of them, and will expand the ones it can. If none are selected, then it will attempt to expand the current row where the cursor is. If the current row has preexisting sub-items, but they are hidden because the current ro is collapsed, this will reveal them in the tree view. |
+| `UP`/`DOWN` | Navigate (To move further, type a number first or use SHIFT) | Moves the cursor one step upward or downward in the tree view (this can be done while in lens view). If a number (of any number of digits) is typed out before pressing `UP` or `DOWN`, then the cursor will move that many steps in that direction. If `SHIFT` is held while pressing, then the cursor will move 12 steps in that direction. If the number of steps goes past the edge of the list, the cursor will sit safely at that edge. |
+| `RIGHT` | Expand current or selected row(s) | If any rows are *selected* this attempts to expand all of them, and will expand the ones it can. If none are selected, then it will attempt to expand the current row where the cursor is. If the current row has preexisting sub-items, but they are hidden because the current row is collapsed, this will reveal them in the tree view. |
 | `LEFT` | Collapse current or selected row(s) | If any rows are *selected* this attempts to collapse all of them, and will collapse the ones it can. If none are selected, then it will attempt to collapse the current row where the cursor is. If the current row either has no sub-items or is already collapsed, this action will collapse its parent row instead and place the cursor there. |
+| `h`/`j`/`k`/`l` | (These keys on the home row can also serve as arrow keys) | This is for those familiar with VIM keybindings! Shift speeds up k/j to 12 steps just the same as UP/DOWN. |
 | `ENTER` | Close Scry, returning current or selected object(s) (Key or Value) | Returns the subject object (based on current subject type, :value or :key) of the current item, or, if any items are selected (`->`), it returns all of those in an array. The order matches the order in which they were marked as selected. In the case of \| and \*, the order of the array will be top to bottom. If the current Subject Type (toggled by `L`) is :key, rows without "keys" will return `nil`. |
 | `SPACEBAR` | Toggle Lens View | Switches between Tree View and Lens View. This will not change the view position of the lens view, but the view position of the tree view will still follow the cursor if the cursor moves while in lens view. |
-| `l` | Cycle through lens types | Cycles through the different lens types in the lens view. These all take the current row, at either the "key" or the "value" object depending on the current subject type (toggled by `L`), and display a string of it, transformed through that particular lens. New lenses can be written in the config. |
-| `L` | Toggle subject  (Key/Value of row) | This change is only perceptible in the lens view, but does also change which objects are returned by `ENTER`. Any objects without "keys" will return nil for their :key if they don't have one. |
-| `w`/`a`/`s`/`d` | Move view window (ALT increases speed) | The W/A/S/D keys form a second set of arrow keys for moving around the "screen" through which you view the tree view and the lens view, when the contents don't all fit on the screen at once. They move 5 cells in the specificied direction, or 50 if ALT is held before pressing. Can be held down for continuous movement. |
+| `>` | Cycle through lens types | Cycles through the different lens types in the lens view. These all take the current row, at either the "key" or the "value" object depending on the current subject type (toggled by `L`), and display a string of it, transformed through that particular lens. New lenses can be written in the config. |
+| `<` | Toggle subject  (Key/Value of row) | This change is only perceptible in the lens view, but does also change which objects are returned by `ENTER`. Any objects without "keys" will return nil for their :key if they don't have one. |
+| `w`/`a`/`s`/`d` | Move view window (ALT increases speed) | The W/A/S/D keys form a second set of arrow keys for moving around the "screen" through which you view the tree view and the lens view, when the contents don't all fit on the screen at once. They move 5 cells in the specified direction, or 50 if ALT is held before pressing. Can be held down for continuous movement. |
 | `0` | Reset view location (Press again: reset cursor) | This resets/zeros the current view (tree or lens). If you are in the tree view, and the view is in the zero (top left) position, then this will instead move the cursor there. |
 | `@` | Build instance variable sub-rows for current or selected row(s) | Identifies all instance variables on the object (or value of a key-value pair) of the current or selected rows. Then these instance variables are turned into a list of keys, called on the original object, and then paired with the resulting objects. Known Enumerables are recursively navigable as always. |
-| `.` | Build ActiveRecord association sub-rows for current or selected row(s) | If the `ActiveRecord` constant is not defined by the system, this will do nothing. If it is, this will navigate the reflections of the the class of the object (or value of a key-value pair) in order to find its AR Associations and turn them into key-value sub-items. Note: With the default configuration, the way it uses reflections *purposefully ignores `:through` relations and `scope`d relations (e.g. the extraneous `CURRENT_phone_numbers`).* |
+| `.` | Build ActiveRecord association sub-rows for current or selected row(s) | If the `ActiveRecord` constant is not defined by the system, this will do nothing. If it is, this will navigate the reflections of the the class of the object (or value of a key-value pair) in order to find its AR Associations and turn them into key-value sub-items. Note: With the default configuration, the way it uses reflections *purposefully ignores `:through` relations and `scope`d relations (e.g. the extraneous `CURRENT_phone_numbers`).* Note: The `·` cursor indicator does not take the time to traverse all reflections, nor account for all configured filters. It's possible that `.` will produce no sub-rows despite the indicator. |
 | `(` | Attempt to smart-build sub-rows for current or selected row(s), if Enumerable. Usually '@' is preferable | Attempts a "smart reading" of the object (or value of a key-value pair) of the current or selected rows. If the object is an Enumerable, it will attempt to parse it into sub-items. if the object has keys, it will be parsed as key-value pairs like a hash, otherwise singular objects like an array. This can sometimes create sub-items that would otherwise be more neatly accesible under a single instance variable if instance variables are built instead, so default to trying that first. |
+| `o` | Quick Open: builds the most likely helpful sub-rows ( '.' \|\| '@' \|\| '(' ) | "Quick Open" first tries opening AR Associations. If none are produced, it tries for instance variables. If none are produced, it attempts to open as it would an unknown Enumerable type. Can be pressed repeatedly to produce all types of sub-rows. |
 | `*` | Select/Deselect ALL rows | This includes hidden rows. If all rows are already selected, they will be unselected, regardless of how they became selected. |
 | `\|` | Select/Deselect every sibling row under the same parent row | If all siblings under that parent row are already selected, they will be unselected, regardless of how they became selected. |
 | `-` | Select/Deselect current row | If these objects are later returned, the order in which they were selected will determine their order in the returned array. |
+| `Tab` | Change session tab (to the right) (`Shift`+`Tab` moves left) | Changes which scry session is the current one, and brings up the tab bar for a couple seconds. |
+| `Q` | Close current session tab | Permanently exits the current session tab, but keeps scry running if another tab remains. Switches one tab to left if there is one.
 | `/` | Begin a text search (in tree view) | Begins a case-sensitive regex search of all items, in a loop, starting with just below the current row. For a matching object to be found, the search must match its *truncated sample string in tree view* (regardless of what is on or off screen) (it must match either the key or the value, not the full line they create) (known enumerable types, like `[•••]`, may count as a match if they contain the string in the backend). |
 | `n` | Move to next search result | Will, using the most recent search entry, move the cursor on to the next match downward, cycling through all rows. This follows the same matching rules as the original search. |
+| `=` | Open prompt to type a console handle for current or selected row(s) | Gets text from user (not including the '@') and saves the current subject, or array of selected row(s) subjects, under that instance variable name. These variables live in the console itself: the binding of wherever `scry` was called. Care is taken not to allow them to conflict with preexisting IV names or method names. Note: But still, if you are prying inside an object/context, your IVs will be defined on that object. Note: If you switch from one pry context to another and then back, your first pry's instance variables will be there despite not being listed in the IV outro message. |
+| `Esc` | Resets selection, last search, and number-to-move. (or returns to Tree View) | (Essentially, clears the values represented in the Tree View header if you're in the Tree View; otherwise it returns you to the Tree View) |
 
 ## Configuration / Customization (all optional)
 
@@ -187,18 +193,28 @@ Scryglass.configure do |config|
   ## UX
   # config.cursor_tracking = [:flexible_range, :dead_center][0] # Default: [0]
   # config.lenses = [ # Custom lenses can easily be added as name+lambda hashes! Or comment some out to turn them off.
+  #   { name: 'Amazing Print (`ap`)',
+  #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { ap o } } }, # This has colors!
   #   { name: 'Pretty Print (`pp`)',
   #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { pp o } } },
   #   { name: 'Inspect (`.inspect`)',
   #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { puts o.inspect } } },
   #   { name: 'Yaml Print (`y`)',
-  #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { y o } } }, # OR: `puts o.to_yaml`
+  #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { require 'yaml' ; y o } } }, # OR: `puts o.to_yaml`
   #   { name: 'Puts (`puts`)',
   #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { puts o } } },
-  #   # { name: 'Method Showcase',  # Not included by default
-  #   #   lambda: ->(o) { Scryglass::LensHelper.method_showcase_for(o) } },
+  #   { name: 'Method Showcase',
+  #     lambda: ->(o) { Scryglass::LensHelper.method_showcase_for(o, char_limit: 20_000) } },
   # ]
 
+  ## AmazingPrint defaults, if the user has not set their own:
+  # AmazingPrint.defaults ||= {
+  #   index: false,  # (Don't display array indices).
+  #   raw:   true,   # (Recursively format instance variables).
+  # }
+  # See https://github.com/amazing-print/amazing_print
+
+
   ## Building ActiveRecord association sub-rows:
   # config.include_empty_associations = true # Default: true
   # config.include_through_associations = false # Default: false

data/example_config.rb

@@ -12,16 +12,26 @@ Scryglass.configure do |config|
   # config.lenses = [ # Custom lenses can easily be added as name+lambda hashes! Or comment some out to turn them off.
   #   { name: 'Pretty Print (`pp`)',
   #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { pp o } } },
+  #   { name: 'Amazing Print (`ap`)',
+  #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { ap o } } }, # This has colors!
   #   { name: 'Inspect (`.inspect`)',
   #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { puts o.inspect } } },
   #   { name: 'Yaml Print (`y`)',
-  #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { y o } } }, # OR: `puts o.to_yaml`
+  #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { require 'yaml' ; y o } } }, # OR: `puts o.to_yaml`
   #   { name: 'Puts (`puts`)',
   #     lambda: ->(o) { Hexes.capture_io(char_limit: 20_000) { puts o } } },
-  #   # { name: 'Method Showcase',  # Not included by default
-  #   #   lambda: ->(o) { Scryglass::LensHelper.method_showcase_for(o) } },
+  #   { name: 'Method Showcase',
+  #     lambda: ->(o) { Scryglass::LensHelper.method_showcase_for(o, char_limit: 20_000) } },
   # ]
 
+  ## AmazingPrint defaults, if the user has not set their own:
+  # AmazingPrint.defaults ||= {
+  #   index: false,  # (Don't display array indices).
+  #   raw:   true,   # (Recursively format instance variables).
+  # }
+  # See https://github.com/amazing-print/amazing_print
+
+
   ## Building ActiveRecord association sub-rows:
   # config.include_empty_associations = true # Default: true
   # config.include_through_associations = false # Default: false

data/lib/hexes.rb

@@ -107,7 +107,7 @@ module Hexes
     necessary_constants_defined = necessary_constants.all?(&:constant_defined?)
     return yield unless necessary_constants_defined
 
-    rails_logger_defined = 'Rails'.constant_defined? && Rails.try(:logger).present?
+    rails_logger_defined = 'Rails'.constant_defined? && !!Rails.try(:logger)
 
     ## These are purposefully preserved as global variables so retrieval, in
     ##   debugging or errored usage, is as easy as possible.

data/lib/refinements/ansiless_string_refinement.rb

@@ -7,5 +7,150 @@ module AnsilessStringRefinement
     def ansiless_length
       ansiless.length
     end
+
+    ## Splits string into characters, with each ANSI escape code being its own
+    ##   grouped item, like so:
+    ##     irb> "PLAIN\e[32mCOLOR\e[0mPLAIN".ansi_string_breakout
+    ##     => ["P", "L", "A", "I", "N", "\e[32m", "C", "O", "L", "O", "R",
+    ##         "\e[0m", "P", "L", "A", "I", "N"]
+    def ansi_string_breakout
+      breakout_array = []
+      working_self = self.dup
+
+      while working_self[0]
+        if (working_self =~ /\e\[[\d\;]*m/) == 0 # if begins with
+          end_of_escape_code = (working_self.index('m'))
+          leading_escape_code = working_self[0..end_of_escape_code]
+          breakout_array << leading_escape_code
+          working_self = working_self[(end_of_escape_code + 1)..-1]
+        else
+          leading_character = working_self[0]
+          breakout_array << leading_character
+          working_self = working_self[1..-1]
+        end
+      end
+
+      breakout_array
+    end
+
+    def is_ansi_escape_code?
+      (self =~ /^\e\[[\d\;]*m$/) == 0
+    end
+
+    ## Returns the indexed character of the real string, determined by the index
+    ##   given in reference to its ANSIless display form. e.g.:
+    ##     > s = "\e[31mTEST\e[00m"
+    ##     > puts s
+    ##       TEST
+    ##     > s.ansiless_pick(1) = 'y'
+    ##     > s
+    ##       => "\e[31mTyST\e[00m"
+    def ansiless_pick(given_index)
+      ansiless_self = self.ansiless
+
+      return nil if ansiless_self[given_index].nil?
+
+      given_index = (given_index + ansiless_self.length) if given_index.negative?
+
+      mock_index = 0 # A scanning index that *doesn't* count ANSI codes
+      real_index = 0 # A scanning index that *does* count ANSI codes
+
+      ansi_string_array = ansi_string_breakout
+
+      until mock_index == given_index
+        while ansi_string_array.first.is_ansi_escape_code?
+          real_index += (ansi_string_array.shift.length)
+        end
+
+        ansi_string_array.shift
+
+        while ansi_string_array.first.is_ansi_escape_code?
+          real_index += (ansi_string_array.shift.length)
+        end
+
+        mock_index += 1
+        real_index += 1
+      end
+
+      self[real_index]
+    end
+
+    ## Like ansiless_pick, but it can set that found string character instead
+    def ansiless_set!(given_index, string)
+      raise ArgumentError, 'First argument must be an Integer' unless given_index.is_a?(Integer)
+      raise ArgumentError, 'Second argument must be a String'  unless string.is_a?(String)
+
+      ansiless_self = self.ansiless
+
+      return nil if ansiless_self[given_index].nil?
+
+      given_index = (given_index + ansiless_self.length) if given_index.negative?
+
+
+      new_string = string.to_s
+
+      mock_index = 0 # A scanning index that *doesn't* count ANSI codes
+      real_index = 0 # A scanning index that *does* count ANSI codes
+
+      ansi_string_array = ansi_string_breakout
+
+      until mock_index == given_index
+        while ansi_string_array.first.is_ansi_escape_code?
+          real_index += (ansi_string_array.shift.length)
+        end
+
+        ansi_string_array.shift
+
+        while ansi_string_array.first.is_ansi_escape_code?
+          real_index += (ansi_string_array.shift.length)
+        end
+
+        mock_index += 1
+        real_index += 1
+      end
+
+      self[real_index] = new_string
+    end
+
+    def ansi_slice(arg1, arg2 = nil) # i.e. like 'test'[0..2] and 'test'[2, 1]
+      unless (arg1.is_a?(Range)   && arg2.nil?) ||
+             (arg1.is_a?(Integer) && arg2.is_a?(Integer))
+      raise ArgumentError, 'ansi_slice takes either a single Range ' \
+        'or two integers (index and length) as its arguments.'
+      end
+
+      target_range = arg1.is_a?(Range) ? arg1 : (arg1...(arg1 + arg2))
+
+      if target_range.min.negative? || target_range.max.negative?
+        raise ArgumentError, 'Range must be entirely positive!'
+      end
+
+      args = [arg1, arg2].compact
+      return self[*args] if (self =~ /\e\[[\d\;]*m/).nil? # No work need be done
+
+      ## And here we match the normal `:[]` behavior outside of boundaries, e.g:
+      ##   irb> 'TEST'[4..9]
+      ##   => ""
+      ##   irb> 'TEST'[5..9]
+      ##   => nil
+      return nil if target_range.min > self.ansiless_length
+
+      mock_index = 0 # A scanning index that *doesn't* count ANSI codes
+      result_string_array = []
+
+      ansi_string_breakout.each do |char|
+        char_is_ansi_escape_code = char.is_ansi_escape_code?
+        within_target_range =
+          target_range.include?(mock_index)
+
+        if within_target_range || char_is_ansi_escape_code
+          result_string_array << char
+        end
+
+        mock_index += 1 unless char_is_ansi_escape_code
+      end
+
+      result_string_array.join('')
+    end
   end
 end