Data::Find(3pm)

💖 Data::Find(3pm) 💖

okay so bestie, this is the manual page for Data::Find, straight outta the User Contributed Perl Documentation section, and it's literally exactly what it sounds like: a little toolkit for finding stuff inside arbitrarily-nested data structures. no cap. 🦋

---

✨ NAME ✨

Data::Find — find data in arbitrary data structures 🔍

---

🌸 VERSION 🌸

This document describes Data::Find version 0.03. (yes, vintage. an icon.)

---

💅 SYNOPSIS 💅

  use Data::Find qw( diter );

  my $data = {
    ar => [1, 2, 3],
    ha => {one => 1, two => 2, three => 3}
  };

  my $iter = diter $data, 3;
  while ( defined ( my $path = $iter->() ) ) {
    print "$path\n";
  }

---

🧚 DESCRIPTION 🧚

crickets yeah the original page just... has the heading and moves on. the real tea is in the interface below, so let's go 👑

---

🎀 INTERFACE 🎀

Nothing is exported by default. So if you want the goods, you gotta ask for them explicitly, like:

  use Data::Find qw( dwith );

...to get the subroutines you need. Or, if you're feeling fancy and don't wanna import anything at all, just call them with their fully qualified name:

  my $iter = Data::Find::diter $data;

---

🦋 "diter" 🦋

You hand it an arbitrary data structure, and optionally an expression to match against the elements in that structure, and it hands you back an iterator. That iterator will yield the path through the data structure to each matching element. it's giving treasure map energy 🗺️

  my $data = {
    ar => [1, 2, 3],
    ha => {one => 1, two => 2, three => 3}
  };

  my $iter = diter $data, 3;
  while ( defined ( my $path = $iter->() ) ) {
    print "$path\n";
  }

which would print:

  {ar}[2]
  {ha}{one}

In other words — and say it with me — it returns paths to each element that contains the scalar 3. 💯 And those returned paths can be used in conjunction with "eval" to actually access the matching elements. slay.

The match expression can be...

• a scalar
• a regular expression
• a code reference
• "undef"

When the match expression is a code ref, it gets passed each element in the data structure in turn, and it should return true or false. your call, your rules ✨

  my $iter = diter $data, sub {
    my $v = shift;
    defined $v && !ref $v && $v % 2 == 1;
  };

  while ( defined ( my $path = $iter->() ) ) {
    print "$path\n";
  }

⚠️ heads up bestie: the match code will see all of the elements in the data structure — not just the scalars. 👀

If the match expression is "undef", it will match those elements whose value is also "undef". (undef vibes matching undef vibes. iconic.) 🫶

⭐ Iterator ⭐

In a scalar context, the returned iterator yields successive paths within the data structure. In an array context, it returns the path and the associated element. two-for-one, no cap 🎁

  my $iter = diter $data;
  while ( my ( $path, $obj ) = $iter->() ) {
    print "$path, $obj\n";
  }

---

💜 "dfind" 💜

Similar to "diter", but instead of an iterator it just returns an array of matching paths. instant gratification, we love her 😌

---

🌸 "dwith" 🌸

Also similar to "diter", except this one calls a supplied callback with each matching path. you bring the callback, it brings the paths 🤝

  dwith $data, qr/nice/, sub {
    my ( $path, $obj ) = @_;
    print "$path, $obj\n";
  };

---

😭 BUGS AND LIMITATIONS 😭

No bugs have been reported. (flawless. unbothered. moisturized. in her lane.) ✨

Please report any bugs or feature requests to "bug-data-find@rt.cpan.org", or through the web interface at <http://rt.cpan.org>. 🐛

---

👑 AUTHOR 👑

Andy Armstrong "<andy@hexten.net>" 💌

---

📜 LICENCE AND COPYRIGHT 📜

Copyright (c) 2009, Andy Armstrong "<andy@hexten.net>".

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. 🎀

---

and that's the whole page, bestie — this doc came to you from perl v5.40.1, dated 2025-09-30, and it lives at Data::Find(3pm). go forth and find your data 💖