The CDPD Public Domain Collection for CDTV 3/CDPDIII.bin/fish/771-780/ff773/ls/ls.doc

Text File | 1992-12-05 | 24KB | 636 lines

                                LS 4.7ljr
                            USER DOCUMENTATION
                         Mon Oct 26 01:31:10 1992

IMPORTANT NOTE: LS 4.7ljr is compatible with Amiga OS Release 2.04
        (and later) ONLY!

Use version 4.4ljr or before if you haven't upgraded to 2.04 yet.
Due to library version differences and bugs, this software will not
work with pre-release versions of 2.0 (basically anything below 2.04).
LS 4.7ljr will report ``ls: Need AmigaOS Release 2.04'' if it doesn't
think that you have the correct version of the OS installed.

The change to 2.04 ONLY was done for various reasons (ranked from
most to least important):
1) More robust, powerful and consistent pattern matching.
2) More robust and consistent date handling.
3) 2.0 style (local) environment variables.
4) Author's desire to `convince' people to upgrade to 2.04.
5) Smaller binary size (due to use of ROM library routines).
   Of course all the new features help offset this saving... :-)

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

     LS 4.7ljr - A versatile Amiga directory listing utility.

This software is Copyright © 1989, 1990, 1991, 1992  Loren J. Rittle.
This software is Copyright for the sole purpose of protecting
the fact that this is indeed free software.

This software is wholly based upon Justin V. McCormick's PD LS
``V3.1    July 29, 1989'' with enhancements and bug fixes by
the copyright holder, Loren J. Rittle.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

The word free above refers to freedom of software not cost of software.
Learn about software patents.  Learn about interface copyrights.  Learn
why you as a user should abhor software patents and interface copyrights
in their current (and becoming) form.

I can be reached at the following address:

Loren J. Rittle
1008 Landing Rd.
Naperville, IL  60540
[phone]

EMail: [e-mail]
       and as 'Loren Rittle' on the MicroTech BBS [phone]

