I've attached a small documentation fix patch that hopefully clears up the
ambiguity in the documentation of the APR_FNM_PERIOD flag to apr_fnmatch().
apr_fnmatch() is designed to allow applications to duplicate shell style
globbing in a platform independent way. There are several flags to change the
behavior slightly in order to match what the application may want.
The APR_FNM_PATHNAME flag prevents wildcards from matching the '/' character,
which allows applications to prevent wildcards to avoid cross path segments.
This flag is documented as "Slash must be matched by slash."
The APR_FNM_PERIOD flag prevents a leading period (the very first character in
the string to apply the pattern against) from matching a wildcard. The purpose
of this flag is to allow applications to avoid matching files that have names
with an initial period, which is commonly used as a way to hide files on *nix
platforms. This flag is documented as "Period must be matched by period."
Unfortunately, this documentation of APR_FNM_PERIOD implies to a reader (that
doesn't look at the code or experiment with the code) that it prevents the
wildcard from matching any character in the string with a period. Similar to
how APR_FNM_PATHNAME behaves, especially due to the shared phrasing of the
documentation.
I believe my attached patch resolves this ambiguity (or at least makes it clear
that APR_FNM_PATHNAME and APR_FNM_PERIOD do not share the same behavior just
for different characters) and would appreciate if it would be applied.
Index: include/apr_fnmatch.h
===================================================================
--- include/apr_fnmatch.h (revision 1608972)
+++ include/apr_fnmatch.h (working copy)
@@ -59,7 +59,7 @@ extern "C" {
#define APR_FNM_NOESCAPE 0x01 /**< Disable backslash escaping. */
#define APR_FNM_PATHNAME 0x02 /**< Slash must be matched by slash. */
-#define APR_FNM_PERIOD 0x04 /**< Period must be matched by period. */
+#define APR_FNM_PERIOD 0x04 /**< Leading period must be matched by
period. */
#define APR_FNM_CASE_BLIND 0x08 /**< Compare characters case-insensitively.
*/
/**
@@ -112,7 +112,7 @@ extern "C" {
* <pre>
* APR_FNM_NOESCAPE Disable backslash escaping
* APR_FNM_PATHNAME Slash must be matched by slash
- * APR_FNM_PERIOD Period must be matched by period
+ * APR_FNM_PERIOD Leading period must be matched by period
* APR_FNM_CASE_BLIND Compare characters case-insensitively.
* </pre>
*/
