Debian Codegraph @

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

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