MASK() Function - Scan String for Matching Substring

For this topic's original documentation, see the MASK() Function - Scan String for Matching Substring.

BBj-Specific information

Syntax

MASK(str1{,str2}{,ERR=lineref})

Description

The MASK() function scans a string for a matching substring. This differs from the POS() function because str2 may contain pattern matching specifications similar to the UNIX operating system "grep" command.

BBj uses a new regular expression engine that supports most of the masking features of Perl 5.

Parameter	Description
str1	String to be scanned
str2	Substring to be located.
ERR=lineref	Branch to be taken if an error occurs during execution.

The value returned is the starting position instr1 fitting the mask. A returned value of zero indicates that no matching areas were found. If a match was made, the TCB(16) function returns the length of the string matched. If str2 is not given, the prior mask is reused. This is important to program performance because a certain amount of time is spent "compiling" the mask string. Repeated use of the same mask string should specify the mask only once.

Most characters in the mask string must simply match themselves. For example, a mask of "abc" only matches the string "abc". In this case, MASK(A$,"abc") and POS("abc"=A$) return the same result.

Mask String Operators

Operator	Operator name	Description
?	question mark	Indicates that something is optional. For example, a mask of "ab?c" indicates that the "b" is optional. This mask matches "abc" or "ac". Use parentheses for grouping. A mask of "(ab)?c" considers the sequence "ab" optional and matches either "abc" or just "c".
*	asterisk	Zero or more occurrences of the preceding item.
+	plus	One or more occurrences of the preceding item.
\|	pipe	Alternate choices. The "\|" is lower in precedence than the above operations
.	period	Matches any character.
[]	brackets	Match the contained character(s).
-	hyphen	Matches a range in a character list.
^	caret	Excludes characters or matches only those at the beginning of the target string.
\	backslash	Forces the next character in the mask to be taken literally. For example, a backslash must be used to match a plus sign.
$	dollar sign	Added at the end of the mask. Matches only characters at the end of the target string.

Within a regular expression, the characters in the following table have special meanings. The operators unique to BBj are identified.

Operator Type	Operator	Matches	Notes
Positional	^	Beginning of a line.
	$	End of a line.
	\A	Start of the entire string.	New to BBj
	\Z	End of the entire string.	New to BBj
Single Character	.	Any single character except $0A$.
	\d	Any decimal digit.	New to BBj
	\D	Any non-digit.	New to BBj
	\n	Newline ($0A$)	New to BBj
	\r	Return ($0D$)	New to BBj
	\s	Any whitespace character.	New to BBj
	\S	Any non-whitespace character.	New to BBj
	\t	A tab character ($09$).	New to BBj
	\w	Any word (alphanumeric or _) character.	New to BBj
	\W	Any non-word (alphanumeric or _) character.	New to BBj
	\0	Null ($00$)	New to BBj
	\0xxx	Octal (e.g. \007)	New to BBj
	\xXX	Hex (e.g. \xFF)	New to BBj
	\cX	Control character (e.g. \cC = $03$)	New to BBj
	\Q	Quote (disable) special characters until \E	New to BBj
	\E	Ends quoting of special characters	New to BBj
	\x	Character x, if x is not one of the above listed escape sequences.
Character Class	[abc]	Any character in the set a, b or c.
	[^abc]	Any character not in the set a, b or c.
	[a-z]	Any character in the range a to z, inclusive.
Grouping	(abc)	This is used to refer to a group of characters.
Branching (Alternation)	a\|b	Matches either a or b.
Repeating		Matching is normally "greedy" – the largest possible match which will allow the remainder of the mask to also match. If any of the repeat specifiers is immediately followed by a ?, the repeat specifiers will stop at the minimal number of repetitions that can complete the rest of the match.
	?	Matches the preceding expression 0 or 1 time.
	*	Matches the preceding expression 0 or more times.
	+	Matches the preceding expression 1 or more times.
	{num}	Matches exactly num repetitions of the preceding expression.
	{min,max}	Matches at least min, but no more than max, repetitions of the preceding pattern.
	{min,}	Matches min or more repetitions of the preceding pattern.

Operator Examples

String Example	Matches
"ab*c"	Any string beginning with "a", ending with "c", and having any number of b's in between.
"ab+c"	Any string beginning with "a", ending with "c", and having at least one "b" in between.
"(ab)*c"	Any string with any number of occurrences of "ab" finally ending with a "c". For example, "c", "abc", "ababababc".
"abc\|def"	Either "abc" or "def".
"a(b\|c)"	Either "ab" or "ac".
"a(b\|c)*"	A string beginning with "a", followed by any number of "b" and "c" (in any combination).
"a.c"	A string beginning with "a", ending with "c", and with any character in the middle.
"a.*c"	Any string beginning with "a" and ending with "c".
"[abc]"	Either "a", "b", or "c".
"[abc]+"	Any string containing only a's, b's, and c's.
"[abc][0123456789]"	Any string consisting of an "a", "b", or "c" followed by any digit.
"[0-9]"	Characters 0-9. This is the same as "[0123456789]".
"[a-zA-Z]"	Any string consisting of upper- and lower-case characters.
"[^0-9]"	Any character that is not a digit.
"^abc"	"abc" only if it occurs at the beginning of the string.
"a\+c"	Only "a+c"
"a+c"	Any sequence of a's ending with a "c".
"abc$"	"abc" only if it occurs at the end of the string.
"^a[0-9]*c$"	A string that begins with an "a", ends with a "c", and contains only digits in between.

Example 1

1000 PRINT STR(MASK("config.bbx",".*bbx"))+" "+STR(TCB(16))

Example 2

The following displays all file names matching a particular pattern:

1000 INPUT "MASK: ",M$
1010 LET A=MASK("",M$,ERR=1000); REM - establish mask
1020 LET CHAN=UNT; OPEN (CHAN)DIR("")
1030 READ RECORD (CHAN,END=1200)F$
1040 IF MASK(F$)=1 THEN PRINT F$
1050 GOTO 1030
1200 end