home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
514a.lha
/
sregexp.library_v9.0
/
sregexp.doc
< prev
next >
Wrap
Text File
|
1991-06-08
|
14KB
|
433 lines
TABLE OF CONTENTS
sregexp.library/AnchorPath
sregexp.library/BuildPath
sregexp.library/FreeSpathInfo
sregexp.library/FreeSregExp
sregexp.library/IsWild
sregexp.library/ParseSregExp
sregexp.library/MatchNSregExp
sregexp.library/MatchSregExp
sregexp.library/NextFile
sregexp.library/AnchorPath sregexp.library/AnchorPath
NAME
AnchorPath -- get set up to match a wildcard path.
SYNOPSIS
spath = AnchorPath(anc, wld)
D0 A0 A1
struct SpathInfo *AnchorPath(char *, char *);
FUNCTION
This is the first step in matching a wildcarded path. This routine
will preparse all of the wildcard elements in the path and set
everything up for subsequent calls to NextFile.
If NULL is returned, then IoErr can be examined to find out more on
whatever went wrong.
The wildcarded path is made up of (almost, see bug note) any legal
AmigaDOS path name, with wildcard expressions in the place of file
and directory names. There is one additional syntax: '.../' means
recursively search all sub-directories. so:
DH0:.../fred
would search all of DH0 for a (file or directory or either, see
NextFile) named fred.
One pretty nifty feature is that wildcards are legal in the volume
node part of the path. This will match to any file system device or
assigned directory or volume node that the system currently has
mounted. So to match all of the hard drive partitions in your system
you would use 'DH?:.../fred'. The root of your current device will
be matched only if the pattern explicitly matches a null string (ie
either just ':' or '%:')
INPUTS
anc - a null terminated string which is the name of a
directory. All paths returned by BuildPath and NextFile
will be relative to this directory.
wld - the wildcarded path to be matched.
RESULTS
spath - a pointer to a SpathInfo structure ready for calls to
NextFile.
NOTES
It will be most usual to pass a pointer to a null string for anc,
this will make all paths relative to the current working directory.
If the wildcarded path ends in a '/' then the search will match only
directories, and the '/' will be appended to all paths returned by
BuildPath and NextFile. If you specify a path ending in '/' and then
ask NextFile to look for only files the search will fail. If the
path does not end in a '/' then no '/' will be appended to the path
returned, regardless of whether the match is to a file or a
directory.
BUGS
(well, possible bugs actually) If one of the elements of the path
explicitly matches a null string (ie. either /%/ or just //) then
the routine will match to the parent directory. This works in all of
the cases I have tried (and the only important use, which is at the
beginning of the path.) I am just not terribly confident with the
way it's done, so if funny bugs creep up, look here first.
SEE ALSO
ParseSregExp, NextFile, BuildPath, FreeSpathInfo
sregexp.library/BuildPath sregexp.library/BuildPath
NAME
BuildPath -- build the path to the current match to a SpathInfo
structure
SYNOPSIS
len = BuildPath(spi,buff,len)
D0 A0 A1 D0
int BuildPath(Struct SpathInfo *, char *, int);
FUNCTION
The path to the current match of the SpathInfo structure is copied
into the buffer and null terminated. This will have unpredictable
results, possibly including fireworks, if it is called before the
first call to NextFile.
This routine will mainly be used to try again with a bigger buffer
if NextPath failed with SPE_BUFF_FULL.
INPUTS
spi - The pointer returned by a call to AnchorPath
buff - a buffer length len long to copy the path name into.
len - the length of the buffer, buff.
RESULTS
len - exactly the same as returned by NextFile.
SEE ALSO
NextFile, AnchorPath.
sregexp.library/FreeSpathInfo sregexp.library/FreeSpathInfo
NAME
FreeSpathInfo -- free up all of the resources locked by calls
to AnchorPath and NextFile
SYNOPSIS
FreeSpathInfo(spi)
A0
void FreeSpathInfo(struct SpathInfo *);
FUNCTION
This will free all of the memory and file locks currently wrapped up
in the SpathInfo structure. This is the ONLY way you should try to
free up these resources.
This routine can be called at any point, either immediately after
the call to AnchorPath, or after any calls to NextFile or BuildPath.
INPUTS
spi - A pointer to a SpathInfo structure to be freed.
SEE ALSO
AnchorPath.
sregexp.library/FreeSregExp sregexp.library/FreeSregExp
NAME
FreeSregExp -- free up a preparsed wildcard created by ParseSregExp
SYNOPSIS
FreeSregExp(sreg)
A0
void FreeSregExp(struct SregExp *);
FUNCTION
This routine will free all of the resources associated with a
preparsed wildcard expression. This is the only legal way to free
the object created by ParseSregExp, and you should not try to do it
yourself.
INPUTS
sreg - a pointer to the preparsed wildcard expression returned
by ParseSregExp.
SEE ALSO
ParseSregExp, MatchNSregExp, MatchSregExp.
sregexp.library/IsWild sregexp.library/IsWild
NAME
IsWild -- test if a string has any unescaped wildcard characters.
SYNOPSIS
bool = IsWild(wildcard);
D0 A0
int IsWild(char *);
FUNCTION
This routine merely checks if the string contains any unescaped
wildcard characters. It does not actually test if the string is
wild. For example, it would fail on '(this is a test)' because of
the round brackets, which are wildcard characters.
INPUTS
wildcard - a pointer to a wildcard string.
RESULTS
bool - non-zero if any unescaped wildcard characters were
found.
NOTES
This routine has very little merit, and is not really all that
useful. I will probably add a routine in future versions that does
the same thing but takes the preparsed wildcard expression and
returns the unique string which it will match, or NULL.
SEE ALSO
ParseSregExp.
sregexp.library/ParseSregExp sregexp.library/ParseSregExp
NAME
ParseSregExp -- preparse a wildcard expression for matching.
SYNOPSIS
sreg = ParseSregExp(wildcard)
D0 A0
struct SregExp *ParseSregExp(char *);
FUNCTION
A wildcard string must be preparsed before it can be passed to
MatchSregExp or MatchNSregExp to actually test if it matches a given
target string.
This function returns a pointer to the successfully created
structure, or NULL on failure. On failure, IoErr() can be examined
to get more information on the cause of the trouble.
ERROR_INVALID_COMPONENT_NAME is returned if the wildcard string is
illegal and ERROR_NO_FREE_STORE is returned if memory allocation
failed.
WILDCARD SYNTAX
The wildcard syntax accepted is an extension of the usual AmigaDOS
wildcards. Any 1.3 wildcard expression should be ok. Apparently
under 2.0 they have added a not operator, and the one here may or
may not be compatible with the way they have done it. (They SHOULD
have done it this way.)
Here is a synopsis:
? matches any one character
#(pat) matches zero or more occurrences of the pattern pat.
(pat) separates out a piece of the pattern.
pat1|pat2 matches to either pat1 or pat2
' escapes the special meaning of these symbols.
% matches the null string.
These are the extensions:
[chars] will match any single character in the set chars,
specified as single characters or ranges separated by a
-. Ex. [af-i+] would match a, f, g, h, i, and +. If ~
is the first character in the set then the set matched
is the complement of the set specified. Ex. [~a-z] would
match any one character that is not a (lower case if
case sensitivity is on) letter. Note that a [~a] is NOT
the same as a ~[a]. The former would match a 'b' but not
a 'ab', whereas the latter would match both. Special
care should be taken when using this wildcard in case
insensitive matches. As expected, [a] would match either
'a' or 'A' in a case insensitive search, but [~a] would
match anything, since it doesn't match 'a', but would
match a 'A'.
~(pat) will match anything that doesn't match the pattern.
Note: it is illegal to repeat a not. ie #~a is illegal.
(So is #(~(a)) so don't even try it.) You can repeat
something with a not IN it, as long as it can't be
reduced to the form #~(pattern). (A #[~a] is OK.)
However ~#a has the expected effect (matches any
non-null string not composed entirely of a's.)
* same as #?.
INPUTS
wildcard - a pointer to the null terminated wildcard expression
string.
RETURNS
sreg - a preparsed version of the wildcard expression.
SEE ALSO
FreeSregExp, MatchNSregExp, MatchSregExp.
sregexp.library/MatchNSregExp sregexp.library/MatchNSregExp
NAME
MatchNSregExp - match a preparsed wildcard expression to a target
SYNOPSIS
bool = MatchNSregExp(target,sreg,case,len)
D0 A0 A1 D0 D1
int MatchNSregExp(char *, struct SregExp *, int int);
FUNCTION
This function tests if the given fixed length target string matches
the preparsed wildcard expression.
This routine is identical to MatchSregExp, except it takes a pointer
to a string and its length, rather than a null terminated string.
INPUTS
target - the null terminated target string you wish to test
against the wildcard expression.
sreg - the preparsed wildcard expression.
case - if this is non-zero then the match is case sensitive,
otherwise it is case insensitive.
len - the length of the string pointed to by target.
RESULTS
bool - non-zero if the target matches the expression, zero
otherwise.
NOTES
See ParseSregExp for a discussion of the wildcard expression and the
tricky behaviour of character sets (ie. [...]) when the search is
case insensitive.
This routine is handy for matching BCPL strings. If p is a c
pointer (byte, not longword address) of a BCPL string then
MatchNSregExp(p+1,sreg,case,*p)
will test the BCPL string for a match.
SEE ALSO
FreeSregExp, ParseSregExp, MatchSregExp.
sregexp.library/MatchSregExp sregexp.library/MatchSregExp
NAME
MatchSregExp - match a preparsed wildcard expression to a target
SYNOPSIS
bool = MatchSregExp(target,sreg,case)
D0 A0 A1 D0
int MatchSregExp(char *, struct SregExp *, int);
FUNCTION
This function tests if the given null terminated target string
matches the preparsed wildcard expression.
This routine is identical to MatchNSregExp, except it takes a
pointer to a null terminated string, rather than a string and its
length.
INPUTS
target - the null terminated target string you wish to test
against the wildcard expression.
sreg - the preparsed wildcard expression.
case - if this is non-zero then the match is case sensitive,
otherwise it is case insensitive.
RESULTS
bool - non-zero if the target matches the expression, zero
otherwise.
NOTES
See ParseSregExp for a discussion of the wildcard expression and the
tricky behaviour of character sets (ie. [...]) when the search is
case insensitive.
This call currently just results in the call:
MatchNSregExp(target,sreg,case,strlen(target));
but this may change in future version.
SEE ALSO
FreeSregExp, ParseSregExp, MatchNSregExp.
sregexp.library/NextFile sregexp.library/NextFile
NAME
NextFile -- return the next (or first) file matching the path.
SYNOPSIS
len = NextFile(spi,buff,len,dirs)
D0 A0 A1 D0 D1
int NextFile(struct SpathInfo *, char *, int int);
FUNCTION
This routine copies the path to the next (or first, if this is the
first call) file or directory matching the wildcard in the SpathInfo
structure created by a call to AnchorPath.
The usual calling sequence would be:
AnchorPath
repeat while no errors and more files
NextFile
FreeSpathInfo
The length of the path is returned, or if there is an error or there
are no more matches a negative result is returned. Both the
negative number and the Value if IoErr will give more information
about why the routine returned.
INPUTS
spi - The pointer returned by a call to AnchorPath
buff - a buffer length len long to copy the path name into.
len - the length of the buffer, buff.
dirs - if this is greater than zero, only directories will
match; if it is zero, both files and directories will
match; if it is less than zero, only files will match.
See the defines in the include file.
RESULTS
len - on success this will be the length of the path copied
into the buffer. If it is less than zero, some kind of
special event is signalled.
SPE_ALL_DONE - This signals there are no more matches
to the path. IoErr will also be set to
ERROR_NO_MORE_ENTRIES
SPE_ERROR - Some error happened, see IoErr.
SPE_BUFF_FULL - The buffer you suplied was not big
enough for the path name. Get a bigger
one and call BuildPath.
SPE_SIGBREAK - One of the dos break signals was
received by your process. This does not
clear the signals, but since some
searches can take a while it checks
every now and again. You can just clear
the signal and call NextPath again to
ignore the signal.
NOTES
It is meaningless to mix calls with a different value of dirs.
Anything passed by in a call in which you did not ask for objects of
a given type will not reappear in subsequent calls in which you do
ask for that type.
SEE ALSO
AnchorPath, BuildPath.