Amiga Elysian Archive/AmigaElysianArchive.iso/newc_dev/ls32.lha/ls.doc

Text File | 1992-06-10 | 9KB | 269 lines

                   LS 3.0 USER DOCUMENTATION

-----------------------------------------------------------------------

     LS 3.0 - A versatile Amiga directory listing utility.

Revision History:

  V1.0    August 1986 Written from scratch by Justin V. McCormick.
  V2.0  November 1988 Revised for Lattice 5.0 and made 1.3 compatible.
  V2.1  December 1988 Minor size reduction, fixed a few bugs from 2.0.
  V2.2  December 1988 Fixed status return and multiple wildcard pathnames.
  V3.0  July 25, 1989 Instant sorting, best-fit output, new features.
  V3.1  July 29, 1989 Bug fixes, new output width and height options.
  V3.1a May  28, 1992 Now works with O.S.2 (by Paolo Dell'Aquila)
  V3.2  June 10, 1992 new options: now give the real block occupation

Notices:

  This program is placed in the public domain with the
understanding that the author makes no claims or guarantees with
regard to its suitability for any given application, and that
the author assumes no responsibility for damages incurred by its
usage.  Any resemblance of this program to any other program,
either living or dead, is purely coincidental.

  Feel free to borrow this code and make millions of dollars
from its sale or commercial use, but please give credit where
credit is due.

  Please do not send me money or stolen software!  I enjoy mail,
phone calls, and legitimate software contributions of all kinds.

           Thanks for your encouragement and support,
                      Justin V. McCormick

I can be reached via:

  BIX: jmccormick
PLINK: JVM

PHONE: [phone]

USMAIL: 8330 E. Quincy Ave.
        Bldg. C, #312
        Denver CO, 80237



Synopsis:
---------

  Features intelligent columnar listing, versatile sort options,
UNIX-style pattern matching, recursive subdirectory listing,
customized output formatting and much more!

Usage:
        LS [options] [pattern1] [pattern2] ...


Installation:
-------------
LS can be put in your C: directory where LIST and DIR are
normally found.  LS can be made resident in your
startup-sequence, but you must set the pure bit on LS after
dearchiving to prevent spurious warnings:

    PROTECT C:LS +P

Or you can ignore the pure bit warning in the startup-sequence:

    RESIDENT >NIL: C:LS PURE


The Command Line:
-----------------

  All arguments are optional.  The default action is to give a
short columnar listing, sorted alphabetically, using the current
directory.  Alphabetizing is always case insensitive.

You can group your options together in any order, like this:

    LS -tlr df0:

Or you can have options specified independently:

    LS -t -l -r df0:

However, if you specify several file or path names, the options
will return to their default settings between paths.  Thus, you
have a command like this:

    LS -l df0: -r df0:

This would give you a two listings of df0:, the first one a long
listing, and the second one a reverse sorted short listing.


Options:
--------

  There are many command options for LS.  You can get a quick
reference list of options by typing:

    LS -?

Here is the complete list and description of the options:

a   Real block occupation (calculate also extension block). Both FFS and OFS
c   Show filenotes, implies long listing.
d   Show directory entries only.
f   Show file entries only.
h   Same as ?, help!
k   Do not use ANSI escape codes in output (for colored text).
l   Give long listing.
n   Do not sort entries before displaying.
p   Permit system requests ("Please insert disk xxx in any drive...").
r   Reverse sort direction.
s   Sort entries by size.
t   Sort entries by date.
v <pattern>
  Do not show entries that match the given pattern.

D   Show directory entries last.
H   Do not print directory headings or subtotals.
I   Non-interactive short listings, no "MORE" prompt between pages.
M   Mix directory and file entries together in final output list.
P   Print full pathnames for all entries, implies long listing.
R   Recursive listing, descend into subdirectories that matches pattern.
T   Print grand total of all entries.

  If LS cannot read the current CLI window size, LS assumes the
output is 77 columns by 23 rows.  The following two options let
you control the output page width and length of the short
columnar listing:

X <wide>
  Set short listing page width to the given number of columns.
Y <high>
  Set short listing page length to the given number of rows.

  There are two special options that expect a valid directory or
filename after the option:

N <name>
  Show entries that are newer (more recent than) the given entry name.
O <name>
  Show entries that are older (less recent than) the given entry name.

  By using these two options, you can generate a list of files
newer or older than a given file or directory.  For instance,
suppose you had a directory containing C source files for a
project.  Typing "LS -t df0:" produces the following list of
files sorted by time:

    joe.c  fred.c  pete.c  ted.c  sam.c

Now, if we give the following command:

    LS -N df0:pete.c df0:

The following files newer than pete.c would be listed:

    ted.c  sam.s

Also, -N and -O can be used together.  This command:

    LS -N df0:fred.c -O df0:ted.c df0:

would produce the only file newer than fred.c and older than ted.c:

    pete.c

Tip:  If you need to list files older or newer than a certain
date, rather than a certain file, you can do this:

  echo >RAM:datemark "Marker"    ; Create a temp file in RAM:
  setdate RAM:datemark 07-Jul-89 ; Set the datestamp for the temp file
  LS -N ram:datemark df0:        ; List files newer than "datemark"
  delete ram:datemark            ; Remove the temp file


Formatted Output:
-----------------

  For customized output, there is a special option that expects
a format rule as the next "option":

F <format>
  Format output with <format), with the following special symbols:

    %p   Print the protection bits
    %d   Print the date, YY-MM-DD
    %t   Print the time, hh-mm-ss
    %b   Print the number of filesystem blocks used by this entry.
    %s   Print the number of bytes used by this entry.
    %n   Print the name of the entry.
    %%   Print a percent symbol.
    \n   Print a linefeed.
    \t   Print a tab.
    \\   Print a backslash symbol.

