Home / Autodocs / dos.library
NAME
- ParsePattern
-
Create a tokenized string for MatchPattern() (V36)
SYNOPSIS
IsWild = ParsePattern(Source, Dest, DestLength)
d0 D1 D2 D3
LONG ParsePattern(STRPTR, STRPTR, LONG)
d0 D1 D2 D3
LONG ParsePattern(STRPTR, STRPTR, LONG)
FUNCTION
Tokenizes a pattern, for use by MatchPattern(). Also indicates if there are any wildcard characters in the pattern (i.e. whether it might match more than one item). Note that Dest must be at least 2 times as large as Source plus bytes to be (almost) 100% certain of no buffer overflow. This is because each input character can currently expand to 2 tokens (with one exception that can expand to 3, but only once per string). Note: this implementation may change in the future, so you should handle error returns in all cases, but the size above should still be a reasonable upper bound for a buffer allocation.
The patterns are fairly extensive and approximate some of the ability of UNIX/grep "regular expression" patterns. Here are the available tokens:
The patterns are fairly extensive and approximate some of the ability of UNIX/grep "regular expression" patterns. Here are the available tokens:
-
? Matches a single character.
-
# Matches the following expression 0 or more times.
-
(ab|cd) Matches any one of the items seperated by '|'.
-
~ Negates the following expression. It matches all strings that do not match the expression (aka ~(foo) matches all strings that are not exactly "foo").
-
[abc] Character class: matches any of the characters in the class.
-
[~bc] Character class: matches any of the characters not in the class.
-
a-z Character range (only within character classes).
-
% Matches 0 characters always (useful in "(foo|bar|%)").
-
* Synonym for "#?", not available by default in 2.0. Available as an option that can be turned on.
-
' The apostrophe is the escape character for wildcard patterns. Add the apostrophe in front of any AmigaDOS wildcard pattern character to turn it into a regular character, e.g. a "?" will no longer match a single character if you prefix it with the apostrophe ("'?") but will match only the "?" character.
- CAUTION:
-
The apostrophe only affects a wildcard pattern character directly following it. If there is no wildcard pattern directly following it, the effect will be completely different (see NOTES).
INPUTS
- source
-
unparsed wildcard string to search for.
- dest
-
output string, gets tokenized version of input.
- DestLength
-
length available in destination (should be at least as twice as large as source + 2 bytes).
RESULT
- IsWild
-
1 means there were wildcards in the pattern. 0 means there were no wildcards in the pattern.
-1 means there was a buffer overflow or another error
NOTES
ParsePattern() will change the error code value which can be retrieved by IoErr() if the function fails.
It is not safe to call this function from a Task!
The apostrophe can be used to turn any AmigaDOS wildcard pattern character which directly follows it into a regular character. If what follows the apostrophe is not an AmigaDOS wildcard pattern character, the apostrophe will become part of the pattern string. For example, the pattern "foo'bar" will match "foo'bar" but not "foobar", as you may have expected. However, the pattern "foo''bar" will match "foo'bar". Similarly, the name "foo'" and the pattern "foo''" will both match "foo'".
The use of the "*" as a wildcard pattern, as enabled by setting the RNF_WILDSTAR flag in the DOSBase->dl_root.rn_Flags field, is discouraged because it causes ambiguities in the processing of the parameters provided to AmigaDOS shell commands. What may appear to be a wildcard pattern could in fact be the name of a stream (* is equivalent to "CONSOLE:") or it might be the other way round.
It is not safe to call this function from a Task!
The apostrophe can be used to turn any AmigaDOS wildcard pattern character which directly follows it into a regular character. If what follows the apostrophe is not an AmigaDOS wildcard pattern character, the apostrophe will become part of the pattern string. For example, the pattern "foo'bar" will match "foo'bar" but not "foobar", as you may have expected. However, the pattern "foo''bar" will match "foo'bar". Similarly, the name "foo'" and the pattern "foo''" will both match "foo'".
The use of the "*" as a wildcard pattern, as enabled by setting the RNF_WILDSTAR flag in the DOSBase->dl_root.rn_Flags field, is discouraged because it causes ambiguities in the processing of the parameters provided to AmigaDOS shell commands. What may appear to be a wildcard pattern could in fact be the name of a stream (* is equivalent to "CONSOLE:") or it might be the other way round.