bug#58364: [PATCH] Add new function 'file-name-parent-p'

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 597 bytes --]

Tags: patch


Unless I am mistaken, there is no direct function to quickly test if a
directory is a super-directory of file.  As I have encountered this
issue more than once the last few days of hacking, I would like to
propose the below function.


In GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.34, cairo version 1.17.6) of 2022-10-07 built on rhea
Repository revision: 51f5a7cf127934aa93d860c8fd3e8d58fbc594cb
Repository branch: feature/package+vc
System Description: Fedora Linux 36 (Workstation Edition)

Configured using:
 'configure --with-pgtk --with-imagemagick'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-function-file-name-parent-p.patch --]
[-- Type: text/patch, Size: 2059 bytes --]

From 87ca79778f3220c80826257d2b67e405940a9b11 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Fri, 7 Oct 2022 22:20:30 +0200
Subject: [PATCH] Add new function 'file-name-parent-p'

* doc/lispref/files.texi (Directory Names): Explain it.
* etc/NEWS: Mention in.
* lisp/files.el (file-name-parent-p): Add it.
---
 doc/lispref/files.texi | 5 +++++
 etc/NEWS               | 4 ++++
 lisp/files.el          | 5 +++++
 3 files changed, 14 insertions(+)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index e1aa2de523..30cc950ad2 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2454,6 +2454,11 @@ Directory Names
 non-@code{nil}, it ends in a slash.
 @end defun
 
+@defun file-name-parent-p directory filename
+This function will return a non-@code{nil} value if @var{directory} is
+a parent directory of @var{filename}.
+@end defun
+
 @node File Name Expansion
 @subsection Functions that Expand Filenames
 @cindex expansion of file names
diff --git a/etc/NEWS b/etc/NEWS
index 68cd8bd906..c02ff2ecb5 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3675,6 +3675,10 @@ This returns a list of all the components of a file name.
 ** New function 'file-name-parent-directory'.
 This returns the parent directory of a file name.
 
++++
+** New function 'file-name-parent-p'.
+This checks if a directory is an eventual parent of a file.
+
 +++
 ** New macro 'with-undo-amalgamate'.
 It records a particular sequence of operations as a single undo step.
diff --git a/lisp/files.el b/lisp/files.el
index 43c5d7d1da..1a670b25a9 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -5220,6 +5220,11 @@ file-name-parent-directory
      (t
       parent))))
 
