home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / tlist007.lha / tl.doc < prev   
Encoding:
Text File  |  1995-06-03  |  11.4 KB  |  377 lines
  1.                      TurboList v0.07 alpha (3-Jun-95)
  2.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4.                          coded by Conrad Sanderson
  5.                     (e-mail: g.sanderson@ais.gu.edu.au)
  6.  
  7.                 Mail me with bug reports or suggestions...
  8.  
  9.  
  10. TABLE OF CONTENTS
  11. ~~~~~~~~~~~~~~~~~
  12. 0.    Legal Notice
  13. 1.    Requirements
  14. 2.    Quick Overview
  15. 3.    List of features
  16. 4.    Why is it faster?
  17. 5.    It's still experimental
  18. 6.    Options
  19. 7.    Aliasing
  20. 8.    History
  21. 9.    To do
  22.  
  23.  
  24. 0. LEGAL NOTICE
  25. ~~~~~~~~~~~~~~~
  26. TurboList is (c) Copyright 1995 Conrad Sanderson.
  27.  
  28. This program can be distributed and used freely, as long as the following
  29. conditions are satisfied:
  30.  
  31.     (a) it is not modified in any way
  32.     (b) it is not stored on, or transferred from/to,
  33.             any device which is property (whole or partially)
  34.         of Microsoft or any of its subsidiaries.
  35.  
  36. Failure to follow these points results in a breach of copyright.
  37.  
  38.  
  39. 1. Requirements
  40. ~~~~~~~~~~~~~~~
  41. At least Kickstart 2.04 (v37.175)
  42.  
  43. The  68020  version  requires  at least a 68020 processor (ie.  Amiga A1200,
  44. CD32,  A2500,  A3000, A4000 or any machine with a 68020+ accelerator).  This
  45. version  has been specifically optimized for 32 bit memory access and 32 bit
  46. maths and hence is faster than the 68000 version.
  47.  
  48. The  68000 version can be used on any Amiga, but is best suited for machines
  49. which only have the 68000 or the 68010 processor (A500, A600, A2000).
  50.  
  51.  
  52. 2. Quick Overview
  53. ~~~~~~~~~~~~~~~~~
  54. TurboList is a command similar to the standard list command supplied with
  55. AmigaDOS.
  56.  
  57.  
  58. The normal 'list' command, lists files like this:
  59.  
  60. etherpeek                   2369 ---arwed 04-Jan-95 22:21:34
  61. alien.iff                1314114 ----rwed 07-Jan-95 01:31:08
  62. desert.rat.toxic.article.gz    3684 ----rwed 05-Apr-95 17:24:34
  63. ultoa020.o                   444 ----rwed 28-Mar-95 19:11:11
  64. ftphunt.gz                 13768 ---arwed 04-Jan-95 14:27:41
  65. mui23usr.LZX              504572 ----rwed 26-Mar-95 19:21:54
  66. electric.bullet             1416 ---arwed 04-Jan-95 22:16:54
  67. ar311.lha                  95557 ----rwed Today     02:44:23
  68. replacement.functions       1029 ----rwed 11-Mar-93 23:20:17
  69. 9 files - 3796 blocks used
  70.  
  71.  
  72. TurboList lists them like this (similar to unix ls):
  73.  
  74. ---arwed 04-Jan 22:21 2.3K etherpeek
  75. ----rwed 07-Jan 01:31 1.3M alien.iff
  76. ----rwed 05-Apr 17:24 3.6K desert.rat.toxic.article.gz
  77. ----rwed 28-Mar 19:11 444b ultoa020.o
  78. ---arwed 04-Jan 14:27  13K ftphunt.gz
  79. ----rwed 26-Mar 19:21 493K mui23usr.LZX
  80. ---arwed 04-Jan 22:16 1.4K electric.bullet
  81. ----rwed Tod 02:44:23  93K ar311.lha
  82. ----rwed 11-Mar-93      1K replacement.functions
  83. TOTAL:  9 files [1.8M] and 0 dirs [1.9M used, 1M free]
  84.  
  85.  
  86. As you can see, long filenames do not stuffup the formatting.  Additionally,
  87. where possible, file sizes are approximated to their nearest multiplier (ie.
  88. Kilobytes,  Megabytes  or  Gigabytes),  which  is much easier to read.  This
  89. behaviour can be switched off.
  90.  
  91. The  date/time output is also different - if the file was created on the day
  92. you  are listing it,  it will print  out "Tod hh:mm:ss",  where Tod = Today,
  93. hh  =  hours,  mm = minutes, ss = seconds.  If the file was created within 6
  94. months  of  Today, the day of the month and the month will be printed, along
  95. with hh:mm.  If the file is older than 6 months, the full date, but no time,
  96. is printed.  This unix-like behaviour can be switched off and the full date
  97. printed without any conditions.
  98.  
  99. Additionally,  the file sizes are added up and listed at the end (the [1.8M]
  100. in  above  example).   The actual space taken up by the listed files is also
  101. printed  (ie.   1.9M  used) - this is due to the amount of blocks being used
  102. for a file, and blocks have constant sizes (usually 512 bytes on FFS), hence
  103. a  file which takes up 444 bytes actually takes up 2 blocks, 1 * 512 for the
  104. file,  and  1  * 512 for the directory entry (these values all depend on the
  105. file system used).  The amount of free space (ie.  1M free) on the device is
  106. also printed.
  107.  
  108. Files which have the hidden ('h') protection bit enabled will be ignored and
  109. not  taken  into  account  when  counting sizes/space taken up.  This can be
  110. switched off.
  111.  
  112. File size conversion explanation:
  113.  
  114. K = 1024 bytes  (1 Kilobyte)
  115. M = 1024K       (1 Megabyte)
  116. G = 1024M       (1 Gigabyte)
  117.  
  118. For the file mui23usr.LZX, which is 504572 bytes long, the following
  119. size conversion is done:
  120.  
  121. 504572 / 1024 = 492.746 K, or approximately 493 K
  122.  
  123.  
  124. NOTE: If any of the above values exceed 4 Gigabytes, strange/incorrect
  125.       results will be printed... but not many people have 4 Gigabyte
  126.       drives.
  127.  
  128.  
  129. 3. List of features
  130. ~~~~~~~~~~~~~~~~~~~
  131.  - Can be upto 30% faster than the normal 'list' command
  132.  - Long filenames fit without stuffing up the display
  133.  - Approximates the file size so it can be read easily (can be turned off)
  134.  - similar to unix-ls date printing behaviour
  135.  - doesn't display hidden files (with the h bit) (can be turned off)
  136.  - handles patterns (ie. stuff like foobar.#? etc)
  137.  - listing according to dates (since/upto date limitations)
  138.  
  139.  
  140. 4. Why is it faster?
  141. ~~~~~~~~~~~~~~~~~~~~
  142.  - grabs 3 filenames before printing them (can be turned off)
  143.    (note: caching filenames may not be desirable when using pattern
  144.           matching on a slow drive... will be fixed later)
  145.  - Turns off the cursor while printing, but turns it back on as soon
  146.    as it has finished printing a set of names.  The cursor can be
  147.    configured to remain on at all times.
  148.  - Direct writes (can be forced to use normal printing methods)
  149.  
  150.  
  151. 5. It's still experimental
  152. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  153.  - don't expect everything working perfectly
  154.  - a lot of functions are missing when compared to the normal list command
  155.    eg. recursive directories
  156.  
  157.  
  158. 6. Options
  159. ~~~~~~~~~~
  160. The letters after '/' specify the type of argument
  161.  
  162. /M = multiple strings    (keyword doesn't have to be present)
  163. /S = switch (ie. enable) (keyword has to be present)
  164. /K = keyword followed by a string
  165.  
  166. If a keyword (or its shortcut) has the same name as a directory/filename you
  167. are  trying  to  list,  you  must  use  DIR=filename  to avoid the conflict.
  168. Alternatively,  you  can  use UNIX like keywords (see the "-unix" option for
  169. more information).
  170.  
  171.           DIR/M,
  172. -h=-?=HELP    = ABOUT/S,
  173. -sh=SH        = SHOWHIDDEN/S,
  174. -co=CO        = CURSORON/S,
  175. -nj=NJ        = NOJUMP/S,
  176. -nd=ND        = NODIRECT/S,
  177. -unix/S,
  178. -files        = FILES/S,
  179. -dirs        = DIRS/S,
  180. -noda=NODA    = NODATES/S,
  181. -ex=EX        = EXACT/S,
  182. -free        = FREE/S,
  183. -since        = SINCE/K,
  184. -upto        = UPTO/K,
  185. -both        = BOTH/S,
  186. -normd=NORMD    = NORMALDATE/S
  187.  
  188.  
  189. DIR
  190.  
  191. Name of a directory or a file or nothing (will list current dir).  Currently
  192. tlist can only process one name (no multiple directories).
  193.  
  194.  
  195. ABOUT, HELP, -?, -h
  196.  
  197. Print  version/date  information.   In  some  versions  this option may also
  198. display various debugging information.
  199.  
  200.  
  201. SHOWHIDDEN, SH, -sh
  202.  
  203. Show hidden files/directories (h protection bit).
  204.  
  205.  
  206. CURSORON, CO, -co
  207.  
  208. Keep  the cursor on at all times.  Tlist turns the cursor off while printing
  209. something.   If you are using tlist over a comm link (eg.  modem link, AUX:,
  210. null-modem,  etc.), your terminal may not be able to interpret cursor on/off
  211. commands, hence this option.
  212.  
  213.  
  214. NOJUMP, NJ, -nj
  215.  
  216. Do  not  cache  filenames - print out filnames as soon as they are read from
  217. the  disk.   This  can  be  used  if  you  have a slow drive and are listing
  218. patterns.   Normally  tlist  caches  3  names  before  printing  them.  I'll
  219. probably change the name of this option to NOCACHE in later versions.
  220.  
  221.  
  222. NODIRECT, ND, -nd
  223.  
  224. Use  normal  printing  methods  instead of direct writes.  Direct writes may
  225. conflict  with some console-handlers (eg.  KingCON with Jump Scroll enabled)
  226. or communication links.
  227.  
  228.  
  229. -unix
  230.  
  231. Instructs  tlist  to use options _only_ which start with '-'.  Useful when a
  232. option  has  the  same name as a dir/file, or you prefer UNIX type keywords.
  233. Only works properly when it is specified as part of the command line.
  234.  
  235. (note:    even if you do not specify -unix, options starting with '-'
  236.     still work. )
  237.  
  238.  
  239. FILES, -files
  240.  
  241. List only files
  242.  
  243.  
  244. DIRS, -dirs
  245.  
  246. List only directories
  247.  
  248.  
  249. NODATES, NODA, -noda
  250.  
  251. Do not print date/time of files/dirs.
  252.  
  253.  
  254. EXACT, EX, -ex
  255.  
  256. Print out the exact size of files (ie. no approximations).
  257.  
  258.  
  259. FREE, -free
  260.  
  261. Display the amount of used and free space only.  Example:
  262.  
  263. shell> tlist free dh0:
  264. [7.1M used, 917K free]
  265.  
  266. 'dh0:'  can  be replaced with any filename/directory/device or even omitted.
  267. If it's omitted, tlist will use the current directory as the argument.
  268.  
  269.  
  270. SINCE, -since
  271.  
  272. Limit  listing  of  files to only those which were created since a specified
  273. date/time.   The  date/time  must  be specified in standard AmigaDOS format.
  274. Examples  of  valid  dates:  today, yesterday, thursday (ie.  any day of the
  275. week), 01-Jun-93, 2:08 (ie. hh:mm), 2:08:01 (ie. hh:mm:ss).  When specifying
  276. a time, it will be assumed you are referring to a time which was Today.
  277.  
  278. UPTO, -upto
  279.  
  280. Similar to SINCE, but instead it limits listing of files to only those which
  281. were created upto a specified date/time.
  282.  
  283.  
  284. BOTH, -both
  285.  
  286. Print  the  approximated  file size along with the exact size.
  287. NOTE:  this option has a small bug when listing directories.
  288.  
  289.  
  290. 7. Aliasing
  291. ~~~~~~~~~~~
  292. You can alias tlist to have a default behaviour which you want.
  293. It has to be aliased for every shell window you open (can be part of
  294. s:shell-startup)
  295.  
  296. Example1:
  297. shell> alias tlist tlist showhidden exact
  298.  
  299. ... and whenever tlist is used, the showhidden and exact options
  300. will be on.
  301.  
  302. Example2:
  303. shell> alias tlist tlist -unix
  304.  
  305. ... and whenever tlist is used, only options which start with '-'
  306. will be used.
  307.  
  308. In later versions tlist will also use environment variables, so the default
  309. behaviour can be modified globally.
  310.  
  311.  
  312. 8. History
  313. ~~~~~~~~~~
  314. 0.01    tested the theory that print buffering and no cursor would
  315.     speed up directory listing
  316.  
  317. 0.02    added protection bits
  318. 0.03    replaced many occurences of mysprintf() with strcat()/strcpy()
  319.     added filestats()
  320.  
  321. 0.04    added dates
  322. 0.05    implemented patterns (#?.sfsf#? etc)
  323.  
  324. 0.06    major code update (read: optimized the crap out of it)
  325.  
  326.     - replaced many occurances of strcat()/strcpy() with
  327.       mystrcpy()/mystrcat() which are much faster...  tlist
  328.       now accesses memory much less
  329.  
  330.     - replaced most occurances of mysprintf() (and hence RawDoFmt())
  331.       with mystrcat()/mystrcpy()/mystrputchar()/ultoa()
  332.  
  333.     - due to above changes, tlist now is ~8% faster than last version
  334.  
  335.     added FREE keyword
  336.     
  337.     rearranged filestats(), added total size of files and total space
  338.     used by files
  339.  
  340.     added CPU check for 68020+ version
  341.     68000 version uses utility.library for 32 bit maths
  342.  
  343.  
  344. 0.07    reversed order of fields when printing - now looks similar
  345.     to unix ls
  346.  
  347.     modified code to use jump tables instead of checking variables
  348.     all the time when deciding what function to use.
  349.  
  350.     modified filestats() - ignores hidden files completely
  351.  
  352.     modified date output to look like unix ls
  353.  
  354.     modified string handling function again... in time critical
  355.     code, replaced mystrcat() with combinations of mystrputchar(),
  356.     mystrputword(), mystrputlong() - results in smaller and faster
  357.     code
  358.  
  359.     using memcpy() instread of mystrcat() when handling long strings
  360.     results in much less access to memory, hence faster
  361.  
  362.     added SINCE, UPTO, NORMALDATE, and BOTH keywords
  363.  
  364.     modified ultoa() so it can pad generated strings with spaces,
  365.     depending on the length of the generated string.  This made
  366.     mysprintf() totally redundant.
  367.  
  368.  
  369. 9. To do
  370. ~~~~~~~~
  371.     - show/don't show .info files (hidden by default, SHOWINFO)
  372.     - option for bytes (b) or nothing at the end of file size
  373.     - option for a space between approximated file size and multiplier
  374.     - show files/dirs bigger/smaller according to specified size
  375.     - multiple directories
  376.     - recursive directories
  377.