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

[James Youngman-5]

2007-08-19  James Youngman  <jay@...>

        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 <jay@...>
---
 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 @file{foo@{1,2@}}, not the files @file{foo1} and
 @node Full Name Patterns
 @subsection Full Name Patterns
 
-@deffn Test -wholename pattern
-@deffnx Test -iwholename pattern
+@deffn Test -path pattern
+@deffnx 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
+@code{find} and will soon be part of POSIX.
 @end deffn
 
-@deffn Test -path pattern
-@deffnx Test -ipath pattern
-These tests are deprecated, but work as for @samp{-wholename} and
-@samp{-iwholename}, respectively.  The @samp{-ipath} test is a GNU
-extension, but @samp{-path} is also provided by HP-UX @code{find}.
+@deffn Test -ipath pattern
+@deffnx 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},
+@samp{-ipath} 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
+
+@example
+$ 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
+@end example
+
+Notice that the second @code{find} command prints nothing, even though
+@file{/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



_______________________________________________
Findutils-patches mailing list
Findutils-patches@...
http://lists.gnu.org/mailman/listinfo/findutils-patches

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to James Youngman on 8/19/2007 12:56 PM:

> 2007-08-19  James Youngman  <jay@...>
>
> 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.
>
>  
> -@deffn Test -wholename pattern
> -@deffnx Test -iwholename pattern
> +@deffn Test -path pattern
> +@deffnx 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
> +@code{find} and will soon be part of POSIX.

It may be worth following this sentence with one more, explaining why we
provide -wholename as a synonym for -path (because -path, although chosen
by POSIX, has the wrong connotation of being a list of directories, rather
than a single file name including directories).

>  
> +
> +In the context of the tests @samp{-path}, @samp{-wholename},
> +@samp{-ipath} 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
> +
> +@example
> +$ 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
> +@end example
> +
> +Notice that the second @code{find} command prints nothing, even though
> +@file{/tmp/foo/bar} exists and was examined by @code{find}.

Also, it may be worth an example showing how * in the pattern matches even
/ and leading `.'.

> +++ 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 */

Not introduced by this bug, but those are some long lines.  Is it worth
reformatting a bit to get 80-column lines?

Missing a NEWS entry.  Otherwise, I think this is ready for applying to
4.3.x, after addressing the above points.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             ebb9@...
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGyYuj84KuGfSFAYARAk0MAJwI1FAbV3vvFNNj4R1SNPXG0Z/H6QCfadKV
BuwirMhrfQCSg2p0v5IqTRE=
=GArm
-----END PGP SIGNATURE-----


_______________________________________________
Findutils-patches mailing list
Findutils-patches@...
http://lists.gnu.org/mailman/listinfo/findutils-patches

[James Youngman-5]

On 8/20/07, Eric Blake <ebb9@...> wrote:

> It may be worth following this sentence with one more, explaining why we
> provide -wholename as a synonym for -path (because -path, although chosen
> by POSIX, has the wrong connotation of being a list of directories, rather
> than a single file name including directories).

I fear this may be confusing, since "wholename" is problematic; the
names concerned are not the whole name of the file, either.

I created a bug to reming myself to add in the extra documentation for -path.

> Not introduced by this bug, but those are some long lines.  Is it worth
> reformatting a bit to get 80-column lines?

On the whole I don't go overboard with that, but I have reduced the
length of the longest examples where this seemed to help readability.


> Missing a NEWS entry.  Otherwise, I think this is ready for applying to
> 4.3.x, after addressing the above points.

Thanks; done.


_______________________________________________
Findutils-patches mailing list
Findutils-patches@...
http://lists.gnu.org/mailman/listinfo/findutils-patches

[James Youngman-5]

I had forgotten the ChangeLog entry.   I have just added it:-

2007-08-22  James Youngman  <jay@...>

        * find/parser.c (parse_path): This is the 'canonical' name once
        again.
        (parse_wholename): This is not.
        (parse_ipath): No longer deprecated.
        * NEWS: Mention this.


_______________________________________________
Findutils-patches mailing list
Findutils-patches@...
http://lists.gnu.org/mailman/listinfo/findutils-patches