NAME
String::Wildcard::Bash - Bash wildcard string routines
VERSION
This document describes version 0.044 of String::Wildcard::Bash (from
Perl distribution String-Wildcard-Bash), released on 2022-08-06.
SYNOPSIS
use String::Wildcard::Bash qw(
$RE_WILDCARD_BASH
contains_wildcard
convert_wildcard_to_sql
convert_wildcard_to_re
);
say 1 if contains_wildcard("")); # -> 0
say 1 if contains_wildcard("ab*")); # -> 1
say 1 if contains_wildcard("ab\\*")); # -> 0
say convert_wildcard_to_sql("foo*"); # -> "foo%"
say convert_wildcard_to_re("foo*"); # -> "foo.*"
DESCRIPTION
VARIABLES
$RE_WILDCARD_BASH
FUNCTIONS
contains_wildcard
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 "*".
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 ("!").
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.
contains_brace_wildcard
Like "contains_wildcard", but only return true if string contains brace
("{...,}") wildcard pattern.
contains_class_wildcard
Like "contains_wildcard", but only return true if string contains
character class ("[...]") wildcard pattern.
contains_joker_wildcard
Like "contains_wildcard", but only return true if string contains any of
the joker ("?", "*", or "**") wildcard patterns.
contains_qmark_wildcard
Like "contains_wildcard", but only return true if string contains the
question mark joker ("?") wildcard pattern.
contains_glob_wildcard
Like "contains_wildcard", but only return true if string contains the
glob joker ("*", and not "**") wildcard pattern.
contains_globstar_wildcard
Like "contains_wildcard", but only return true if string contains the
globstar joker ("**" and not "*") wildcard pattern.
convert_wildcard_to_sql
Usage:
$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.
convert_wildcard_to_re
Usage:
$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".
Examples:
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.
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/String-Wildcard-Bash>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-String-Wildcard-Bash>.
SEE ALSO
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.
Other "String::Wildcard::*" modules.
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTOR
Steven Haryanto <stevenharyanto@gmail.com>
CONTRIBUTING
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, and sometimes one or two
other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
steps required beyond that are considered a bug and can be reported to
me.
COPYRIGHT AND LICENSE
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.
BUGS
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.
