[Findutils-patches] [PATCH] POSIX will soon standarise -path; un-deprecate it.

[James Youngman]

2007-08-19  James Youngman  <address@hidden>

        Prepare for POSIX standardisation of -path.
        * find/parser.c (parse_path): This is the 'canonical' name once
        again.
        (parse_wholename): This is not.
        (parse_ipath): No longer deprecated.

Signed-off-by: James Youngman <address@hidden>
---
 doc/find.texi |   50 ++++++++++++++++++++++++++++++++++++--------------
 find/find.1   |   53 +++++++++++++++++++++++++++++++++--------------------
 find/parser.c |   51 +++++++++++++++++++++++++--------------------------
 3 files changed, 94 insertions(+), 60 deletions(-)

diff --git a/doc/find.texi b/doc/find.texi
index d6e9c64..1fce6a2 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -422,26 +422,48 @@ matches a file named @address@hidden,address@hidden, not 
the files @file{foo1} and
 @node Full Name Patterns
 @subsection Full Name Patterns
 
address@hidden Test -wholename pattern
address@hidden Test -iwholename pattern
address@hidden Test -path pattern
address@hidden Test -wholename pattern
 True if the entire file name, starting with the command line argument
 under which the file was found, matches shell pattern @var{pattern}.
-For @samp{-iwholename}, the match is case-insensitive.  To ignore a
-whole directory tree, use @samp{-prune} rather than checking every
-file in the tree (@pxref{Directories}).  The ``entire file name'' as
-used by @code{find} starts with the starting-point specified on the
-command line, and is not converted to an absolute pathname, so for
-example @code{cd /; find tmp -wholename /tmp} will never match
-anything.
+To ignore a whole directory tree, use @samp{-prune} rather than
+checking every file in the tree (@pxref{Directories}).  The ``entire
+file name'' as used by @code{find} starts with the starting-point
+specified on the command line, and is not converted to an absolute
+pathname, so for example @code{cd /; find tmp -wholename /tmp} will
+never match anything.   The name @samp{-wholename} is GNU-specific,
+but @samp{-path} is more portable; it is supported by HP-UX
address@hidden and will soon be part of POSIX.
 @end deffn
 
address@hidden Test -path pattern
address@hidden Test -ipath pattern
-These tests are deprecated, but work as for @samp{-wholename} and
address@hidden, respectively.  The @samp{-ipath} test is a GNU
-extension, but @samp{-path} is also provided by HP-UX @code{find}.
address@hidden Test -ipath pattern
address@hidden Test -iwholename pattern
+These tests are like @samp{-wholename} and @samp{-path}, but the match
+is case-insensitive.
 @end deffn
 
+
+In the context of the tests @samp{-path}, @samp{-wholename},
address@hidden and @samp{-wholename}, a ``full path'' is the name of
+all the directories traversed from @code{find}'s start point to the
+file being tested, followed by the base name of the file itself.
+These paths are often not absolute paths; for example
+
address@hidden
+$ cd /tmp
+$ mkdir -p foo/bar/baz
+$ find foo -path foo/bar -print
+foo/bar
+$ find foo -path /tmp/foo/bar -print
+$ find /tmp/foo -path /tmp/foo/bar -print
+/tmp/foo/bar
address@hidden example
+
+Notice that the second @code{find} command prints nothing, even though
address@hidden/tmp/foo/bar} exists and was examined by @code{find}.
+
+
+
 @deffn Test -regex expr
 @deffnx Test -iregex expr
 True if the entire file name matches regular expression @var{expr}.
diff --git a/find/find.1 b/find/find.1
index 230ed9f..197a4e6 100644
--- a/find/find.1
+++ b/find/find.1
@@ -482,7 +482,7 @@ matches shell pattern \fIpattern\fR.  The metacharacters 
(`*', `?',
 and `[]') match a `.' at the start of the base name (this is a change
 in findutils-4.2.2; see section STANDARDS CONFORMANCE below).  To ignore a
 directory and the files under it, use \-prune; see an example in the
