.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Data::Dumper::Compact 3pm" .TH Data::Dumper::Compact 3pm "2020-06-13" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Data::Dumper::Compact \- Vertically compact width\-limited data formatter .SH "SYNOPSIS" .IX Header "SYNOPSIS" Basic usage as a function: .PP .Vb 1 \& use Data::Dumper::Compact \*(Aqddc\*(Aq; \& \& warn ddc($some_data_structure); \& \& warn ddc($some_data_structure, \e%options); .Ve .PP Slightly more clever usage as a function: .PP .Vb 1 \& use Data::Dumper::Compact ddc => \e%default_options; \& \& warn ddc($some_data_structure); \& \& warn ddc($some_data_structure, \e%extra_options); .Ve .PP \&\s-1OO\s0 usage: .PP .Vb 1 \& use Data::Dumper::Compact; \& \& warn Data::Dumper::Compact\->dump($data, \e%options); \& \& my $ddc = Data::Dumper::Compact\->new(\e%options); \& \& warn $ddc\->dump($data); \& \& warn $ddc\->dump($data, \e%extra_options); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Data::Dumper::Compact, henceforth referred to as \s-1DDC,\s0 was born because I was annoyed at valuable wasted whitespace paging through both Data::Dumper and Data::Dump based logs \- Data::Dump attempts to format horizontally first, but then if it fails, immediately switches to formatting fully vertically, rather than trying to e.g. format a six element arrayref three per line. .PP So here's a few of the specifics (noting that all examples unless otherwise specified are dumped with default options): .SS "Arrays and Strings" .IX Subsection "Arrays and Strings" Given arrays consisting of reasonably long strings, \s-1DDC\s0 does its best to produce a sane representation within its \*(L"max_width\*(R": .PP .Vb 10 \& [ \& 1, 2, [ \& \*(Aqlongstringislonglongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislong\*(Aq, \*(Aqlongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislong\*(Aq, \*(Aqlongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislong\*(Aq, \*(Aqlongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislong\*(Aq, \*(Aqlongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislong\*(Aq, \*(Aqlongstringislong\*(Aq, \& \*(Aqlongstringislong\*(Aq, \*(Aqlongstringislonglongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislong\*(Aq, \*(Aqlongstringislong\*(Aq, \*(Aqlongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislong\*(Aq, \*(Aqa\*(Aq, \*(Aqb\*(Aq, \*(Aqc\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislonglongstringislong\*(Aq, \& \*(Aqlongstringislonglongstringislonglongstringislonglongstringislong\*(Aq, \& ], 3, \& ] .Ve .SS "Keys and Hashrefs" .IX Subsection "Keys and Hashrefs" When faced with a \f(CW\*(C`\-foo\*(C'\fR style value, it gets a \f(CW\*(C`=>\*(C'\fR even in an array, and hash values that we can are single-line formatted: .PP .Vb 7 \& [ \& \*(Aqaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\*(Aq, [ \& \*(Aqbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\*(Aq, \& \*(Aqcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\*(Aq, \& ], \& \-blah => { baz => \*(Aqquux\*(Aq, foo => \*(Aqbar\*(Aq }, \& ] .Ve .SS "The String Thing" .IX Subsection "The String Thing" Strings are single quoted when \s-1DDC\s0 is absolutely sure that's safe, and double quoted otherwise: .PP .Vb 5 \& [ { \-foo => { \& bar => \& \*(Aqaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\*(Aq, \& baz => "bbbbbbbbbbbbbbbbbbbb\enbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", \& } } ] .Ve .SS "Lonely hash key" .IX Subsection "Lonely hash key" When a single hash key can't be formatted in a oneline form within the length, \s-1DDC\s0 will try spilling it to its own line: .PP .Vb 3 \& { \& \-xxxxxxxxxxxxx => \*(Aqaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\*(Aq \& } .Ve .PP If even that isn't enough, it formats it below and indented: .PP .Vb 3 \& { \-xxxxxxxxxxxxx => \& \*(Aqaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\*(Aq \& } .Ve .SS "Strings and the dot operator" .IX Subsection "Strings and the dot operator" If a string simply won't fit, \s-1DDC\s0 splits it and indents it using \f(CW\*(C`.\*(C'\fR: .PP .Vb 5 \& [ \*(Aqxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyx\*(Aq \& .\*(Aqyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxy\*(Aq \& .\*(Aqxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxyx\*(Aq \& .\*(Aqyxyxyxyxyxyxyxyxyxyxyxyxyxyxyxy\*(Aq \& ] .Ve .SS "Unknown unknowns" .IX Subsection "Unknown unknowns" Anything \s-1DDC\s0 doesn't understand is passed through its \*(L"dumper\*(R" option, though since Data::Dumper (at the time of writing) forgets to pass through its indentation level to B::Concise, we slightly tweak that behaviour on the way in for the default \*(L"dumper\*(R". But the end result looks like: .PP .Vb 6 \& { foo => { bar => sub { \& use warnings; \& use strict \*(Aqrefs\*(Aq; \& my($x, $y) = @_; \& return $x * $y; \& } } } .Ve .SS "Bless you" .IX Subsection "Bless you" When encountering an object, if it's a blessed array or hashref, \s-1DDC\s0 will attempt to format that too: .PP .Vb 5 \& [ bless( { \& x => 3, \& y => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq, \*(Aqquux\*(Aq, \*(Aqfleem\*(Aq, \*(Aqblather\*(Aq, \*(Aqobrien\*(Aq ], \& z => \*(Aqlololololololololololololololol\*(Aq, \& }, "OhGods::Lol" ) ] .Ve .SS "All together now" .IX Subsection "All together now" The full set of behaviours allows compact (and, we hope, readable) versions of complex data structures. To provide one of the examples that expired this module \- here is the formatting under standard options for a moderately complex SQL::Abstract update statement: .PP .Vb 10 \& { \& _ => [ \& \*(Aqtree_table\*(Aq, \-join => { \& as => \*(Aqtree\*(Aq, \& on => { \*(Aqtree.id\*(Aq => \*(Aqtree_with_path.id\*(Aq }, \& to => { \-select => { \& from => \*(Aqtree_with_path\*(Aq, \& select => \*(Aq*\*(Aq, \& with_recursive => [ \& [ \*(Aqtree_with_path\*(Aq, \*(Aqid\*(Aq, \*(Aqparent_id\*(Aq, \*(Aqpath\*(Aq ], { \-select => { \& _ => [ \& \*(Aqid\*(Aq, \*(Aqparent_id\*(Aq, { \-as => \& [ \& { \-cast => { \-as => [ \*(Aqid\*(Aq, \*(Aqchar\*(Aq, 255 ] } }, \& \*(Aqpath\*(Aq, \& ] \& }, \& ], \& from => \*(Aqtree_table\*(Aq, \& union_all => { \-select => { \& _ => [ \& \*(Aqt.id\*(Aq, \*(Aqt.parent_id\*(Aq, { \-as => [ \& { \-concat => [ \*(Aqr.path\*(Aq, \e"\*(Aq/\*(Aq", \*(Aqt.id\*(Aq ] }, \& \*(Aqpath\*(Aq, \& ] }, \& ], \& from => [ \& \*(Aqtree_table\*(Aq, \-as => \*(Aqt\*(Aq, \-join => { \& as => \*(Aqr\*(Aq, \& on => { \*(Aqt.parent_id\*(Aq => \*(Aqr.id\*(Aq }, \& to => \*(Aqtree_with_path\*(Aq, \& }, \& ], \& } }, \& where => { parent_id => undef }, \& } }, \& ], \& } }, \& }, \& ], \& set => { path => { \-ident => [ \*(Aqtree\*(Aq, \*(Aqpath\*(Aq ] } }, \& } .Ve .PP And the version (generated by setting \*(L"max_width\*(R" to \f(CW40\fR) that runs out of space and thereby forces the \*(L"spill vertically\*(R" logic to kick in while still attemping to be at least somewhat compact: .PP .Vb 10 \& { \& _ => [ \& \*(Aqtree_table\*(Aq, \& \*(Aq\-join\*(Aq, \& { \& as => \*(Aqtree\*(Aq, \& on => { \& \*(Aqtree.id\*(Aq => \*(Aqtree_with_path.id\*(Aq, \& }, \& to => { \& \-select => { \& from => \*(Aqtree_with_path\*(Aq, \& select => \*(Aq*\*(Aq, \& with_recursive => [ \& [ \& \*(Aqtree_with_path\*(Aq, \& \*(Aqid\*(Aq, \& \*(Aqparent_id\*(Aq, \& \*(Aqpath\*(Aq, \& ], \& { \& \-select => { \& _ => [ \& \*(Aqid\*(Aq, \& \*(Aqparent_id\*(Aq, \& { \& \-as => [ \& { \& \-cast => { \& \-as => [ \& \*(Aqid\*(Aq, \& \*(Aqchar\*(Aq, \& 255, \& ], \& }, \& }, \& \*(Aqpath\*(Aq, \& ], \& }, \& ], \& from => \*(Aqtree_table\*(Aq, \& union_all => { \& \-select => { \& _ => [ \& \*(Aqt.id\*(Aq, \& \*(Aqt.parent_id\*(Aq, \& { \& \-as => [ \& { \& \-concat => [ \& \*(Aqr.path\*(Aq, \& \e"\*(Aq/\*(Aq", \& \*(Aqt.id\*(Aq, \& ], \& }, \& \*(Aqpath\*(Aq, \& ], \& }, \& ], \& from => [ \& \*(Aqtree_table\*(Aq, \& \*(Aq\-as\*(Aq, \& \*(Aqt\*(Aq, \& \*(Aq\-join\*(Aq, \& { \& as => \*(Aqr\*(Aq, \& on => { \& \*(Aqt.parent_id\*(Aq => \*(Aqr.id\*(Aq, \& }, \& to => \*(Aqtree_with_path\*(Aq, \& }, \& ], \& }, \& }, \& where => { \& parent_id => undef, \& }, \& }, \& }, \& ], \& }, \& }, \& }, \& ], \& set => { \& path => { \& \-ident => [ \& \*(Aqtree\*(Aq, \& \*(Aqpath\*(Aq, \& ], \& }, \& }, \& } .Ve .SS "Summary" .IX Subsection "Summary" Hopefully it's clear what the goal is, and what we've done to achieve it. .PP While the system is already somewhat configurable, further options are almost certainly implementable, although if you really want such an option then we expect you to turn up with documentation and test cases for it so we just have to write the code. .SH "OPTIONS" .IX Header "OPTIONS" .SS "max_width" .IX Subsection "max_width" Represents the width that \s-1DDC\s0 will attempt to keep as the maximum (if something overflows it in spite of our best efforts, \s-1DDC\s0 will fall back to a more vertically sprawling format to at least overflow as little as feasible). .PP Default: \f(CW78\fR .SS "indent_by" .IX Subsection "indent_by" The string to indent by. To set e.g. 4 space indent, pass \f(CW\*(C`\*(Aq \*(Aqx4\*(C'\fR. .PP Default: \f(CW\*(Aq \*(Aq\fR (two spaces). .SS "indent_width" .IX Subsection "indent_width" How many characters one indent should be considered to be. Generally you only need to manually set this if your \*(L"indent_by\*(R" is \f(CW"\et"\fR. .PP Default: \f(CW\*(C`length($self\->indent_by)\*(C'\fR .SS "transforms" .IX Subsection "transforms" Set of transforms to apply on every \*(L"dump\*(R" operation. See \*(L"transform\*(R" for more information. .PP Default: \f(CW\*(C`[]\*(C'\fR .SS "dumper" .IX Subsection "dumper" The dumper function to be used for dumping things \s-1DDC\s0 doesn't understand, such as coderefs, regexprefs, etc. .PP Defaults to the same options as Data::Dumper::Concise (which is, itself, only a Data::Dumper configuration albeit it comes with Devel::Dwarn which is rather more interesting) \- although on top of that we add a little bit of extra cleverness to make B::Deparse use the correct indentation, since for some reason Data::Dumper doesn't (at the time of writing) do that. .PP If you supply it yourself, it needs to be a single argument coderef \- you could for example use \f(CW\*(C`\e&Data::Dumper::Dumper\*(C'\fR though that would almost certainly be pointless. .SH "EXPORTS" .IX Header "EXPORTS" .SS "ddc" .IX Subsection "ddc" .Vb 2 \& use Data::Dumper::Compact \*(Aqddc\*(Aq; \& use Data::Dumper::Compact \*(Aqddc\*(Aq => \e%options; .Ve .PP If the first argument to \f(CW\*(C`use\*(C'\fR/\f(CW\*(C`import()\*(C'\fR is 'ddc', a subroutine \f(CW\*(C`ddc()\*(C'\fR is installed in the calling package which behaves like calling \*(L"dump\*(R". .PP If the second argument is a hashref, it becomes the options passed to \*(L"new\*(R". .PP This feature is effectively sugar over \*(L"dump_cb\*(R", in that: .PP .Vb 1 \& Data::Dumper::Compact\->import(ddc => \e%options) .Ve .PP is equivalent to: .PP .Vb 1 \& *ddc = Data::Dumper::Compact\->new(\e%options)\->dump_cb; .Ve .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 3 \& my $ddc = Data::Dumper::Compact\->new; \& my $ddc = Data::Dumper::Compact\->new(%options); \& my $ddc = Data::Dumper::Compact\->new(\e%options); .Ve .PP Constructor. Takes a hash or hashref of \*(L"\s-1OPTIONS\*(R"\s0 .SS "dump" .IX Subsection "dump" .Vb 1 \& my $formatted = Data::Dumper::Compact\->dump($data, \e%options?); \& \& my $formatted = $ddc\->dump($data, \e%merge_options?); .Ve .PP This is the method you're going to want to call most of the time, and ties together the rest of the functionality into a single data-structure-to-string bundle. With just a data argument, it's equivalent to: .PP .Vb 1 \& $ddc\->format( $ddc\->transform( $ddc\->transforms, $ddc\->expand($data) ); .Ve .PP In class method form, options provided are passed to \*(L"new\*(R"; in instance method form, options if provided are merged into \f(CW$ddc\fR just for this invocation. .SS "dump_cb" .IX Subsection "dump_cb" .Vb 1 \& my $cb = $ddc\->dump_cb; .Ve .PP Returns a subroutine reference that's a curried call to \*(L"dump\*(R": .PP .Vb 1 \& $cb\->($data, \e%extra_options); # equivalent to $ddc\->dump(...) .Ve .PP Mostly useful for if you want to create a custom \f(CW\*(C`ddc()\*(C'\fR like thing: .PP .Vb 2 \& use Data::Dumper::Compact; \& BEGIN { *Dumper = Data::Dumper::Compact\->new\->dump_cb } .Ve .SS "expand" .IX Subsection "expand" .Vb 1 \& my $exp = $ddc\->expand($data); .Ve .PP Expands a data structure to \s-1DDC\s0 tagged data. The result is, recursively, .PP .Vb 1 \& [ $type, $payload ] .Ve .PP where if \f(CW$type\fR is one of \f(CW\*(C`string\*(C'\fR, \f(CW\*(C`key\*(C'\fR, or \f(CW\*(C`thing\*(C'\fR, the payload is a simple string (\f(CW\*(C`thing\*(C'\fR meaning something unknown and therefore delegated to \&\*(L"dumper\*(R"). If the type is an array: .PP .Vb 1 \& [ array => \e@values ] .Ve .PP and if the type is a hash: .PP .Vb 1 \& [ hash => [ \e@keys, \e%value_map ] ] .Ve .PP where the keys provide an order for formatting, and the value map is a hashref of keys to expanded values. .PP A plain string becomes a \f(CW\*(C`string\*(C'\fR, unless it fits the \f(CW\*(C`\-foo\*(C'\fR style pattern that autoquotes, in which case it becomes a \f(CW\*(C`key\*(C'\fR. .SS "add_transform" .IX Subsection "add_transform" .Vb 2 \& $ddc\->add_transform(sub { ... }); \& $ddc\->add_transform({ hash => sub { ... }, _ => sub { ... }); .Ve .PP Appends a transform to \f(CW\*(C`$ddc\->transforms\*(C'\fR, see \*(L"transform\*(R" for behaviour. .PP Returns \f(CW$ddc\fR to enable chaining. .SS "transform" .IX Subsection "transform" .Vb 1 \& my $tf_exp = $ddc\->transform($tfspec, $exp); .Ve .PP Takes a transform specification and expanded tagged data and returns the transformed expanded expression. A transform spec is an arrayref containing transforms, where each transform is applied in order, so the last transform added via \*(L"add_transform\*(R" will be the last one to transform the data (each transform will consist of a datastructure representing which parts of the \&\f(CW$exp\fR tree it should be called for, plus subroutines representing the relevant transforms). .PP Transform subroutines are called as a method on the \f(CW$ddc\fR with the arguments of \f(CW\*(C`$type, $payload, $path\*(C'\fR where \f(CW$path\fR is an arrayref of the keys/values of the containing hashes and arrays, aggregated as \s-1DDC\s0 descends through the \f(CW$exp\fR tree. .PP Each transform is expected to return either nothing, to indicate it doesn't wish to modify the result, or a replacement expanded data structure. The simplest form of transform is a subref, which gets called for everything. .PP So, to add ' \s-1IN MICE\s0' to every string that's part of an array under a hash key called study_results, i.e.: .PP .Vb 4 \& my $data = { study_results => [ \& \*(AqSense Of Touch Is Formed In the Brain Before Birth\*(Aq. \& "We can\*(Aqt currently cure MS but a single cell could change that", \& ] }; \& \& my $tf_exp = $ddc\->transform([ sub { \& my ($self, $type, $payload, $path) = @_; \& return unless $type eq \*(Aqstring\*(Aq and ($path\->[\-2]||\*(Aq\*(Aq) eq \*(Aqstudy_results\*(Aq; \& return [ $type, $payload.\*(Aq IN MICE\*(Aq ]; \& } ], $ddc\->expand($data)); .Ve .PP will return: .PP .Vb 7 \& [ hash => [ \& [ \*(Aqstudy_results\*(Aq ], \& { study_results => [ array => [ \& [ string => \*(AqSense Of Touch Is Formed In the Brain Before Birth IN MICE\*(Aq ], \& [ string => "We can\*(Aqt currently cure MS but a single cell could change that IN MICE", ], \& ] ] } \& ] ] .Ve .PP If a hashref is found, then the values are expected to be transforms, and \&\s-1DDC\s0 will use \f(CW\*(C`$hashref\->{$type}||$hashref\->{_}\*(C'\fR as the transform, or skip if neither is present. So the previous example could be written as: .PP .Vb 5 \& $ddc\->transform([ { string => sub { \& my ($self, $type, $payload, $path) = @_; \& return unless ($path\->[\-2]||\*(Aq\*(Aq) eq \*(Aqstudy_results\*(Aq; \& return [ $type, $payload.\*(Aq IN MICE\*(Aq ]; \& } } ], $ddc\->expand($data)); .Ve .PP If the value of the spec entry itself \fIor\fR the relevant hash value is an arrayref, it is assumed to contain a spec for trailing path entries, with the last element being the transform subroutine. A path entry match can be an exact scalar (tested via \f(CW\*(C`eq\*(C'\fR since it works fine for both strings and integer array indices), regexp, \f(CW\*(C`undef\*(C'\fR to indicate \*(L"any value is fine here\*(R", or a subroutine which will be called with the path entry as both \f(CW$_[0]\fR and \&\f(CW$_\fR. So the example we've been using could \fBalso\fR be written as: .PP .Vb 4 \& $ddc\->transform([ { string => [ \& \*(Aqstudy_results\*(Aq, undef, \& sub { [ string => $_[2].\*(Aq IN MICE\*(Aq ] } \& ] } ], $ddc\->expand($data)); .Ve .PP or .PP .Vb 4 \& $ddc\->transform([ { string => [ \& qr/^study_results$/, sub { 1 }, \& sub { [ string => $_[2].\*(Aq IN MICE\*(Aq ] } \& ] } ], $ddc\->expand($data)); .Ve .PP Note that while the \f(CW$tfspec\fR is not passed to transform subroutines, for the duration of the \*(L"transform\*(R" call the \*(L"transforms\*(R" option is localised to the provided routine, so .PP .Vb 5 \& sub { \& my ($self, $type, $payload, $path) = @_; \& my $tfspec = $self\->transforms; \& ... \& } .Ve .PP will return the top level \f(CW$tfspec\fR passed to the transform call. .PP Thanks to for the inspiration. .SS "format" .IX Subsection "format" .Vb 1 \& my $formatted = $ddc\->format($exp); .Ve .PP Takes expanded tagged data and renders it to a formatted string, suitable for printing or warning or etc. .PP Accepts the following type tags: \f(CW\*(C`array\*(C'\fR, \f(CW\*(C`list\*(C'\fR, \f(CW\*(C`hash\*(C'\fR, \f(CW\*(C`key\*(C'\fR, \&\f(CW\*(C`string\*(C'\fR, \f(CW\*(C`thing\*(C'\fR. Arrays and hashes are formatted as compactly as possible within the constraint of \*(L"max_width\*(R", but if overflow occurs then \s-1DDC\s0 falls back to spilling everything vertically, so newlines are used for most spacing and therefore it doesn't exceed the max width any more than strictly necessary. .PP Strings are formatted as single quote if obvious, and double quote if not. .PP Keys are treated as strings when present as hash values, but when an element of array values, are formatted ask \f(CW\*(C`the_key =>\*(C'\fR where possible. .PP Lists are formatted as single line \f(CW\*(C`qw()\*(C'\fR expressions if possible, or \&\f(CW\*(C`( ... )\*(C'\fR if not. .PP Arrays and hashes are formatted in the manner to which one would hope readers are accustomed, except more compact. .SH "ALGORITHM" .IX Header "ALGORITHM" The following is a description of the current algorithm of \s-1DDC.\s0 We reserve the right to change it for the better. .PP If you didn't already read the overview examples in \*(L"\s-1WHY\*(R"\s0 do that first. .PP Vertical mode means \s-1DDC\s0 has given up on fitting within the desired width and is now just trying to not use \fItoo\fR much vertical space. .PP Oneline mode is \s-1DDC\s0 testing to see if a single line rendering of something will fit within the available space. Things will often be rendered more than once since \s-1DDC\s0 is optimising for compact readable output rather than raw straight line performance. .SS "Top level formatting" .IX Subsection "Top level formatting" If something is formatted and the remaining width is zero or negative, \s-1DDC\s0 accepts default on \*(L"max_width\*(R" and bails out to a fully vertical approach so it overflows the desired width no more than necessary. .SS "Array formatting" .IX Subsection "Array formatting" If already in vertical mode, formats one array element per line, appended with \f(CW\*(C`,\*(C'\fR: .PP .Vb 5 \& [ \& 1, \& 2, \& 3 \& ] .Ve .PP If in possible oneline mode, formats all but the last element according to the \*(L"Array element\*(R" rules, the last element according to normal formatting, and joins them with \f(CW\*(Aq \*(Aq\fR in the hopes this is narrow enough. Return this if oneline is forced or it fits: .PP .Vb 1 \& [ 1, 2, 3 ] .Ve .PP If there's only a single internal member, tries to use the \&\*(L"Single entry formatting\*(R" strategy to cuddle it. .PP .Vb 3 \& [ [ \& \& ] ] .Ve .PP Otherwise, attempts to bundle things as best possible: Each element is formatted according to the \*(L"Array element\*(R" rules, and multiple results are concatenated together onto a single line where that still remains within the available width. .PP .Vb 4 \& [ \& \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq, \& \*(Aqred\*(Aq, \*(Aqwhite\*(Aq, \*(Aqblue\*(Aq, \& ] .Ve .SS "Array element" .IX Subsection "Array element" Elements are normally formatted as \f(CW\*(C`$formatted.\*(Aq,\*(Aq\*(C'\fR except if an element is of type \f(CW\*(C`key\*(C'\fR in which cases it becomes \f(CW\*(C`$key =>\*(C'\fR. .PP .Vb 2 \& "whatever the smeg", \& smeg_off => .Ve .SS "List formatting" .IX Subsection "List formatting" The type \f(CW\*(C`list\*(C'\fR is synthetic and only introduced by transforms. .PP It is formatted identically to an arrayref except with \f(CW\*(C`( )\*(C'\fR instead of \&\f(CW\*(C`[ ]\*(C'\fR, with the exception that if it consists of only plain strings and will fit onto a single line, it formats as a \f(CW\*(C`qw(x y x)\*(C'\fR style list. .PP .Vb 6 \& qw(foo bar baz) \& ( \& \*(Aqfoo\*(Aq, \& \*(Aqbar\*(Aq, \& \*(Aqbaz\*(Aq, \& ) .Ve .SS "Single entry formatting" .IX Subsection "Single entry formatting" Where possible, a single entry will be cuddled such that the opening delimiters are both on the first line, and the closing delimiters both on the final line, to reduce the vertical space consumption of nested single entry array and/or hashrefs. .PP .Vb 3 \& to => { \-select => { \& ... \& } } \& \& [ \*(AqSRV:8FB66F32\*(Aq ], [ [ \& \*(Aq/opt/voice\-srvc\-native/bin/async\-srvc\-att\-gateway\-poller\*(Aq, 33, \& \*(AqNERV::Voice::SRV::Native::AsyncSRVATTGatewayPoller::main\*(Aq, \& ] ], .Ve .SS "Hash formatting" .IX Subsection "Hash formatting" If already in vertical mode, key/value pairs are formatted separated by newlines, with no attention paid to key length. .PP .Vb 4 \& { \& foo => ..., \& bar => ..., \& } .Ve .PP If potentially in oneline mode, key/value pairs are formatted separated by \&\f(CW\*(Aq, \*(Aq\fR and the value is returned if forced or if remaining width allows the oneline rendering. .PP .Vb 1 \& { foo => ..., bar => ... } .Ve .PP Otherwise, all key/value pairs are formatted as \f(CW\*(C`key => value\*(C'\fR where possible, but if the first line of the value is too long, the value is moved to the next line and indented. .PP .Vb 3 \& key => \*(Aqshortvalue\*(Aq \& key => \& \*(Aqoverlylongvalue\*(Aq .Ve .PP If there's only a single such key/value pair, tries to use the \&\*(L"Single entry formatting\*(R" strategy to cuddle it. .PP .Vb 3 \& { zathrus => { \& listened_to => 0, \& } } .Ve .PP Otherwise returns key/value pairs indented and separated by newlines .PP .Vb 4 \& { \& foo => ..., \& bar => ..., \& } .Ve .SS "String formatting" .IX Subsection "String formatting" Uses single quotes if sure that's safe, double quotes otherwise. .PP .Vb 2 \& \*(Aqfoo bar baz quux\*(Aq \& "could have been \*(Aq\*(Aq but nicer to not screw up\en the indents with a newline" .Ve .PP Attempts to format a string within the available width, using multiple lines and the \f(CW\*(C`.\*(C'\fR concatenation operator if necessary,. .PP .Vb 3 \& \*(Aqthis would be an\*(Aq \& .\*(Aqannoyingly long\*(Aq \& .\*(Aqstring\*(Aq .Ve .PP The target width is set to 20 in vertical mode to try and not be too ugly. .SS "Object formatting" .IX Subsection "Object formatting" Objects are tested to see if their underlying reference is an array or hash. If so, it's formatted with 'bless( ' prepended and ', \f(CW$class\fR)' appended. This so far appears to interact nicely with everything else. .SH "AUTHOR" .IX Header "AUTHOR" mst \- Matt S Trout (cpan:MSTROUT) .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" None so far. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2019 the Data::Dumper::Compact \*(L"\s-1AUTHOR\*(R"\s0 and \*(L"\s-1CONTRIBUTORS\*(R"\s0 as listed above. .SH "LICENSE" .IX Header "LICENSE" This library is free software and may be distributed under the same terms as perl itself. See .