home *** CD-ROM | disk | FTP | other *** search
/ Network PC / Network PC.iso / amiga utilities / disk utilities / compression / imploderv4.0 / imploder / tools / fimp.man < prev    next >
Encoding:
Text File  |  1997-11-21  |  9.7 KB  |  248 lines
  1.  
  2. File Imploder V2.33 by A.J. Brouwer
  3. ===================================
  4.  
  5. This program is Freely-Distributable, as opposed to Public Domain.
  6. Permission is given to freely distribute this program provided you
  7. include this documentation and any other related files, and no fee
  8. is charged in excess of reasonable media and mailing costs.
  9.  
  10.  
  11. Usage:
  12. FImp <Source> [Target] [-M?|MODE?] [-XO|EXPLODEONLY] [-IO|IMPLODEONLY]
  13.      [-RF|RUNFORMAT "..%s.."] [-AL|ARGLIST "stctsct..."] [-V|VERBOSE]
  14.  
  15. Modes range from 0 to 11.
  16.  
  17. FImp is a compress/uncompress command that allows you to reduce
  18. the size of any file. The algorithms used are similar to those in
  19. The Imploder; they sport a good compression ratio and blazing
  20. decompression speed.
  21. You can be easily customize FImp to operate transparently on files
  22. in your environment.
  23.  
  24.  
  25. Operation
  26. ---------
  27.  
  28. If you don't specify a target file, FImp will try to replace the
  29. file you specified, and will expect/create imploded files with a
  30. .im extension. Suppose you have a file "test" in the current
  31. directory, "FImp test" will cause it to be replaced with an
  32. imploded file "test.im", and typing "FImp test" once more will
  33. replace "test.im" with the exploded file "test".
  34.  
  35. Alternatively you can specify a target file or directory.
  36. In the case of a complete target file specification, optionally
  37. with preappended path, FImp will use both the source and target
  38. without any modifications. If you specify only a target directory,
  39. the filename part of the source will be used as a filename.
  40.  
  41. This works fine because FImp examines the file data to see whether
  42. a file is imploded, and thus can determine if it should proceed with
  43. imploding or exploding.
  44.  
  45. Note that the ".im" entension is only relevant when you don't
  46. specify a target.  If you do, it will be neither appended while
  47. imploding, nor removed when exploding to a directory.  This means
  48. that it's up to you to specify the ".im" extension for the target
  49. if you prefer to recognize the file type by way of the file name.
  50. Both FInf and FImp have support for recognizing a file as having
  51. been fimped by examining its contents, so if you use batchfiles or
  52. pipe aliases to interface with whatever you've fimped there's no
  53. need to use the ".im" extension. In any case, you can have it both
  54. ways.
  55.  
  56. The NICE switch causes FImp to operate with a task priority of one
  57. count lower than the one it was invoked with. The old priority will
  58. be restored upon exit. Thus FImp will only eat the spare cycles
  59. without bogging down the system.
  60.  
  61. If you use the VERBOSE switch, FImp will give a progress report
  62. while compressing, and report on current activities like loading,
  63. exploding etc.
  64.  
  65.  
  66. Compression
  67. -----------
  68.  
  69. FImp doesn't (yet) support streaming compression/decompression; the
  70. file to be compressed needs to be loaded into a memory buffer.
  71. As is the case with The Imploder, a special turbo compression mode
  72. kicks in when you've about 300K memory left (more for higher
  73. compression modes).  This will drastically speed up the implosion
  74. process.
  75.  
  76. Decompression also requires a contiguous memory buffer as large as
  77. the decompressed file, but doesn't require any memory in addition
  78. to that. Before decompression, FImp performs a quick checksum to
  79. make sure the file hasn't been corrupted.
  80.  
  81. By default what's most probably the optimal compression mode will
  82. automatically be selected by FImp. If you want to override this, you
  83. may specify the mode yourself using the "mode?" switches. Large
  84. compression modes normally have a higher gain, but take more time,
  85. and, in case of turbo compression, use up a lot of memory. The speed
  86. differences between the various modes are quite large if no turbo
  87. mode could be initiated due to lack of memory.
  88.  
  89. The large compression modes require quite a bit of memory in order
  90. to be able to execute. If you have some free memory (>300K) but not
  91. a whole lot, and yet want to ensure operation in turbo mode, the
  92. best course of action is to override the automatic compression mode
  93. selection with a relatively small value, e.g. MODE5.
  94.  
  95.  
  96. Advanced Features
  97. -----------------
  98.  
  99. FImp has a number of features that allow you to easily apply it to
  100. customized tasks such as transparently decompressing imploded text
  101. files and loading them into your editor.
  102.  
  103. The "ImplodeOnly" and "ExplodeOnly" switches allow only compression
  104. or decompression respectively. Normally FImp decides by itself by
  105. looking whether the file is already imploded.
  106.  
  107. Beyond the "RunFormat" keyword you may specify a command to be
  108. executed when FImp has completed its operation. This isn't very
  109. useful unless you can in some way pass on the files just processed
  110. by FImp.
  111. Therefore this "RunFormat" string allows PrintF like formatting;
  112. Any "%s" format statements present in the string will be replaced
  113. by a filename.
  114.  
  115. However if you use %s statements you'll also have to specify which
  116. filename it should be replaced with. That's what the ArgList keyword
  117. is all about. Beyond it you may specify a list containing only the
  118. characters "s" and/or "c" or "t".  "c" and "t" are mutually exclusive.
  119. The "s" stands for source, the "t" for target, and "c" for
  120. conditional.
  121. So the ArgList string "st" will replace the first occurance of %s
  122. in the RunFormat string with the source path+filename, and the
  123. second occurance of %s with the target path+filename.
  124.  
  125. Note that if you specify only a destination directory, a "t" will
  126. still cause replacment by both the path and an appended filename
  127. derived from the source file specification.
  128.  
  129. Now what's this conditional thing?
  130. Well, if you don't know for sure whether a file has been imploded
  131. and e.g. only care about doing something with the exploded version,
  132. such as loading it into your editor, you can set the "ExplodeOnly"
  133. switch to prevent the file from being imploded when it hasn't
  134. already been imploded.
  135. In this case you'd want FImp to also perform the RunFormat command
  136. (probably containing an invocation string for your editor) even
  137. though it didn't explode a thing. And you'd want the source file
  138. to be loaded into your editor (The one that FImp found out was
  139. already in a non-imploded state).
  140.  
  141. So this is what the "c" does; It replaces its respective "%s"
  142. in the RunFormat string by the target file name if FImp exploded
  143. or imploded the file. Yet when the file couldn't be processed
  144. due to you setting the ExplodeOnly or ImplodeOnly switches,
  145. the source file name will be used.
  146.  
  147. One last thing that needs to be mentioned is that the runformat
  148. string supports escaping by means of the \ escape character.
  149. Thus with \" you can include a quote in the runformat string,
  150. and \n inserts a line feed.
  151.  
  152.  
  153. Examples
  154. --------
  155.  
  156. "FImp data"
  157.  
  158. Will implode the file "data" and replace it by data.im if the
  159. file "data" hasen't been imploded already.
  160. The same command will explode any file "data.im" if present and
  161. replace the exploded version called "data". This way you can
  162. toggle a file between its imploded and exploded state.
  163.  
  164.  
  165. "FImp source target -rf "Delete %s" -al s"
  166.  
  167. This will implode or explode the file "source" to the file "target"
  168. (depending on what state the source file is in) and delete the
  169. source file, but only when the operation could be completed with
  170. success.
  171.  
  172.  
  173. The best thing to do is to define some aliases to hide the rather
  174. longish commandlines from view;
  175.  
  176. Edx=FImp >NIL: [] T:Explode -XO -RF "Execute ExEdit %s" -AL "c"
  177.  
  178. This will execute a batchfile called ExEdit. This could contain
  179. something like;
  180.  
  181. <---"S:ExEdit"
  182. .key filepa/a
  183.  
  184. Edit <filepa>
  185. Delete T:Explode/#?
  186. <---
  187.  
  188. Thus conditionally loading either the exploded target or the never-
  189. imploded-in-the-first-place source into an editor.
  190. The delete command subsequently purges any intermediate files from
  191. a subdirectory in T:.
  192. Instead of using a batchfile, you may separate commands in the
  193. RunFormat string by using \n line feeds. Still, batchfiles are
  194. more flexible because of e.g. the If/Endif/Skip flow control.
  195.  
  196.  
  197. FImp Fish:Contents Fish:Contents -IO
  198.  
  199. If you don't want to bother with re-imploding files when they
  200. have been modified, you could add a list of these FImp statements
  201. to your CronTab, thus causing re-implosion during nighttime.
  202.  
  203. As you can see, you may implode or explode a file to itself, but
  204. you need to explicitly specify an identical source and target.
  205. The original file will be deleted, and the new file written. This
  206. results in a "window of vulnerability"; during the write operation
  207. there is no backup of the file.
  208. The replace mode (when you don't specify a target), is safe in this
  209. sense. The source file will only be deleted after the target file has
  210. been successfully written.
  211.  
  212.  
  213. General Info
  214. ------------
  215.  
  216. Don't think of FImp as a general purpose archiver. Rather it is
  217. a quick and easy solution to compress single files. I don't endorse
  218. FImped files as a "public" format. There's enough confusion already.
  219.  
  220. You might use FInf to "add" wildcarding capabilities to FImp,
  221. or to preselect only FImped files from a directory.
  222.  
  223. The rationale behind all this is that by providing only the building
  224. blocks, documentation and some examples, the user retains the freedom
  225. to implement things as he/she sees fit.
  226.  
  227.  
  228. FImp stands out because of its decompression speed. If you'd like
  229. to compress external data used by a program you are writing, while
  230. hardly incurring any performance penalty, consider using FImp.
  231.  
  232. If you query us, we'll provide you with the decompression routines
  233. in linkable, object format. Note that decompression happens in-situ
  234. and doesn't require any additional memory.
  235.  
  236. If you wish to make a program that deals with "public" data, e.g.
  237. a text reader or a picture display program, you'd do best to wait
  238. for the xpk library by Urban Mueller. This is an interface library
  239. a la XPR to various compression algorithms. This way people will
  240. have an easy way of decompressing this "public" data without having
  241. to know about the various formats.
  242.  
  243.  
  244. FImp is pure and can be made resident.
  245. Enjoy.
  246.  
  247. # AJ
  248.