pattern.txt

汇编编程艺术

Flags affected:	      N/A

Example of Usage:

	(Note: 	Generally, matchtopat 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].)

	MTPexample	pattern	<matchtopat, somepat>
	SomePat		pattern	<arbitrary_pattern....>

Description:

Matchtopat matches an arbitrary number of characters up to *and including*
the characters matched by the pattern specified by the "MatchParm" parameter.
Success or failure on return depends entirely on whether or not the pattern
specified as a parameter matches at some point or another.

MatchToPat uses "shy" pattern matching.  That is, it first attempts to match
zero characters (the empty string) followed by the parameter pattern.  If
this succeeds, it quits.  Otherwise MatchToPat matches a single character
and tries to match the parameter pattern again.  Each time it fails it matches
one additional character and tries again until there are no more characters
in the source string, at which point it fails.

SNOBOL4+ programmers- MatchToPat is the pattern which is most comparble to
the ARB PAT pattern in SNOBOL4+.

Whether or not MatchToPat is faster than ARB (stdlib version) followed by
some other pattern depends entirely on the location of the second pattern.
ARB uses a greedy algorithm and backtracks to match any following patterns.
MatchToPat uses a shy algorithm which tries the parameter pattern first and
eats characters from the source string only if the parameter pattern fails.
If the match generally occurs earlier in the source string, MatchToPat will
be faster.  If the match occurs later in the source string, ARB/PAT will
probably be faster.  If matching generally fails, MatchToPat is marginally
faster.

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

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, anycset 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].)

	ACexample	pattern	<anycset, alpha>

Description:

Anycset matches a single character from the character set (cset) specified
by the "MatchParm" parameter.  If the character at the match cursor position
is in this set, anycset advances the match cursor and succeeds.  Otherwise
it does not advance the match cursor and anycset fails.

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

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, notanycset 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].)

	NACexample	pattern	<notanycset, alpha>

Description:

NotAnycset matches a single character which is *not* in character set (cset)
specified by the "MatchParm" parameter.  If the character at the match cursor
position is not in this set, notanycset advances the match cursor and succeeds.
Otherwise it does not advance the match cursor and notanycset fails.

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

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, EOS 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].)

	EOSexample	pattern	<EOS>

Description:

EOS matches the end of the source string (that is, the zero terminating byte
of the source string).  The standard library pattern matching package does
not require that a source string completely match a pattern for that pattern
to succeed.  Instead, the pattern need only specify a prefix of that string.
If you want the pattern to match the entire string you must stick the EOS
pattern at the end of your pattern list.

Whether EOS succeeds or fails, it does *not* advance the match cursor.

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

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, ARB 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].)

	ARBexample	pattern	<ARB>

Description:

ARB matches an arbitrary number of characters in a string (up to EOS).
It always succeeds.

SNOBOL4+ users- Stdlib's ARB function isn't exactly like SNOBOL4's.  This
ARB function uses a "greedy" algorithm.  It immediately grabs as many char-
acters as it can.  If there is a pattern following ARB (and there generally
is) backtracking *will* occur.  If you want an ARB operation which uses a
"shy" matching algorithm, take a look at the "MatchToPat" function.

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

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, ARBNUM 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].)

	ANexample	pattern	<ARBNUM, SomePattern>
	SomePattern	pattern	<some_other_pattern....>

Description:

ARBNUM matches zero or more occurrences of the pattern specified by the
"MatchParm" pattern.  It always succeeds and leaves the match cursor pointing
beyond the last character matched in the source string.  If it matches zero
occurrences of the specified pattern, it still succeeds and returns the
match cursor unchanged.

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

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, Skip 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].)

	Sexample	pattern	<Skip, 5, 0, NextPat>

Description:

Skip matches (skips over) the next "n" characters in the source string.
"n" is the L.O. word of the "MatchParm" parameter.

Skip succeeds if there were at least "n" characters in the string.  It fails
if there were less than "n" characters in the string.  If you want Skip to
succeed even if there are less than "n" characters in the string you can
use ARB as the alternate pattern for Skip:

	SARBexample	pattern	<Skip, 5, 0, ArbPat>
	ARBPat		pattern	<ARB>

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

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, POS 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].)

	Pexample	pattern	<POS, 5, 0, NextPat>

Description:

POS (position) succeeds if the match cursor is currently at the location
specified by the "MatchParm" parameter.  It fails otherwise.  Note: the
first character in the source string is at position zero.

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

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, RPOS 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].)

	RPexample	pattern	<RPOS, 5, 0, NextPat>

Description:

RPOS (position) succeeds if the match cursor is currently at the specified
location *from the end of the string*.  The last character in the string is
RPOS one (EOS is at position zero).

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

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, GotoPOS 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].)

	GPexample	pattern	<GotoPOS, 5, 0, NextPat>

Description:

GotoPos moves the match cursor *forward* to the specified position.  It fails
if that position does not exist in the string or if you attempt to move the
match cursor backwards in the string.

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

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, RGotoPOS 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].)

	RGPexample	pattern	<RGotoPOS, 5, 0, NextPat>

Description:

RGotoPos moves the match cursor *forward* in the string to the point specified
by the "MatchParm" parameter.  This value is the position in the string from
the *end* of the string.  This function fails if you attempt to move the
match cursor backwards in the string or if the position does not exist in
the string.

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