pattern.txt

汇编编程艺术

assembly language program.  While it's certainly possible to write a program
whose sole purpose is to perform some pattern matching problem, using this
package may not provide any better performance than, say, a SPITBOL (compiled
SNOBOL4) program and it would probably take you longer to write than the
comparable SNOBOL4 program.

Routine:  MATCH
---------------

Category:             Pattern Matching Routine
Author:		      Randall Hyde

Registers on Entry:   ES:DI - pointer to source string
		      DX:SI - pointer to pattern
		      CX-     offset of last valid position+1 in string.
			      Zero to match entire string.


Registers on return:  AX-     Position in string where the pattern stopped
			      matching.


Flags affected:	      carry-	0 denotes failure to match pattern.
				1 denotes success.


Example of Usage:

		lesi	StringToTest
		ldxi	PatternToMatch
		mov	cx, 0		;Match entire string.
		MATCH
		jnc	DidNotMatch

Description:

MATCH is the general purpose matching subroutine provided in the standard
library to perform pattern matching.  On entry, DX:SI must point at a
pattern (list) data structure.  See the pattern.a include file (and the
documentation preceeding this page) for more details on this data structure.

Also on entry, ES:DI should point at the first character where the pattern
matching is to begin.  This need not be the beginning of a string, ES:DI could
point into the middle of a string;  however, the pattern matching begins at
location ES:DI.

ES:CX, on entry, must point at the last byte to check *plus one*.  This
typically points at the zero terminating byte of a string, but it could
point at some character in the string before the zero terminating byte.
If CX contains zero upon entry to the MATCH routine, the MATCH code will
automatically point CX at the zero byte in the string pointed at by ES:DI.

Include:              stdlib.a or pattern.a

Routine:  MATCH2
----------------

Category:             Pattern Matching Routine
Author:		      Randall Hyde

Registers on Entry:   ES:DI - pointer to source string
		      DX:SI - pointer to pattern
		      CX-     offset of last valid position+1 in string.


Registers on return:  AX-     Position in string where the pattern stopped
			      matching.


Flags affected:	      carry-	0 denotes failure to match pattern.
				1 denotes success.


Example of Usage:
			;Typical usage in a matching function:

				ldxi	NewPattern
				MATCH2

Description:

MATCH2 is a special, reentrant, version of MATCH.  You would normally *not*
call this routine to perform pattern matching from your main program.
Instead, this routine is intended for use inside pattern matching functions
you write yourself.  Please see the accompanying documentation for more
details.

Include:              stdlib.a or pattern.a

Routine:  patgrab
-----------------

Category:             Pattern Matching Routine
Author:		      Randall Hyde

Registers on Entry:   ES:DI - pointer to a pattern structure

Registers on return:  ES:DI - String (on heap) corresponding to the chars
			      matched by the pattern.

Flags affected:	      carry-  set if insufficient space on heap to allocate
			      the string.

Example of Usage:

		lesi	SomeString
		ldxi	SomePattern
		Match
		lesi	SomePattern
		patgrab

Description:

You use patgrab to extract the substring matched by some particular pattern.
You always call this routine *after* calling MATCH.  Match stores pointer
information away in the pattern data structure, patgrab extracts this infor-
mation and builds a string to your specifications.

To grab a string which spans several sub-patterns, you can use strcat to
combine the strings or a parenthetical pattern (see the documentation
preceding these routine descriptions for details).

Include:              stdlib.a or pattern.a

Routine:  spancset
------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, spancset is only invoked in a pattern data structure.
		You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	SCexample	pattern	<spancset,alpha>

Description:

Spancset will skip over zero or more characters from the character set (cset)
specified by the "matchparm" field (the second operand above).  This routine
always succeeds and returns the "match cursor" pointing at the first character
position beyond the matched characters in the source string.

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).


Routine:  brkcset
-----------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, brkcset is only invoked in a pattern data structure.
		You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	BCexample	pattern	<brkcset,alpha>

Description:

Brkcset skips over all characters which are *not* in the character set passed
in the "MatchParm" parameter.  This routine always succeeds.  It stops with
the match cursor pointing at the first character found in the specified char-
acter set (it does not "eat" that character).  This routine always succeeds.

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).


Routine:  matchstr
------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, matchstr is only invoked in a pattern data structure.
		You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	MSexample	pattern	<matchstr,str2match>
	Str2Match	db	"String to match",0

Description:

Matchstr compares the next characters in the source string against the
string pointed at by the "MatchParm" parameter.  If the next set of char-
acters in the source string match, this routine succeeds and returns the
match cursor pointing one character beyond the matched string in the
source string.  If the characters do not match, this routine fails and
does not modify the match cursor.

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).

Routine:  matchtostr
--------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, matchtostr is only invoked in a pattern data struct-
		ure.  You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	MTSexample	pattern	<matchtostr,str2match>
	Str2Match	db	"String to match",0

Description:

MatchToStr matches all characters in a string up to *and including* the
string specified by the "MatchParm" parameter.  Note that this is a very
fast (comparatively) routine and is much faster than something like
ARB followed by MatchStr (or some other combination which will force
backtracking).  This routine fails if it cannot find the specified string
in the source string (beyond the match cursor position).

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).

Routine:  matchchar
-------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, matchchar is only invoked in a pattern data struct-
		ure.  You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	MCexample	pattern	<matchchar, 'a'>

Description:

Matchchar tests a single character at the current match cursor position.
If the character in the L.O. byte of "MatchParm" is equal to the current
character in the source string, this routine passes over that character
in the string and returns success.  Otherwise, it does not advance the
match cursor and returns failure.

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).

Routine:  matchtochar
---------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, matchtochar is only invoked in a pattern data struct-
		ure.  You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	MTCexample	pattern	<matchtochar, 'a'>

Description:

MatchToChar matches all characters up to *and including* the character
specified by the L.O. byte of "MatchParm".  It succeeds if it finds the
character in the string (in which case it returns the match cursor pointing
just beyond the specified character).  It fails otherwise.

This is a relatively fast matching routine and should be used in place of
something like ARB followed by MATCHCHAR.

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).

Routine:  matchchars
--------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A
Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, matchchars is only invoked in a pattern data struct-
		ure.  You would not normally call this code directly from your
		program [though it is possible, see the source listings for
		details].)

	MCsexample	pattern	<matchchars, 'a'>

Description:

This routine matches zero or more occurrences of the specified character
starting at the match cursor position.  It always returns success.  If it
matches one or more characters it leaves the match cursor pointing beyond
the last matched character.

Include:	stdlib.a or patterns.a (and then invoke the "matchfuncs"
		macro to obtain the external declaration for this function).

Routine:  matchtopat
--------------------

Category:             Pattern Matching Primitive
Author:		      Randall Hyde

Registers on Entry:   N/A
Registers on return:  N/A