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