29efe1b9 |
1 | \cfg{man-identity}{multi}{1}{2004-11-20}{Simon Tatham}{Simon Tatham} |
29efe1b9 |
2 | |
92dccb8d |
3 | \define{dash} \u2013{-} |
4 | |
8a48d402 |
5 | \title Man page for \cw{multi} |
29efe1b9 |
6 | |
8a48d402 |
7 | \U NAME |
29efe1b9 |
8 | |
92dccb8d |
9 | \cw{multi} \dash bulk file rename/copy utility using Perl regexps |
29efe1b9 |
10 | |
8a48d402 |
11 | \U SYNOPSIS |
29efe1b9 |
12 | |
13 | \c multi [ -n | -q ] [ -r ] cmd perlfragment file [file...] |
14 | \e bbbbb bb bb bb iii iiiiiiiiiiii iiii iiii |
15 | \c multi [ -n | -q ] [ -r ] - cmd cmd - perlfragment file [file...] |
16 | \e bbbbb bb bb bb iii iii iiiiiiiiiiii iiii iiii |
17 | |
8a48d402 |
18 | \U DESCRIPTION |
29efe1b9 |
19 | |
20 | \cw{multi} is a utility which allows you to invoke a command |
21 | (typically, but not always, \cw{mv} or \cw{cp}) on a lot of files in |
22 | a complicated way. |
23 | |
24 | The command-line arguments to \cw{multi} include a command, a set of |
cf1b2a5e |
25 | filenames, and a fragment of Perl. For each of the filenames, |
29efe1b9 |
26 | \cw{multi} will use the fragment of Perl to transform the filename |
27 | into a new filename, and will then invoke the given command, passing |
28 | the old and new filenames as arguments. |
29 | |
30 | \cw{multi} is most often useful as a bulk rename or copy utility, by |
31 | passing \cw{mv} or \cw{cp} as the command. However, it can have more |
32 | complex uses as well; see the examples below. |
33 | |
8a48d402 |
34 | \U ARGUMENTS |
29efe1b9 |
35 | |
36 | \dt \e{cmd} |
37 | |
38 | \dd Provides the command to which pairs of filenames will eventually |
39 | be passed. If this is just one word (typically \c{cp} or \c{mv}), |
40 | you can simply supply that word on the command line. |
41 | |
42 | \lcont{ |
43 | |
44 | A multiple-word command (such as \c{ln -s} or \c{svn mv}) can be |
45 | used if you place it between two arguments containing only minus |
46 | signs. |
47 | |
48 | } |
49 | |
50 | \dt \e{perlfragment} |
51 | |
52 | \dd This fragment of Perl will be run for each file name you supply. |
53 | The file name will be passed in in the special Perl variable |
54 | \cw{$_}, and the altered file name should be passed out in \cw{$_} |
55 | as well. (Therefore, the simplest kind of Perl fragment you could |
56 | use is a single \cw{s///} substitution command.) |
57 | |
58 | \lcont{ |
59 | |
60 | All the Perl variable names used internally by \cw{multi} itself |
61 | begin with two underscore characters. Therefore, your Perl fragment |
62 | can safely define its own variables (provided they do not begin with |
63 | two underscores), without worrying about upsetting the functioning |
64 | of \cw{multi}. |
65 | |
66 | } |
67 | |
68 | \dt \e{files} |
69 | |
70 | \dd After the Perl fragment, \cw{multi} expects a list of file names |
71 | to be transformed. Typically these will be generated by typing one |
72 | or more wildcard expressions on the shell command line. |
73 | |
8a48d402 |
74 | \U OPTIONS |
29efe1b9 |
75 | |
76 | By default, \cw{multi} will print every command it executes on |
77 | standard output, so that you can see what it has just done (in case |
78 | it turns out to be wrong!). |
79 | |
80 | Bourne-shell-style quoting is provided, so that copying the output |
81 | of \cw{multi} and pasting it into a shell script or on to a shell |
82 | command line should work correctly. |
83 | |
84 | \dt \cw{-n} |
85 | |
86 | \dd Do not actually execute the commands. Instead, \e{only} print |
87 | them on standard output as they would be executed. (Useful for a dry |
88 | run to make sure your Perl does what you meant it to do. When you've |
89 | got it right, take off the \cw{-n} option and let it run for real.) |
90 | |
91 | \dt \cw{-q} |
92 | |
93 | \dd \e{Only} execute the commands, without printing them. (Useful |
94 | for running within a larger script.) |
95 | |
96 | By default, the two arguments passed to each invocation of the |
97 | subcommand are the original filename and the transformed filename, |
98 | in that order. |
99 | |
100 | \dt \cw{-r} |
101 | |
102 | \dd Reverse the order of arguments to the subcommand, so that it |
103 | receives the transformed file name \e{before} the original one. |
104 | |
8a48d402 |
105 | \U EXAMPLES |
29efe1b9 |
106 | |
107 | The simplest use of \cw{multi} is to rename a large number of files. |
108 | Suppose, for example, you have a lot of text files with \cw{.txt} |
109 | extensions, and you prefer to use \cw{.text} extensions: |
110 | |
111 | \c $ multi mv 's/.txt$/.text/' *.txt |
112 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
113 | \c mv bar.txt bar.text |
114 | \c mv baz.txt baz.text |
115 | \c mv foo.txt foo.text |
116 | |
117 | If you wanted to copy the files rather than moving them, the command |
118 | becomes |
119 | |
120 | \c $ multi cp 's/.txt$/.text/' *.txt |
121 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
122 | \c cp bar.txt bar.text |
123 | \c cp baz.txt baz.text |
124 | \c cp foo.txt foo.text |
125 | |
126 | If you wanted to create symbolic links, you now need the command |
127 | \cw{ln -s}, which is composed of two words. So you need to tell |
128 | \cw{multi} where the command words stop and the Perl begins, using |
129 | two single-dash arguments: |
130 | |
131 | \c $ multi - ln -s - 's/.txt$/.text/' *.txt |
132 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
133 | \c ln -s bar.txt bar.text |
134 | \c ln -s baz.txt baz.text |
135 | \c ln -s foo.txt foo.text |
136 | |
137 | Note that simply quoting the two-word command would not have worked, |
138 | because \cw{multi} would have assumed you genuinely meant a one-word |
139 | command which had a space in the middle... |
140 | |
141 | \c $ multi "ln -s" 's/.txt$/.text/' *.txt |
142 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
143 | \c 'ln -s' bar.txt bar.text |
144 | \c 'ln -s' baz.txt baz.text |
145 | \c 'ln -s' foo.txt foo.text |
146 | |
147 | ... which was almost certainly not what you wanted! |
148 | |
149 | The version control utility \e{Subversion} has a subcommand for |
150 | moving files around within your working directory. However, it does |
151 | not support wildcards, because \cw{svn mv} expects to see |
152 | \e{precisely} two arguments. So if you want to move a whole load of |
153 | files into a subdirectory, a command such as \cw{svn mv win*.c |
154 | windows} will not work. \cw{multi} comes to the rescue: |
155 | |
156 | \c $ multi - svn mv - 's:^:windows/:' win*.c |
157 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
158 | \c svn mv winmain.c windows/winmain.c |
159 | \c svn mv winprint.c windows/winprint.c |
160 | \c svn mv winutils.c windows/winutils.c |
161 | |
162 | Of course, your Perl fragment can be more complex than just a |
9b9125db |
163 | \cw{s///} command. Here's a means of tidying up after extracting an |
29efe1b9 |
164 | MS-DOS zip file containing all filenames in upper case: |
165 | |
166 | \c $ multi mv 'y/A-Z/a-z/' *[A-Z]* |
167 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
168 | \c mv HEADER.H header.h |
169 | \c mv MAIN.C main.c |
170 | \c mv STUFF.C stuff.c |
171 | |
9b9125db |
172 | Here's an example using \cw{-r}. Suppose you have lots of \c{.wav} |
173 | sound files, and you want to encode them all into compressed Ogg |
174 | Vorbis format. The \c{oggenc} command expects its destination file |
175 | name as an argument to the \c{-o} parameter, so it's most convenient |
176 | to put that \e{before} the input file name: |
177 | |
178 | \c $ multi -r - oggenc -o - 's/.wav$/.ogg/' *.wav |
179 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
180 | \c oggenc -o bar.ogg bar.wav |
181 | \c oggenc -o baz.ogg baz.wav |
182 | \c oggenc -o foo.ogg foo.wav |
29efe1b9 |
183 | |
184 | Finally, here's a general technique for going beyond the limits of |
185 | \cw{multi}, in the case where you need to do something more |
186 | ambitious with your two file names. Suppose you want to use one file |
187 | name as the target of a shell redirection operator, for example. |
188 | |
189 | \c $ multi - sh -c 'grep foo $0 > $1' - 's/.txt$/.grepped/' *.txt |
1a969de4 |
190 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
29efe1b9 |
191 | \c sh -c 'grep foo $0 > $1' bar.txt bar.grepped |
192 | \c sh -c 'grep foo $0 > $1' baz.txt baz.grepped |
193 | \c sh -c 'grep foo $0 > $1' foo.txt foo.grepped |
194 | |
195 | As each of these commands will be executed, the (explicitly invoked) |
196 | shell will substitute the two filename arguments in place of \cw{$0} |
197 | and \cw{$1}, so that the \e{effect} will be that of running a set of |
198 | commands like |
199 | |
200 | \c grep foo bar.txt > bar.grepped |
201 | \c grep foo baz.txt > baz.grepped |
202 | \c grep foo foo.txt > foo.grepped |
203 | |
8a48d402 |
204 | \U ACKNOWLEDGEMENTS |
29efe1b9 |
205 | |
206 | The O'Reilly book \q{Programming Perl} includes a simple example |
207 | script which contains the core idea of this program. It takes a |
208 | single Perl argument followed by filenames, and invokes Perl's |
209 | internal \cw{rename} function. \cw{multi} is a complete rewrite of |
210 | this basic idea, supplying more options and configurability. |
da0f8522 |
211 | |
8a48d402 |
212 | \U LICENCE |
da0f8522 |
213 | |
214 | \cw{multi} is free software, distributed under the MIT licence. Type |
215 | \cw{multi --licence} to see the full licence text. |
1166ff62 |
216 | |
217 | \versionid $Id$ |