-description of \-wholename.  Braces are not recognised as being
+description of \-path.  Braces are not recognised as being
 special, despite the fact that some shells including Bash imbue braces
 with a special meaning in shell patterns.  The filename matching is
 performed with the use of the
@@ -547,8 +547,37 @@ No group corresponds to file's numeric group ID.
 No user corresponds to file's numeric user ID.
 
 .IP "\-path \fIpattern\fR"
-See \-wholename.   The predicate \-path is also supported by HP-UX 
-.BR find .
+File name matches shell pattern \fIpattern\fR.  The metacharacters do
+not treat `/' or `.' specially; so, for example,
+.br
+.in +1i
+find . \-path "./sr*sc"
+.br
+.in -1i
+will print an entry for a directory called `./src/misc' (if one
+exists).  To ignore a whole directory tree, use \-prune rather than
+checking every file in the tree.  For example, to skip the
+directory `src/emacs' and all files and directories under it, and
+print the names of the other files found, do something like this:
+.br
+.in +1i
+find . \-path ./src/emacs \-prune \-o \-print
+.br
+.in -1i
+Note that the pattern match test applies to the whole file name,
+starting from one of the start points named on the command line.  It
+would only make sense to use an absolute path name here if the
+relevant start point is also an absolute path.  This means that this
+command will never match anything:
+.br
+.in +1i
+find bar \-path /foo/bar/myfile \-print
+.br
+.in -1i
+The predicate \-path
+is also supported by HP-UX
+.B find 
+and will be in a forthcoming version of the POSIX standard.
 
 .IP "\-perm \fImode\fR"
 File's permission bits are exactly \fImode\fR (octal or symbolic).
@@ -690,23 +719,7 @@ File was last accessed \fIn\fR days after its status was 
last changed.
 File is owned by user \fIuname\fR (numeric user ID allowed).
 
 .IP "\-wholename \fIpattern\fR"
-File name matches shell pattern \fIpattern\fR.  The metacharacters do
-not treat `/' or `.' specially; so, for example,
-.br
-.in +1i
-find . \-wholename "./sr*sc"
-.br
-.in -1i
-will print an entry for a directory called `./src/misc' (if one
-exists).  To ignore a whole directory tree, use \-prune rather than
-checking every file in the tree.  For example, to skip the
-directory `src/emacs' and all files and directories under it, and
-print the names of the other files found, do something like this:
-.br
-.in +1i
-find . \-wholename ./src/emacs \-prune \-o \-print
-.br
-.in -1i
+See \-path.    This alternative is less portable than \-path.
 
 .IP "\-writable"
 Matches files which are writable.  This takes into account access
diff --git a/find/parser.c b/find/parser.c
index 1c14e7a..10bdd2b 100644
--- a/find/parser.c
+++ b/find/parser.c
@@ -279,7 +279,7 @@ static struct parser_table const parse_table[] =
   PARSE_PUNCTUATION("or",                    or),           /* GNU */
   PARSE_ACTION     ("ok",                    ok),
   PARSE_ACTION     ("okdir",                 okdir), /* GNU (-execdir is BSD) 
*/
-  PARSE_TEST       ("path",                  path), /* GNU, HP-UX, GNU prefers 
wholename */
+  PARSE_TEST       ("path",                  path), /* GNU, HP-UX, RMS prefers 
wholename, but anyway soon POSIX */
   PARSE_TEST       ("perm",                  perm),
   PARSE_ACTION     ("print",                 print),
   PARSE_ACTION     ("print0",                print0),       /* GNU */
@@ -299,7 +299,7 @@ static struct parser_table const parse_table[] =
   PARSE_TEST       ("used",                  used),         /* GNU */
   PARSE_TEST       ("user",                  user),
   PARSE_OPTION     ("warn",                  warn),         /* GNU */