+(defun file-name-parent-p (dir file)
+  "Return non-nil if DIR is a parent-directory of FILE."
+  (and (locate-dominating-file file (apply-partially #'file-equal-p dir))
+       t))
+
 (defcustom make-backup-file-name-function
   #'make-backup-file-name--default-function
   "A function that `make-backup-file-name' uses to create backup file names.
-- 
2.37.3

bug#58364: Acknowledgement ([PATCH] Add new function 'file-name-parent-p')

[Philip Kaludercic]

I have found at least two edge-cases with the current implementation
that don't work as one would expect them to:

- (file-name-parent-p "/etc/passwd" "/etc/passwd")      => t
- (file-name-parent-p "." "/")                          => t

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Drew Adams]

> Unless I am mistaken, there is no direct function
> to quickly test if a directory is a super-directory
> of file.  As I have encountered this issue more
> than once the last few days of hacking, I would
> like to propose the below function.

Parent is not the same as super-directory
(or "eventual parent", as your doc says).

A parent is an immediate direct ancestor.
It's not just _any_ ancestor.

"Ancestor" includes parent, grandparent,...
-- any level.  I guess it's what you
meant by "parent" and "super-directory".
___


FWIW:

I use this, for a _parent_ directory.
(I've likely proposed this to Emacs before.)

The name is because it's defined in dired+.el,
but the function isn't specific to Dired.

(defun diredp-parent-dir (file &optional relativep)
  "Return the parent directory of FILE, or nil if none.
Optional arg RELATIVEP non-nil means return a relative name, that is,
just the parent component."
  (let ((parent  (file-name-directory
                   (directory-file-name
                     (expand-file-name file))))
        relparent)
    (when relativep
      (setq relparent  (file-name-nondirectory
                         (directory-file-name parent))))
    (and (not (equal parent file))
         (or relparent  parent))))

IOW, in a nutshell, this is a parent dir of FILE:

(file-name-directory
  (directory-file-name (expand-file-name FILE)))

FWIW2:

I use this to get a list of all ancestors of DIR.

(defun diredp-ancestor-dirs (dir)
  "Return a list of the ancestor directories of directory DIR."
  (mapcar #'file-name-as-directory
          (diredp-maplist
             (lambda (dd)
               (mapconcat #'identity (reverse dd) "/"))
             (cdr (nreverse (split-string dir "/" t))))))

(You can use `cl-maplist'.  I use `diredp-maplist'
because dired+.el needs compatibility with old Emacs
versions.)

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Date: Fri, 07 Oct 2022 20:23:27 +0000
> 
> Unless I am mistaken, there is no direct function to quickly test if a
> directory is a super-directory of file.  As I have encountered this
> issue more than once the last few days of hacking, I would like to
> propose the below function.

We have file-in-directory-p.  Doesn't that fit the bill?

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Date: Fri, 07 Oct 2022 20:23:27 +0000
>> 
>> Unless I am mistaken, there is no direct function to quickly test if a
>> directory is a super-directory of file.  As I have encountered this
>> issue more than once the last few days of hacking, I would like to
>> propose the below function.
>
> We have file-in-directory-p.  Doesn't that fit the bill?

I hive tried it out and yes that was the function I was looking for.  My
apologies for the noise.

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: 58364-done@debbugs.gnu.org
> Date: Sat, 08 Oct 2022 07:21:01 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Philip Kaludercic <philipk@posteo.net>
> >> Date: Fri, 07 Oct 2022 20:23:27 +0000
> >> 
> >> Unless I am mistaken, there is no direct function to quickly test if a
> >> directory is a super-directory of file.  As I have encountered this
> >> issue more than once the last few days of hacking, I would like to
> >> propose the below function.
> >
> > We have file-in-directory-p.  Doesn't that fit the bill?
> 
> I hive tried it out and yes that was the function I was looking for.  My
> apologies for the noise.

No need to apologize: no one can know and remember everything.  I only
remembered that because I recently fixed a bug in Dired which used
that function.

But perhaps our take from this is that file-in-directory-p is not
discoverable enough?  Can you describe how and where you looked for
this functionality?  Maybe if we know that, we could make some changes
to have this function pop up in similar searches.

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: 58364-done@debbugs.gnu.org
>> Date: Sat, 08 Oct 2022 07:21:01 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Philip Kaludercic <philipk@posteo.net>
>> >> Date: Fri, 07 Oct 2022 20:23:27 +0000
>> >> 
>> >> Unless I am mistaken, there is no direct function to quickly test if a
>> >> directory is a super-directory of file.  As I have encountered this
>> >> issue more than once the last few days of hacking, I would like to
>> >> propose the below function.
>> >
>> > We have file-in-directory-p.  Doesn't that fit the bill?
>> 
>> I hive tried it out and yes that was the function I was looking for.  My
>> apologies for the noise.
>
> No need to apologize: no one can know and remember everything.  I only
> remembered that because I recently fixed a bug in Dired which used
> that function.
>
> But perhaps our take from this is that file-in-directory-p is not
> discoverable enough?  Can you describe how and where you looked for
> this functionality?  Maybe if we know that, we could make some changes
> to have this function pop up in similar searches.

I used M-x apropos-command "file parent" tried to find something in
(elisp) File Names.  I now see that the function is documented under
(elisp) Truenames, which appears unintuitive to me.  My guess is that
had I seen the function name mentioned somewhere, I would have read over
it since it sounds like a function that checks for "direct entries" in a
directory.

When writing my own patch I considered adding it to the shortdocs for
"file-name", but as the function checks for actually existing file names
the examples would probably not work in a portable way.

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: 58364@debbugs.gnu.org
> Date: Sat, 08 Oct 2022 09:23:40 +0000
> 
> > But perhaps our take from this is that file-in-directory-p is not
> > discoverable enough?  Can you describe how and where you looked for
> > this functionality?  Maybe if we know that, we could make some changes
> > to have this function pop up in similar searches.
> 
> I used M-x apropos-command "file parent" tried to find something in
> (elisp) File Names.  I now see that the function is documented under
> (elisp) Truenames, which appears unintuitive to me.  My guess is that
> had I seen the function name mentioned somewhere, I would have read over
> it since it sounds like a function that checks for "direct entries" in a
> directory.

I think a better place is in "Contents of Directories", since
locate-dominating-file is already there.  More importantly, what index
entries should we have for this function to make its discovery easier?
Something like "@cindex parent directory of file", perhaps?

For apropos, how about changing the doc string to say this instead:

  Return non-nil if DIR is a parent directory of FILE.

  Value is non-nil if FILE is inside DIR or inside a subdirectory of
  DIR.  A directory is considered to be a "parent" of itself.

  Dir must be an existing directory, otherwise the function returns
  nil.

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: 58364@debbugs.gnu.org
>> Date: Sat, 08 Oct 2022 09:23:40 +0000
>> 
>> > But perhaps our take from this is that file-in-directory-p is not
>> > discoverable enough?  Can you describe how and where you looked for
>> > this functionality?  Maybe if we know that, we could make some changes
>> > to have this function pop up in similar searches.
>> 
>> I used M-x apropos-command "file parent" tried to find something in
>> (elisp) File Names.  I now see that the function is documented under
>> (elisp) Truenames, which appears unintuitive to me.  My guess is that
>> had I seen the function name mentioned somewhere, I would have read over
>> it since it sounds like a function that checks for "direct entries" in a
>> directory.
>
> I think a better place is in "Contents of Directories", since
> locate-dominating-file is already there.  

I agree, sounds good.

>                                           More importantly, what index
> entries should we have for this function to make its discovery easier?
> Something like "@cindex parent directory of file", perhaps?

Drew brought up the word "ancestor", which might also be a word that
people would use to find such a function.

> For apropos, how about changing the doc string to say this instead:
>
>   Return non-nil if DIR is a parent directory of FILE.
>
>   Value is non-nil if FILE is inside DIR or inside a subdirectory of
>   DIR.  A directory is considered to be a "parent" of itself.
>
>   Dir must be an existing directory, otherwise the function returns
    ^
    shouldn't this be "DIR"?
    
>   nil.

Sounds good otherwise.

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: 58364@debbugs.gnu.org
> Date: Sat, 08 Oct 2022 10:29:23 +0000
> 
> > I think a better place is in "Contents of Directories", since
> > locate-dominating-file is already there.  
> 
> I agree, sounds good.
> 
> >                                           More importantly, what index
> > entries should we have for this function to make its discovery easier?
> > Something like "@cindex parent directory of file", perhaps?
> 
> Drew brought up the word "ancestor", which might also be a word that
> people would use to find such a function.

I added both.

> > For apropos, how about changing the doc string to say this instead:
> >
> >   Return non-nil if DIR is a parent directory of FILE.
> >
> >   Value is non-nil if FILE is inside DIR or inside a subdirectory of
> >   DIR.  A directory is considered to be a "parent" of itself.
> >
> >   Dir must be an existing directory, otherwise the function returns
>     ^
>     shouldn't this be "DIR"?

Yes, of course.

Done on the release branch.

bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Drew Adams]

> For apropos, how about changing the doc string to say this instead:
> 
>   Return non-nil if DIR is a parent directory of FILE.
>   Value is non-nil if FILE is inside DIR or inside a subdirectory of
>   DIR.  A directory is considered to be a "parent" of itself.

This is what's wrong with talking loosely about
a file being "inside" a directory - confusion.

The function is called `file-in-directory-p',
where you expect "in" to mean _either_ "inside"
DIR _or_ "inside" a subdir of DIR.  And does
"subdir" here mean a child of DIR or a
descendent of DIR?

Right away, this introduces confusion.  What
does it mean to be "inside" DIR - does it mean
be directly in DIR?  Or does it mean be directly
in either DIR or a directory that's a descendent
of DIR?

If you mean the latter then it makes no sense
to add "or inside a subdirectory of DIR", since
anything "in" any "subdir" of DIR is in that
case also "in" DIR.

And then there's the first doc-string line:

  ...DIR is a parent directory of FILE.

This is wrong.  The predicate apparently tests
whether DIR is an _ancestor_ directory; it
doesn't test whether it's a _parent_ directory.

In some languages "parent" can mean "ancestor"
or even "relative".  But not in English.

And this leaves aside the problem of whether
you really want to say that a _directory_ is a
parent of a _file_.  A dir _contains_ files.
Do you want to also say that a dir is a parent
or ancestor of a file?  (And this has nothing
to do with the fact that a directory itself is
also a file.)

The predicate is about an ancestor-descendent
relation, not a parent-child relation.

And it's really about such a relation between
the directory that FILE is contained in
directly and DIR - that is, it's more precise
not to speak of a directory being a parent or
an ancestor of a file.  (But if you want to
skip over that distinction, that could be OK.)

The predicate name is maybe less important
than getting the doc to be correct.  But
there's really no reason they can't both be 
accurate.

And if Emacs starts using accurate terminology
here then search, completion, apropos etc.
will be more helpful.

And the manual's Index can still offer (also)
entries that are less than accurate, as some
users may well think of a term like "parent"
before they think of "ancestor".  That
possibility isn't a reason not to use more
accurate terms in the doc (in particular), or
even in the function name.

https://en.wikipedia.org/wiki/Ancestor

https://stackoverflow.com/a/10993384/729907

https://stackoverflow.com/questions/55607027/git-what-is-the-logical-difference-between-parent-and-ancestor

https://stackoverflow.com/a/54889445/729907

https://sebastian.expert/ancestor-descendant-sibling-parent-child-explained/

https://teamtreehouse.com/community/what-is-the-difference-between-an-ancestor-and-parent-how-do-ancestors-parents-and-child-elements-relate

https://www.wwp.northeastern.edu/outreach/seminars/_current/presentations/xslt_intro/xpath_intro_tutorial_08.xhtml

https://wp-qa.com/what-is-the-difference-between-current_page_parent-and-current_page_ancestor

https://wikidiff.com/ancestor/parent