Short:        Match files in a directory hierarchy
Author:       Torsten Poulin
Uploader:     torpou+aminet gmail com (Torsten Poulin)
Type:         util/cli
Version:      40.4
Architecture: m68k-amigaos >= 2.04

Match finds objects based on an expression.

Binary, source code, and documentation included.
Under 2-clause BSD License.

Format: Match [DIR] <directory> [DEPTHFIRST] [WHEN] <expression>

Template: DIR/A,DEPTHFIRST/S,WHEN/F/A


The Match command recursively descends the directory hierarchy for the
specified directory, evaluating <expression> in terms of each file system
object in the tree (files, directories, ...).

The expression is composed of "primaries" and "operators" that are listed
below. The expression is not case sensitive.

The DEPTHFIRST switch causes the descent of the directory hierarchy
to be done so that all entries in a directory are acted on before
the directory itself.


Primaries:
==========

In the descriptions of the primaries, the argument <n> is used as a decimal
integer. GT <n> means greater than <n>, LT <n> means less than <n>,
and EQ <n>, or simply <n>, means equal to <n>.

    COMMENT <pattern>
        True if <pattern> matches the comment attached to the current
        matched object.

    DAYS [GT | LT | EQ] <n>
        True if the current matched object has been modified more than
        in <n> days ago, less than <n> days ago, or <n> days ago.

    FALSE
        This primary is always false.

    FILENOTE <pattern>
        Another name for the COMMENT primary.

    FLAGS <flags>
        True if <flags> matches the protection bits of the current
        matched object.

        The <flags> argument is a string of letters representing the
        protection bits:

            R : The object can be read.
            W : The object can be written to.
            E : The object is an executable program.
            D : The object can be deleted.
            S : The object is a script.
            P : The object can be made resident.
            A : The object has been archived.
            H : The H flag is set.

        If a letter is preceded by a '-', it means that in order to
        match, the corresponding file bit must not be set.

            -R : The object cannot be read.
            -W : The object cannot be written to.
            -E : The object is not an executable program.
            -D : The object cannot be deleted.
            -S : The object is not a script.
            -P : The object cannot be made resident.
            -A : The object has inot been archived.
            -H : The H flag is not set.

        Unspecified bits are ignored in the comparison.
        Whitespace is not allowed in flags.

    LFORMAT <fmtstring>
        Always true. Prints <fmtstring> replacing occurences of the
        substitution operators

            %N with the name of the object,
            %R with its relative path,
            %L with its length in bytes (only useful for file type objects),
            %C with any attached comment,
            %A with its protection bits,
            %D with the date associated with it,
            %T with the time associated with it, and
            %% with the character '%'.

    LIST
        Always true. Outputs information similar to the AmigaDOS
        command LIST with its NOHEAD switch.

    NAME <pattern>
        True if <pattern> matches the name of the current object.

    PRINT
        Always true. Prints the name of the currently matched object.

    PRUNE
        Always true. It makes Match not descend into the current subdirectory.

    QUIT <return code>
        This primary makes Match stop traversing the file system and
        quit immediately, with the specied numeric return code.
        It is recommended that you use the standard return code values
        of 5, 10, and 20. Note that any preceding primaries will be
        evaluated and acted upon before quiting.

    RUN <commmand>
        True if the executed command returns a zero value as its return
        code. A command line containing whitespace must either have the
        whitespace escaped, or be surrounded by quotes.

        The command may contain the same substitution operators as LFORMAT.

    RUNOK <command>
        As RUN except that the generated command line is printed with
        a question mark, and is executed only if the user responds by
        typing a Y.

    SINCE <date>
        True if the object has been modified on or after <date>.
        The format for <date> is either dd-mmm-yy or one of TOMORROW, TODAY,
        YESTERDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY,
        or SUNDAY.

    SIZE [GT | LT | EQ] <n>
        True if the file is greater than <n>, less than <n>, or exactly <n>
        bytes long. Always false if the current name is not a file or a hard
        link to one.

    TYPE <type>
        True if the type of the filesystem object is <type>, where <type>
        is one of FILE, LINKFILE, DIR, LINKDIR, or SOFTLINK for a file, hard
        link to a file, a directory, hard link to a directory, or soft link
        to a file or a directory, respectively.

    UNTIL <date>
    UPTO <date>
	True if the file or directory has been modified on or before <date>.

        The format for <date> is either dd-mmm-yy or one of TOMORROW, TODAY,
        YESTERDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY,
        or SUNDAY.


Operators:
==========

The primaries may be combined using the following operators:

    { expression }
        True if the expression inside the braces evaluates to true.

    NOT <expression>
        This is the unary NOT operator. It evaluates ito true if <expression>
        is false.

    <expression> AND <expression>
    <expression> <expression>
        This is the logical AND operator. It is implied by the juxtaposition
        of two expressions, so it does not have to be specified.  
        The expression evaluates to true if both expressions are true.
        The second expression is not evaluated if the first expression
        is false.

    <expression> OR <expression>
        This is the logical OR operator. The expression evaluates to true
        if either the first or the second expression is true. The second
        expression is not evaluated if the first expression is true.


Escaping characters:
====================

Match uses '*' as an escape character to remove the special meaning of
characters, so to get an '*', it is necssary to enter '**'.

The special escape sequences '*N' and '*T' mean the new-line and tab
characters, respectively.

Escaping works anywhere in the expression, not just inside double quotes.
You can even escape the space character: 

    match "" type file run delete* %R

gives the same result as

    match "" type file run "delete %R"

The escape charecter '*' can be changed by setting the local or global
environment variable ESCAPE.


Examples:
=========

    To remove all files ending in '.bak':

        1> match SYS: type file name #?.bak run "delete %R"


    Print files that have the P protection flag set:

        1> match SYS: flags p print


    To find all files ending in '.c' on DH0: without searching
    the sub-tree starting at the directory 'foo':

        1> match DH0: {type dir name foo prune} or name #?.c print


    List files with comments beginning with the string "http", starting
    from the current directory:

        1> match "" filenote http#? list


    As above, but only outputting the comments:

        1> match "" filenote http#? lformat %c


    Interactively rename all files in the current directory and all
    subdirectories that have not been modified in 30 days:

        1> match "" type file days gt 30 runok "rename %R %R.old"