diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/File::GlobMapper.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/File::GlobMapper.3pm | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/File::GlobMapper.3pm b/upstream/mageia-cauldron/man3pm/File::GlobMapper.3pm new file mode 100644 index 00000000..2cbbe5e3 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/File::GlobMapper.3pm @@ -0,0 +1,350 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "File::GlobMapper 3pm" +.TH File::GlobMapper 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +File::GlobMapper \- Extend File Glob to Allow Input and Output Files +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use File::GlobMapper qw( globmap ); +\& +\& my $aref = globmap $input => $output +\& or die $File::GlobMapper::Error ; +\& +\& my $gm = File::GlobMapper\->new( $input => $output ) +\& or die $File::GlobMapper::Error ; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module needs Perl5.005 or better. +.PP +This module takes the existing \f(CW\*(C`File::Glob\*(C'\fR module as a starting point and +extends it to allow new filenames to be derived from the files matched by +\&\f(CW\*(C`File::Glob\*(C'\fR. +.PP +This can be useful when carrying out batch operations on multiple files that +have both an input filename and output filename and the output file can be +derived from the input filename. Examples of operations where this can be +useful include, file renaming, file copying and file compression. +.SS "Behind The Scenes" +.IX Subsection "Behind The Scenes" +To help explain what \f(CW\*(C`File::GlobMapper\*(C'\fR does, consider what code you +would write if you wanted to rename all files in the current directory +that ended in \f(CW\*(C`.tar.gz\*(C'\fR to \f(CW\*(C`.tgz\*(C'\fR. So say these files are in the +current directory +.PP +.Vb 3 +\& alpha.tar.gz +\& beta.tar.gz +\& gamma.tar.gz +.Ve +.PP +and they need renamed to this +.PP +.Vb 3 +\& alpha.tgz +\& beta.tgz +\& gamma.tgz +.Ve +.PP +Below is a possible implementation of a script to carry out the rename +(error cases have been omitted) +.PP +.Vb 4 +\& foreach my $old ( glob "*.tar.gz" ) +\& { +\& my $new = $old; +\& $new =~ s#(.*)\e.tar\e.gz$#$1.tgz# ; +\& +\& rename $old => $new +\& or die "Cannot rename \*(Aq$old\*(Aq to \*(Aq$new\*(Aq: $!\en; +\& } +.Ve +.PP +Notice that a file glob pattern \f(CW\*(C`*.tar.gz\*(C'\fR was used to match the +\&\f(CW\*(C`.tar.gz\*(C'\fR files, then a fairly similar regular expression was used in +the substitute to allow the new filename to be created. +.PP +Given that the file glob is just a cut-down regular expression and that it +has already done a lot of the hard work in pattern matching the filenames, +wouldn't it be handy to be able to use the patterns in the fileglob to +drive the new filename? +.PP +Well, that's \fIexactly\fR what \f(CW\*(C`File::GlobMapper\*(C'\fR does. +.PP +Here is same snippet of code rewritten using \f(CW\*(C`globmap\*(C'\fR +.PP +.Vb 6 +\& for my $pair (globmap \*(Aq<*.tar.gz>\*(Aq => \*(Aq<#1.tgz>\*(Aq ) +\& { +\& my ($from, $to) = @$pair; +\& rename $from => $to +\& or die "Cannot rename \*(Aq$old\*(Aq to \*(Aq$new\*(Aq: $!\en; +\& } +.Ve +.PP +So how does it work? +.PP +Behind the scenes the \f(CW\*(C`globmap\*(C'\fR function does a combination of a +file glob to match existing filenames followed by a substitute +to create the new filenames. +.PP +Notice how both parameters to \f(CW\*(C`globmap\*(C'\fR are strings that are delimited by <>. +This is done to make them look more like file globs \- it is just syntactic +sugar, but it can be handy when you want the strings to be visually +distinctive. The enclosing <> are optional, so you don't have to use them \- in +fact the first thing globmap will do is remove these delimiters if they are +present. +.PP +The first parameter to \f(CW\*(C`globmap\*(C'\fR, \f(CW\*(C`*.tar.gz\*(C'\fR, is an \fIInput File Glob\fR. +Once the enclosing "< ... >" is removed, this is passed (more or +less) unchanged to \f(CW\*(C`File::Glob\*(C'\fR to carry out a file match. +.PP +Next the fileglob \f(CW\*(C`*.tar.gz\*(C'\fR is transformed behind the scenes into a +full Perl regular expression, with the additional step of wrapping each +transformed wildcard metacharacter sequence in parenthesis. +.PP +In this case the input fileglob \f(CW\*(C`*.tar.gz\*(C'\fR will be transformed into +this Perl regular expression +.PP +.Vb 1 +\& ([^/]*)\e.tar\e.gz +.Ve +.PP +Wrapping with parenthesis allows the wildcard parts of the Input File +Glob to be referenced by the second parameter to \f(CW\*(C`globmap\*(C'\fR, \f(CW\*(C`#1.tgz\*(C'\fR, +the \fIOutput File Glob\fR. This parameter operates just like the replacement +part of a substitute command. The difference is that the \f(CW\*(C`#1\*(C'\fR syntax +is used to reference sub-patterns matched in the input fileglob, rather +than the \f(CW$1\fR syntax that is used with perl regular expressions. In +this case \f(CW\*(C`#1\*(C'\fR is used to refer to the text matched by the \f(CW\*(C`*\*(C'\fR in the +Input File Glob. This makes it easier to use this module where the +parameters to \f(CW\*(C`globmap\*(C'\fR are typed at the command line. +.PP +The final step involves passing each filename matched by the \f(CW\*(C`*.tar.gz\*(C'\fR +file glob through the derived Perl regular expression in turn and +expanding the output fileglob using it. +.PP +The end result of all this is a list of pairs of filenames. By default +that is what is returned by \f(CW\*(C`globmap\*(C'\fR. In this example the data structure +returned will look like this +.PP +.Vb 4 +\& ( [\*(Aqalpha.tar.gz\*(Aq => \*(Aqalpha.tgz\*(Aq], +\& [\*(Aqbeta.tar.gz\*(Aq => \*(Aqbeta.tgz\*(Aq ], +\& [\*(Aqgamma.tar.gz\*(Aq => \*(Aqgamma.tgz\*(Aq] +\& ) +.Ve +.PP +Each pair is an array reference with two elements \- namely the \fIfrom\fR +filename, that \f(CW\*(C`File::Glob\*(C'\fR has matched, and a \fIto\fR filename that is +derived from the \fIfrom\fR filename. +.SS Limitations +.IX Subsection "Limitations" +\&\f(CW\*(C`File::GlobMapper\*(C'\fR has been kept simple deliberately, so it isn't intended to +solve all filename mapping operations. Under the hood \f(CW\*(C`File::Glob\*(C'\fR (or for +older versions of Perl, \f(CW\*(C`File::BSDGlob\*(C'\fR) is used to match the files, so you +will never have the flexibility of full Perl regular expression. +.SS "Input File Glob" +.IX Subsection "Input File Glob" +The syntax for an Input FileGlob is identical to \f(CW\*(C`File::Glob\*(C'\fR, except +for the following +.IP 1. 5 +No nested {} +.IP 2. 5 +Whitespace does not delimit fileglobs. +.IP 3. 5 +The use of parenthesis can be used to capture parts of the input filename. +.IP 4. 5 +If an Input glob matches the same file more than once, only the first +will be used. +.PP +The syntax +.IP \fB~\fR 5 +.IX Item "~" +.PD 0 +.IP \fB~user\fR 5 +.IX Item "~user" +.IP \fB.\fR 5 +.IX Item "." +.PD +Matches a literal '.'. +Equivalent to the Perl regular expression +.Sp +.Vb 1 +\& \e. +.Ve +.IP \fB*\fR 5 +.IX Item "*" +Matches zero or more characters, except '/'. Equivalent to the Perl +regular expression +.Sp +.Vb 1 +\& [^/]* +.Ve +.IP \fB?\fR 5 +.IX Item "?" +Matches zero or one character, except '/'. Equivalent to the Perl +regular expression +.Sp +.Vb 1 +\& [^/]? +.Ve +.IP \fB\e\fR 5 +.IX Item "" +Backslash is used, as usual, to escape the next character. +.IP \fB[]\fR 5 +.IX Item "[]" +Character class. +.IP \fB{,}\fR 5 +.IX Item "{,}" +Alternation +.IP \fB()\fR 5 +.IX Item "()" +Capturing parenthesis that work just like perl +.PP +Any other character it taken literally. +.SS "Output File Glob" +.IX Subsection "Output File Glob" +The Output File Glob is a normal string, with 2 glob-like features. +.PP +The first is the '*' metacharacter. This will be replaced by the complete +filename matched by the input file glob. So +.PP +.Vb 1 +\& *.c *.Z +.Ve +.PP +The second is +.PP +Output FileGlobs take the +.IP """*""" 5 +The "*" character will be replaced with the complete input filename. +.IP #1 5 +.IX Item "#1" +Patterns of the form /#\ed/ will be replaced with the +.SS "Returned Data" +.IX Subsection "Returned Data" +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "A Rename script" +.IX Subsection "A Rename script" +Below is a simple "rename" script that uses \f(CW\*(C`globmap\*(C'\fR to determine the +source and destination filenames. +.PP +.Vb 2 +\& use File::GlobMapper qw(globmap) ; +\& use File::Copy; +\& +\& die "rename: Usage rename \*(Aqfrom\*(Aq \*(Aqto\*(Aq\en" +\& unless @ARGV == 2 ; +\& +\& my $fromGlob = shift @ARGV; +\& my $toGlob = shift @ARGV; +\& +\& my $pairs = globmap($fromGlob, $toGlob) +\& or die $File::GlobMapper::Error; +\& +\& for my $pair (@$pairs) +\& { +\& my ($from, $to) = @$pair; +\& move $from => $to ; +\& } +.Ve +.PP +Here is an example that renames all c files to cpp. +.PP +.Vb 1 +\& $ rename \*(Aq*.c\*(Aq \*(Aq#1.cpp\*(Aq +.Ve +.SS "A few example globmaps" +.IX Subsection "A few example globmaps" +Below are a few examples of globmaps +.PP +To copy all your .c file to a backup directory +.PP +.Vb 1 +\& \*(Aq</my/home/*.c>\*(Aq \*(Aq</my/backup/#1.c>\*(Aq +.Ve +.PP +If you want to compress all +.PP +.Vb 1 +\& \*(Aq</my/home/*.[ch]>\*(Aq \*(Aq<*.gz>\*(Aq +.Ve +.PP +To uncompress +.PP +.Vb 1 +\& \*(Aq</my/home/*.[ch].gz>\*(Aq \*(Aq</my/home/#1.#2>\*(Aq +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +File::Glob +.SH AUTHOR +.IX Header "AUTHOR" +The \fIFile::GlobMapper\fR module was written by Paul Marquess, \fIpmqs@cpan.org\fR. +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright (c) 2005 Paul Marquess. All rights reserved. +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. |