+In many situations, users may want to specify patterns to match but don't need the full power of regexps. Wildcards make one of those sets of simplified rules. This module converts wildcard expressions to Perl regular expressions, so that you can use them for matching. It handles the C<*> and C<?> shell jokers, as well as Unix bracketed alternatives C<{,}>, but also C<%> and C<_> SQL wildcards. Backspace (C<\>) is used as an escape character. Wrappers are provided to mimic the behaviour of Windows and Unix shells.
+
+=head1 VARIABLES
+
+These variables control if the wildcards jokers and brackets must capture their match. They can be globally set by writing in your program
+
+ $Regexp::Wildcards::CaptureSingle = 1;
+ # From then, "exactly one" wildcards are capturing
+
+or can be locally specified via C<local>
+
+ {
+ local $Regexp::Wildcards::CaptureSingle = 1;
+ # In this block, "exactly one" wildcards are capturing.
+ ...
+ }
+ # Back to the situation from before the block
+
+This section describes also how those elements are translated by the L<functions|/FUNCTIONS>.
+
+=head2 C<$CaptureSingle>
+
+When this variable is true, each occurence of unescaped I<"exactly one"> wildcards (i.e. C<?> jokers or C<_> for SQL wildcards) are made capturing in the resulting regexp (they are be replaced by C<(.)>). Otherwise, they are just replaced by C<.>. Default is the latter.
+
+ For jokers :
+ 'a???b\\??' is translated to 'a(.)(.)(.)b\\?(.)' if $CaptureSingle is true
+ 'a...b\\?.' otherwise (default)
+
+ For SQL wildcards :
+ 'a___b\\__' is translated to 'a(.)(.)(.)b\\_(.)' if $CaptureSingle is true
+ 'a...b\\_.' otherwise (default)
+
+=cut
+
+our $CaptureSingle = 0;
+
+sub capture_single {
+ return $CaptureSingle ? '(.)'
+ : '.';
+}
+
+=head2 C<$CaptureAny>
+
+By default this variable is false, and successions of unescaped I<"any"> wildcards (i.e. C<*> jokers or C<%> for SQL wildcards) are replaced by B<one> single C<.*>. When it evalutes to true, those sequences of I<"any"> wildcards are made into B<one> capture, which is greedy (C<(.*)>) for C<$CaptureAny E<gt> 0> and otherwise non-greedy (C<(.*?)>).
+
+ For jokers :
+ 'a***b\\**' is translated to 'a.*b\\*.*' if $CaptureAny is false (default)
+ 'a(.*)b\\*(.*)' if $CaptureAny > 0
+ 'a(.*?)b\\*(.*?)' otherwise
+
+ For SQL wildcards :
+ 'a%%%b\\%%' is translated to 'a.*b\\%.*' if $CaptureAny is false (default)
+ 'a(.*)b\\%(.*)' if $CaptureAny > 0
+ 'a(.*?)b\\%(.*?)' otherwise
+
+=cut
+
+our $CaptureAny = 0;
+
+sub capture_any {
+ return $CaptureAny ? (($CaptureAny > 0) ? '(.*)'
+ : '(.*?)')
+ : '.*';
+}
+
+=head2 C<$CaptureBrackets>
+
+If this variable is set to true, valid brackets constructs are made into C<( | )> captures, and otherwise they are replaced by non-capturing alternations (C<(?: | >)), which is the default.
+
+ 'a{b\\},\\{c}' is translated to 'a(b\\}|\\{c)' if $CaptureBrackets is true
+ 'a(?:b\\}|\\{c)' otherwise (default)
+
+=cut
+
+our $CaptureBrackets = 0;
+
+sub capture_brackets {
+ return $CaptureBrackets ? '('
+ : '(?:';
+}