home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 640a.lha / Foreach / foreach.doc < prev    next >
Text File  |  1992-05-28  |  6KB  |  171 lines
  1.  
  2.  
  3.  
  4.  
  5. When the AmigaWorld Tech Journal stop publication, I was working on an
  6. article for the next issue,  _Writing a 2.0 command_.  I decided to
  7. do a command that would be fairly useful, and use many of the new 2.0
  8. AmigaDOS features.  So I decided on a Foreach command, sort of like
  9. an improved LIST LFORMAT option.  Well, I still want to sell the article
  10. sometime (which includes the source to the command) but I figured,
  11. why not release the command on its own ?
  12.  
  13. Anyway, here it is..
  14.  
  15.  
  16.             andy
  17.  
  18.  
  19.  
  20.  
  21.  
  22. Copyright 1992 Andy Finkel
  23.  
  24.  
  25.  
  26. NAME:       FOREACH
  27. TEMPLATE: NAME, PATH/K, IN/M, FROM/K/N, TO/K/N, STEP/K/N, SCRIPT/K, COM/K, 
  28.       WITH/K, ALL/S,FILES/S, DIRS/S, SORT/S, SINCE/K, UPTO/K
  29.  
  30. PURPOSE:  To perform a script loop using local variables to contain loop 
  31.       values.
  32.  
  33. The Foreach command allows you to loop within scripts with a loop variable 
  34. set to a value selected from a list of names.  Foreach will execute a script 
  35. of your choice; if no script is given, the foreach command allows you to type 
  36. a temporary one in from the command line.  If used from within a script, the 
  37. foreach command will loop within the script.
  38.  
  39. The foreach loop is bounded by a END directive (or an EOF, or a control-\).
  40.  
  41. The foreach loop is executed once for each name specified by the IN keyword.
  42. Full pattern matching is supported.  Names specified with the IN option don't
  43. necessarily have to actually exist as files or directories to be used,
  44. which allows you to create files.
  45.  
  46. The NAME keyword allows you to pick a variable name; each time through the 
  47. loop, that variable is set to the name currently selected from the list of 
  48. names specified with the IN keyword.
  49.  
  50. If no name is specified, no local variables will be created.
  51.  
  52. The PATH keyword allows you to select a local variable name where the PATH 
  53. will be stored; if no PATH keyword is specified, this will be stored in a 
  54. variable with the same name as NAME but with .PATH appended.
  55.  
  56. The basename and extension local variables work in a similar manner, except 
  57. that the names are always based on the name specied by the NAME keyword with
  58. an appended extension.  The extension for the basename of the file found 
  59. is .BASE   The extension (if any) will be found in the variable name with 
  60. the .EXT extension.
  61.  
  62. The nametype local variable contains the type of thing, either dir
  63. (for directory), file (for file), or name (for couldn't find one of those).
  64.  
  65. Remember, to access variables that contain non-alphanumeric characters 
  66. (like a .) on the command line (like a .) you have to surround the name 
  67. with { } like: ${i.base}
  68.  
  69. The ALL keyword causes any pattern matching used in any member of the IN 
  70. namelist to be recursive.
  71.  
  72. The FILES keyword is a 'files only' keyword.  When this is used, only files 
  73. (non-directories) will be selected from the list of IN names.
  74.  
  75. The DIRS keyword is a 'directories only' keyword.  When this is used, only 
  76. directories (non-files) will be selected from the list of IN names.
  77.  
  78. In either the file only or the directory only mode all names which are 
  79. neither files or directories (ie names that don't exist) are selected as well.
  80.  
  81. Even if the FILES only keyword is used, if the ALL option is specified,
  82. directories _will_ be entered.
  83.  
  84. Note:  directories are listed _last_ after all files (and/or subdirectories)
  85. in them are used.  (This allows the Foreach command to be used as an interactive
  86. Delete command.)
  87.  
  88. The COM keyword allows you to specify a single command to execute.  Remember
  89. to use quotes around the entire command;  if one of the arguments
  90. inside requires quotes, you must escape those quotes using the *.  Within
  91. the COM argument, all variables must be preceeded by an additional $, to
  92. avoid expansion on the command line before the command is executed.
  93. By using *N within the COM string, you can define multi-command COM arguments,
  94. which is especially useful when making aliases that use the foreach command.
  95.  
  96. The SCRIPT keyword allows you to specify a script file to excute.  If no
  97. script keyword is used (and no COM keyword is specified) you will be
  98. prompted to create a temporary script.
  99.  
  100. The WITH keyword allows you to specify a file containing a list of names. 
  101. This list is used after any command line names are used.
  102.  
  103.  
  104. The FROM , TO and (optional) STEP keywords allow you to specify a numeric range;
  105. the loop variable will be set to each of the values in the range
  106. in turn.  Both are required to be specified to use this feature.  The
  107. STEP keyword is optional;  it allows you to pick an increment other than 1.
  108. FROM, TO, and STEP can be negative.  STEP cannot be zero, however.
  109.  
  110. The SORT keyword causes the foreach command to do an alphanumeric sort on 
  111. the name list before doing any script execution.
  112.  
  113.  
  114. The SINCE and UPTO keywords are for date comparisons;  SINCE will limit
  115. operations to files/directories since (and including) the specified date/time. 
  116. UPTO will limit operations to files/directories up to (and including)
  117. the specified date/time.  The usual AmigaDOS shortcuts (today, yesterday, and so on)
  118. are allowed.
  119.  
  120.  
  121. The foreach command nests.  WARNING:  The same variable name should not be 
  122. used for nested Foreach commands; make sure the inner loop variable name is
  123. not the same as the outside loop variable name.
  124.  
  125. The foreach command places its temporary files in T:  If T:"If not assigned,
  126. :T is used instead.  In that case, if :T does not exist it will be created.
  127.  
  128.  
  129. BUGS:
  130.     Its sometimes hard to stop the Foreach command from the Shell.
  131. Many things are looking at the signal bits, and the Foreach command is low
  132. on the chain.  Its often easier to go to another Shell, use Status to find
  133. out the process number of the Foreach command, and send that process a
  134. BREAK ALL.
  135.  
  136. (like this, for instance:
  137.  
  138. break `status com=foreach` all
  139.  
  140. )
  141.  
  142. This behavior could be fixed by using the RunCommand AmigaDOS call, rather
  143. than the System() call.  Perhaps it will in a future version.
  144.  
  145. EXAMPLES:
  146.  
  147. foreach i in qwe1 qwe2 ram:#$
  148.   echo "file is $i, path is ${i.path}"
  149.   foreach j in test1 test2
  150.     echo "subname is $j"
  151.     echo "Current local vars are:"
  152.     set
  153.   end
  154. end
  155.  
  156.  
  157.  
  158. Here's a handy alias using foreach that gives an interactive delete command.
  159.  
  160. (note: the alias must be defined on one line, though its shown on two for clarity)
  161.  
  162. alias del foreach i [] 
  163.      com "failat 21*Nask *"delete $i ?*"*N if warn *Ndelete ${i.path}$i*N endif"
  164.  
  165.  
  166.  
  167. ; rename all the .a files to .asm
  168. foreach i in #?.a
  169.   rename $i ${i.base}.asm 
  170. end
  171.