.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Shellish 3"
.TH Shellish 3 2023-07-26 "perl v5.38.0" "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
Regexp::Shellish \- Shell\-like regular expressions
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   use Regexp::Shellish qw( :all ) ;
\&
\&   $re = compile_shellish( \*(Aqa/c*d\*(Aq ) ;
\&
\&   ## This next one\*(Aqs like \*(Aqa*d\*(Aq except that it\*(Aqll
\&   ## match \*(Aqa/d\*(Aq.
\&   $re = compile_shellish( \*(Aqa**d\*(Aq ) ;
\&
\&   ## And here \*(Aq**\*(Aq won\*(Aqt match \*(Aqa/d\*(Aq, but behaves
\&   ## like \*(Aqa*d\*(Aq, except for the possibility of high
\&   ## cpu time consumption.
\&   $re = compile_shellish( \*(Aqa**d\*(Aq, { star_star => 0 } ) ;
\&
\&   ## The next two result in identical $re1 and $re2.
\&   ## The second is a noop so that Regexp references can
\&   ## be easily accomodated.
\&   $re1 = compile_shellish( \*(Aqa{b,c}d\*(Aq ) ;
\&   $re2 = compile_shellish( qr/\eA(?:a(?:b|c)d)\eZ/ ) ;
\&
\&   @matches = shellish_glob( $re, @possibilities ) ;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides shell-like regular expressions.  The wildcards provided
are \f(CW\*(C`?\*(C'\fR, \f(CW\*(C`*\*(C'\fR and \f(CW\*(C`**\*(C'\fR, where \f(CW\*(C`**\*(C'\fR is like \f(CW\*(C`*\*(C'\fR but matches \f(CW\*(C`/\*(C'\fR.  See
"compile_shellish" for details.
.PP
Case sensitivity and constructs like <**>, \f(CW\*(C`(a*b)\*(C'\fR, and \f(CW\*(C`{a,b,c}\*(C'\fR
can be disabled.
.IP compile_shellish 4
.IX Item "compile_shellish"
Compiles a string containing a 'shellish' regular expression, returning a
Regexp reference.  Regexp references passed in are passed through
unmolested.
.Sp
Here are the transformation rules from shellish expression terms to
perl regular expression terms:
.Sp
.Vb 6
\&   Shellish  Perl RE
\&   ========  =======
\&   *         [^/]*
\&   ?         .
\&   **        .*               ## unless { star_star   => 0 }
\&   ...       .*               ## unless { dot_dot_dot => 0 }
\&
\&   (         (                ## unless { parens => 0 }
\&   )         )                ## unless { parens => 0 }
\&
\&   {a,b,c}   (?:a|b|c)        ## unless { braces => 0 }
\&
\&   \ea        a                ## These are de\-escaped and
\&   \e*        \e*               ## passed to quotemeta()
.Ve
.Sp
The wildcards treat newlines as normal characters.
.Sp
Parens group in to \f(CW$1\fR..$n, since they are passed through unmolested
(unless option parens => 0 is passed).  This is useless when using
\&\fBglob_shellish()\fR, though.
.Sp
The final parameter can be a hash reference containing options:
.Sp
.Vb 12
\&   compile_shellish(
\&      \*(Aq**\*(Aq,
\&      {
\&         anchors        => 0,   ## Doesn\*(Aqt put ^ and $ around the
\&                                ## resulting regexp
\&         case_sensitive => 0,   ## Make case insensitive
\&         dot_dot_dot    => 0,   ## \*(Aq...\*(Aq is now just three \*(Aq.\*(Aq chars
\&         star_star      => 0,   ## \*(Aq**\*(Aq is now two \*(Aq*\*(Aq wildcards
\&         parens         => 0,   ## \*(Aq(\*(Aq, \*(Aq)\*(Aq are now regular chars
\&         braces         => 0,   ## \*(Aq{\*(Aq, \*(Aq}\*(Aq are now regular chars
\&      }
\&   ) ;
.Ve
.Sp
No option affects Regexps passed through.
.IP shellish_glob 4
.IX Item "shellish_glob"
Pass a regular expression and a list of possible values, get back a list of
matching values.
.Sp
.Vb 2
\&   my @matches = shellish_glob( \*(Aq*/*\*(Aq, @possibilities ) ;
\&   my @matches = shellish_glob( \*(Aq*/*\*(Aq, @possibilities, \e%options ) ;
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Barrie Slaymaker <barries@slaysys.com>