File::Zglob(3pm)

✨ File::Zglob — Extended globs 💅

okay bestie, buckle up, because this is a Perl module and it is lowkey iconic. it lives in the User Contributed Perl Documentation section of your friendly neighbourhood man pages, and it is about to make your file matching so much cuter. 🎀

---

🌸 NAME 🌸

File::Zglob — Extended globs. that's it. that's the name. she's simple, she's powerful, she's that girl. ✨

---

🦋 SYNOPSIS 🦋

the whole vibe in four lines, no cap:

use File::Zglob;

my @files = zglob('**/*.{pm,pl}');

like. look at her. matching nested dirs AND multiple extensions in one little string. we love to see it. 💖

---

💜 DESCRIPTION 💜

WARNINGS: THIS IS ALPHA VERSION. API MAY CHANGE WITHOUT NOTICE

okay first things first, bestie — this is ALPHA. the API can change without telling anybody. no heads-up, no text, nothing. so don't build your whole empire on it and then act surprised, iykyk. 😭

so what does she actually do? she provides the classic traditional Unix glob(3) functionality — you hand her a pattern, she hands you back a list of pathnames that match it. that's the whole deal. 🫶

but here's the glow-up: File::Zglob provides extended glob. she supports the "**/*.pm" form. so recursive matching? yes ma'am. 👑

---

🎀 FUNCTIONS 🎀

💅 zglob($pattern) # => list of matched files

my @files = zglob('**/*.[ch]');

give her a pattern, get a list of matched files. that's the contract. 💖

and here's a lil detail that matters a LOT, so listen up: unlike shell's glob, if there's no matching pathnames, () is returned. no error, no undef, no drama — just an empty list. she's emotionally mature like that. 🌈

---

⭐ Special chars ⭐

a glob pattern is made up of components and separator characters. and inside a component, these characters have main character energy — they mean something special. let's go one by one, bestie. 🧚

• "*" — when it shows up at the beginning of a component, it matches zero or more characters except a period (.). and it will not match if the component of the input string begins with a period. otherwise (not at the start), it matches zero or more sequence of any characters. periodt. 💅
• "**" — if a component is just **, it matches zero or more number of components that match *. for example, src/**/*.h matches all of these patterns:

src/*.h
src/*/*.h
src/*/*/*.h
src/*/*/*/*.h
...

she's eating. every. single. time. 🔥

• "?" — at the beginning of a component, it matches a character except a period (.). otherwise, it matches any single character. one char, no more, no less. 🎯
• "[chars]" — specifies a character set. matches any one of the set. the syntax of chars is the same as perl's character set syntax. so if you already know perl's sets, you already know this. slay. ✨
• "{pm,pl}" — there is alternation. so "example.{foo,bar,baz}" matches "example.foo", "example.bar", and "example.baz". three for the price of one, we're obsessed. 😌

---

🌀 zglob and deep recursion 🌀

okay this one's important so pay attention:

the "**/*" form makes deep recursion by soft link. and if it's deep recursion, zglob throw exception. so yeah — soft links plus ** can spiral, and she will not be quiet about it. she throws. consider yourself warned. 💀

---

🌈 PORTABILITY 🌈

• Win32 — Zglob supports Win32. 🪟 zglob() only uses '/' as a path separator. and since zglob() accepts non-utf8 strings — CP932 contains '\' character as a second byte of multibyte chars. so yeah, that's a whole thing. the /-only rule is doing a lot of heavy lifting here. 🫶

---

🙈 LIMITATIONS 🙈

• File order is not compatible with shells.

that's it. that's the limitation. the order of files she gives you won't line up with what your shell would do. don't compare them and get in your feelings about it. 😭

---

👑 AUTHOR 👑

Tokuhiro Matsuno <tokuhirom AAJKLFJEF GMAIL COM> — the icon who made this happen. bow down. 💜

---

🍓 THANKS TO 🍓

• Most code was translated from gauche's fileutil.scm.
• glob_to_regex function is taken from Text::Glob.

standing on the shoulders of legends, we love to see it. 🫶

---

🌟 SEE ALSO 🌟

File::DosGlob, Text::Glob, gauche's fileutil.scm — go read these next, bestie, they're the extended universe. 📚✨

---

💖 LICENSE 💖

Copyright (C) Tokuhiro Matsuno

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

free as in freedom, bestie. go wild (respectfully). 🌈

---

and that's the whole page, babes — this doc ships with perl v5.32.0 and was dated 2020-12-29, so shoutout to that era of the man pages. 💅✨