txt: ## dist_zef-raku-community-modules-PrettyDump.md
  [![Actions Status](https://github.com/raku-community-modules/PrettyDump/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/PrettyDump/actions) [![Actions Status](https://github.com/raku-community-modules/PrettyDump/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/PrettyDump/actions) [![Actions Status](https://github.com/raku-community-modules/PrettyDump/actions/workflows/windows.yml/badge.svg)](https://github.com/raku-community-modules/PrettyDump/actions)
  
  # 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;
  
  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 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.
  
  # AUTHORS
  
  * brian d foy
  * Raku Community
  
  This module started as `Pretty::Printer` from Jeff Goff.
  
  Parts of this module were supported by a grant from TPRF.
  
  # COPYRIGHT
  
  Copyright © 2017-2021, brian d foy
  
  Copyright © 2024 Raku Community
  
  # 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.
  