HELP PATTERN_INSTANCE                            Steven Hardy, June 1982
                                     (Updated Mark Rubinstein, Feb 1985)
                                      (Updated Aaron Sloman, 1 Jan 2005)

    pattern_instance(pattern) -> list;

This procedure takes a pattern (ie a list containing "?" or "??") and
returns an 'instance' of it, ie. a list like the pattern, but with all
pattern variables replaced by their values.

For instance "?VAR" is replaced by the valof "VAR", "??VAR" is replaced
by splicing in elements of the valof "VAR", which should be a list.

For example:

    vars x, y;
    "steve" -> x;
    "home" -> y;
    pattern_instance([?x is at ?y]) =>
    ** [steve is at home]

In the above case it would be simpler to write:

    [^x is at ^y] =>

PATTERN_INSTANCE is to be used when the pattern is not known at compile
time because, for example, it is the value of a variable, or is
constructed at run time.

If a double query prefix is used, then the value of the variable to be
instantiated must be a list. E.g.

    [tom dick harry] -> x;
    pattern_instance([the children of joe are ??x])=>
    ** [the children of joe are tom dick harry]

Normally PATTERN_INSTANCE does not check that the value of the variable
is known, so that you could have something like:

    pattern_instance([the value of newword is ?newword]) =>
    ;;; DECLARING VARIABLE newword
    ** [the value of newword is <undef newword>]
and
    pattern_instance([the values in newword are ??newword]) =>
    ;;; MISHAP - LIST NEEDED
    ;;; INVOLVING:  <undef newword>
    ;;; DOING    :  null dl pattern_instance compile nextitem compile


To get round this PATTERN_INSTANCE can now take an optional second
argument which must be a procedure to be run if the value of a variable
is not known or if it is not a list when used after the double query
(??) prefix.

If this argument is provided, then if at run time the value of the
variable is not known (that is if its *IDENTPROPS == "undef" or its
*VALOF is an *UNDEF object) or if its value is not a list when it is
used after the double query prefix, then the procedure is run with two
arguments, the prefix and the word.  Any results the procedure returns
will be included in the list returned by PATTERN_INSTANCE.

For example if you want the list to be unchanged if the words are not
known you can do:

    pattern_instance([the value is ?another_new_word], identfn) =>
    ** [the value is ? another_new_word]
or
    pattern_instance([the value is ??another_new_word], identfn) =>
    ** [the value is ?? another_new_word]

If you want PATTERN_INSTANCE to *MISHAP if the value is not known then do:

    pattern_instance([the value is ?unknown],
        mishap(%1, 'value of variable not known'%)) =>
    ;;; MISHAP - value of variable not known
    ;;; INVOLVING:  unknown
    ;;; DOING    :  pattern_instance compile nextitem compile

If you want the variable to be replaced by the word "undef" then do:

    pattern_instance([the value is ? unknown],
    procedure(x, y); undef endprocedure) =>
    ** [the value is undef]

or, using erasenum, the procedure concatenator <>, identfn:

    pattern_instance([the value is ? unknown],
    erasenum(%2%) <> identfn(%undef%) ) =>;
    ** [the value is undef]

An explanation of the use of '(% ...%)', or partial application can be
found in HELP *CLOSURES, *PERCENT

Of course if the value of the variable is acceptable then the procedure
provided will not be used, and if the procedure is not provided then the
behaviour of PATTERN_INSTANCE will not be affected. That is, as
illustrated above, the normal consequence of applying VALOF to an
identifier not declared as a variable, and/or the normal consequence of
applying list operations to a non-list will ensue!

See also
    HELP *MATCHES

-----<Copyright University of Sussex 1987.  All rights reserved.>-------


--- $poplocal/local/help/pattern_instance
--- Copyright University of Birmingham 2005. All rights reserved.