-  PARSE_TEST_NP    ("wholename",             wholename), /* GNU, replaces 
-path */
+  PARSE_TEST_NP    ("wholename",             wholename), /* GNU, replaced 
-path, but anyway -path will soon be in POSIX */
   {ARG_TEST,       "writable",               parse_accesscheck, 
pred_writable}, /* GNU, 4.3.0+ */
   PARSE_OPTION     ("xdev",                  xdev),
   PARSE_TEST       ("xtype",                 xtype),        /* GNU */
@@ -1184,30 +1184,27 @@ parse_inum (const struct parser_table* entry, char 
**argv, int *arg_ptr)
 static boolean
 parse_ipath (const struct parser_table* entry, char **argv, int *arg_ptr)
 {
-  error (0, 0,
-        _("warning: the predicate -ipath is deprecated; please use -iwholename 
instead."));
-  
-  return parse_iwholename(entry, argv, arg_ptr);
-}
-
-static boolean
-parse_iwholename (const struct parser_table* entry, char **argv, int *arg_ptr)
-{
   const char *name;
 
-  fnmatch_sanitycheck();
-  if (collect_arg(argv, arg_ptr, &name))
+  fnmatch_sanitycheck ();
+  if (collect_arg (argv, arg_ptr, &name))
     {
       struct predicate *our_pred = insert_primary_withpred (entry, pred_ipath);
       our_pred->need_stat = our_pred->need_type = false;
       our_pred->args.str = name;
-      our_pred->est_success_rate = estimate_pattern_match_rate(name, 0);
+      our_pred->est_success_rate = estimate_pattern_match_rate (name, 0);
       return true;
     }
   return false;
 }
 
 static boolean
+parse_iwholename (const struct parser_table* entry, char **argv, int *arg_ptr)
+{
+  return parse_ipath (entry, argv, arg_ptr);
+}
+
+static boolean
 parse_iregex (const struct parser_table* entry, char **argv, int *arg_ptr)
 {
   return insert_regex (argv, arg_ptr, entry, RE_ICASE|options.regex_options);
@@ -1652,36 +1649,38 @@ parse_or (const struct parser_table* entry, char 
**argv, int *arg_ptr)
   return true;
 }
 
-/* -path is deprecated (at RMS's request) in favour of 
- * -iwholename.   See the node "GNU Manuals" in standards.texi
- * for the rationale for this (basically, GNU prefers the use 
- * of the phrase "file name" to "path name".
+/* For some time, -path was deprecated (at RMS's request) in favour of
+ * -iwholename.  See the node "GNU Manuals" in standards.texi for the
+ * rationale for this (basically, GNU prefers the use of the phrase
+ * "file name" to "path name".
  *
  * We do not issue a warning that this usage is deprecated
- * since HPUX find supports this predicate also.
+ * since
+ * (a) HPUX find supports this predicate also and 
+ * (b) it will soon be in POSIX anyway.
  */
 static boolean
 parse_path (const struct parser_table* entry, char **argv, int *arg_ptr)
 {
-  return parse_wholename(entry, argv, arg_ptr);
-}
-
-static boolean
-parse_wholename (const struct parser_table* entry, char **argv, int *arg_ptr)
-{
   const char *name;
   if (collect_arg(argv, arg_ptr, &name))
     {
       struct predicate *our_pred = insert_primary_withpred (entry, pred_path);
       our_pred->need_stat = our_pred->need_type = false;
       our_pred->args.str = name;
-      our_pred->est_success_rate = estimate_pattern_match_rate(name, 0);
+      our_pred->est_success_rate = estimate_pattern_match_rate (name, 0);
       return true;
     }
   return false;
 }
 
 static boolean
+parse_wholename (const struct parser_table* entry, char **argv, int *arg_ptr)
+{
+  return parse_path (entry, argv, arg_ptr);
+}
+
+static boolean
 parse_perm (const struct parser_table* entry, char **argv, int *arg_ptr)
 {
   mode_t perm_val[2];
-- 
1.5.2.1