home *** CD-ROM | disk | FTP | other *** search
/ Boldly Go Collection / version40.iso / TS / 25D / XT23.ZIP / XT.DOC next >
Encoding:
Text File  |  1992-05-19  |  11.2 KB  |  283 lines
  1. ═════════════════════════════════════════════════════════════════════
  2. XT 2.3 [May 19 1992]      Copyright (c) 1991, 1992 by Paul Whittemore
  3. ═════════════════════════════════════════════════════════════════════
  4.  
  5. Summary
  6. ═══════
  7. See the license agreement at the end of this  document  before  using
  8. this program.  Don't worry, it's as liberal as they get.
  9.  
  10. What is XT?    A lot of people demanded this one.   It is perhaps the
  11. single most important utility I have except for my text editor.  It
  12. has a single general goal, but in accomplishing this goal, the
  13. program becomes a multi-purpose utility.  XT's goal is to provide a
  14. general way of traversing a DOS directory structure performing some
  15. (usually external) operation on a subset of the files found.  In many
  16. ways it resembles earlier SWEEP utilities, but is perhaps better. 
  17. Much user feedback has been applied since it's first incarnation and
  18. improvements continue to be made to the program.
  19.  
  20. WARNING:  This command is very powerful.  With power comes
  21. responsibility.  If you are unsure of a command, do NOT use XT or use
  22. the -n option to test it first.  The author is not responsible for
  23. any loss due to the use of this program.
  24.  
  25.  
  26. Syntax
  27. ══════
  28.  
  29. This is perhaps the most difficult aspect of LS.  Although completely 
  30. consistent, many people find the command line very confusing.  The
  31. syntax is:
  32.  
  33.         XT  [<options> [<filespec> [<command-template>] ] ]
  34.  
  35. Before we get to the actual options, an explanation is in order.
  36.  
  37. XT will traverse a given directory tree applying a command for every
  38. match.  XT without a command template will simply list all matches.
  39. If no filespec (pattern) is specified, "*.*" is assumed.  The
  40. <command-template> field can be as long as DOS will allow the line
  41. and can specify any command including batch (.BAT) files.
  42.  
  43. Some examples:
  44.  
  45.   XT readme.doc
  46.     - displays the name of all README.DOC files in and under the 
  47.       current directory.
  48.  
  49.   XT
  50.     - displays the names of all files in and under the current directory.
  51.  
  52.   XT *.com
  53.     - displays the names of all files whose filename extension is '.COM'.
  54.  
  55.   XT readme.doc type readme.doc         
  56.     - displays the CONTENTS of all README.DOC files in and under the 
  57.       current directory (by executing the DOS TYPE command).
  58.  
  59. In the last example, "type readme.doc" is the <command-template> part
  60. of the command line.  Rather than retyping the name of the file
  61. (readme.doc), XT has special placeholders which begin with a dollar
  62. sign ($).  For example, $n represents the name (root + ext) of the
  63. file.  Thus, the previous command could have been abreviated to the
  64. following:
  65.         XT readme.doc type $n
  66.  
  67. Template Escape Codes
  68. ═════════════════════
  69. The following command template escape codes (placeholders) may occur
  70. as many times as desirable in the <command-template> part of the
  71. command line:
  72.         $f  the full path name of the matching file
  73.         $p  the directory part of the matching filename
  74.         $d  the relative directory part of the matching filename
  75.         $n  the filename & ext of the matching file
  76.         $r  the root file name of the matching file
  77.         $e  the extension name of the matching file
  78.  
  79. Another example:  Assume your current directory is C:\TOPLEVEL and
  80. you execute the following command:
  81.  
  82.         XT *.doc
  83.  
  84. Let's say XT displays the following files:
  85.  
  86.         1.  C:\TOPLEVEL\README.DOC
  87.         2.  C:\TOPLEVEL\PERSONAL\RESUME.DOC
  88.         3.  C:\TOPLEVEL\SUBDIR1\README.DOC
  89.         4.  C:\TOPLEVEL\UTILITY\XT\XT.DOC
  90.         5.  C:\TOPLEVEL\UTILITY\LS304\LS.DOC
  91.         (The numbers are for reference below.)
  92.  
  93. The paths above represent the value of $f for each match.  The value
  94. of $p is constant for each execution of XT, in this case it will have
  95. a value of "C:\TOPLEVEL\".  The quotes are for readability in this 
  96. document only.  Note the trailing slash.  The values of the $d are 
  97. listed below:
  98.  
  99.         Match    $d              
  100.         ----- ----------------
  101.           1      ""              
  102.           2   "PERSONAL\"
  103.           3   "SUBDIR1\"
  104.           4   "UTILITY\XT\"
  105.           5   "UTILITY\LS304\"
  106.  
  107. In the examples above, $n is always "README.DOC", $r is always
  108. "README", and $e is always ".DOC".  The value of $f is always the
  109. concatenation of $p$d$n or $p$d$r$e.
  110.  
  111.  
  112. Options
  113. ═══════
  114. The following options can be specified before the <filespec> pattern
  115. (if present):
  116.  
  117.          -h, -?  displays this usage help
  118.              -r  non-recursive (do NOT scan subdirectories)
  119.              -c  change to directory of match before running command
  120.              -d  match directory names only
  121.              -q  enables quiet mode (no command echo)
  122.              -n  do not execute commands (echo only)
  123.              -p  patterned list of directories only
  124.             (-p assumes -nq, just lists files as in template)
  125.  
  126. The -p option is useful in creating batch files.  For example, the
  127. command "XT -p *.doc copy $f d:\docs >copydocs.bat" might produce a
  128. file COPYDOCS.BAT containing:
  129.         copy C:\TOPLEVEL\README.DOC d:\docs
  130.         copy C:\TOPLEVEL\PERSONAL\RESUME.DOC d:\docs
  131.         copy C:\TOPLEVEL\SUBDIR1\README.DOC d:\docs
  132.         copy C:\TOPLEVEL\UTILITY\XT\XT.DOC d:\docs
  133.         copy C:\TOPLEVEL\UTILITY\LS304\LS.DOC d:\docs
  134.  
  135. If any of the following are specified, it is an explicit list of
  136. the include set (the directory entries to match):
  137.              +r  include read-only files
  138.              +w  include read-write files
  139.              +h  include hidden files
  140.              +s  include system files
  141.  
  142. For example, "XT +r" lists all read-only file in and under the
  143. current directory.
  144.  
  145.  
  146. A Word About The -d Option
  147. ══════════════════════════
  148. The -d option applies the pattern specified by <filespec> to
  149. directory entries rather than regular files.  The matching directory
  150. entry can be referenced by the $n and $f escape codes, just like it
  151. is for matching files.  This can be confusing but is, at least,
  152. consistent.  (This may change in the future, but is not a planned
  153. change at this time.)
  154.  
  155. To list all directories starting with 'T', the following command
  156. would be used:  xt -d t*.*
  157.  
  158. To remove all such directories, use one of the following:
  159.         xt -d t*.* rd $f
  160.         xt -d t*.* rd $d$n
  161. or, if your a 'real' geek,
  162.         xt -d t*.* rd $p$d$r$e
  163.         xt -d t*.* rd $p$d$n
  164.  
  165. Note that the point here is that $d is NOT sufficient.  When using
  166. the -d option, $d is the relative name of the *parent* of the matching
  167. directory, rather than the directory itself.
  168.  
  169.  
  170. Recent Revisions
  171. ════════════════
  172.  
  173. Version 2.3:
  174. -----------
  175. Added -c option.  When specified, XT will change the current
  176. directory and drive, if necessary, to the directory part of any
  177. matches found.  For directories matched via -d, this includes the
  178. whole directory ($f), not everything except the last component ($p$d).
  179.  
  180. XT will now always save the current directory on the current drive
  181. (only) and will restore it on normal or CTRL-BREAK termination.
  182.  
  183.  
  184. Version 2.2:
  185. -----------
  186. Added attribute patterns (+r +w +h +s).  Recommend +r and +w use
  187. only, since +h and +s may not achieve desired results.  Try XT with
  188. the -n option to verify expectations.  
  189.  
  190. Options may be combined (e.g. +rh).
  191.  
  192.  
  193. Version 2.1:
  194. -----------
  195. A lot of people have been pushing for improvements in my XTREE program,
  196. so over the weekend I upgraded it to use my PATHS library...  This combined
  197. with some other work results in several improvements:
  198.  
  199.     - You can now specify absolute or relative paths in front of the pattern.
  200.     - The command template filter/escape sequences have been revised to
  201.       allow the inclusion of the relative part of a matching path name ($d).
  202.     - The program now aborts cleanly on a Ctrl-Break signal.
  203.     - You can specify (-d) that the pattern should be used to match
  204.       *directory* names.
  205.     - The program is now recursive by default.
  206.  
  207. Due to the incompatable changes to both the escape filtering and the defaults,
  208. combined with the fact that there is a commercial program named XTREE, I have
  209. decided to rename the executable to XT.EXE.
  210.  
  211. More Examples:
  212. ══════════════
  213.  
  214.         XT ?   or   XT -?  or  XT -h
  215.         Gives help, the command syntax and options.
  216.  
  217.         XT *.c
  218.         Like WHEREIS.  Displays all .C files under the current directory.
  219.  
  220.         XT \*.c
  221.         Like WHEREIS.  Displays all .C files anywhere on the current drive.
  222.  
  223.         XT -d C:\X*.*
  224.         WHEREIS for directories.  Finds all directories on drive C: that
  225.         start with an X.
  226.  
  227.         XT -d c:*.* md d:$d
  228.         Copies the directory structure existing under the current directory
  229.         on drive C: to the current directory on drive D:.  Note that $d is
  230.         the *relative* directory name, needed in this case.
  231.  
  232.         XT c:*.c copy c:$f d:$d$n
  233.         Recursively copies all .C files existing under the current directory
  234.         on drive C: to the corresponding current directory on drive D:.  Note
  235.         that $d is the *relative* directory name, and that the full path of
  236.         the matching (source) file is $f.
  237.  
  238.  
  239. License Agreement
  240. ═════════════════
  241. Use of this program is ALMOST completely without restriction.  Stupid
  242. little command-line utilities which aid the user in some small manner
  243. should not be restricted since a better working enviroment  helps  us
  244. all and may even lower the cost of more significant programs.
  245.  
  246. This program may NOT be sold or exchanged for any other consideration
  247. without express written consent of the author.  Where bundled as part
  248. of a larger collection of programs, this program may be  included  in
  249. cases where it does not represent a significant portion (greater than
  250. ten (10) percent) of the functionality of the product being sold.  It
  251. may be included in sales of public domain software disks provided the
  252. charge for such services does not exceed five dollars  ($5) U.S.  for
  253. the disk containing this program.  (I  know  that's  less  than  some
  254. folks charge, but come on guys,  twice  the  cost  of  the  disk  for
  255. something somebody else gave you for free should be enough!)
  256.  
  257. Other than  this  single  restriction,  this  program  may  be  used,
  258. distributed and/or included with other  products  provided  both  the
  259. program and this document file are included  unchanged.   This  means
  260. that you can use it at home or at  work,  company  software  and  LAN 
  261. administrators can distribute  to  it  to  fellow  employees  without
  262. reservation and you can even provide it as  a  bonus  with  your  own
  263. termination emulation, email or other fine product).
  264.  
  265. Due to the nature of this program, the author wishes to make it clear
  266. that the use of this utility is subject to the discretion of the user
  267. and that no implied warrantee exists.   The  author  will  accept  no
  268. responsibility for its use.  There are no  intentionally  destructive
  269. 'features', however commands like "XT *.* del $f" could have  serious
  270. impact on the user's blood pressure (not to mention the hard disk).
  271.  
  272. The author can be contacted at the following addresses:
  273.  
  274.                 Paul Whittemore
  275.                 853 Grenoble Blvd.
  276.                 Pickering, Ontario
  277.                 Canada     L1W 1T7
  278.  
  279. CompuServe:     72007,3305
  280. Internet:       pwhittem@novell.com
  281. MHS:            pwhittem@novell
  282.  
  283.