[comment {-*- flibs -*- doctools manpage}]
[manpage_begin flibs/strings n 1.1]
[copyright {2006 Arjen Markus <arjenmarkus@sourceforge.net>}]
[moddesc flibs]
[titledesc {Glob matching}]

[description]

The [strong glob_matching] module provides a string matching method
known as [strong "glob matching"]: it is used for instance under UNIX,
Linux and DOS to select files whose names match a certain pattern -
strings like "*.f90" describe all file swhose names end in ".f90".
[para]

The method implemented in the module is somewhat simplified than the
full glob matching possible under UNIX: it does not support character
classes.
[para]

Glob patterns are intended to match the entire string. In this
implementation, however, trailing blanks in both the string and the
pattern are ignored, so that it is a bit easier to use in Fortran.
[para]

The module supports both "*" and "?" as wild cards, where "*" means any
sequence of characters, including zero and "?" means a single character.
If you need to match the [strong characters] "*" or "?", then precede
them with a backslash ("\"). If you need to match a backslash, you will
need to use two:

[example {
    match = string_match( "c:\somedir" "c:\\*" )
}]

will return [strong .true.], while:

[example {
    match = string_match( "c:\somedir" "c:\*" )
}]

will not match, as the backslash "escapes" the asterisk, which then
becomes an ordinary character.


[section ROUTINES]
The module contains a single function:

[list_begin definitions]

[call [cmd "use glob_matching"]]
To import the glob matching function, use this module.

[call [cmd "matches = string_match( string, pattern)"]]
Check whether the (entire) string matches the given "glob" pattern.
Trailing blanks in both the string and the pattern are ignored.
The function returns .true. if the string matches the pattern, .false.
otherwise.

[list_begin arg]

[arg_def "character(len=*)" string]
The string to be examined

[arg_def "character(len=*)" pattern]
The string containing the pattern

[list_end]


[list_end]

[section BUGS]
The matching algorithm is not flawless:

[list_begin bullet]

[bullet]
Patterns like "e* *" may fail, because trailing blanks are removed. The
string "e " ought to match this pattern, but because only the substring
"e" will be considered, the trailing blank that is necessary for
matching between the two asterisks is removed from the matching process.
[nl]
The test program contains a case that should fail on this, but it does
not, oddly enough.

[bullet]
Patterns like "b*ba" fail on a string like "babababa" because the
algorithm finds an early match (the substring at 3:4) for the last
literal substring "ba" in the pattern. It should instead skip
over that substring and search for the substring 7:8.
[nl]

There are two ways to deal with this:
[list_begin bullet]
[bullet]
Insert an extra character at the end, which does not occur anywhere in
the pattern.
[bullet]
If the match fails, continue at a point after the position of the
literal substring where matching failed.
[list_end]
[nl]
The second is probably the way to go, but it may be a bit slower.

[list_end]

[manpage_end]
