LS...

       * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
       *                                                               *
       * LS is the equivalent of the AmigaDOS command List. It lists a *
       *                                                               *
       * directory in such a way that it'll  wait for you to press the *
       *                                                               *
       * [RETURN] key to list the next part (Handy when you're working *
       *                                                               *
       * with a small CLI window).                                     *
       *                                              M.i.A. Software. *
       *                                                               *
       * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


 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.


 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: 303-290-8429

 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 format-
 ting 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:

 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 af-
 ter 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 option-
 al 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 form-
 at, 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 a-
 round 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