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)

🔮 Scryglass Intro Summary

• ⚡️ tl;dr SUPER Quick Start
• Installing Scryglass
• Enabling Scryglass
• Launching a Scry Session
• Basic Usage
• Reading the UI
  • Tree View (default) Row Sample Strings
  • Known Enumerables
  • The Cursor, and Unknown Enumerables
  • Waiting!
• In-Depth Control Rundown
• Configuration / Customization (all optional)
  • A Note on Adding Your Own Lenses
  • Controlling How Some Objects Are Displayed in Tree View / Using Scryglass as the UI for Another Tool
• Miscellaneous Troubleshooting Notes
• Contributing

If you're in a real hurry to get your hands in it (though not necessarily in the most efficient way), here are the quickest steps!

Add the following, with whatever version specifics you like, to your Gemfile, if you use Bundler:

gem 'scryglass'

And then execute:

$ bundle install

If you don't have a Gemfile, you can simply install from RubyGems:

$ gem install 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):

Scryglass.load

...Which will print the success or failure of loading Scryglass, along with a note of which file loaded it, or

Scryglass.load_silently

...Which will never print anything upon loading the tool.

And then you're good to go – the syntax is loaded!

In console (Ruby||Rails), you can get some help information with Scryglass.help. Among other things, it will tell you:

[...]

To start a Scry Session, call:
>   scry my_object   OR
>   my_object.scry

[...]

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] })).

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.

Every object (or key-value pair) is one row. Nested objects will be displayed under their parent object, with one more layer of indentation. The cursor will generally look like a horizontal line.

This default view is the Tree View. You can seitch between that and Lens View with SPACEBAR.

Each row has either an object or a key-value pair. The objects are given a sample representation in the Tree View using inspect, and long ones are cut off and marked with '……'. For display purposes, newlines ("\n") are removed from these strings, but remain untouched on the object, including in Lens View.

If the object (or the value in a key-value pair) is one of the known Enumerable types, it will display with one of the following wrappers:

The known Enumerable will also indicate its state:

However, some objects (both known and unknown Enumerable types) have sub-items that can be calculated and opened on the spot.

The cursor, movable by arrow keys, is represented by a straight line (––––). It may overlap with a selection marker (->), if the current row is also a selected row. The left two characters of the cursor serve as gentle indicators of how objects of an unknown Enumerable type might be opened:

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.

Scryglass has two features to make wait time a little easier:

• 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.

Scry is (optionally) configured with a configure method on the Scryglass module, allowing you to overwrite default attributes of the Config object, like so:

Scryglass.configure do |config|
  config.tab_length = 3
  # config... etc
end

This can be placed in any loaded path of your system, including .irbrc and .pryrc, or directly into the ruby||rails console itself to quickly experiment with settings. But the ideal place for it in an application is likely your own config/initializers/scryglass.rb or config/scryglass.rb.

Here is a commented-out config file template (you can uncomment and alter things as you wish):
(Found in example_config.rb)

Scryglass.configure do |config|
  ## Display
  # config.tab_length = 2 # Default: 2
  # config.tree_view_key_string_clip_length = 200 # Default: 200
  # config.tree_view_value_string_clip_length = 500 # Default: 500
  # config.dot_coloring = true # Default: true

  ## 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) { 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',
  #     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
  # config.include_scoped_associations = false # Default: false
  # config.show_association_types = true # Default: true
end

If you ever wish to restore the "factory" default config settings for a particular console session, you can run:

Scryglass.reset_config

Here are some explanations of some less obvious configurations:
show_association_types, when true, will show association types indicators:
(HM) : has_many
(HO) : has_one
(BT) : belongs_to

(t) : :through (if through relations are enabled)
(s) : scoped (if scoped relations are enabled)

For properly capturing output methods of various kinds, and for the ability to truncate strings of cosmic scale before they've been entirely printed to the invisible IO (can be minutes and trillions of characters), we highly recommend using the Hexes.capture_io method with the char_limit: keyword argument as seen in the template config file (and Scryglass code). capture_io captures console output as a string; char_limit: will run the capture in a separate thread which can be truncated before it finishes printing.

Scryglass originally started as a small subtool to be used as the UI for another console project, which, in short, would output a large branching hash which was then to be navigated. To have more control over the tree panel display, you can wrap objects in a Scryglass::ViewWrapper. For example, by default, this array item: [unsightly_object] will appear in the tree view in its inspected form, "#UnsightlyObject:0x00007f9ac8224e78". But say you want it to show it's best face to the user, using the sightly return of it's best_face method. You can instead hand scryglass the following item:

Scryglass::ViewWrapper.new(unsightly_object,
                           string: unsightly_object.best_face)

Scryglass will use the original object as usual in every way, except the tree view will display it according to your nicer string:

[
  Unsightly Object (id:55)

This can be used for "key" objects in your hashes just as easily. For example, Scryglass itself, when generating instance variable subitems, uses the following ViewWrapper to make them display a little more naturally, without the colon:

iv_key = Scryglass::ViewWrapper.new(iv_name,
                                    string: iv_name.to_s) # to_s removes ':'

So

:@attributes : {...}

becomes, just in the tree view:

@attributes : {...}

And if it's useful, a string_lambda: argument can be passed instead, and the string will be generated once from the lambda, in context, when the session is first built.

If you ever use the search function ('/'), press enter, and the only thing that happens is you add a '^M' to your entry text: Go back to your shell and run:

$ stty sane

Or you can try from your ruby console:

system('stty sane')

And that should do the trick.

Scryglass is being released as a relatively mature piece of software, with smaller improvements to be made over time. As such, we're not looking for contributors at the moment. However:

• Please feel free to use a fork and modify it to your heart's content!
• Please feel free to open a github issue for any problems you run into, or any ideas for possible improvements!