PrettyDump

NAME

PrettyDump - represent a Raku data structure in a human readable way

SYNOPSIS

Use it in the OO fashion:

use PrettyDump;
	my $pretty = PrettyDump.new:
		after-opening-brace => True
		;

my $raku = { a => 1 };
	say $pretty.dump: $raku; # '{:a(1)}'

Or, use its subroutine:

use PrettyDump;

my $ds = { a => 1 };

say pretty-dump( $ds );

# setting are named arguments
	say pretty-dump( $ds
		:indent("\t")
		);

Or, a shorter shortcut that dumps and outputs to standard output:

use PrettyDump;

my $ds = { a => 1 };
	pd $ds;

DESCRIPTION

This module creates nicely formatted representations of your data structure for your viewing pleasure. It does not create valid Raku code and is not a serialization tool.

When .dump encounters an object in your data structure, it first checks for a .PrettyDump method. It that exists, it uses it to stringify that object. Otherwise, .dump looks for internal methods. So far, this module handles these types internally:

* List
* Array
* Pair
* Map
* Hash
* Match

Custom dump methods

If you define a .PrettyDump method in your class, .dump will call that when it encounters an object in that class. The first argument to .PrettyDump is the dumper object, so you have access to some things in that class:

class Butterfly {
		has $.genus;
		has $.species;

method PrettyDump ( PrettyDump $pretty, Int:D :$depth = 0 ) {
			"_{$.genus} {$.species}_";
			}
		}

The second argument is the level of indentation so far. If you want to dump other objects that your object contains, you should call .dump again and pass it the value of $depth+1 as it's second argument:

class Butterfly {
		has $.genus;
		has $.species;
		has $.some-other-object;

method PrettyDump ( PrettyDump $pretty, Int:D :$depth = 0 ) {
			"_{$.genus} {$.species}_" ~
			$pretty.dump: $some-other-object, $depth + 1;
			}
		}

You can add a PrettyDump method to an object with but role:

use PrettyDump;

my $pretty = PrettyDump.new;

my Int $a = 137;
	put $pretty.dump: $a;

my $b = $a but role {
		method PrettyDump ( PrettyDump:D $pretty, Int:D :$depth = 0 ) {
			"({self.^name}) {self}";
			}
		};
	put $pretty.dump: $b;

This outputs:

137
	(Int+{<anon|140644552324304>}) 137

Per-object dump handlers

You can add custom handlers to your PrettyDump object. Once added, the object will try to use a handler first. This means that you can override builtin methods.

$pretty = PrettyDump.new: ... ;
	$pretty.add-handler: "SomeTypeNameStr", $code-thingy;

The code signature for $code-thingy must be:

(PrettyDump $pretty, $ds, Int:D :$depth = 0 --> Str)

Once you are done with the per-object handler, you can remove it:

$pretty.remove-handler: "SomeTypeNameStr";

This allows you to temporarily override a builtin method. You might want to mute a particular object, for instance.

You can completely ignore a type as if it's not even there. It's a wrapper around g that supplies the code for you.

$pretty.ignore-type: SomeType;

This works by returning a Str type object instead of a defined string. If the type you want to exclude is at the top of the data structure, you'll get back a type object. But why are you dumpng something you want to ignore?

Formatting and Configuration

You can set some tidy-like settings to control how .dump will present the data stucture:

debug

Output debugging info to watch the module walk the data structure.

indent

The default is a tab.

intra-group-spacing

The spacing inserted inside (empty) ${} and $[] constructs. The default is the empty string.

pre-item-spacing

The spacing inserted just after the opening brace or bracket of non-empty ${} and $[] constructs. The default is a newline.

post-item-spacing

The spacing inserted just before the close brace or bracket of non-empty ${} and $[] constructs. The default is a newline.

pre-separator-spacing

The spacing inserted just before the comma separator of non-empty ${} and $[] constructs. The default is the empty string.

post-separator-spacing

The spacing inserted just after the comma separator of non-empty ${} and $[] constructs. Defaults to a newline.

AUTHOR

brian d foy, < <[email protected]> >.

This module started as Pretty::Printer from Jeff Goff, which you can find at https://github.com/drforr/perl6-pp

Parts of this module were supported by a grant from the Perl Foundation.

SOURCE

The repository for this source is in GitHub at https://github.com/briandfoy/raku-PrettyDump

COPYRIGHT

LICENSE

This module is available under the Artistic License 2.0. A copy of this license should have come with this distribution in the LICENSE file.