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