each v0.01 (12 May 1998)
========================

SYNTAX

    each <path> <expression>

DESCRIPTION

    "each" recursively descends the given directory path, evaluating the
    expression for each entry it finds.  Anyone familiar with the Unix "find"
    utility should be instantly at home as the syntax is (intentionally) very
    similar.

    The path should be any valid RISC OS path, such as "ADFS::4.$", or (for
    Unix compatibility) a single ".", which is automatically translated into
    "@".  The expression is composed of "primaries" and "operands" which are
    defined below.  Note that all primaries and operands must be separated by
    whitespace.

PRIMARIES

    -atime [+|-]<n>
    -ctime [+|-]<n>
    -mtime [+|-]<n>
        Synonyms for -time.  Provided for compatibility with find.

    -exec <command> [arguments ...] ;
        True if the command returns a zero value as its exit status.  The
        argument list is terminated by a single semicolon, which must be
        separated from the command or arguments (ie, "info %0 ;" rather than
        "info %0;").  The following arguments are available to the command:
            %0  the full pathname, as shown by -print
            %1  the pathname minus the starting directory
            %2  the leafname
        For compatibility with find "{}" is automatically translated into
        "%0", although only if it appears with whitespace on either side.

    -ok <command> [arguments ...] ;
        Identical to the -exec primary, except that you will be prompted
        before the command is executed.  If you choose not to execute it then
        the primary will evaluate to false.

    -name <pattern>
        True if the leafname matches the wildcarded pattern.  A "*" will
        match any number characters.  A "#" or "?" will match any single
        character.  A range of characters can be specified between "[" and
        "]", with a negated range indicated by immediately following the "["
        by either "!" or "^".  For example, the pattern "[0-9]*" would match
        any leafnames starting with a number, while "*[^a-zA-Z0-9]*" would
        match any leafnames containing non-alphanumeric characters.  These
        wildcard characters can be matched explicitly by escaping them with a
        backslash ("\").

    -newer <filename>
        True if the current file is newer than the specified file.

    -path <pattern>
        True if the full pathname matches the wildcarded pattern.  See -name
        for information on the wildcards.

    -perm [-]<permission>
        The permission is either an octal number (Unix/find compatibility) or
        a string.  Only bits 0606 of the octal number are used since these
        are the only ones that have a meaning under RISC OS.  The following
        characters have significance in a permission string:
            L   locked
            W   owner write
            R   owner read
            w   public write
            r   public read
        If the permission is preceded by a dash then the primary evaluates to
        true when all the specified permission flags are set.  Otherwise, it
        will only evaluate to true when the permission flags match exactly. 
        For example, "-perm -Rr" will evaluate to true for all file with read
        access, whereas "-perm Rr" will only be true for unlocked files
        without write access.

    -print
        This always evaluates to true and prints the full pathname of the
        current file followed by a newline.

    -print0
        This always evaluates to true and prints the full pathname of the
        current file followed by a null character.

    -prune
        This always evaluates to true and stops each from descending into the
        current file (which could be a directory or an image file).

    -size [+|-]<size>[c|B|k|M]
        This evaluates to true or false based on a comparison between the
        given value and the current file's size.  A preceding plus matches
        larger files, and a minus matches smaller files.  If neither a plus
        or minus is given, an equality test is performed.  For compatibility
        with find the size is assumed to be in units of 512 bytes, but this
        can be changed by suffixing the number with one of the following:
            c   characters (bytes)
            B   bytes
            k   kilobytes
            M   megabytes
        For example, "-size +1M" would match files over a megabyte in size.

    -time [+|-]<n>
        True if the file was last modified n days ago.  If the number is
        preceded by a minus then it evaluates to true for files modified
        within the last n days.  If preceded by a plus it evaluates to true
        for files modified more than n days ago.

    -type <type>
        True if the file is of the given type, which is either a RISC OS
        filetype (numeric or textual) or one of the following single
        characters:
            f   file
            d   directory
            i   image file
        For example, "-type absolute", "-type i" or "-type &fff".

OPERATORS

    ( <expression> )
        True if the expression between the brackets evaluates to true.

    ! <expression>
        True if the expression is false.

    <expression> -and <expression>
    <expression> <expression>
        True if both expressions are true.

    <expression> -or <expression>
        True if either expression is true.  The second expression is not
        evaluated if the first is true.

    <expression> , <expression>
        As with the sequencing operator in C and C++.  The first expression
        is evaluated but its value is ignored, and the operator returns the
        result of evaluating the second expression.

EXAMPLES

    each ADFS::4.$ ( -type i -prune ) , ( -size +1M -print )
        Show all the files over one megabyte on ADFS::4, but without looking
        inside any image files (such as a PC partition).

    each <Wimp$ScrapDir> -type f -print
        List all the files in the scrap directory.

    each . -time -3 -exec info %0 ;
        Display info on all the files in and beneath the current directory
        that have been modified in the last 3 days.

    each <Dustbin$Dir> -type f -time +3 -print > pipe:$.filelist
    xargs remove < pipe:$.filelist
        This removes any files in "<Dustbin$Dir>" over 3 days old, leaving
        the directory structure intact.  It is important to note that this
        cannot (safely) be done using "-exec remove %0 ;" since this will
        alter the contents of the directory while it is still being looked
        at and confuse each.

    each @ ( -type i -prune ) -or ( -type d -exec cdir RAM:$.%1 ; )
        Replicate the directory structure (from the current directory
        downwards) on the RAM disk.

CONTACT

    Bug reports, fixes, comments, etc.. to paul@plasma.demon.co.uk

COPYRIGHT

    This program can be freely distributed, so long as the author's name is
    not removed from any of the files.  The program comes with no guarantee,
    implied or stated, and no responsibility can be accepted by the author
    for any kind of loss.
