HELP MATCHES                                       A. Sloman, March 1982

    <list> matches <list with pattern elements> -> <boolean>;
    <list> --> <list with pattern elements>;

For a tutorial introduction to the POP-11 matcher see the following
TEACH files:

    TEACH *MATCHES
    TEACH *MATCHES2
    TEACH *MOREMATCH

-- THE POP-11 MATCHER --------------------------------------------------

MATCHES is an infix operator which takes two arguments, returns a
boolean result (TRUE or FALSE), and as a side effect can bind variables.
The first argument is any list, and the second argument is a list which
may contain pattern elements.

MATCHES works by attempting to find a match between the two lists;
ordinary list elements must be identical, but list elements in the first
list may match pattern elements in the second. These elements make
certain restrictions on what can be in that position in the list.
Pattern elements may be:

    =               match one item
    ==              match an arbitrary number of items
    ?<variable>     match one item and bind it to the variable
    ??<variable>    match any number of items (possibly none), make a
                    list of them, and bind the list (possibly []) to the
                    variable.

(Note: MATCHES can also be used with vectors as arguments, but
?<variable> and ??<variable> do not work on vectors; MATCHES simply
behaves like = under these circumstances.)


-- PATTERN ELEMENTS WITH ADDITIONAL RESTRICTIONS -----------------------

    ??<variable>:integer    e.g. ??x:3
                    Restrict the variable to match the given number of
                    items.

    ?<variable>:<procedure name>    e.g. ?x:isword
    ?<variable>:<procedure>         e.g. ?x: % ismorethan(%0%) %
                    Before allowing the match, apply the procedure to
                    the matching item. If the result is FALSE, don't
                    allow the match to succeed. If the result is TRUE,
                    allow it. If the result is anything else, allow the
                    match, but bind the result to the variable.

    ??<variable>:<procedure name>   e.g. ??x:noun_prhase
    ??<variable>:<procedure>        e.g. ??x: % refersto(%item%) %

Other elements of patterns are compared with corresponding elements of
the list, using the equality test = rather than strict equality ==, so
that two lists, strings or vectors with the same elements will match.

Examples of the matcher at work:
--------------------------------

    vars list x y;
    [a b c d e] -> list;

    list matches [a b c d e] =>
    ** <true>

    list matches [ a == e] =>
    ** <true>

    list matches [ a = c = e] =>
    ** <true>

    list matches [ a = d = e ] =>
    ** <false>

Examples with variable binding:
-------------------------------

    list matches [?x b c d e] =>
    ** <true>

    x=>
    ** a

    list matches [?x d e] =>
    ** <false>

    list matches [??x d e] =>
    ** <true>

    x =>
    ** [a b c]

    list matches [??x c ??y] =>
    ** <true>

    x=>
    ** [a b]

    y=>
    ** [d e]

    list matches [??x ??y] =>
    ** <true>

    x=>
    ** []

    y=>
    ** [a b c d e]

Repeated Variables:
-------------------
If the same variable is used more than once in the pattern, the match
will succeed only if it is matched against the same thing in all its
occurrences. Thus:

    [a b c a b c] matches [??x ??x] =>
    ** true

    x=>
    [a b c]

    [a b c c b a] matches [??x ??x]=>
    ** false

Examples with restrictions on matches:
--------------------------------------
    list matches [??x:3 ??y] =>
    ** <true>

    x =>
    ** [a b c]

    y=>
    ** [d e]

    list matches [?x:isinteger ??y] =>
    ** <false>

    list matches [?x:isword ??y] =>
    ** <true>

    x=>
    ** a

    y=>
    ** [b c d e]

    list matches [??x:length d e] =>
    ** <true>

    x=>
    ** 3

    define value(item);
        if item == "a" then 10
        elseif item == "b" then 20
        else false
        endif
    enddefine;

    list matches [?x:value == ] =>
    ** <true>

    x=>
    ** 10

    list matches [== ?x:value] =>
    ** <false>

    list matches [??x:value d e] =>
    ** <false>

    [a 3 ] matches [a ?x: %nonop>(%0%)%] =>
    ** <true>

    x=>
    ** 3


-- THE MATCHER ARROW ---------------------------------------------------
The infix operator --> calls MATCHES, but instead of producing a boolean
result it produces no result, but causes an error if the arguments don't
match. It can therefore function as a multiple assignment, e.g.

    list --> [?x ?y ?z]

will assign the three elements of LIST to X, Y and Z.

WARNING:
    If a match fails, variables in the pattern have undefined values.
    I.e. the value can be altered by either a successful or an
    unsuccessful match.

See also HELP
    *MATCHESONEOF - takes a list of patterns and tries to find one match
    *MATCHESALLOF - takes a list of patterns, all of which must match
    *DATABASE     - use of the POP-11 DATABASE
    *AREIN        - matches a list of patterns against list elements
    *ISIN         - matches a single pattern against list elements


    *FMATCHES     - a version of the matcher that can use lexical
        variables, work in sections, and solve some matching problems
        that -matches- cannot.

--- C.all/help/matches
--- Copyright University of Sussex 1990. All rights reserved. ----------
