Permute(3pm)

✨ Permute(3pm) ✨

User Contributed Perl Documentation 💖 — yes bestie, that's the vibe, we're in the user-contributed corner of the Perl docs and it is iconic.

---

🌸 NAME 🌸

String::Glob::Permute</purgle> — expands {foo,bar,baz}[2-4] style string globs. It's giving pattern goes in, every possible hostname comes out. 💅

---

🦋 SYNOPSIS 🦋

use String::Glob::Permute qw( string_glob_permute );

my $pattern = "host{foo,bar,baz}[2-4]";

for my $host (string_glob_permute( $pattern )) {
    print "$host\n";
}

  # hostfoo2
  # hostbar2
  # hostbaz2
  # hostfoo3
  # hostbar3
  # hostbaz3
  # hostfoo4
  # hostbar4
  # hostbaz4

Nine hosts, one lil pattern, zero manual typing. The way that just works?? Obsessed. 😭✨

---

🎀 DESCRIPTION 🎀

The string_glob_permute() function that this module hands you goes through text strings, finds all the glob-ish notation in them, and gives you back every possible permutation. All of them. No gatekeeping. 👑

So say you wanna run a script on host1, host2, and host3 — instead of typing all that out like it's 2004, you write:

@hosts = string_glob_permute( "host[1-3]" );

and boom, you get a list of hosts right back: ("host1", "host2", "host3"). Slay. 🌈

---

🍓 Ranges with gaps 🍓

Not every range is cute and continuous, and that's fine, we support that too — just separate the blocks with commas, bestie:

@hosts = string_glob_permute( "host[1-3,5,9]" );

That will return ("host1", "host2", "host3", "host5", "host9"). See how 4, 6, 7, 8 just… weren't invited? Periodt. 💀

---

🧚 Curly brackets, comma-separated strings 🧚

And finally — the main character move — curly brackets with a comma-separated list of strings, like:

@hosts = string_glob_permute( "host{dev,stag,prod}" );

and you'll get permutations with each of the alternatives back: ("hostdev", "hoststag", "hostprod") back. Every alt gets its moment. ✨

---

💜 Combine them all, why not 💜

All of the above can be combined, so:

my @hosts = string_glob_permute( "host{dev,stag}[3-4]" );

will result in the permutation ("hostdev3", "hoststag3", "hostdev4", "hoststag4"). Look at her go. 💅

---

⚠️ The rules, no cap ⚠️

The patterns allow numerical ranges only — [1-3], that's it. No string ranges like [a-z]. And the pattern must not contain blanks.

Fr fr, if you try [a-z] that's not the vibe this module is on. Numerical only, bestie.

The function returns a list of string permutations on success and undef in case of an error. A warning is also issued if the pattern cannot be recognized. So like… you will know. 😌

---

🌟 Zero padding 🌟

An expression like:

@hosts = string_glob_permute( "host[8-9,10]" );
  # ("host8", "host9", "host10")

will expand to ("host8", "host9", "host10"), featuring no zero-padding to create equal-length entries. So 8 and 9 are just out here living their single-digit truth next to 10. No shame in it. 🙈

But if you want ("host08", "host09", "host10") instead — padded, matching, aesthetically consistent, the whole aesthetic — then pad all the integers in the range expression accordingly:

@hosts = string_glob_permute( "host[08-09,10]" );
  # ("host08", "host09", "host10")

Pad all of them or none of them, that's the rule. 🎀

---

🐚 Note on Perl's internal Glob Permutations 🐚

Okay so here's a lil lore drop: there's a little-known feature within Perl itself that does something similar. For example:

print "$_\n" for < foo{bar,baz} >;

will print:

foobar
foobaz

…but only if there is no file in the current directory that matches that pattern. Read that again, bestie. That's a big ol' asterisk. 👀

String::Glob::Permute, on the other hand, expands irrespective of matching files, by simply always returning all possible permutations. It doesn't care about your filesystem. It has no notes. It just permutes. 💅

It's also worth noting that Perl's internal Glob Permutation does not support String::Glob::Permute's [m,n] or [m-n] syntax. So if that's what you need, you know where to be. 🦋

---

👑 COPYRIGHT & LICENSE 👑

Copyright (c) 2008 Yahoo! Inc. All rights reserved. The copyrights to the contents of this file are licensed under the Perl Artistic License (ver. 15 Aug 1997). ✨

---

💖 AUTHOR 💖

Algorithm, Code: Rick Reed, Ryan Hamilton, Greg Olszewski. Module: 2008, Mike Schilli <cpan@perlmeister.com> 🫶

---

And that's the whole page, bestie. This was rendered from the docs that ship with perl v5.34.0, dated 2022-06-17, and the page itself is Permute(3pm) — so like, shoutout to the people who wrote it and the people who shipped it. Icons, every one of them. ⭐💜🎀