Amiga Elysian Archive/AmigaElysianArchive.iso/newc_dev/dr_11.lzh/Dr.doc

Text File | 1990-10-21 | 15KB | 271 lines

                                    DR         (release 1.1)

What we got here is Yet Another CLI Directory Listing Command, called Dr
(pronounced "dr") because it leaves out icons.  (Like, the missing I in Dir
stands for icon...?  never mind.)  It is a => Fast And Full Featured <=
program which is superior to all of the seven other Amiga directory listers
I've tried.  I couldn't live without it.  Even its half-finished versions
were preferable to Dir.  This is version 1.0.  The features it offers are:

  + By default, .info files are not mentioned in the output.  Instead, it
    shows you which files have xxxxx.info files associated with them by
    writing their names in orange.  This makes it much quicker and easier to
    find the information you want, since more of the text on the screen is
    actually relevant.  Any xxxxx.info file that is not associated with a
    regular file or directory is shown normally, e.g. Disk.info.  You can see
    all .info files normally with the -I option.

  + It is fully reentrant and reexecutable.  The "pure" bit is set.  Make it
    resident, and AmigaShell has a classy built-in directory command.  (And I
    didn't use any fancy new purifying startup code either.  I made it pure
    the old fashioned way, by writing actual reentrant code in Aztec 3.6.)

  + It is about as fast as a directory listing program can possibly be on the
    Amiga.  (Which is still slow.)  Other allegedly fast listing programs are
    often slower (I have one that is sometimes slower than regular Dir), and
    sometimes can't handle some devices, or have errors where others don't,
    and some methods can sometimes fail to turn a floppy drive's motor off.
    Benchmarks: the root directory of the SoundScape disk (v1.4) has 57 files
    and directories.  Dir takes 16 seconds to scan it, eless takes 11,
    fd takes 10, Dir with FSDirs takes 11, and Dr takes 6.5 seconds.  (All
    times include writing output to a CON: window, with FastFonts.)  When I
    created a floppy disk directory with 200 files in it, some of them
    largeish in order to reduce efficient disk layout, Dir took exactly one
    minute to scan it, eless took 34 seconds, fd fired up "read/write error"
    requesters, and Dr took 16 seconds.  When using the Fast File System, Dir
    is almost the same speed as Dr, but there's still a slight improvement.

  + Other commands may be available (I would think so, but I don't actually
    have one) which will scan a single directory this fast, but I bet nothing
    else does recursive listing of subdirectories as fast as Dr does with its
    -R option.  Even with the Fast File System, the speedup is considerable.
    Benchmarks:  My hard disk's main partition, which uses the Fast File
    System, took 120 seconds to list with Dir Opt A.  Dr -R took 75 seconds.
    (The difference got smaller when I reformatted and restored the disk,
    reducing fragmentation.  The times then became 116 vs 88 seconds; the
    disk was much fuller in the second test.)  When I tried a floppy disk
    with lots of fragmentation and a complex directory structure (my most
    heavily used incremental backup disk) Dir Opt A took 71 seconds and Dr -R
    took 30 seconds.  Another backup disk produced times of 23 vs 10 seconds.

  + It arranges the output in a variable number of columns, with spacing
    based on both the length of the longest filenames and the width of the
    window.  It assumes a width of 77 when output is going to some file or
    device other than a CON: window.  By default, it sorts the entries in
    columns, not in rows.  This makes it easier to find things alphabetic-
    ally.  The -H option makes it sort in rows.

  + It handles AmigaDOS wildcard patterns, like #?.(c|o) to list all xxxxx.c
    and xxxxx.o files.  And if an actual directory has a name with pattern
    characters in it, like maybe a directory called "Doesn't-work?", it will
    list that directory instead of expanding the pattern.  You can force it
    to expand by adding an extra percent sign to the pattern, so it doesn't
    match the name.

  + It can sort alphabetically (the default) or chronologically (newest
    last) with the -C option.

  + It has an option (-O) to list each filename on a separate line as a
    complete pathname.  This is useful for generating input to other
    programs.  Especially when combined with -F (show only files) and -R
    (show contents of subdirectories).  Someday I'll add something like the
    LFORMAT option of List.  Files are listed in "natural" order (actually
    reverse natural order) when you use this, instead of sorted.  This makes
    the list more efficient for other programs to process, sometimes.

  + It can list the size of each file in bytes with the -S option, or list
    complete information about each file and directory (size, protection,
    datestamp, filenote) like the List program with the -L option.  -L is
    automatic if the argument you give it is the name of a single file
    instead of a directory.  The -X option makes it give this information
    about a directory instead of showing that directory's contents.

  + The -U option makes it like "du", showing only disk space consumption.

  + It uses a significant amount of memory, but if that much isn't available,
    it won't fail.  (Well not TOO often anyway...)  It will simply work less
    efficiently.  When there's only a little extra room, it will work at the
    same speed as Dir.

  + And last but certainly not least, it's public domain and the source
    code is provided.  This includes the fast directory scanning routines
    FastExamine and FastExNext, which many programs may find useful since
    they are almost compatible with regular Examine and ExNext.  See the file
    FastExNext.doc.  CREDIT:  the pattern matching code is PatMatch by Jeff
    Lydiatt, available on Fish disk 85.

