Debian Codegraph @

upstream/debian-trixie/man3/File::File::Rename.3pm

raw
1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
60 . if \nF \{\
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{\
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\" ========================================================================
72 .\"
73 .IX Title "File::Rename 3pm"
74 .TH File::Rename 3pm "2024-01-01" "perl v5.36.0" "User Contributed Perl Documentation"
75 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
76 .\" way too many mistakes in technical documents.
77 .if n .ad l
78 .nh
79 .SH "NAME"
80 File::Rename \- Perl extension for renaming multiple files
81 .SH "SYNOPSIS"
82 .IX Header "SYNOPSIS"
83 .Vb 2
84 \& use File::Rename qw(rename); # hide CORE::rename
85 \& rename \e@ARGV, sub { s/\e.pl\ez/.pm/ }, 1;
86 \&
87 \& use File::Rename;
88 \& File::Rename::rename \e@ARGV, \*(Aq$_ = lc\*(Aq;
89 \&
90 \& use File::Rename qw(:config no_require_order);
91 .Ve
92 .SH "DESCRIPTION"
93 .IX Header "DESCRIPTION"
94 .SS "\s-1USE OPTIONS\s0"
95 .IX Subsection "USE OPTIONS"
96 Parameters to \f(CW\*(C`use File::Rename\*(C'\fR consists of
97 functions to be imported and configuration options.
98 .PP
99 The only exported function is \f(CW\*(C`rename()\*(C'\fR. The
100 configuation options are preceded by :config,
101 and are passed to File::Rename::Options.
102 .SS "\s-1FUNCTIONS\s0"
103 .IX Subsection "FUNCTIONS"
104 .ie n .IP """rename( FILES, CODE [, VERBOSE])""" 4
105 .el .IP "\f(CWrename( FILES, CODE [, VERBOSE])\fR" 4
106 .IX Item "rename( FILES, CODE [, VERBOSE])"
107 rename \s-1FILES\s0 using \s-1CODE,\s0
108 if \s-1FILES\s0 is empty read list of files from stdin
109 .ie n .IP """rename_files( CODE, VERBOSE, FILES)""" 4
110 .el .IP "\f(CWrename_files( CODE, VERBOSE, FILES)\fR" 4
111 .IX Item "rename_files( CODE, VERBOSE, FILES)"
112 rename \s-1FILES\s0 using \s-1CODE\s0
113 .ie n .IP """rename_list( CODE, VERBOSE, HANDLE [, FILENAME])""" 4
114 .el .IP "\f(CWrename_list( CODE, VERBOSE, HANDLE [, FILENAME])\fR" 4
115 .IX Item "rename_list( CODE, VERBOSE, HANDLE [, FILENAME])"
116 rename a list of file read from \s-1HANDLE,\s0 using \s-1CODE\s0
117 .SS "\s-1OPTIONS\s0"
118 .IX Subsection "OPTIONS"
119 .IP "\s-1FILES\s0" 8
120 .IX Item "FILES"
121 List of files to be renamed,
122 for \f(CW\*(C`rename\*(C'\fR must be an \s-1ARRAY\s0 reference
123 .IP "\s-1CODE\s0" 8
124 .IX Item "CODE"
125 Subroutine to change file names,
126 for \f(CW\*(C`rename\*(C'\fR can be a string,
127 otherwise it is a code reference
128 .IP "\s-1VERBOSE\s0" 8
129 .IX Item "VERBOSE"
130 Flag for printing names of files successfully renamed,
131 optional for \f(CW\*(C`rename\*(C'\fR
132 .IP "\s-1HANDLE\s0" 8
133 .IX Item "HANDLE"
134 Filehandle to read file names to be renames
135 .IP "\s-1FILENAME\s0 (Optional)" 8
136 .IX Item "FILENAME (Optional)"
137 Name of file that \s-1HANDLE\s0 reads from
138 .SS "\s-1HASH\s0"
139 .IX Subsection "HASH"
140 Either \s-1CODE\s0 or \s-1VERBOSE\s0 can be a \s-1HASH\s0 of options.
141 .PP
142 If \s-1CODE\s0 is a \s-1HASH, VERBOSE\s0 is ignored
143 and \s-1CODE\s0 is supplied by the \fB_code\fR key.
144 .PP
145 Other options are
146 .IP "\fBverbose\fR" 16
147 .IX Item "verbose"
148 As \s-1VERBOSE\s0 above, provided by \fB\-v\fR.
149 .IP "\fBinput_null\fR" 16
150 .IX Item "input_null"
151 Input separator \e0 when reading file names from stdin.
152 .IP "\fBno_action\fR" 16
153 .IX Item "no_action"
154 Print names of files to be renamed, but do not rename
155 (i.e. take no action), provided by \fB\-n\fR.
156 .IP "\fBover_write\fR" 16
157 .IX Item "over_write"
158 Allow files to be over-written by the renaming, provided by \fB\-f\fR.
159 .IP "\fBfilename_only\fR" 16
160 .IX Item "filename_only"
161 Only apply renaming to the filename component of the path,
162 provided by \fB\-d\fR.
163 .IP "\fBshow_help\fR" 16
164 .IX Item "show_help"
165 Print help, provided by \fB\-h\fR.
166 .IP "\fBshow_manual\fR" 16
167 .IX Item "show_manual"
168 Print manual page, provided by \fB\-m\fR.
169 .IP "\fBshow_version\fR" 16
170 .IX Item "show_version"
171 Print version number, provided by \fB\-V\fR.
172 .IP "\fBunicode_strings\fR" 16
173 .IX Item "unicode_strings"
174 Enable unicode_strings feature, provided by \fB\-u\fR.
175 .IP "\fBencoding\fR" 16
176 .IX Item "encoding"
177 Encoding for filenames, provided by \fB\-u\fR.
178 .SS "\s-1EXPORT\s0"
179 .IX Subsection "EXPORT"
180 rename
181 .SH "ENVIRONMENT"
182 .IX Header "ENVIRONMENT"
183 No environment variables are used.
184 .SH "SEE ALSO"
185 .IX Header "SEE ALSO"
186 \&\fBmv\fR\|(1), \fBperl\fR\|(1), \fBrename\fR\|(1)
187 .SH "AUTHOR"
188 .IX Header "AUTHOR"
189 Robin Barker <[email protected]>
190 .SH "Acknowledgements"
191 .IX Header "Acknowledgements"
192 Based on code from Larry Wall.
193 .PP
194 Options \fB\-e\fR, \fB\-f\fR, \fB\-n\fR suggested
195 by more recent code written by Aristotle Pagaltzis.
196 .SH "DIAGNOSTICS"
197 .IX Header "DIAGNOSTICS"
198 Errors from the code argument are not trapped.
199 .SH "COPYRIGHT AND LICENSE"
200 .IX Header "COPYRIGHT AND LICENSE"
201 Copyright (C) 2004, 2005, 2006, 2011, 2018, 2021, 2022, 2023
202 by Robin Barker
203 .PP
204 This library is free software; you can redistribute it and/or modify
205 it under the same terms as Perl itself, either Perl version 5.8.4 or,
206 at your option, any later version of Perl 5 you may have available.