Add file-parent-directory function

* doc/lispref/files.texi: Document the function.
* etc/NEWS: Add its entry.
* lisp/emacs-lisp/shortdoc.el: Add it to 'file-name' group.
* lisp/files.el: implementation (bug#56355).

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ea8683a6d8e0e524080f89cc4efa0c332de1fe3c..ee4e1ec4d96277a8f0acb7ae163cbf8a0cfecc56 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2445,6 +2445,12 @@ You can use this function for directory names and for file names,
 because it recognizes abbreviations even as part of the name.
 @end defun
 
+@defun file-parent-directory filename
+This function returns the parent directory of @var{filename}.  If
+@var{filename} is at the top level, return @code{nil}.  @var{filename}
+can be relative to @code{default-directory}.
+@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 3836efa692751b5eab26f923498c45eb18250a1b..7967190c6e72ebf6e2a9b3142a688bb64c7251f6 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -339,6 +339,10 @@ increase and decrease the font size globally.  Additionally, the
 variable 'global-text-scale-adjust-resizes-frames' controls whether
 the frames are resized when the font size is changed.
 
++++
+** New function 'file-parent-directory'.
+Get the parent directory of a file.
+
 ** New config variable 'syntax-wholeline-max' to reduce the cost of long lines.
 This variable is used by some operations (mostly syntax-propertization
 and font-locking) to treat lines longer than this variable as if they

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index f53e783111c38b47cf2b2ea9fddce39faa471557..68293931c3c0858fdfa1782bb46ebaeffe3d1d90 100644 (file)
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -353,6 +353,13 @@ A FUNC form can have any number of `:no-eval' (or `:no-value'),
   (abbreviate-file-name
    :no-eval (abbreviate-file-name "/home/some-user")
    :eg-result "~some-user")
+  (file-parent-directory
+   :eval (file-parent-directory "/foo/bar")
+   :eval (file-parent-directory "~")
+   :eval (file-parent-directory "/tmp/")
+   :eval (file-parent-directory "foo/bar")
+   :eval (file-parent-directory "foo")
+   :eval (file-parent-directory "/"))
   "Quoted File Names"
   (file-name-quote
    :args (name)

diff --git a/lisp/files.el b/lisp/files.el
index 1295c24c9334c6e91cb5cc258092cbd64601466c..b952b08ff4783285039744b8a7c5f07a5c05f832 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -5145,6 +5145,23 @@ On most systems, this will be true:
           (setq filename nil))))
     components))
 
+(defun file-parent-directory (filename)
+  "Return the parent directory of FILENAME.
+If FILENAME is at the top level, return nil.  FILENAME can be
+relative to `default-directory'."
+  (let* ((expanded-filename (expand-file-name filename))
+         (parent (file-name-directory (directory-file-name expanded-filename))))
+    (cond
+     ;; filename is at top-level, therefore no parent
+     ((or (null parent)
+          (file-equal-p parent expanded-filename))
+      nil)
+     ;; filename is relative, return relative parent
+     ((not (file-name-absolute-p filename))
+      (file-relative-name parent))
+     (t
+      parent))))
+
 (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.