Data::...sformer(3pm)

💖 Data::Transformer 💖 — the Data::Transformer(3pm) page, but make it group chat 💅

straight outta the User Contributed Perl Documentation, bestie. buckle up, we're going in. 🦋

---

🌸 NAME 🌸

Data::Transformer — traverse a data structure, altering it in place. yes. in place. no copy. we go in and we redecorate. periodt. 💅

---

🎀 SYNOPSIS 🎀

four whole vibes, pick your fighter:

✨ A: SIMPLE USAGE ✨

use Data::Transformer;

# A: SIMPLE USAGE:
# trim extra whitespace from normal strings inside %data.
my $trim = sub { local($_)=shift; $$_ =~ s/^\s*//; $$_ =~ s/\s*$//; };
my $t = Data::Transformer->new(normal=>$trim);
$t->traverse(\%data);

okay so you got a lil coderef, you hand it to new() keyed by normal, you traverse(\%data), and every normal string inside %data gets its extra whitespace trimmed. it's giving ✨glow up✨.

🔥 B: MORE COMPLEX USAGE 🔥

the brief: (a) uppercase all keys in all hashes contained in $data, and (b) convert any arrays to hashes. two jobs. one transformer. iconic.

# B: MORE COMPLEX USAGE:
# (a) uppercase all keys in all hashes contained in $data
# and (b) convert any arrays to hashes:
my $uc_hash = sub {
  my $h = shift;
  my @keys = keys %h;
  foreach (@keys) {
    my $uc = uc($_);
    if ($uc ne $_ && !exists($h->{$uc})) {
      $h->{$uc} = $h->{$_};
      delete $h->{$_};
    } elsif ($uc ne $_) {
      die "Bad key $_: '$uc' exists already";
    }
  }
};
my $ar_conv = sub {
  my %h = @{$_[0]};
  return sub { \%h };
};
my $t = Data::Transformer->new(
   hash       => $uc_hash,
   array      => $ar_conv,
   node_limit => 500_000 );
eval { $t->traverse($data) };
warn "Could not complete transformation: $@" if $@;

notice the node_limit => 500_000? yeah. that's not a flex, that's a necessity — see the CAVEATS, bestie, it gets real in there. and the eval + warn? that's the "if it goes feral, at least we find out" energy. 🙈

🦋 C: NON-DESTRUCTIVE TRAVERSAL 🦋

plot twist: you don't actually have to change anything. just vibe. collect intel. 🌈

# C: NON-DESTRUCTIVE TRAVERSAL
# You don't actually have to change anything...
my $size = 0;
my $t = Data::Transformer->new(
   normal => sub { $size+=length(${ $_[0] }) },
   hash   => sub { $size+=length($_) for keys %{ $_[0] } },
);
my $nodes = $t->tranverse(\%data);
print "Number of nodes: $nodes\n";
print "Size of keys + values: $size\n";

(yes, the example literally says tranverse up there. we are reproducing the example exactly, typos and all, no cap. 💀 do NOT come for me.)

👑 D: OBJECTS INSIDE A DATA STRUCTURE 👑

# D: OBJECTS INSIDE A DATA STRUCTURE
# Affect objects by using the class name as a key:
my $t = Data::Transformer->new(
   'My::Class' => sub { shift->set_foo('bar') }
);

want to touch objects? use the class name as the key. that's the whole trick. main character move honestly. 💅

---

💜 DESCRIPTION 💜

🌸 Data type callbacks 🌸

the basic idea — and I'm quoting the vibe here — is that you provide a callback subroutine for each type of data that you wish to affect or collect information from. one callback per data type. match made in heaven. 💖

the constructor, new(), expects a hash with at least one of these keys:

• normal — for normal, non-reference data. the everyday girlies.
• array — for array references. 📚
• hash — for hash references. 🗂️
• code — for anonymous subroutines (coderefs). 🤖
• scalar — for scalar references. ✨
• glob — for globs (such as filehandle holders). 🌐

in every single case, the value is a coderef representing the callback for the data type in question. coderef in, magic out.

now the tea ☕: array and hash are special — they're the ones that get traversed into. they're not just leaves, they're doorways. 🚪

you can affect objects inside the data structure by specifying a callback keyed to the name of the class they belong to. but — and this is important — they are not automatically recursed into, even if they happen to be blessed hash or array references. blessed ≠ invited in. 🙅

same energy for scalar references: a scalar reference is not automatically traversed into, even if it may contain a reference to an arrayref or a hashref. to make the module traverse into scalar references, you need to return a coderef encapsulating a different data type in the scalar handler — which changes them and prompts a reiteration over that data point. and yes, this applies to objects as well. 🫶

🎀 Additional option for the constructor 🎀

• node_limit — if you give it an integer value, it overrides the default node processing limit of 2**16. it cannot be set higher than 2**20-1. that's the ceiling. don't test it. 🚫

✨ traverse() ✨

the traverse() method returns the number of nodes processed. and ngl, that number might not match either the number of nodes in the actual data structure or the number of nodes after the transformation. here's why:

• Reiteration into a particular node may have occurred, which increments the node count.
• Blessed references (objects) will not normally be iterated into — they're merely treated as leaves in the data structure. 🍃
• The processing code you passed to the constructor may well affect the number of nodes. you did that. that's on you. 💅

🔥 Note on data type changes 🔥

want to change a data type — like replacing an array with a hash, as in example B up there? you have to return a coderef from the callback for the original data type. that coderef encapsulates the replacement data for the node in question. ✨

after the node has been replaced like that, it gets re-evaluated so any transformations you defined for the new data type get applied. glow up on top of glow up.

🚨 be careful of potential infinite loops when doing this with more than one data type at a time, or when replacing coderefs with other coderefs. also — because of reiteration — complex changes of large data structures may require setting the node processing limit higher than the default. do with that information what you will. 😭

💀 Note on circular references 💀

data structures containing circular references should not cause problems. Data::Transformer will skip any node containing a reference which has already been processed. it's seen it. it's not going back. it's protecting its peace. 🧚

---

🚨 CAVEATS 🚨

okay bestie, real talk. it is not feasible to use this module for very large data structures. accordingly, there is a hard node processing boundary of 2**20-1 (about 1 million); attempting to set the limit higher results in an immediate, fatal error. immediately. fatally. no warning shot. 💀

for the vast majority of cases, though, the default limit of 2**16 (about 65 thousand) should be more than enough. she's generous. she's fine. 🫶

---

🌈 SEE ALSO 🌈

the author is aware of two modules doing similar things — check them out if this one doesn't fit your needs:

• Data::Rmap by Brad Bowman 🌸
• Data::Walk by Guido Flohr 🌸

---

👑 AUTHOR 👑

Baldur Kristinsson <bk@mbl.is>, 2006 — legend behaviour, honestly.

 Copyright (c) 2006 Baldur Kristinsson. All rights reserved.
 This program is free software; you can redistribute it and/or
 modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 💖 — this one came to you via perl v5.36.0, dated 2022-11-21, and it's called Data::Transformer(3pm). go forth and traverse responsibly. slay. 💅✨