Directory names are listed before file names, and they are separated by a
line of dashes, unless one or the other came up empty.  Each directory name
is followed by a slash.  Only the name itself, not the slash, is orange if it
has an icon.  Things with associated .info files will be marked as such even
if the .info file itself is excluded by the pattern, or by the -D option.  If
you list just a single file, it will check whether it has a .info file,
unless you use the -I option.  It does not check to see whether files with
names ending in .info are actual valid icon files.

Note that if the output is not a CON window, it doesn't show you which files
had icons.  It used to precede iconed names with a plus sign, but I concluded
that this was not a win.  If you want to find icons when you're saving the
output, you just gotta use the -I option.  Let me know if you want this
changed.  I heard that the numerous .info files are gonna disappear in
AmigaDOS 2.0 anyway.  That and FFS in ROM will eliminate most of my reasons
for writing Dr in the first place.  Sigh.  So the 2.0 version of Dr might
be two thirds the size of this one, but not really better than some other
programs.  Damn, a lot of the work I did in 1989 is turning out to be wasted.
It would have been less wasted of course if I had gotten this thing out the
door a year earlier ...  "Dr:  the Video Toaster of directory listers."

Pattern wildcard characters are currently only recognized at the end of
a pathname (that is, after the last slash or colon if any); you can't yet go
"Dr #?/src/#?.c" to find all .c files in subdirectories named src.  This
ability will be added someday.  If anybody cares.

USAGE:  type Dr followed by zero or more file names, directory names,
patterns, or options.  The options in this version are:

    ?   Briefly explain all of the options.

    -I  List .info files like normal files instead of marking the other
        files they are associated with.

    -S  Show the size of each file in bytes.

    -C  Sort chronologically (newest last) instead of alphabetically.

    -H  Sort into rows instead of columns, if more than one column.

    -O  Put each filename on a separate line, as a complete pathname.  There
        is no other extraneous output and no sorting.  Overrides -L, -S, and
        -C.  The beginning of the pathname is the directory arg you
        specified, not the absolute path.  (The pathname has a maximum length
        of 300 characters.)

    -D  Do not show file names, only subdirectory names.  Cancels -F.

    -F  Do not show subdirectory names, only file names.  Cancels -D.

    -L  Show sizes, protection bits, datestamps and filenotes like List.
        Overrides -S.  Show total bytes/blocks used.

    -X  Show directory args as if they were in a -L listing, instead of
        scanning their contents.  Ignored if -R or a pattern is used.

    -R  Recursively show contents of all subdirectories.  If you're going to
        descend a whole lot of levels (like more than about nine) you might
    need a bigger stack than the default 4K.  * NEW FEATURE * -=> Dr
    checks for adequate stack before entering each subdirectory.  An 8K
    stack would let you go about 40 levels deep.

    -U  Show only disk space consumed without listing any names.  Overrides
        -S, -L, -O, and -I.

Some other options and other features I might add someday:

    -A  Show file's timestamp as age; days and hh:mm:ss before present.
        Or maybe -G means aGe and -A means show absolute date without any
        stuff like "Yesterday" or "Wednesday".

    Some way to cause a pattern at the end of the path to apply to files in
        all subdirectories scanned.  That is, path/foo#? would now be
        essentially also equivalent to path/#?/foo#? and path/#?/#?/foo#?,
        etc.  Maybe a pattern that starts with :: acts this way.

    Along that line ... a pattern starting with ~ would mean, all files and
        directories that do NOT fit the pattern.

    Some way of inserting the filenames listed into a pre-specified line of
    text, like List's LFORMAT option.  Also an option to execute the line
    produced as a command instead of writing it out, thus creating a
    "ForEach" command or the equivalent of the SPAT and DPAT scripts.

