1File::GlobMapper(3pm) Perl Programmers Reference Guide File::GlobMapper(3pm)
2
6 File::GlobMapper - Extend File Glob to Allow Input and Output Files
7
9 use File::GlobMapper qw( globmap );
10 my $aref = globmap $input => $output
12 or die $File::GlobMapper::Error ;
13 my $gm = new File::GlobMapper $input => $output
15 or die $File::GlobMapper::Error ;
16
18 This module needs Perl5.005 or better.
19 This module takes the existing "File::Glob" module as a starting point
21 and extends it to allow new filenames to be derived from the files
22 matched by "File::Glob".
23 This can be useful when carrying out batch operations on multiple files
25 that have both an input filename and output filename and the output
26 file can be derived from the input filename. Examples of operations
27 where this can be useful include, file renaming, file copying and file
28 compression.
29 Behind The Scenes
31 To help explain what "File::GlobMapper" does, consider what code you
32 would write if you wanted to rename all files in the current directory
33 that ended in ".tar.gz" to ".tgz". So say these files are in the
34 current directory
35 alpha.tar.gz
37 beta.tar.gz
38 gamma.tar.gz
39 and they need renamed to this
41 alpha.tgz
43 beta.tgz
44 gamma.tgz
45 Below is a possible implementation of a script to carry out the rename
47 (error cases have been omitted)
48 foreach my $old ( glob "*.tar.gz" )
50 {
51 my $new = $old;
52 $new =~ s#(.*)\.tar\.gz$#$1.tgz# ;
53 rename $old => $new
55 or die "Cannot rename '$old' to '$new': $!\n;
56 }
57 Notice that a file glob pattern "*.tar.gz" was used to match the
59 ".tar.gz" files, then a fairly similar regular expression was used in
60 the substitute to allow the new filename to be created.
61 Given that the file glob is just a cut-down regular expression and that
63 it has already done a lot of the hard work in pattern matching the
64 filenames, wouldn't it be handy to be able to use the patterns in the
65 fileglob to drive the new filename?
66 Well, that's exactly what "File::GlobMapper" does.
68 Here is same snippet of code rewritten using "globmap"
70 for my $pair (globmap '<*.tar.gz>' => '<#1.tgz>' )
72 {
73 my ($from, $to) = @$pair;
74 rename $from => $to
75 or die "Cannot rename '$old' to '$new': $!\n;
76 }
77 So how does it work?
79 Behind the scenes the "globmap" function does a combination of a file
81 glob to match existing filenames followed by a substitute to create the
82 new filenames.
83 Notice how both parameters to "globmap" are strings that are delimited
85 by <>. This is done to make them look more like file globs - it is
86 just syntactic sugar, but it can be handy when you want the strings to
87 be visually distinctive. The enclosing <> are optional, so you don't
88 have to use them - in fact the first thing globmap will do is remove
89 these delimiters if they are present.
90 The first parameter to "globmap", "*.tar.gz", is an Input File Glob.
92 Once the enclosing "< ... >" is removed, this is passed (more or less)
93 unchanged to "File::Glob" to carry out a file match.
94 Next the fileglob "*.tar.gz" is transformed behind the scenes into a
96 full Perl regular expression, with the additional step of wrapping each
97 transformed wildcard metacharacter sequence in parenthesis.
98 In this case the input fileglob "*.tar.gz" will be transformed into
100 this Perl regular expression
101 ([^/]*)\.tar\.gz
103 Wrapping with parenthesis allows the wildcard parts of the Input File
105 Glob to be referenced by the second parameter to "globmap", "#1.tgz",
106 the Output File Glob. This parameter operates just like the replacement
107 part of a substitute command. The difference is that the "#1" syntax is
108 used to reference sub-patterns matched in the input fileglob, rather
109 than the $1 syntax that is used with perl regular expressions. In this
110 case "#1" is used to refer to the text matched by the "*" in the Input
111 File Glob. This makes it easier to use this module where the parameters
112 to "globmap" are typed at the command line.
113 The final step involves passing each filename matched by the "*.tar.gz"
115 file glob through the derived Perl regular expression in turn and
116 expanding the output fileglob using it.
117 The end result of all this is a list of pairs of filenames. By default
119 that is what is returned by "globmap". In this example the data
120 structure returned will look like this
121 ( ['alpha.tar.gz' => 'alpha.tgz'],
123 ['beta.tar.gz' => 'beta.tgz' ],
124 ['gamma.tar.gz' => 'gamma.tgz']
125 )
126 Each pair is an array reference with two elements - namely the from
128 filename, that "File::Glob" has matched, and a to filename that is
129 derived from the from filename.
130 Limitations
132 "File::GlobMapper" has been kept simple deliberately, so it isn't
133 intended to solve all filename mapping operations. Under the hood
134 "File::Glob" (or for older versions of Perl, "File::BSDGlob") is used
135 to match the files, so you will never have the flexibility of full Perl
136 regular expression.
137 Input File Glob
139 The syntax for an Input FileGlob is identical to "File::Glob", except
140 for the following
141 1. No nested {}
143 2. Whitespace does not delimit fileglobs.
145 3. The use of parenthesis can be used to capture parts of the input
147 filename.
148 4. If an Input glob matches the same file more than once, only the
150 first will be used.
151 The syntax
153 ~
155 ~user
156 . Matches a literal '.'. Equivalent to the Perl regular expression
157 \.
159 * Matches zero or more characters, except '/'. Equivalent to the
161 Perl regular expression
162 [^/]*
164 ? Matches zero or one character, except '/'. Equivalent to the Perl
166 regular expression
167 [^/]?
169 \ Backslash is used, as usual, to escape the next character.
171 [] Character class.
173 {,} Alternation
175 () Capturing parenthesis that work just like perl
177 Any other character it taken literally.
179 Output File Glob
181 The Output File Glob is a normal string, with 2 glob-like features.
182 The first is the '*' metacharacter. This will be replaced by the
184 complete filename matched by the input file glob. So
185 *.c *.Z
187 The second is
189 Output FileGlobs take the
191 "*" The "*" character will be replaced with the complete input
193 filename.
194 #1 Patterns of the form /#\d/ will be replaced with the
196 Returned Data
199 A Rename script
200 Below is a simple "rename" script that uses "globmap" to determine the
201 source and destination filenames.
202 use File::GlobMapper qw(globmap) ;
204 use File::Copy;
205 die "rename: Usage rename 'from' 'to'\n"
207 unless @ARGV == 2 ;
208 my $fromGlob = shift @ARGV;
210 my $toGlob = shift @ARGV;
211 my $pairs = globmap($fromGlob, $toGlob)
213 or die $File::GlobMapper::Error;
214 for my $pair (@$pairs)
216 {
217 my ($from, $to) = @$pair;
218 move $from => $to ;
219 }
220 Here is an example that renames all c files to cpp.
222 $ rename '*.c' '#1.cpp'
224 A few example globmaps
226 Below are a few examples of globmaps
227 To copy all your .c file to a backup directory
229 '</my/home/*.c>' '</my/backup/#1.c>'
231 If you want to compress all
233 '</my/home/*.[ch]>' '<*.gz>'
235 To uncompress
237 '</my/home/*.[ch].gz>' '</my/home/#1.#2>'
239
241 File::Glob
242
244 The File::GlobMapper module was written by Paul Marquess,
245 pmqs@cpan.org.
246
248 Copyright (c) 2005 Paul Marquess. All rights reserved. This program is
249 free software; you can redistribute it and/or modify it under the same
250 terms as Perl itself.
251perl v5.12.4 2011-06-07 File::GlobMapper(3pm)