String::Wildcard::Bash - Bash wildcard string routines
This document describes version 0.045 of String::Wildcard::Bash (from Perl distribution String-Wildcard-Bash), released on 2022-08-12.
use String::Wildcard::Bash qw( $RE_WILDCARD_BASH contains_wildcard contains_brace_wildcard contains_class_wildcard contains_joker_wildcard contains_qmark_wildcard contains_glob_wildcard contains_globstar_wildcard convert_wildcard_to_sql convert_wildcard_to_re ); say 1 if contains_wildcard("")); # -> say 1 if contains_wildcard("ab*")); # -> 1 say 1 if contains_wildcard("ab\\*")); # -> say 1 if contains_glob_wildcard("ab*")); # -> 1 say 1 if contains_glob_wildcard("ab?")); # -> say 1 if contains_qmark_wildcard("ab?")); # -> 1 say convert_wildcard_to_sql("foo*"); # -> "foo%" say convert_wildcard_to_re("foo*"); # -> "foo.*"
Usage:
$bool = contains_wildcard($wildcard_str)
Return true if $str contains wildcard pattern. Wildcard patterns include joker such as * (meaning zero or more of any characters) and ? (exactly one of any character), character class [...], and brace {...,} (brace expansion). A pattern can be escaped using a bacslash so it becomes literal, e.g. foo\* does not contain wildcard because it's foo followed by a literal asterisk *.
$str
*
?
[...]
{...,}
foo\*
foo
Aside from the abovementioned wildcard patterns, bash does other types of expansions/substitutions too, but these are not considered wildcard. These include tilde expansion (e.g. ~ becomes /home/alice), parameter and variable expansion (e.g. $0 and $HOME), arithmetic expression (e.g. $[1+2]), or history (!).
~
/home/alice
$0
$HOME
$[1+2]
!
Although this module has 'Bash' in its name, this set of wildcards should be applicable to other Unix shells. Haven't checked completely though.
For more specific needs, e.g. you want to check if a string just contains joker and not other types of wildcard patterns, use "$RE_WILDCARD_BASH" directly or one of the contains_*_wildcard functions.
contains_*_wildcard
Like "contains_wildcard", but only return true if string contains brace ({...,}) wildcard pattern.
Like "contains_wildcard", but only return true if string contains character class ([...]) wildcard pattern.
Like "contains_wildcard", but only return true if string contains any of the joker (?, *, or **) wildcard patterns.
**
Like "contains_wildcard", but only return true if string contains the question mark joker (?) wildcard pattern.
Like "contains_wildcard", but only return true if string contains the glob joker (*, and not **) wildcard pattern.
Like "contains_wildcard", but only return true if string contains the globstar joker (** and not *) wildcard pattern.
$sql_str = convert_wildcard_to_sql($wildcard_str);
Convert bash wildcard to SQL pattern. This includes:
converting unescaped * to %
%
converting unescaped ? to _
_
escaping unescaped %
escaping unescaped _
Unsupported constructs will cause the function to die.
$re_str = convert_wildcard_to_re([ \%opts, ] $wildcard_str);
Convert bash wildcard to regular expression string.
Known options:
brace
Bool. Default is true. Whether to expand braces or not. If set to false, will simply treat brace as literals.
Examples:
convert_wildcard_to_re( "{a,b}"); # => "(?:a|b)" convert_wildcard_to_re({brace=>0}, "{a,b}"); # => "\\{a\\,b\\}"
dotglob
Bool. Default is false. Whether joker * (asterisk) will match a dot file. The default behavior follows bash; that is, dot file must be matched explicitly with .*.
.*
This setting is similar to shell behavior (shopt) setting dotglob.
convert_wildcard_to_re({} , '*a*'); # => "[^.][^/]*a[^/]*" convert_wildcard_to_re({dotglob=>1}, '*a*'); # => "[^/]*a[^/]*"
globstar
Bool. Default is false. Whether globstar (**) can match across subdirectories (matches path separator). The default behavior follows bash; that is, globstar option is off and ** behaves like *.
This setting is similar to shell behavior (shopt) setting globstar.
convert_wildcard_to_re({}, '*'); # => "[^.][^/]*" convert_wildcard_to_re({}, '**'); # => "[^.][^/]*" convert_wildcard_to_re({globstar=>1}, '**'); # => "(?:[^/.][^/]*)(?:/+[^/.][^/]*)*" convert_wildcard_to_re({globstar=>1, dotglob=>1}, '**'); # => ".*"
path_separator
String, 1 character. Default is /. Can be used to customize the path separator.
/
Please visit the project's homepage at https://metacpan.org/release/String-Wildcard-Bash.
Source repository is at https://github.com/perlancar/perl-String-Wildcard-Bash.
Regexp::Wildcards can also convert a string with wildcard pattern to equivalent regexp pattern, like "convert_wildcard_to_re". Can handle Unix wildcards as well as SQL and DOS/Win32. As of this writing (v1.05), it does not handle character class ([...]) and interprets brace expansion differently than bash. String::Wildcard::Bash's convert_wildcard_to_re follows bash behavior more closely and also provides more options.
convert_wildcard_to_re
Other String::Wildcard::* modules.
String::Wildcard::*
perlancar <perlancar@cpan.org>
Steven Haryanto <stevenharyanto@gmail.com>
To contribute, you can send patches by email/via RT, or send pull requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.
This software is copyright (c) 2022, 2019, 2015, 2014 by perlancar <perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=String-Wildcard-Bash
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
To install String::Wildcard::Bash, copy and paste the appropriate command in to your terminal.
cpanm
cpanm String::Wildcard::Bash
CPAN shell
perl -MCPAN -e shell install String::Wildcard::Bash
For more information on module installation, please visit the detailed CPAN module installation guide.