You can give several option letters after one dash, like "Dr -ch foo".  The
case of the letters doesn't matter.  Each option affects those files and
directories that come after it on the command line, except that any options
at the end, after the last filename, act as if they were entered at the
beginning.  Example:  "dr foo -s bar" lists directory foo without showing
sizes, and directory bar with sizes shown.  If a directory name begins with a
dash, put quotes around so that it isn't taken as options.  If you give an
option twice, the second one cancels the first.  This means that if you make
an alias like "alias list dr -lc []", you can make it sort alphabetically by
saying "list -c".  Or, you can show directory foo with sizes, and directory
bar without sizes, with the command "Dr -s foo -s bar".

When you combine -R with a pattern, the complete contents of those subdirect-
ories whose names match the pattern will be shown.  If you combine -R with -D
or -F, all subdirectories will be listed, with only the directory or file
contents of each, according to the option, shown.

If you give more than one directory/pattern in the command line, each one's
listing will be preceded by the name you gave, written like this:
                              -- name --
unless you use -O in which case the different listings will not be
separated.  If you give no directory or pattern, it lists the current
directory, of course.  Or you can specify the current directory as empty
quotes: "".

Note that the usage totals given at the end of a -L or -U output count only
the files and dirs actually listed.  If some of the files are marked as
having icons, then the blocks used by those .info files are not counted (they
are in the case of -U).  Likewise things excluded by a pattern or -D or -F.
But the total count of blocks used by all files and directories is given in
parentheses.  If you want complete totals for everything, use the -I option
(if you're using -L and not -U) and don't use -D or -F or a pattern.

There is another version of Dr which is called Dr-S here.  It is smaller and
slower (and eats less ram as it runs) because it uses regular ExNext instead
of FastExNext.  To make it, compile dr.c with SMALLSLOW defined, and don't
link with fastex.o.  It is actually faster in some cases when AddBuffers
is of some use, e.g. if you list the same dir twice on the slow file system.
It is about 5k bytes smaller than the regular Dr.  Some users might prefer
it, especially those who don't use floppy disks much.

I did not give it a BCPL style argument template for reasons of size.  17k
is plenty for a resident command.  (That's sure a lot bigger than Dir or
List, but it's smaller than both together, and it pretty much replaces both.
It also replaces du (with the -u option) and Donald Kindred's rls (with
options -orf).)  Maybe I should have used arp.library ... would use less
memory *IF* you would routinely have that library loaded anyway.  I did make
sure that quoted quotes are done with *" instead of Manx's default "", and
that quotes make -options be treated as directory names.

The Amiga is now the fourth system I have written a directory lister for.
First was TOPS-20 (one that showed only files that you are the owner of),
next Kaypro II (fast, 2K long, sorted, showed size), third 4.2 BSD Un*#%$!x
(like ls -ls but faster because don't look up group names, just indicate
whether your group).  So this one is like the crowning achievement of a great
career in directory lister writing.  There is now almost no use at all for
any other directory lister, except maybe if you're using the LFORMAT option
of List (I'll write something to do that kind of job sooner or later), or you
actually find Dir's interactive mode to be of any use.  My original goal was
just to produce an adequate alternative that left out .info files; my goal
now is for Dr to be the best available.

Dr is in the public domain, written by

        bbses: try                      Paul Kienitz
        Winners Circle 415-845-4812     6430 San Pablo ave.
        Triple-A 415-222-9416           Oakland, CA  94608
        slower: FAUG 415-595-2479       USA

Feature suggestions and bug reports are appreciated.  I think it's pretty
bulletproof, but there might be some file devices it can't read properly,
one never knows.  Shareware incentive:  anyone who sends in a financial
contribution will receive...   (drum roll)   a nice thank-you note.  Which
is more than I've gotten from some of our better known hackers.


Differences between release 1.1 and release 1.0:

1.0 gurued on many device drivers which did not support ETD_READ.  1.1 uses
CMD_READ when ETD_READ fails, and the dumb mistake which caused a guru when
it tried to report the error was fixed.

1.1 pays attention to the MaxTransfer mount parameter, and if it is an
integral fraction of the track size it pretends that this fraction is a
"track", otherwise (gotta fix this someday) falls through to ExNext.

1.0 did not check for adequate stack.

It also had a small bug in reporting .info files with the -o option.