home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / dos_util / af126.zip / AF.ENG < prev    next >
Text File  |  1993-08-14  |  18KB  |  457 lines
  1.  
  2.    -------------------------------------------------------------------------
  3.  
  4.                           A r c h i v e   F i n d e r
  5.  
  6.                                  version 1.26
  7.  
  8.    -------------------------------------------------------------------------
  9.  
  10.    What is it ?
  11.    ------------
  12.  
  13.    Archive Finder (AF) is a program that searches files on a disk. A bit
  14.    like Peter Norton's FileFind/FileLocate (FF) or WhereIs. e.g. I need to
  15.    know where my *.DOC files are located, the program finds and displays
  16.    them, very very easy.
  17.  
  18.    But since then compression era started, we have more and more files
  19.    Archived, ARJed, ZIPped, ARCed into archives. To find them out quite
  20.    quickly, very few programs were available when AF came out. This
  21.    version of Archive Finder can be compared in a way to SST from Keith
  22.    Ledbetter or to Vernon Buerg's FileView (FV), except that you get more
  23.    flexibility and *FREE FULL SOURCE CODE* in Turbo Pascal.
  24.  
  25.    It can also tell you the REAL disk size that would be occupied by files
  26.    once extracted. This is very different from a sum of all the unpacked
  27.    sizes !
  28.  
  29.    This is neither Commercial nor Shareware nor Freeware. It is real public
  30.    domain. The author has completely abandonned his rights on it. His name
  31.    must be mentionned when you use AF or part of it in a package or program.
  32.  
  33.    Archive Finder recognizes .ARJ .ZIP .PAK .ARC .LZH .ZOO, some Mac .SIT and
  34.    some .EXE self extracting archives (ARJ's and LZH's)
  35.  
  36.    Archive Finder will never WRITE to your disk (except if redirected). So,
  37.    no harm, no data loss is possible. All it does is READ in a very
  38.    conventionnal way.
  39.  
  40.  
  41.    Yes, but how ?
  42.    --------------
  43.  
  44.    The correct syntax for Archive Finder is :
  45.  
  46. C:\> AF [FileMask] [-Parameter(s)] [/Parameter(s)] [...]
  47.  
  48.    The symbols `[` and `]` mean that all parameters are optional. You could
  49.    simply enter AF <Return>
  50.    (Don't... 'Could take quite a long time as this lists ALL files in and out
  51.    archives on drives C, D and E).
  52.  
  53.    [FileMask] represents the DOS definition of the files you wish to find.
  54.    So if you would like to list all the .DOC files, you would enter :
  55.  
  56. C:\> AF *.DOC <Return>
  57.  
  58.    If you omit this mask, AF considers you're looking for all the files *.*
  59.    20 different masks can be searched simultaneously.
  60.  
  61.    AF accepts another wildcard `#` which replaces any digit (`0'...`9`).
  62. C:\> AF *.###       will find HELLO.001    BACKUP.321    A.000
  63.                     but not   HELLO.01     BACKUP.12T    A.
  64.  
  65.    Since version 1.14, AF also recognizes the extended masks of 4Dos 3.x and
  66.    so NDOS's too. That means you can place the `*` at the beginning and/or
  67.    anywhere in the name or extension.
  68.    Not so clear ? Let's see some examples :
  69.  
  70. C:\> AF *A*.*     picks up every file containing an `A` in it's name or ext.
  71.                   this is identical to `AF *A`
  72.  
  73. C:\> AF A*A.*     finds all files with name starting and ending with `A`,
  74.                   any extension.
  75.  
  76. C:\> AF A*B*A.*   searches all files with name starting and ending with `A`
  77.                   and having a `B` anywhere between the two, any extension.
  78.  
  79. C:\> AF A?B*A.*   locates all files with name starting and ending with `A`
  80.                   and having a `B` at the third position.
  81.  
  82. Remark:
  83.    Suppose you wish to search for DOC*.* files.
  84.  
  85.    Don't add systematically `.*` at the end of your masks. It's tiring.
  86.    The above example can be written easier `AF DOC*`.
  87.  
  88.    The ending `*` is not even useful since AF would add it automatically.
  89.    So `AF DOC` is tedious enough. (I am still waiting for the computer
  90.    reading in my mind, taking it's orders DIRECTLY at the source. Hope I
  91.    live long enough to `see` that !).
  92.  
  93.    The [1-9A-Z] and other enhancements of 4Dos 4.0 and Borland's Grep are
  94.    for the future (these are called `regular expressions`). Please take note
  95.    that the file AF.INC is the standalone Pascal source of the mask matching
  96.    mechanism. It's very short. Take a look at it and re-use it at will !
  97.  
  98.  
  99.    Command line parameters
  100.    -----------------------
  101.  
  102.    Parameters can be prefixed (preceeded) by either `-` or `/`. Most of
  103.    them can be cumulated together.
  104.  
  105.    Some parameters change the state of `boolean` (True/False) values.
  106.    In the list below, they are listed with a `+` or `-` sign to indicate
  107.    the default value.
  108.    You can either inverse the value or stick it to True or False. See below.
  109.  
  110.    /G+  Global search
  111.         This tells AF to search for files on disk. If this option is turned
  112.         off, AF will only search in archives.
  113.  
  114.    /R   initial diRectory
  115.         If this options is not specified, AF starts in `\` (current disk's
  116.         root directory).
  117.         /R must be immediately (no whitespace) followed by the directory
  118.         name.
  119.         e.g.: AF /RC:\UTIL
  120.         Specifying then final `\` is not necessary, except if the root
  121.         directory is asked for.
  122.  
  123.    /S+  Sub directories too
  124.         This will make AF look in the directories situated below then
  125.         initial (/R) directory.
  126.  
  127.    /C   Current directory only
  128.         This is identical to AF /R. /S+
  129.  
  130.    /M  Only this mask when searching into archives. Use this if you wish
  131.        to search in FREE*.ZIP :
  132.        AF /MFREE*.ZIP
  133.        This mask is a regular DOS mask (*DOC*.ZIP not allowed). Only one
  134.        mask is allowed here.
  135.        If this option is not set, AF looks for /M*.*
  136.  
  137.    /A  Only look for archives whatever their contents. This option is
  138.        meant to `give an idea` of the number of archives present. It only
  139.        gives the archive names (and their size if the /F parameter is
  140.        specified). You can use the /M option to only look for the LZH
  141.        archives : AF /A /M*.LZH (or AF -am*.lzh).
  142.        If you use the /F switch, you can sort the archives by size :
  143.        AF -af | Sort
  144.        You can also use file masks and the /N switch (preventing the word
  145.        `Archive` to appear). This is very useful for grouping all the archives
  146.        containing one particular kind of file to execute a command on them :
  147.        AF -A BBS.AD /N /M*.ZIP >FILELIST
  148.          ^this creates a file called FILELIST containing the full path name
  149.           of all the ZIP archives containing the file BBS.AD.
  150.           If you use 4Dos or NDos, you can then enter :
  151.        For %a in (@FILELIST) do Pkzip -d %a BBS.AD
  152.  
  153.    /P  Do not look inside the archives. This options, of course, speeds
  154.        up the search making AF act like any normal file finder.
  155.  
  156.    /E  Make AF also write the name of the archives not containing the
  157.        files matching the mask.
  158.        if the /G option is on, the directories not containing files matching
  159.        the mask(s) will also be displayed.
  160.  
  161.    /N  Only display the full path name of the files. I could have called
  162.        this option `batch mode`. It is useful to create file lists that
  163.        can be re-used by archivers or 4Dos programs or whatever.
  164.  
  165.    /W  Like Dos's /W switch for DIR : Wide display. Does only display
  166.        the file name (neither drive nor dir).
  167.  
  168.    /T  Display the size the file really occupies (if not in archive) or
  169.        the size it would occupy (if in archive) when unpacked to the
  170.        specified or implied disk. MSDOS uses disk space by clusters. So
  171.        one file, even 1 byte long occupies 512 bytes on a diskette and
  172.        at least 1024 bytes up to 8192 bytes on a hard disk depending on
  173.        the FORMAT that was made.
  174.        Specifying /T immediately followed by the name of the drive on which
  175.        you want to unpack the files, AF calculates the size it would
  176.        REALLY occupy on this particular disk. /T0 means current drive.
  177.        This options automatically activates the /F switch (display totals).
  178.  
  179.        For example:
  180.        AF /GTC /MARCHIVE.ARC *.PAS
  181.           tells the size occupied by the *.PAS files (contained in ARCHIVE.ARC)
  182.           once unpacked on disk C:
  183.        AF /GTA /MARCHIVE.ARC *.PAS
  184.           same but on A:
  185.        AF /GT0 /MARCHIVE.ARC *.PAS
  186.           if `0` (zero) is specified after the /T, AF detects what disk to
  187.           use default or the one specified by /R.
  188.        AF /GU /T- /MARCHIVE.ARC *.PAS
  189.           if you use `-` (minus sign) as the disk's name, AF will not look
  190.           for the real size. Use this when modifying an alias execution or
  191.           using the /U switch.
  192.  
  193.    /F  Display the totals. Number of files found in archives, not in archives
  194.        and total, with the respective sub-total REAL size.
  195.  
  196.    /U  Only display the totals. This automatically activates /F+ and /T0.
  197.        You can remove /F switch by specifying /F- after /U
  198.  
  199.    /*  High speed search : AF will not look for directories with an
  200.        extension like SILLYSFT.DIR
  201.        This REALLY speeds up the search. It is only active when AF does
  202.        not have to look inside archives.
  203.  
  204.    /D  Lets you select a date after and/or before which the file has been
  205.        modified.
  206.          AF *.COM /d+011580   : all .COM files modified on Jan,15 80 or after
  207.          AF *.COM /d-011590   : all .COM files modified on Jan,15 90 or before
  208.          AF *.COM /d=011590   : all .COM filed modified on Jan,15 90
  209.            same as
  210.          AF *.COM /d+011590 /d-011590
  211.        If no date is specified after /D+ /D- or /D=, it means today.
  212.          AF *.* /d=   displays all the files modified/created today
  213.  
  214.    /I  In a same way, this lets you select files to display depending on
  215.        their size.
  216.          AF *.COM /i+1024   : all .COM files greater or equal 1024 bytes
  217.          AF *.COM /i-1024   : all .COM files below   or equal 1024 bytes
  218.          AF *.COM /i=1024   : all .COM files of exactly       1024 bytes
  219.  
  220.    /L  Select which drives to search on. By default, AF looks on C, D and E.
  221.          AF *.COM /lABC     searches .COM files on A: B: et C:
  222.        /L0 (zero) means only look on current drive or /R specified
  223.  
  224.    /B+ AF 1.19 and up have another look for displaying files, a bit like SST
  225.        Supersonic Search Tools from Keith Ledbetter). The /B option is used
  226.        to deactivate this look and give a more Dos-conventionnal display.
  227.  
  228.    /X+ AF 1.26 introduces EXE Self extracting archives processing for ARJ and
  229.        LZH (handling PkWare's is as always a hassle so you'll have to wait
  230.        for it).
  231.        This parameter enables the EXE files processing (it is on by default)
  232.  
  233.    /)  This option tells you what AF understood while parsing your
  234.        command line. VEERRRYYY useful to understand why something does not
  235.        work as you would. If you have a problem with a command line, retype
  236.        it (or recall it) and add /) or -)
  237.  
  238.  
  239. Redirections
  240. ------------
  241.  
  242. AF can be used redirected. That is using the `|` and/or `>` sign.
  243. For example, to store the result of a search in file TEMP.LST you just
  244. add >TEMP.LST to your command line :
  245. Ex: AF *.PAS >PASLIST
  246. You could also ask for a pause between pages by typing
  247. AF *.PAS | More
  248. or get the sorted archives list in a file
  249. AF /AF |Sort >LISTARCH.TXT
  250. Etc...
  251.  
  252.  
  253. Entering parameters
  254. -------------------
  255.  
  256. Note you can group commands together.
  257. Exemple :
  258.    AF -cp      same as      AF /c /p
  259. But :
  260. Parameters /M... /R... and /L... can only be at the end of such a grouping :
  261.    AF -cpm*.ZIP    is valid
  262.    AF -cp*.ZIPm    is not
  263.  
  264. You can also specify explicitely if the parameter should be activated or
  265. disabled. Just add a `+` or a `-` (minus) immediately after the command
  266. (command grouping is still possible). This is very useful to force a
  267. parameter if you use batches or synonyms/alias/doskeys.
  268. Example :
  269.    AF /C+P+   same as      AF /cp
  270.               because -c et -p are `-` by default
  271.  
  272. AF analyses the parameters one after the order from left to right. If an
  273. option appears twice on the same command line, is important :
  274.    AF /P/P  does nothing
  275.  
  276.  
  277. Examples
  278. --------
  279.  
  280. To understand all the power of AF, you should try the following examples :
  281.  
  282. Find all *.DOC files wether they are on the disk or placed in an archive :
  283.    Af *.doc
  284.  
  285. Find all *.DOC files only in archives :
  286.    Af *.doc /G-
  287.  
  288. Find all *.DOC files on the disk without looking in archives :
  289.    Af *.doc /P
  290.  
  291. Find all *.DOC files on the disk without looking into archives, searching
  292. only in directory \DOS and it's subdirectories :
  293.    Af *.doc /P /R\DOS
  294.  
  295. Find all *.DOC files on the disk, not in archives, only in directory \DOS :
  296.    Af *.doc /P /S /R\DOS
  297.  
  298. Find all *.DOC files on the disk, not in archives, only in current dir :
  299.    Af *.doc /P /C
  300.  
  301. Find all *.DOC files in the current directory and in *.ZIP archives (of current
  302. dir) :
  303.    Af *.doc /G- /C /M*.ZIP
  304.  
  305. Find all *.DOC files in the current dir and in *.ZIP archives, displaying
  306. REAL occupation size and total sizes :
  307.    Af *.doc -t0fm*.ZIP
  308.        can also be written
  309.    Af *.DOC /T0 /F /M*.ZIP
  310.  
  311. Find all *.DOC files on the disk, not in archives, displaying full path names
  312. (for use in batch files) :
  313.    Af *.doc -pn
  314.  
  315. Find all *.DOC and *.TXT files on the disk and within archives
  316.    Af *.doc *.txt
  317.  
  318. Find all *.DOC files, not in archives, on disk H: only :
  319.    Af *.doc -plh
  320.  
  321. Find all *.DOC files, only in archives being on H:
  322.    Af *.doc -glh
  323.  
  324. Find all files modified or created today on the disk only
  325.    Af /PD=
  326.  
  327. Find all archives
  328.    Af /A
  329.  
  330. Find all archives containing some .DOC files
  331.    Af /A *.DOC
  332.  
  333. Find all archives containing some .DOC files, listing them with full
  334. path name. This is VERY useful in batch/aliases
  335.    AF /AN *.DOC
  336.  
  337. Find all self-extracting archives (recognized by AF)
  338.    AF /ANM*.EXE
  339.  
  340.  
  341. Users of 4Dos / CED / DosEdit / DosKey
  342. ---------------------------------------------
  343.  
  344. You HAVE TO make aliases (synonyms) with AF !
  345.  
  346. This is a FileFind equivalent (just faster)
  347. Syn FF AF /P /* /R%1 %2 %3      for CED
  348. FF=AF /P /* /R%1                for 4Dos
  349.  
  350. To view one/many archives in current dir (this is the most powerful one) :
  351. Syn V=AF -CG-t0M%1 -l0 %2 %3 %4     for CED
  352. V=AF -cg-t0M%1 -l0                  for 4Dos
  353. With this you can do :
  354.   v             View all archives contents
  355.   v a           View all archives, any type, name starting with an `A`
  356.   v a:*.ZIP     View all A:*.ZIP archives
  357.   v * *.DOC     View all *.DOC files contained in archives of current dir
  358.   v * /g        View everything in the current dir, inside and outside archives
  359.   and so on...
  360.  
  361. Even a DIR command (you won't get the directory names) :
  362. DDIR=AF /PC %1
  363.  
  364. A DIR displaying real file sizes :
  365. FDIR=AF -pct0f %1
  366.     p=don't look in archives
  367.     c=only in current dir
  368.    t0=detect current or specified disk
  369.     f=display totals
  370.  
  371. Remark: In the examples of FF and V, the first parameter (%1) is passed
  372.         to /R or /M. If you wish to add parameters to the command line
  373.         with a /U for instance, you will have to enter :
  374.           FF .\ /U
  375.           V * /U
  376.  
  377.           The `*` alone is the widest mask for AF. It's MSDOS *.*'s
  378.           equivalent. *.* will work also but is much tedious.
  379.  
  380.  
  381. If you missed the beginning
  382. ---------------------------
  383. I'm sorry, since version 1.25 of AF is the first English version, I won't
  384. waste time/energy translating all the list.
  385.  
  386. - 1.25  English version
  387. - 1.26  Removed a bug in the memory management
  388.         Added EXE self extracting archives processing for ARJ and LZH
  389.  
  390.  
  391. Diffusion
  392. ---------
  393.  
  394. This program is placed in public domain WITH ITS SOURCES. Anyone can use,
  395. give away, modify or include all or part of it at the only condition of
  396. explicitly giving proper credit to it's author. When I say anyone, I
  397. really MEAN it, even for commercial purposes, even for CDROMS...
  398.  
  399.  
  400. Planned changes
  401. ---------------
  402.  
  403. - Correctly handle SIT (mac) files and add CPT (mac compactor) formats
  404. - add SQZ format
  405. - add Self-extracting archives for PkWare's
  406. - File exclusions
  407. - Limit searches to n files
  408. - Command execution on found files (maybe)
  409. - improvements of -) option
  410. - Debugging of masks containing a #
  411. - Support of all TPZ archives
  412. - Use of an environment variable and/or config file to modify AF's default
  413.   options (you can recompile it if you have nearly any version of TP/BP),
  414.   changing the default options to your convenience
  415. - Use of an environment variable to retrieve the "real" unpacked size of
  416.   files (with cluster overhead). Would be useful with 4Dos/NDos !
  417.  
  418.  
  419. Contact
  420. -------
  421.  
  422.    Minitel (France)         3614/3615  DP
  423.  
  424.    CompuServe               100117,3213
  425.  
  426.    Usenet                   cat@spia.frmug.fr.net
  427.  
  428.    French mail              Jean-Christophe Boggio
  429.                             8, rue de la Corne
  430.                             37370 Chemillé sur Dême
  431.                             France
  432.  
  433.  
  434. Thanks
  435. ------
  436.  
  437.    to JrB for writing LhFind (which searches in Yoshi's LZH). It was
  438.       AF's ancestor
  439.    to Philip Burns, the author of PibCat for the ZOO format
  440.    to Vernong Buerg's FileView which gave me the idea of the /W command
  441.       (i never used it before)
  442.    to Master Yoshizaki (Lharc's author) for making me discover compression
  443.    to Master Jung (RK not CG) for writing the best ever (the easiest and
  444.       most powerful) archiver, I named ARJ.
  445.    to Keith Ledbetter (SST author) for the challenge
  446.    to PkWare for their PkArc and PkZip 1.1 programs (PkZip 2.x is really
  447.       an awful bug nest. I hate being forced to use it.
  448.    to Patrick `Next` Teil for his TPZ archiver and his shell for AF
  449.    to all of those who reported bugs, ideas (GEX, California, Kadorbra,
  450.       Next, Solex and the other ones)
  451.    to you for using Archive Finder.
  452.  
  453.  
  454.  Author: Jc Boggio   Diffusion: Public domain with Turbo Pascal source code
  455. Version: 1.26             Date: August, 14 1993
  456.  
  457.