Original Notices by Justin:
/*
 *      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
 *
 *    Justin V. McCormick 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!

People who like the UNIX ls should feel right at home.

LS Version 4.5ljr, Sun Dec 29 22:23:52 1991
Usage: ls [-h?acdeklnrst1ADFHIMNOPRTXY <args>] [path] ...
    a  List all entries        A  Display entries across line
    c  Show filenotes        D  Show dirs last
    d  About dirs            F <format> Format output
    e  Sort by extension        H  No headings and subtotals
    k  No ANSI display codes    I <pattern> Ignore pattern
    l  Long listing            M  Mixed output files and dirs
    n  No sort            N <date> Show newer than date
    r  Reverse sort            O <date> Show older than date
    s  Sort by size            P  Show full pathnames
    t  Sort by date            R  Recursive listing
    1  Force one entry per line    T  Total all subtotals
    Y <high> Set output rows    X <wide> Set output columns


Installation:
-------------

LS can be put in your C: directory where LIST and DIR are
normally found.  LS can be made resident in your s:user-startup
(2.0 and later) or s:startup-sequence (1.3 and before), but you
may need to set the pure bit on LS after dearchiving to prevent
spurious warnings:

    protect c:ls +p

Normal Shell users should add to s:user-startup (2.0 and later)
or s:startup-sequence (1.3 and before):

    resident c:ls

WShell users would want to add to s:Config-WShell:

    resi c:ls


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:

'-' and '--' signal the end of options on the command line to
allow filenames that begin with a dash to be specified:

    ls -l -- -l        - long listing of a file called '-l'.

Also, a non-option argument signals the end of options on the
command line:

    ls -l df0: -R      - long listing of df0: and then a
             long listing of a file called '-R'.

However, if you specify several file or path names, the options
will *not* (as opposed to version 3.1 by Justin) return to
their default settings between paths.  For example:

    ls -l df0: df1:    - this will cause ls to print the long listing of
             df0: then the long listing of df1:


Options:
--------

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

    LS -? or LS -h (this output is shown up in the Synopsis section)

Here is the complete list and description of the options:

a   List all entries [LS usually skips those files which have
    their 'h' protection bit set or their file name's of the
    form .#? (Like unix ls), #?.bak or #?.info (Because I hate to
    see the damn things).  With the -a option, LS will reveal all
    entries in a directory].

    "(#?.(info|bak)|.#?)" is the default hide pattern.  This
    can be changed by setting the ls_hidepattern local environment
    variable (see subsection entitled, ``Environment variables'').
    For example, the following issued in a shell (or added to a
    shell-startup command file): set ls_hidepattern ".#?",
    would cause Amiga ls to function as a normal unix ls.

c   Show filenotes, implies long listing.

    The placement and way filenotes are displayed can be modified
    by setting the ls_highlight0.on and ls_highlight0.off local
    environment variables (see subsection entitled, ``Environment
    variables'') and the format string (see subsection entitled,
    ``Formatted Output'').  The default format string is
    "%p %5b %8s %d %n%w%C\\n".  The %C sequence is the place the
    filenote will appear in the output if requested with the '-c' option.
    ls_highlight0.on defaults to "\n\x9b" "2m/* " and ls_highlight0.off
    defaults to " */\x9b" "22m".  Thus all filenotes will appear on the
    line after the normal long listing entry (that \n means linefeed
    in case you don't know C style formatting).  E. g.

    R(0);T(00.266) > ls -c ram:a
    -----rwed c     1        0 Sep 30 22:37 a
    /* this file is neat */

    For example:
    R(0);T(00.000) > set ls_highlight0.on " /** "
    R(0);T(00.016) > set ls_highlight0.off " **/"
    R(0);T(00.000) > ls -c ram:a
        -----rwed c     1        0 Sep 30 22:37 a /* this file is neat */

d   Show information about directory entries only (i.e. doesn't
    display the files in a directory).

e   Sort by extension.

k   Do not use ANSI escape codes in output (for colored text,
    hiding cursor and obtaining the size of the window).

l   Give long listing.

n   Do not sort entries before displaying.

r   Reverse sort direction.

s   Sort entries by size.

t   Sort entries by date.

1   Forces one entry per line of output. Useful when piping ls output to
    other programs.

A   Force listing to flow across a line instead of down a column.
    For example:
    Without -A option you might see:
        apple  far    zip
        blue   ghost
        cars   jacks

    But with the -A option you would see:
        apple  blue   cars
        far    ghost  jacks
        zip

D   Show directory entries last.

F   Format output (see below).

    Please see ALIASES/ for some example usages of this feature.

H   Do not print directory headings or subtotals.

I <pattern>   Ignore pattern.
  Do not show entries that match the given pattern.
  May be given multiple times on a command line (As per GNU ls).
  Please see the section entitled ``Wildcards'' for more details
  on the format of a pattern.  In short, uses the standard Amiga OS
  Release 2.04 pattern matching style.

M   Mix directory and file entries together in final output list.

N <date>   Show entries that are newer than the given date.
O <date>   Show entries that are older than the given date.
  Currently a date must be formatted as follows:

    /* Standard "MMM DD HH:MM YYYY" 'ls' format */
    "Dec 09 21:19 1991" or "Dec  9 21:19 1991"
    (two spaces or a ' 0' MUST be present before a single
     digit day of month.)

  OR

    /* Standard "DD-MMM-YY HH:MM:SS" AmigaDOS 'date' and internal format */
    "08-Jan-92 18:35:38"

  I have ARexx scripts called todayls, weekls and monthls that
  use these features.  Please see REXX/ for these macros.  As I
  can't imagine anyone actually using these features in the raw, I
  can't see a good reason to provide a more general/standard date
  format...  Finally, you will note that the date format is quite
  close to the standard 'ls' long listing date format (except the
  user is always required to list both the year and the hour:minute,
  instead of one or the other).

P   Print full pathnames for all entries, implies one entry per line.

R   Recursive listing, descend into subdirectories that matches pattern.

T   Print grand total of all entries.

  If LS cannot determine 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.

BTW, LS doesn't care what the number of rows in a window is
anymore.  -Y is obsolete, but left in LS for compatibility
with past releases.  LS needed the height of a window to support
pagination (which was removed because it was a masive hack! :-).

Actual method to determine horizontal size:

The actual method for finding a horizontal size to use is as
follows (in order checked):

1. -X <wide> (or -1 option)

2. size returned from the Windows Bounds Request.

[NOTE: Step two is skipped if the output is not to an interactive
file or if the suppress ANSI escape codes option ('-k') is given.]

3. 2.0 style (local) environment variables `console_width'.

4. Hard-coded 77.


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, "MMM DD  YYYY" (if entry is over 180
         days old) or "MMM DD HH:MM" (if a recent file).
    %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.
    %S<arg1>   Print the `time to upload' for this entry.
     <arg1> is the characters per second transmitted.
     Default, if not listed, is 230 cps which appears
     to be a good value for ZModem over a 2400 baud modem.
    %h   Print the `hex file size' for this entry.
    %C   Print filenote comment if present and requested with '-c'.
         Filenote comment will have the highlight entry 0 applied to it
         (see comments given in section describing '-c' option) before
         printing.  In general, highlighting (ANSI color sequences, etc.)
         should never be placed in the format string directly
         as it will not be filtered out correctly when ls is given the
         '-k' option or when ls is printing to a non-interactive device.
         In %C's case, this is especially important and in fact nothing
         related to filenote formatting should be included because not
         all files have filenotes and in any event they are not always
         printed.
    %%   Print a percent symbol.
    \n   Print a linefeed.
    \t   Print a tab.
    \"   Print a double quote (").
    \\   Print a backslash symbol.

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

    -F "%p %5b %8s %d %n%w%C\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

WShell 2.0 users could say the following to perform the same
operation and avoid the use of a temporary file (and a bit of
typing :-):

    ls -PF "copy %n RAM:\n" df0:#?.h | stdin


User Customization of the Short Listing:
----------------------------------------

  Above, user customization of the long format is discussed.  Now we turn
our attention to look at user customization of the short listing.  LS
implements user definable highlighting to entry types in the short listing.

What does that mean in plain English?  In past versions of LS, the default
was to color directory entries in the short listing, but keep plain file
entries colored normally.  If the output was to a non-interactive file
(e.g. a pipe or a file on disk) or the '-k' options was given on the
command line, then the default changed to appending a '/' to directory
entries in the short listing.

With the advent of Amiga OS Release 2.04, there are now many more types of
entries that can appear on a filing system (a disk).  A number is
associated with each entry type, e.g.:
-4     is associated with a FILE LINK (hard link)
-3     " " " PLAIN FILE
-2 - 0 " " " NOT USED CURRENTLY
1      " " " ROOT
2      " " " USER DIR
3      " " " SYMBOLIC LINK (soft link)
4      " " " DIR LINK (hard link)

[Please note that C= currently recommends that users not use soft links.]

By default, LS 4.7ljr highlights entries as follows:
FILE LINK: boldface
PLAIN FILE: plain
everything NOT USED CURRENTLY (as of OS 2.04) and out of range: plain
ROOT: secondary color
USER DIR: secondary color
SYMBOLIC LINK: italics
DIR LINK: boldface, secondary color

Users of LS can modify the highlighting to be applied to each and every
file type by simply setting local environment variables.  Users can set as
many or as few of the highlighting strings as they want, but must always
set the 'on' string for LS to look for a new 'off' string.  These setting,
as all local environment variables, are on a per shell basis.

The names of the environment variables to set is generated by concatenating
the string sequences given below:
"ls_highlight" <number_of_filetype_to_set_for> ".on"
"ls_highlight" <number_of_filetype_to_set_for> ".off"

For example, ls_highlight3.on would be the prepend string related to
directory entries.  Likewise, ls_highlight3.off is the name of the
append string related to directory entries.

Entering
set ls_highlight3.on ""
set ls_highlight3.off "*e[2m/*e[22m"
would tell LS to append a colored '/' after each directory entry in a short
listing.

LS will keep track of the number of printable characters in the
highlight strings and continues to format columns properly.  LS
only supports embedded ANSI sequences that start with a CSI ('0x9b') or
ESC ('0x1b') '[' and end with 'm'.  These ANSI sequences handle everything
from text style to text color (foreground to background).  As a special
exception, a filenote comment highlighting string (0), is set to
"\n/* " (on) and " */" (off) if found to contain an ANSI sequence.

Sample ANSI sequences (as used from shell):

"*e1m" boldface
"*e2m" faint (secondary color)
"*e22m" normal color, not bold
"*e3m" italic
"*e23m" italic off
"*e4m" underscore
"*e24m" underscore off
"*e7m" reversed
"*e27m" reversed off

"*e3<digit 0-7>m" character color
"*e39m" default character color
"*e4<digit 0-7>m" background color
"*e49m" default background color

"*e1;2m" boldface, faint (secondary color)
"*e22m" normal color, not bold
"*e1;34m" boldface, color 4
"*e22;39m" normal color, not bold

For more information see: ``Amiga ROM Kernel Reference Manual: Devices''
3rd Edition pages 69-71.

If the output of LS is to a non-interactive file (e.g. a pipe or a file on
disk) or the '-k' options was given on the command line, then the prepend
('on') and append ('off') strings are striped of ANSI sequences.  The
search only checks the first character of each string to see if it is
either a CSI ('0x9b') or ESC ('0x1b').  If an ANSI sequence is detected,
then *both* highlighting strings are set to "".


Environment variables:
----------------------

  Starting with LS 4.5ljr, LS uses the standard 2.0 style (local)
environment variables and support routines.  See HIGHLIGHT_SETS/
for some example usages.  The following is a list of all the
environment variables LS deals with:

console_width (see subsection entitled, ``Actual method to determine
horizontal size'')

ls_highlight-4.on, ls_highlight-4.off, ls_highlight-3.on, ls_highlight-3.off
ls_highlight-2.on, ls_highlight-2.off, ls_highlight-1.on, ls_highlight-1.off
ls_highlight0.on, ls_highlight0.off, ls_highlight1.on, ls_highlight1.off
ls_highlight2.on, ls_highlight2.off, ls_highlight3.on, ls_highlight3.off
ls_highlight4.on, ls_highlight4.off (see section entitled,
``User Customization of the Short Listing''), ls_hidepattern (see '-a'
option subsection)

Note that LS doesn't require any environment variables to be set.
The use of these environment variables is for advanced users to
take advantage of advanced features in LS.  Also, note that for
performance reasons, LS only refers to local environment variables.


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

  Starting with LS 4.5ljr, LS uses the standard Amiga OS Release
2.04 pattern matching style and support routines.  If you want to
continue to use a UNIX-style '*' in patterns, you should look into
obtaining StarBurst or some similar utility that turns on the
RNB_WILDSTAR bit in DOSBase->dl_Root->rn_Flags.  This is one area
that the standard Amiga OS is so far ahead of the unix standard
that I had to switch!

  Wildcards may be used in file names and in the last level of a
directory path name.  The '#?' characters are 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 100 separate
pathname patterns in per command line.

Please refer to page 7-31 of the Amiga Release 2 Manuals or page 255
of ``The AmigaDOS Manual 3rd Edition'' for more details.  The
following chart may help someone who already knows what regular
expressions are (actually, with the examples anyone should understand):

'?' - match a single character.
      E.G. a?b matches 'axb', 'ayb', 'atb', etc.

'#' - matches the following expression 0 or more times.
      E.G. a#?b matches 'ab', 'axxb', 'ayyb', 'azitb', etc.
       a#b matches 'a', 'ab', 'abb', 'abbb', etc.

'*' - synonym for '#?' if WILDSTAR option is turned on.  NOT on by
      default.  The WILDSTAR option is a system wide option, thus
      there is no switch in ls to control it.
      E.G. a*b matches 'axxb', 'ayyb', 'azitb', etc.

'(' - start a new expression.
'|' - separate items enclosed in '(' and ')'.
')' - end an expression.
      E.G. (cat|dog) matches 'cat' OR 'dog' only.
       #(cat|dog) matches 'cat', 'catcat', 'catdog', 'dogdogdog', etc.

'~' - negate next expression.
      E.G. ~(cat|dog) matches anything but 'cat' OR 'dog'.
      E.G. ~c#? matches anything that doesn't start with a 'c'.

'%' - matches 0 characters. (only considered special if other
      wildcards are present at same level, or in '(cat|%)' case).
      E.G. hi(cat|%)(dog|%) matches 'hi', 'hicat', 'hidog', 'hicatdog' only.

'^' - listed in include file, but I don't know what it does...

'[' - start character class.
'-' - range (only special in '[]')
']' - end character class.
      E.G. [a-z]#? matches anything that starts with 'a' through 'z'.

'<any char not listed above>' - an expression.
      As you have seen above, any plain character matches itself.
      LS uses the `NoCase' style pattern matching routines, thus
      an 'a' or 'A' will match an 'a' or 'A', etc.

Here are some simple examples:

    LS -a df0:#?.info       ; List all .info files in df0:
    LS -a df0:#?/#?.info    ; List all dirs and .info files in df0:
    LS -a df0:l#?/#?.info   ; List dirs that start with 'l' and .info files

[NOTE:  '-a' is needed because the current implementation of LS gives
greater weight to patterns provided by '-I' and the builtin ignore
patterns, namely #?.info, #?.bak and .#?, over explicitly mentioned
patterns in all cases.  This problem is being looked into.  It seems that
explicitly mentioned patterns should override particular ignore patterns in
some cases.  E.g.  #?.info or source#?.info should override the builtin
#?.info ignore pattern.  BUT, #? should not override the builtin #?.info
pattern.

I currently believe the rule could be written as follows:  If ignore
pattern A covers explicitly mentioned pattern B, then ignore pattern A
should be discarded while dealing with explicitly mentioned pattern B.  The
definition of cover is the same as when used in boolean algebra (function A
is true whenever function B is true).

Because of the computation time involved, I don't think that this
problem will be addressed anytime soon.  In fact, in general, proving that
one pattern covers another may be NP complete or impossible.  Since 99.99%
of the time (or more :-) we could care less about the files mentioned in
the default ignored list it makes no sense to slow down the program to
cover this odd case.  I just wanted the user to be informed of this
behavior.  -ljr]

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

    LS -I #?.o         ; List current dir, do not show .o files.
    LS -I #?.o df0:    ; Same as above but lists df0: instead.
    LS -I #?.o df0:c#? ; List entries that start with the letter "c"
                       ; in df0:, but do not list .o files.