home *** CD-ROM | disk | FTP | other *** search
/ Aminet 10 / aminetcdnumber101996.iso / Aminet / util / cli / for_HBW.readme < prev    next >
Text File  |  1996-01-05  |  8KB  |  152 lines
  1. Short:        Adds wildcards and multiple cmds to CLI
  2. Author:       Herbert Wollman   hwollman@mitre.org
  3. Uploader:     Herbert Wollman   hwollman@mitre.org
  4. Type:         util/cli
  5. Requires:     util/libs/rexxarplib.library
  6. Distribution: All
  7.  
  8. For.doc -- Documentation for For.rexx
  9. Version 1.00 August 13, 1995  © Herbert Wollman
  10.  
  11. For.rexx is a utility program, written in AREXX, which will execute 
  12. one or more commands on each filename specified by one or more patterns.
  13.  
  14. USAGE:
  15.   >  For pattern action containing one (or more) @(s) or <Alt N>(s) 
  16. OR>  For [OPT] 'pat1 ["paterns with spaces"]' action1[¶action2[¶...]]
  17.   Each filename within the single quotes that matches a pattern will be
  18. substituted for each @ in each action.  Multiple actions are separated
  19. by a ¶ (Alt p) character.  In any action each ­ <Alt N> character will be
  20. replaced by the root_name of each matching pattern.
  21. The root_name is the part of the matching pattern up to the last '.'
  22.   To modify the replacement character, separator character, or root_name
  23. character, the OPT parameter must be -CRSN, where R is the replacement
  24. character, S is the separator character, and N is the root_name character.
  25. The default is -C@¶­ i.e.  -C@<Alt P><Alt N>
  26.  
  27. Because the <Alt N> character looks like the hyphen "-" on screen, I will
  28. always indicate it as <Alt N>.  Note that <Alt P> is ASCII(182) or HEX(B6), 
  29. and <Alt N> is ASCII(173) or HEX(AD).
  30.  
  31. EXAMPLE 1:
  32.   For h*.c lha a @.lha @
  33. This will use lha to create separate compressed versions of each C source 
  34. code file (whose name ends with .c) that starts with the character h. 
  35.  
  36. EXAMPLE 2:
  37.   For 'work*.for he*.for' "f77 -U @¶ <Alt N> -H >> Help"
  38. This will first use f77 to compile each FORTRAN source file whose name 
  39. starts with either "work" or an h (and end with .for), useing the option -U.
  40. Then it will run the resulting program with option -H, and send the output to 
  41. add onto a file called Help.
  42.  
  43.  
  44. History:
  45. The UNIX (Bourne) Shell has the keyword "for", which can create a loop that 
  46. executes multiple commands over each parameter in a list (i.e. filenames) 
  47. of arguments.  The UNIX shell will automatically expand any patterns of 
  48. filenames containing a regular expression or wildcards into a list of 
  49. matches.  Neither the standard Commodore Shell nor the Wshell has this 
  50. feature.  If you want to perform several actions on a group of files, it is 
  51. usually easiest to use an editor to create a shell script first, and then 
  52. execute the script.  I recently downloaded a Public Domain program called 
  53. "Foreach.lha" Version 1.0 by Dirk Farin, Kapellenweg 15, 72070 Tübingen, 
  54. Germany.  I have used this Foreach program, and found it useful, but felt 
  55. that it could be modified to meet my personal tastes.  Foreach accepts 
  56. either a single pattern with wildcards to be expanded, or a list of 
  57. complete filenames which it does not expand.  It will perform only a single 
  58. command.  In addition, its syntax requires the use of the &, > amd < 
  59. characters.  These characters have special meaning to the Shell, and 
  60. therefore the action MUST be quoted.  If any of the filenames contain 
  61. spaces, there must be a second level of quotes, and the required syntax can 
  62. get very messy.  Unfortunately, Mr. Farin supplied only the executable, not 
  63. the source.  Hence this version, For.rexx.  It is written in AREXX, so the 
  64. source is the executable, and you can easilly customize it to your own 
  65. preferences.  
  66.  
  67. Installation:
  68. The actual filename expansion is performed by the FileList() function in 
  69. the rexxarplib.library, which must be in your libs: directory.  It provides 
  70. the full ARP regular expressions.  Since For.rexx is an AREXX program, it 
  71. should be placed in your REXX: directory.  
  72.  
  73. Notes:
  74. If you run For.rexx with option -H (or -h), you will see several lines that 
  75. give a brief summarry of the correct useage.  
  76.  
  77. The syntax for For.rexx involves several special characters which have 
  78. specified default meanings.  I chose to use the single quote, ', the at 
  79. sign, @, the paragraph sign, ¶ or <Alt P>, and the ­ <Alt N>.  They may 
  80. seem weird, but the Shell does NOT consider them to be special, so you do 
  81. NOT have to use any quotes on the command line, unless some of the 
  82. filenames contain spaces or other oddball characters.  If you do not like 
  83. my choises, you can make permanent changes by modifying the source.  Or you 
  84. can make a temporary change by using the command line option -C.  The 
  85. -C must be immediately followed by one to three characters, with NO spaces. 
  86. The whole option word can be double quoted if required, i.e. "-C&;<"  
  87.  
  88. The first option character defaults to @.  Wherever this character 
  89. appears in an action, it will be replaced by the filenames that match the 
  90. patterns.  I used the at sign, because the filename is placed "at" that 
  91. location.  The second option character defaults to ¶, the paragraph sign, 
  92. which you type as <Alt P>, (both the Alt and P keys at the same time).  It 
  93. is used to separate different actions whenever there are more than one.  
  94. In normal programming, when you type a single command on a line, your 
  95. editor shows the ¶ symbol at the end of each line as a seperator, so it is 
  96. easy to remember.  The third option character defaults to - <Alt N>, which 
  97. means Name.  Unfortunately it looks just like a hyphen on the screen.  
  98. Whereever this character appears in an action, it will be replaced by the 
  99. root filename of all matching patterns.  This is the portion of the filename 
  100. up to but not including the last . (period) in the filename.  If the name 
  101. does not have a period, then <Alt N> and @ have the same results.  You can 
  102. have one or more actions and each action can involve one or more @'s and 
  103. <Alt N>'s.  Note that the root_name <Alt N> replacement is performed AFTER 
  104. the @ replacement.  Therefore if any of the filenames that match a pattern 
  105. contain the <Alt N> character, that character in the name will be replaced 
  106. by the root_name, which probably is not what you want.  In that case , use 
  107. the options to change the root_name character.  
  108.  
  109. After the optional -CRSN, the first argument is the list of filename 
  110. patterns to match.  If you only want to use one pattern, just type it in. 
  111. If the pattern contains spaces, it must be enclosed in the usual double 
  112. quotes.  In this case, you probably also want to enclose each @ and <Alt N> 
  113. in the actions in double quotes.  If there are multiple patterns, you 
  114. indicate this by surrounding them with single quotes, as in EXAMPLE 2 
  115. above.  If any of the filename patterns has a single quote in it, try 
  116. replaceing the single quote in the name with the ? wildcard, "Lots of Luck".
  117.  
  118. EXAMPLE 3:
  119. For 'm* "Letter To J*"' Copy "@" "DF0:@.backup"
  120. This will copy all files whose name begining with an M, and the 
  121. "Letter to Jill Smith", and the "Letter to Joe Jones" etc. to the DF0: 
  122. floppy, with the extension .backup added to the name. 
  123.  
  124.  
  125. ***********************************************************************
  126.  
  127. GENERAL PUBLIC LICENSE
  128. All of the files in this release may be freely distributed for any 
  129. purpose, however I request that if you redistribute them, please keep them 
  130. together with this doc file.  If you have any comments, or discover any 
  131. Bugs, please notify me.  If you wish to contact me, I can be reached at 
  132. Herbert Wollman, 5 Fowler Ter., Burlington, MA 01803, U. S. A.
  133. Telephone (617) 272-2994.
  134. E-mail at hwollman@mitre.org
  135.  
  136. I am the Secretary of the Amiga User Group of the Boston Computer Society. 
  137. You can contact me, and obtain any updates on the BCS Amiga bulletin 
  138. board at (617) 729-7340.
  139.  
  140. This program and documentation file are provided with no warrantee of any 
  141. type.  Use at your own risk.  
  142.  
  143. ***********************************************************************
  144.  
  145.  
  146. ============================= Archive contents =============================
  147.  
  148. Original  Packed Ratio    Date     Time    Name
  149. -------- ------- ----- --------- --------  -------------
  150. -------- ------- ----- --------- --------
  151.        0       0  0.0% 17-Nov-95 16:31:52   0 files
  152.