.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Permute 3pm"
.TH Permute 3pm "2018-01-18" "perl v5.26.1" "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"
String::Glob::Permute \- Expand {foo,bar,baz}[2\-4] style string globs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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\en";
\&    }
\&
\&      # hostfoo2
\&      # hostbar2
\&      # hostbaz2
\&      # hostfoo3
\&      # hostbar3
\&      # hostbaz3
\&      # hostfoo4
\&      # hostbar4
\&      # hostbaz4
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`string_glob_permute()\*(C'\fR function provided by this module expands 
glob-like notations in text strings and returns all possible permutations.
.PP
For example, to run a script on hosts host1, host2, and host3, you might
write
.PP
.Vb 1
\&    @hosts = string_glob_permute( "host[1\-3]" );
.Ve
.PP
and get a list of hosts back: (\*(L"host1\*(R", \*(L"host2\*(R", \*(L"host3\*(R").
.PP
Ranges with gaps are also supported, just separate the blocks by
commas:
.PP
.Vb 1
\&    @hosts = string_glob_permute( "host[1\-3,5,9]" );
.Ve
.PP
will return (\*(L"host1\*(R", \*(L"host2\*(R", \*(L"host3\*(R", \*(L"host5\*(R", \*(L"host9\*(R").
.PP
And, finally, using curly brackets and comma-separated lists of strings,
as in
.PP
.Vb 1
\&    @hosts = string_glob_permute( "host{dev,stag,prod}" );
.Ve
.PP
you'll get permutations with each of the alternatives back:
(\*(L"hostdev\*(R", \*(L"hoststag\*(R", \*(L"hostprod\*(R") back.
.PP
All of the above can be combined, so
.PP
.Vb 1
\&    my @hosts = string_glob_permute( "host{dev,stag}[3\-4]" );
.Ve
.PP
will result in the permutation
(\*(L"hostdev3\*(R", \*(L"hoststag3\*(R", \*(L"hostdev4\*(R", \*(L"hoststag4\*(R").
.PP
The patterns allow numerical ranges only [1\-3], no string ranges like 
[a\-z]. Pattern must not contain blanks.
.PP
The function returns a list of string permutations on success and
\&\f(CW\*(C`undef\*(C'\fR in case of an error. A warning is also issued if the pattern
cannot be recognized.
.SS "Zero padding"
.IX Subsection "Zero padding"
An expression like
.PP
.Vb 2
\&    @hosts = string_glob_permute( "host[8\-9,10]" );
\&      # ("host8", "host9", "host10")
.Ve
.PP
will expand to (\*(L"host8\*(R", \*(L"host9\*(R", \*(L"host10\*(R"), featuring no zero-padding to
create equal-length entries. If you want (\*(L"host08\*(R", \*(L"host09\*(R", \*(L"host10\*(R"),
instead, pad all integers in the range expression accordingly:
.PP
.Vb 2
\&    @hosts = string_glob_permute( "host[08\-09,10]" );
\&      # ("host08", "host09", "host10")
.Ve
.SS "Note on Perl's internal Glob Permutations"
.IX Subsection "Note on Perl's internal Glob Permutations"
Note that there's a little-known feature within Perl itself that does 
something similar, for example
.PP
.Vb 1
\&    print "$_\en" for < foo{bar,baz} >;
.Ve
.PP
will print
.PP
.Vb 2
\&    foobar
\&    foobaz
.Ve
.PP
if there is no file in the current directory that matches that pattern.
String::Glob::Permute, on the other hand, expands irrespective of matching
files, by simply always returning all possible permutations. It's also
worth noting that Perl's internal Glob Permutation does not support
String::Glob::Permute's [m,n] or [m\-n] syntax.
.SH "COPYRIGHT & LICENSE"
.IX Header "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).
.SH "AUTHOR"
.IX Header "AUTHOR"
Algorithm, Code: Rick Reed, Ryan Hamilton, Greg Olszewski. 
Module: 2008, Mike Schilli <cpan@perlmeister.com>