.FLAGS CAPITALIZE;.NONUMBER
.TITLE ^^$MATCH - STRING PATTERN RECOGNITION ROUTINE\\
.PAGE
.INDENT 50
<$MATCH
.SKIP 1
.CENTER
^^$MATCH - STRING PATTERN RECOGNITION ROUTINE
.LEFT MARGIN 10
.SKIP 1
.INDENT -10
^^ROUTINE NAME: $MATCH\\
.SKIP 1
.INDENT -10
^^PURPOSE:\\ <$MATCH IS A ^^FORTRAN-\\CALLABLE ROUTINE FOR PERFORMING ^^SNOBOL\\-LIKE
PATTERN RECOGNITION FUNCTIONS ON STRINGS OR BYTE ARRAYS.   <$MATCH
COMPARES A PATTERN AGAINST A STRING AND RETURNS A YES/NO ANSWER AS TO
WETHER THE TWO MATCH.
.SKIP 1
.INDENT -10
^^CALLABLE:\\#^FROM <FORTRAN (SEE <$MATCH WRITEUP FOR A <MACRO-CALLABLE VERSION).
.SKIP 1
.INDENT -10
^^PARAMETERS:\\ ^^CALL MATCH(PATT,STRNG[,LEN][,VERD])
.INDENT 20;\\OR^^
.BREAK
###VERD=MATCH(PATT,STRNG[,LEN])
.SKIP
.INDENT -6;PATT\\##^THE PATTERN THAT IS TESTED AGAINST THE STRING.  ^SEE THE
LIST OF LEGAL PATTERN CONSTRUCTS BELOW.
.INDENT -6;<STRNG ^THE STRING TO BE TESTED.
.INDENT -6;<LEN ##^THE MAXIMUM ALLOWED LENGTH OF THE PATTERN OR THE STRING.
.INDENT -6;<VERD #^THE INTEGER VERDICT OF THE MATCH, WHERE 1=MATCH AND
0=NO MATCH.
.SKIP
.CENTER;^^LEGAL PATTERN CONSTRUCTS\\
.PARAGRAPH;^WITHIN THE PATTERN SEVERAL SPECIAL CHARACTERS ARE USED TO MATCH
SPECIAL SETS OF CHARACTERS IN THE STRING.
.SKIP;.INDENT -2;_?#^THE QUESTION MARK CHARACTER WILL MATCH ANY CHARACTER IN THE
SAME POSITON IN THE
STRING EXCEPT A <NUL (SEE NOTE BELOW ABOUT TERMINATING STRINGS).
^FOR EXAMPLE: 'A?C' WILL MATCH 'ABC' OR 'A$C' ETC.
.SKIP;.INDENT -2;_\ ^FOR HYSTERICAL (SCRATCH THAT -- HISTORICAL) REASONS HERE AT
<CETUS, THE BACKSLASH CHARACTER IS IDENTICAL TO THE QUESTION MARK: IT MATCHES
ANY CHARACTER IN THE CORRESPONING POSITION IN THE STRING.
.SKIP;.INDENT -2;_* ^THE ASTERISK MATCHES ANY SUBSTRING (INCLUDING THE NULL STRING)
THAT STARTS IN THE CORRESSPONDING POSITION IN THE STRING.  ^EXAMPLE: 'AB*S'
WILL MATCH 'ABSOLUTES' AS WELL AS 'ABS'.
.SKIP;.INDENT -2;_- ^THE MINUS SIGN WILL REVERSE THE VERDICT OF THE NEXT CHARACTER
MATCH.  ^FOR EXAMPLE: '-A' WILL MATCH ANY CHARACTER EXCEPT 'A'.
.SKIP;.INDENT -5;[SS] ^CHARACTERS ENCLOSED IN SQUARE BRACKETS ARE CALLED AN <OR
CONSTRUCT.
^THIS CONSTRUCT MATCHES ANY SINGLE ONE OF THE CHARATERS ENCLOSED IN THE
BRACKETS.
^FOR EXAMPLE: '[AEIOU]' WILL MATCH ANY VOWEL, AND -[AEIOU] MATCHES ANY
CONSONANT.
.SKIP;.INDENT -5;"SS" ^CHARACTERS ENCLOSED IN DOUBLE QUOTES, CALLED A SUBSTRING,
ARE MATCHED TO THE STRING NORMALLY, BUT THEY ARE TREATED LOGICALLY AS ONE
CHARATER IN THE PATTERN.  ^THIS IS USEFULL WHEN YOU ARE NESTING CONSTRUCTS,
FOR EXAMPLE:  '-"<TSK"' WILL FAIL ON ALL STRINGS ACCEPT '<TSK', WHEREAS THE
PATTERN '-<T-S-K'  WILL FAIL ON ANY STRING THAT STARTS WITH A T OR HAS AN
S IN THE SECOND POSITION OR ENDS IN A K.  ^ANOTHER USE OF THE SUBSTRING CONSTRUCT IS FOR
MATCHING STRINGS THAT MEAN THE SAME THING BUT ARE OF DIFFERENT LENGTHS, LIKE
THE PATTERN '["PH"F]' WHICH MATCHES ANY F SOUND.
^A NOTE ABOUT NESTING:  THE [] _\ - AND "" CONSTRUCTS CAN BE NESTED WITHIN
EACH OTHER TO ANY DEPTH, BUT THE * CONSTRUCT CAN NEVER OCCURR INSIDE BRACKETS
OR QUOTES.  ^IF YOU DO THIS THE RESULTS WILL BE UNPREDICTABLE -- EXCEPT THAT WHATEVER
THE ROUTINE DOES IN THIS CASE WILL PROBABLY TAKE A LONG TIME.
.SKIP;.INDENT -4;S_>S#^TWO CHARACTERS SEPARATED BY A GREATER THAN SYMBOL
IS CALLED A '<THROUGH CONSTRUCT.  ^THIS ALLOWS YOU TO SPECIFY A GROUP OF
SEQUENTIAL <ASCII CHARACTERS WITHOUT HAVING TO TYPE THEM ALL IN MANUALLY. ^THIS
CONSTRUCT WILL MATCH ANY CHARACTER IN THE SAME POSITION IN THE STRING WHICH
HAS AN <ASCII VALUE GREATER THAN OR EQUAL TO THE FIRST CHARACTER AND LESS THAN
OR EQUAL TO THE SECOND CHARACTER.  ^THE FIRST CHARACTER IN THE '<THROUGH' MUST
HAVE AN <ASCII VALUE LESS THAN THE SECOND OR THE PATTERN WILL FAIL ON ANY STRING.
^THE IMPLEMENTATION OF THIS CONSTRUCT IS NOT AS "CLEAN" AS THE OTHERS, AND IT
CANNOT BE NESTED THE WAY MOST OTHERS CAN.  ^CONSTRUCTS LIKE "AB">"BZ" WILL
SIMPLY NOT WORK, BUT CONSTRUCTS LIKE -A>Z WILL.  ^THIS CONSTRUCT DOES NOT
NEED QUOTES OR BRACKETS AROUND IT TO MAKE IT ACT LOGICALLY AS ONE CHARACTER,
EVEN THOUGH IT DOES ACT MUCH LIKE AN '<OR'.
.SKIP;.INDENT -2;__ ^THE 'ESCAPE' CHARACTER IS AN UNDERLINE.  ^ANY CHARACTER THAT IS
PRECEEDED BY AN UNDERLINE IS COMPARED AGAINST THE NEXT CHARACTER IN THE
STRING WITHOUT CHECKING TO SEE IF IT IS A SPECIAL CONSTRUCT.  ^THIS ALLOWS YOU
TO SEARCH FOR BRACKETS, DOUBLE QUOTES, ASTERISKS, MINUS SIGNS, BACK SLASHES,
QUESTION MARKS, AND OF COURSE UNDERLINES AS WELL.
.SKIP
.CENTER;^^TERMINATING THE STRINGS\\
.PARAGRAPH
^BOTH THE PATTERN AND THE STRING ARGUMENT ARE "STRINGS" BY THE SAME DEFINITION
USED IN MANY OTHER <CETUS SUBROUTINES.  ^A STRING IS A BYTE ARRAY TERMINATED BY
A <NUL (A ZERO BYTE).  ^IN ADDITION, IF ANY STRING IS LONGER THAN <MAXLEN BYTES,
IT WILL BE TRUNCATED TO <MAXLEN BYTES LONG.  <MAXLEN DEFAULTS TO 32 BYTES,
BUT THIS CAN BE CHANGED TO ANY SIZE REQUIRED BY CALLING THE <SETMAX ROUTINE.
^ANOTHER WAY OF OVER RIDING THE <MAXLEN RESTRICTION IS TO INCLUDE A <LEN
ARGUMENT IN YOUR CALL TO <$MATCH.  ^THIS LENGTH WILL BE USED EVEN IF IT IS
GREATER THAN <MAXLEN.
.INDENT;^ANOTHER SPECIAL CASE IN <CETUS STRINGS IS TRAILING BLANKS.  ^IF
EITHER THE PATTERN OR THE STRING HAS TRAILING BLANKS BEFORE THE <NUL, THEY
WILL STILL MATCH EVEN IF THEY HAVE UNEQUAL NUMBERS OF BLANKS, EVEN IF ONE
OF THEM HAS NO BLANKS AT ALL.  ^OF COURSE THEY MUST MATCH UP TO THAT POINT
BEFORE THIS CASE APPLIES.
.SKIP 1
.INDENT -10
^^ROUTINES USED:\\ <$MATCH, <LEN
.SKIP 1
.INDENT -10
^^EXAMPLE:\\ 
.BREAK
.NOFILL
^^BYTE PATT(20),STRNG(20)
READ(5,100)PATT
READ(5,100)STRMG
I=MATCH(PATT,STRNG,20)
WRITE(5,200)I\\
.FILL
.SKIP 1
.INDENT -10
^^FEATURES:\\#^THIS <FORTRAN DRIVER FOR THE <$MATCH ROUTINE WILL TERMINATE BOTH THE PATTERN
AND THE STRING WITH A <NUL BEFORE STARTING PROCESSING.  ^THIS MEANS THAT
YOUR BYTE ARRAYS FOR THOSE TWO ARGUMENTS MUST BE LARGE ENOUGH TO CONTAIN NOT
ONLY THEIR OWN DATA, BUT THAT EXTRA ZERO BYTE AT THE END, EVEN IF YOU DO NOT
SPECIFICALLY PUT THE <NUL IN YOURSELF.
^<$MATCH USES THE <LEN ROUTINE TO FIND WHERE TO PUT THE <NUL, AND THIS CAN
MAKE A PROGRAM RUN SLOWER THAN NECESSARY IF IT CALLS <$MATCH MANY TIMES.  ^IF
YOU ALREADY KNOW THAT YOUR PATTERNS AND STRINGS ARE CORRECTLY TERMINATED WITH
^^NUL\\'S, YOU CAN USE A DIFFERENT ROUTINE, CALLED <MATFAS (FAST MATCH), WHICH
DOES NO CHECKING.
.SKIP 1
.INDENT -10
^^AUTHOR:\\ ^MIKE ^HIGGINS
.SKIP 1
.INDENT -10
^^WRITTEN:\\ ^MARCH 1978
.SKIP 1
.INDENT -10
^^SOURCE LANGUAGE:\\ <SUPERMAC
.SKIP 1
.INDENT -10
^^OBJECT MODULE NAME:\\ <$MATCH
.SKIP 1
.INDENT -10
^^LIBRARY:\\ <[60,60]CETUS.OLB
.SKIP 1
.INDENT -10
^^MAINTENANCE:\\ ^SEE ^MIKE ^HIGGINS
.SKIP 1
.INDENT -10