For.doc -- Documentation for For.rexx
Version 1.00 August 13, 1995 © Herbert Wollman
For.rexx is a utility program, written in AREXX, which will execute
one or more commands on each filename specified by one or more patterns.
USAGE:
> For pattern action containing one (or more) @(s) or <Alt N>(s)
OR> For [OPT] 'pat1 ["paterns with spaces"]' action1[¶action2[¶...]]
Each filename within the single quotes that matches a pattern will be
substituted for each @ in each action. Multiple actions are separated
by a ¶ (Alt p) character. In any action each <Alt N> character will be
replaced by the root_name of each matching pattern.
The root_name is the part of the matching pattern up to the last '.'
To modify the replacement character, separator character, or root_name
character, the OPT parameter must be -CRSN, where R is the replacement
character, S is the separator character, and N is the root_name character.
The default is -C@¶ i.e. -C@<Alt P><Alt N>
Because the <Alt N> character looks like the hyphen "-" on screen, I will
always indicate it as <Alt N>. Note that <Alt P> is ASCII(182) or HEX(B6),
and <Alt N> is ASCII(173) or HEX(AD).
EXAMPLE 1:
For h*.c lha a @.lha @
This will use lha to create separate compressed versions of each C source
code file (whose name ends with .c) that starts with the character h.
EXAMPLE 2:
For 'work*.for he*.for' "f77 -U @¶ <Alt N> -H >> Help"
This will first use f77 to compile each FORTRAN source file whose name
starts with either "work" or an h (and end with .for), useing the option -U.
Then it will run the resulting program with option -H, and send the output to
add onto a file called Help.
History:
The UNIX (Bourne) Shell has the keyword "for", which can create a loop that
executes multiple commands over each parameter in a list (i.e. filenames)
of arguments. The UNIX shell will automatically expand any patterns of
filenames containing a regular expression or wildcards into a list of
matches. Neither the standard Commodore Shell nor the Wshell has this
feature. If you want to perform several actions on a group of files, it is
usually easiest to use an editor to create a shell script first, and then
execute the script. I recently downloaded a Public Domain program called
"Foreach.lha" Version 1.0 by Dirk Farin, Kapellenweg 15, 72070 Tübingen,
Germany. I have used this Foreach program, and found it useful, but felt
that it could be modified to meet my personal tastes. Foreach accepts
either a single pattern with wildcards to be expanded, or a list of
complete filenames which it does not expand. It will perform only a single
command. In addition, its syntax requires the use of the &, > amd <
characters. These characters have special meaning to the Shell, and
therefore the action MUST be quoted. If any of the filenames contain
spaces, there must be a second level of quotes, and the required syntax can
get very messy. Unfortunately, Mr. Farin supplied only the executable, not
the source. Hence this version, For.rexx. It is written in AREXX, so the
source is the executable, and you can easilly customize it to your own
preferences.
Installation:
The actual filename expansion is performed by the FileList() function in
the rexxarplib.library, which must be in your libs: directory. It provides
the full ARP regular expressions. Since For.rexx is an AREXX program, it
should be placed in your REXX: directory.
Notes:
If you run For.rexx with option -H (or -h), you will see several lines that
give a brief summarry of the correct useage.
The syntax for For.rexx involves several special characters which have
specified default meanings. I chose to use the single quote, ', the at
sign, @, the paragraph sign, ¶ or <Alt P>, and the <Alt N>. They may
seem weird, but the Shell does NOT consider them to be special, so you do
NOT have to use any quotes on the command line, unless some of the
filenames contain spaces or other oddball characters. If you do not like
my choises, you can make permanent changes by modifying the source. Or you
can make a temporary change by using the command line option -C. The
-C must be immediately followed by one to three characters, with NO spaces.
The whole option word can be double quoted if required, i.e. "-C&;<"
The first option character defaults to @. Wherever this character
appears in an action, it will be replaced by the filenames that match the
patterns. I used the at sign, because the filename is placed "at" that
location. The second option character defaults to ¶, the paragraph sign,
which you type as <Alt P>, (both the Alt and P keys at the same time). It
is used to separate different actions whenever there are more than one.
In normal programming, when you type a single command on a line, your
editor shows the ¶ symbol at the end of each line as a seperator, so it is
easy to remember. The third option character defaults to - <Alt N>, which
means Name. Unfortunately it looks just like a hyphen on the screen.
Whereever this character appears in an action, it will be replaced by the
root filename of all matching patterns. This is the portion of the filename
up to but not including the last . (period) in the filename. If the name
does not have a period, then <Alt N> and @ have the same results. You can
have one or more actions and each action can involve one or more @'s and
<Alt N>'s. Note that the root_name <Alt N> replacement is performed AFTER
the @ replacement. Therefore if any of the filenames that match a pattern
contain the <Alt N> character, that character in the name will be replaced
by the root_name, which probably is not what you want. In that case , use
the options to change the root_name character.
After the optional -CRSN, the first argument is the list of filename
patterns to match. If you only want to use one pattern, just type it in.
If the pattern contains spaces, it must be enclosed in the usual double
quotes. In this case, you probably also want to enclose each @ and <Alt N>
in the actions in double quotes. If there are multiple patterns, you
indicate this by surrounding them with single quotes, as in EXAMPLE 2
above. If any of the filename patterns has a single quote in it, try
replaceing the single quote in the name with the ? wildcard, "Lots of Luck".
EXAMPLE 3:
For 'm* "Letter To J*"' Copy "@" "DF0:@.backup"
This will copy all files whose name begining with an M, and the
"Letter to Jill Smith", and the "Letter to Joe Jones" etc. to the DF0:
floppy, with the extension .backup added to the name.
***********************************************************************
GENERAL PUBLIC LICENSE
All of the files in this release may be freely distributed for any
purpose, however I request that if you redistribute them, please keep them
together with this doc file. If you have any comments, or discover any
Bugs, please notify me. If you wish to contact me, I can be reached at
Herbert Wollman, 5 Fowler Ter., Burlington, MA 01803, U. S. A.
Telephone (617) 272-2994.
E-mail at hwollman@mitre.org
I am the Secretary of the Amiga User Group of the Boston Computer Society.
You can contact me, and obtain any updates on the BCS Amiga bulletin
board at (617) 729-7340.
This program and documentation file are provided with no warrantee of any
type. Use at your own risk.
***********************************************************************
|
aminet net>