The default format rule that LS uses for long listings looks like this:

    -F "%p %d %t %4b %8s %n\n"

  Any of the format options that begin with the '%' symbol can
have an optional pad count that lets you specify how many
columns to use.  For example:

    -F "%40n\n"

would print each entry name right justified in a field of 40 columns.

  You can use this feature of LS to help create simple batch
command files.  For example, look at this command:

    LS -PF "copy %n RAM:\n" df0:*.h

  This tells LS to perform a listing using full pathnames with a
special format, matching only filenames that end with ".h" in
directory df0:.  Suppose df0:  has the following files in it:

    joe.h  fred.h  pete.h  ted.h

Our example LS command would result in the following list of commands:

    copy df0:fred.h RAM:
    copy df0:joe.h RAM:
    copy df0:pete.h RAM:
    copy df0:ted.h RAM:

We could create a script file from this by redirecting the
output of LS to a temporary file:

    LS >ram:templist -PF "copy %n RAM:\n" df0:*.h
    EXECUTE ram:templist    ;Do the script
    DELETE ram:templist     ;Delete it


Wildcards:
----------

  Wildcards may be used in file names and in the last level of a
directory path name.  The UNIX-style '*' character is used to
match any number of characters, and a '?' matchs any single
character.  If you need to specify a pathname with spaces in it
like "Wombat Soup", you need to put quotes around it.  LS can
process up to 30 separate pathname patterns in per command line.

Here are some simple examples:

    LS df0:*.info      ; List all .info files in df0:
    LS df0:*/*.info    ; List all dirs and .info files in df0:
    LS df0:L*/*.info   ; List dirs that start with 'L' and .info files

  Also, wildcards are helpful when you are trying to avoid showing
certain files with the "-v <pattern>" option.  For instance:

    LS -v *.info        ; List current dir, do not show .info files.
    LS -v *.info df0:   ; Same as above but lists df0: instead.
    LS -v *.info df0:C* ; List entries that start with the letter "c"
                        ; in df0:, but do not list .info files.

---------------------------------------------------------------------
        May all your directory listings be more readable,
                      Justin V. McCormick