Add hook for customizing the debug representation of an object

[amomchilov]

This PR depends on the changes in #1004. Only this last commit of this PR is unique to this change.

Description

I propose we add a hook method that developers can implement in their classes to customize the structural representation of their objects in a debugger. Used judiciously, this has the potential to really improve the clarify of certain types of objects.

I found it particularly useful for container-like objects, like OpenStruct and ActionController::StrongParameters.

Before	After

example.rb

require'ostruct'require'action_controller'classOpenStruct# Use our hash representation directly, to hide the `@table` clutter.defdebug_representation=to_hendclassActionController::Parameters# Flatten the parameters right into the top level of this object's representation.defdebug_representation{:@permitted=>@permitted,:@logging_context=>@logging_context,
**@parameters}endendline=OpenStruct.new(start_point: OpenStruct.new(x: 1,y: 2),end_point: OpenStruct.new(x: 3,y: 4),)params=ActionController::Parameters.new({person: {name: "Francesco",age: 22,role: "admin"}})

I chose the spelling #debug_representation, because it's clear and to-the-point, but it's open to ideas.

[amomchilov]

Perhaps it should take unused rest args, in case any need to be added in the future?

Suggested change

	defdebug_representation
	defdebug_representation(*, **)

[jabamaus]

A big +1 for this feature. This would be great. Surprised this wasn't in from the start. Being able to control what's on the debug inspector without overloading to_s and inspect (which may be needed for something else) seems like a very sensible idea.

When are some of these PRs going to get applied? It's been quiet the last few months...

[ko1]

Could you give us the API specification?

[jabamaus]

I'm not sure what the content of this PR exactly is but what I'd simply like is the ability to define a method on my objects called something like "to_rdbg" (or something I don't really mind) and have rdbg call that preferentially to to_s/inspect. In this way I could have to_s/inspect freed up for just my use and control over what appears in the debug window.

[amomchilov]

@jabamaus@ko1 Ignore the first few commits that come from other branches. This is the relevant commit to this PR: 8942797

@ko1 The API is really simple: If your object responds to #debug_representation, the debugger will call it and use the result as the representation of your object.

Look closely at the PR description, I put an example.rb that shows an examples for OpenStruct and ActionController::Parameters.

[jabamaus]

Thanks @amomchilov that makes it easier to follow. What will happen if the object being inspected is a BasicObect? BasicObject does not implement respond_to?

[amomchilov]

@jabamaus Please have a look at the implementation. It always uses the Kernel implementation of respond_to?, so that it works even on BasicObject, or any objects with a bad override of #respond_to?.

[ko1]

@ko1 The API is really simple: If your object responds to #debug_representation, the debugger will call it and use the result as the representation of your object.

Could you explain the specification of #debug_representation?

[cloudbees-smart-tests]

✅ All Tests passed!

✖️no tests failed ✔️669 tests passed(1 flake)