README

   1 NAME
   2     Regexp::Wildcards - Converts wildcard expressions to Perl regular
   3     expressions.
   4
   5 VERSION
   6     Version 0.03
   7
   8 SYNOPSIS
   9         use Regexp::Wildcards qw/wc2re/;
  10
  11         my $re;
  12         $re = wc2re 'a{b.,c}*' => 'unix';   # Do it Unix style.
  13         $re = wc2re 'a.,b*'    => 'win32';  # Do it Windows style.
  14         $re = wc2re '*{x,y}.'  => 'jokers'; # Process the jokers & escape the rest.
  15
  16 DESCRIPTION
  17     In many situations, users may want to specify patterns to match but
  18     don't need the full power of regexps. Wildcards make one of those sets
  19     of simplified rules. This module converts wildcard expressions to Perl
  20     regular expressions, so that you can use them for matching. It handles
  21     the "*" and "?" jokers, as well as Unix bracketed alternatives "{,}",
  22     and uses the backspace ("\") as an escape character. Wrappers are
  23     provided to mimic the behaviour of Windows and Unix shells.
  24
  25 FUNCTIONS
  26   "wc2re_unix"
  27     This function takes as its only argument the wildcard string to process,
  28     and returns the corresponding regular expression according to standard
  29     Unix wildcard rules. It successively escapes all unprotected regexp
  30     special characters that doesn't hold any meaning for wildcards, turns
  31     jokers into their regexp equivalents, and changes bracketed blocks into
  32     "(?:|)" alternations. If brackets are unbalanced, it will try to
  33     substitute as many of them as possible, and then escape the remaining
  34     "{" and "}". Commas outside of any bracket-delimited block will also be
  35     escaped.
  36
  37         # This is a valid bracket expression, and is completely translated.
  38         print 'ok' if wc2re_unix('{a{b,c}d,e}') eq '(?:a(?:b|c)d|e)';
  39
  40     The function handles unbalanced bracket expressions, by escaping
  41     everything it can't recognize. For example :
  42
  43         # The first comma is replaced, and the remaining brackets and comma are escaped.
  44         print 'ok' if wc2re_unix('{a\\{b,c}d,e}') eq '(?:a\\{b|c)d\\,e\\}';
  45
  46         # All the brackets and commas are escaped.
  47         print 'ok' if wc2re_unix('{a{b,c\\}d,e}') eq '\\{a\\{b\\,c\\}d\\,e\\}';
  48
  49   "wc2re_win32"
  50     Similar to the precedent, but for Windows wildcards. Bracketed blocks
  51     are no longer handled (which means that brackets will be escaped), but
  52     you can provide a comma-separated list of items.
  53
  54         # All the brackets are escaped, and commas are seen as list delimiters.
  55         print 'ok' if wc2re_win32('{a{b,c}d,e}') eq '(?:\\{a\\{b|c\\}d|e\\})';
  56
  57   "wc2re_jokers"
  58     This one only handles the "?" and "*" jokers. All other unquoted regexp
  59     metacharacters will be escaped.
  60
  61         # Everything is escaped.
  62         print 'ok' if wc2re_jokers('{a{b,c}d,e}') eq '\\{a\\{b\\,c\\}d\\,e\\}';
  63
  64   "wc2re"
  65     A generic function that wraps around all the different rules. The first
  66     argument is the wildcard expression, and the second one is the type of
  67     rules to apply, currently either "unix", "win32" or "jokers". If the
  68     type is undefined, it defaults to "unix".
  69
  70 EXPORT
  71     These four functions are exported only on request : "wc2re",
  72     "wc2re_unix", "wc2re_win32" and "wc2re_jokers".
  73
  74 DEPENDENCIES
  75     Text::Balanced, which is bundled with perl since version 5.7.3
  76
  77 SEE ALSO
  78     Some modules provide incomplete alternatives as helper functions :
  79
  80     Net::FTPServer has a method for that. Only jokers are translated, and
  81     escaping won't preserve them.
  82
  83     File::Find::Match::Util has a "wildcard" function that compiles a
  84     matcher. It only handles "*".
  85
  86     Text::Buffer has the "convertWildcardToRegex" class method that handles
  87     jokers.
  88
  89 AUTHOR
  90     Vincent Pit, "<perl at profvince.com>"
  91
  92 BUGS
  93     Please report any bugs or feature requests to "bug-regexp-wildcards at
  94     rt.cpan.org", or through the web interface at
  95     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Regexp-Wildcards>. I
  96     will be notified, and then you'll automatically be notified of progress
  97     on your bug as I make changes.
  98
  99 SUPPORT
 100     You can find documentation for this module with the perldoc command.
 101
 102         perldoc Regexp::Wildcards
 103
 104 COPYRIGHT & LICENSE
 105     Copyright 2007 Vincent Pit, all rights reserved.
 106
 107     This program is free software; you can redistribute it and/or modify it
 108     under the same terms as Perl itself.
 109