home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d09xx / d0907.lha / DD / AnaLib / AnaLib.doc next >
Text File  |  1993-08-28  |  7KB  |  261 lines
  1. ******************************************************************************
  2.  
  3.                               The File Analyser
  4.  
  5.                 (c) 1993 Martin Mares, MJSoft System Software
  6.  
  7. ******************************************************************************
  8.  
  9.  
  10. Copyright:
  11. ----------
  12.  
  13.    The Analyser Library and its documentation is Copyright (c) Martin Mares,
  14. MJSoft System Software, Prague, Czech Republic.
  15.  
  16.    This archive can be freely redistributed, as long as all of its files are
  17. included in their original form without any additions, deletions or
  18. modifications, and no more than a nominal fee is charged for its distribution.
  19. All copyright notices in the programs and accompanying documentation files
  20. must remain on their places.  Also '.displayme' and other similar files may
  21. not be added. This is generally known as FREEWARE.
  22.  
  23.    Special permission is given to Fred Fish to distribute this program on his
  24. "Fish Disks".
  25.  
  26.    This software is provided "AS IS" without warranty of any kind, either
  27. expressed or implied.  The author is not responsible for any damage caused by
  28. it.
  29.  
  30.    The library itself (analyser.library) can be distributed with any software
  31. package, either commercial or non-commercial.
  32.  
  33.    To maintain compatibility, you shouldn't make any changes on the library.
  34. Updates will be released by the author.
  35.  
  36.  
  37. What analyser.library does:
  38. ---------------------------
  39.  
  40.    Some time ago, I wrote small program, which tried to analyse files and
  41. estimate their types.  It was only a joke, but when I were working on DD, I
  42. thought that it could be useful to include the analyser in it.  But it seemed
  43. to be interesting to include the analyser in some different programs (file
  44. requesters etc.), therefore I have converted it to this library.
  45.  
  46.  
  47. Library functions:
  48. ------------------
  49.  
  50. ==============================================================================
  51.  
  52. AnaName(A0=Name,A3=DataNode,D1=Size,D2=AnaMode,D3=ProtBits)
  53.  
  54. FUNCTION
  55.  
  56.    Analyse file name, size and protection bits.
  57.  
  58. INPUTS
  59.  
  60.    Name = pointer to file name
  61.    DataNode = pointer to data node of this file
  62.    Size = file size (used for detection of empty files)
  63.    AnaMode = analysis mode
  64.       ANAMO_SIMPLE - analyse file name only
  65.       ANAMO_CONTENTS - analyse file contents only
  66.       ANAMO_GOOD - analyse name, if it isn't enough, analyse file contents
  67.       ANAMO_FULL - analyse name and contents, find the best alternative
  68.    ProtBits = file protection bits (used to detect scripts)
  69.  
  70. RESULT
  71.  
  72.    Zero in case the contents analysis hasn't to be performed.
  73.       (ANAMO_SIMPLE: always 0, ANAMO_CONTENTS and ANAMO_FULL: always -1,
  74.        ANAMO_GOOD: -1 only if the name analysis has failed)
  75.  
  76.    DataNode->d_nclass contains name classification.
  77.  
  78. SEE ALSO
  79.  
  80.    AnaContents, AnaEstimate
  81.  
  82. ==============================================================================
  83.  
  84. AnaContents(A0=FileData,A3=DataNode,D0=Size)
  85.  
  86. FUNCTION
  87.  
  88.    Analyse contents of first max.  488 bytes of the file.  (The magic number
  89. 488 is the smallest possible size of file data block.  It allows to read all
  90. data needed for the analysis without reading of multiple sectors.)
  91.  
  92.    You should not call AnaContents without calling AnaName first.
  93.  
  94. INPUTS
  95.  
  96.    FileData = pointer to the buffer, which is filled with file contents
  97.    DataNode = pointer to file node
  98.    Size = size of file data (max. 488)
  99.  
  100. RESULT
  101.  
  102.    DataNode->d_cclass contains the classification.
  103.  
  104. SEE ALSO
  105.  
  106.    AnaName, AnaEstimate
  107.  
  108. ==============================================================================
  109.  
  110. AnaEstimate(A1=DataNode,D0=AnaMode)
  111.  
  112. FUNCTION
  113.  
  114.    Estimate final classification. You should call this function after
  115. AnaName and (sometimes) AnaContents.
  116.  
  117. INPUTS
  118.  
  119.    DataNode = pointer to file node
  120.    AnaMode = required analysis mode (see AnaName)
  121.              bit 8 of this parameter means "Exclude all non-reliable classes"
  122.              The most reliable method is ANAMO_FULL + ANAMO_RELIABLE
  123.  
  124. RESULT
  125.  
  126.    DataNode->d_class contains final file classification
  127.    DataNode->d_subclass contains file subclass
  128.       (Only IFF files have the subclass now - it's the type of IFF (8SVX etc.))
  129.  
  130. SEE ALSO
  131.  
  132.    AnaName, AnaContents, AnaMsg
  133.  
  134. ==============================================================================
  135.  
  136. AnaMsg(A0=DataNode,A1=LineBuf)
  137.  
  138. FUNCTION
  139.  
  140.    Construct file class text according to previous file analysis.  AnaEstimate
  141. should be called before it.
  142.  
  143.    This function finds the class text and appends the subclass.
  144.  
  145. INPUTS
  146.  
  147.    DataNode = pointer to file node
  148.    LineBuf = buffer you want to store the text to (minimally 80 bytes)
  149.  
  150. RESULT
  151.  
  152.    LineBuf holding the null-terminated string.
  153.  
  154. SEE ALSO
  155.  
  156.    AnaPlur, AnaText, AnaEstimate
  157.  
  158. ==============================================================================
  159.  
  160. AnaPlur(D0=Class,A0=LineBuf)
  161.  
  162. FUNCTION
  163.  
  164.    Construct file class name in plural. Subclass is not appended to the name.
  165.  
  166. INPUTS
  167.  
  168.    Class = file class number
  169.    LineBuf = buffer you want to store the string to (minimally 80 bytes)
  170.  
  171. RESULT
  172.  
  173.    LineBuf filled with the message (preceeded by two space characters).
  174.  
  175. SEE ALSO
  176.  
  177.    AnaMsg, AnaText
  178.  
  179. ==============================================================================
  180.  
  181. AnaGetMax
  182.  
  183. FUNCTION
  184.  
  185.    Get number of file classes.
  186.  
  187. INPUTS
  188.  
  189.    None.
  190.  
  191. RESULT
  192.  
  193.    Number of file classes (it's the number of the last class + 1).
  194.  
  195. ==============================================================================
  196.  
  197. AnaText(D0=Class)
  198.  
  199. FUNCTION
  200.  
  201.    Get file class text without subclass. Used mostly for sorting.
  202.  
  203. INPUTS
  204.  
  205.    Class = file class number
  206.  
  207. RESULT
  208.  
  209.    Pointer to name of the class.
  210.  
  211. SEE ALSO
  212.  
  213.    AnaMsg, AnaPlur
  214.  
  215. ==============================================================================
  216.  
  217. AnaSortTab(A0=ArpBase)                                                    (V2)
  218.  
  219. FUNCTION
  220.  
  221.    Create  the  sorting  tables.
  222.  
  223.    The first table is a sequence of words presenting the class numbers
  224. arranged in alphabetical (read:  ASCII) order.
  225.  
  226. The second one contains the inverse permutation to the first one, which is
  227. very useful for sorting by analysis result (you can sort by TAB2[i] instead of
  228. AnaText(i), which is significantly faster, because you haven't to compare any
  229. strings).
  230.  
  231.   For each i in <0;AnaGetMax()), you can really say:
  232.  
  233.      (a)  TAB1[TAB2[i]] = i
  234.      (b)  NAME[i] < NAME[j]  equals to  TAB2[i] < TAB2[j]
  235.  
  236. INPUTS
  237.  
  238.    ArpBase = base of opened arp.library (this library is used for sorting
  239. of the tables and it cannot be opened twice by the same process!)
  240.  
  241. RESULT
  242.  
  243.    Pointer to two long words representing addresses of the sorting tables.
  244. If there isn't enough memory, 0 will be returned.
  245.  
  246. NOTES
  247.  
  248.    There  is no way to remove the sorting tables without removing the analyser
  249. library,  but  if  there isn't enough memory, the library will be expunged and
  250. the  tables  will be properly deallocated.  This eats some memory (4*number of
  251. known  classes),  but  it  makes  repeated  invocation  of  DD  ANA  F SORT AN
  252. significantly faster than it was before.
  253.  
  254. ==============================================================================
  255.  
  256. Notes:
  257. ------
  258.  
  259.    Send all suggestions and bug reports to mjsoft@k332.feld.cvut.cz
  260.  
  261.