From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/elisp/file-name-components.html | 77 +++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 devdocs/elisp/file-name-components.html (limited to 'devdocs/elisp/file-name-components.html') diff --git a/devdocs/elisp/file-name-components.html b/devdocs/elisp/file-name-components.html new file mode 100644 index 00000000..8199a4a4 --- /dev/null +++ b/devdocs/elisp/file-name-components.html @@ -0,0 +1,77 @@ +

File Name Components

The operating system groups files into directories. To specify a file, you must specify the directory and the file’s name within that directory. Therefore, Emacs considers a file name as having two main parts: the directory name part, and the nondirectory part (or file name within the directory). Either part may be empty. Concatenating these two parts reproduces the original file name.

On most systems, the directory part is everything up to and including the last slash (backslash is also allowed in input on MS-DOS or MS-Windows); the nondirectory part is the rest.

For some purposes, the nondirectory part is further subdivided into the name proper and the version number. On most systems, only backup files have version numbers in their names.

Function: file-name-directory filename +
+

This function returns the directory part of filename, as a directory name (see Directory Names), or nil if filename does not include a directory part.

On GNU and other POSIX-like systems, a string returned by this function always ends in a slash. On MS-DOS it can also end in a colon. 

(file-name-directory "lewis/foo")  ; GNU example
+     ⇒ "lewis/"
+
+
(file-name-directory "foo")        ; GNU example
+     ⇒ nil
+
+
+
Function: file-name-nondirectory filename +
+

This function returns the nondirectory part of filename. 

(file-name-nondirectory "lewis/foo")
+     ⇒ "foo"
+
+
(file-name-nondirectory "foo")
+     ⇒ "foo"
+
+
(file-name-nondirectory "lewis/")
+     ⇒ ""
+
+
+
Function: file-name-sans-versions filename &optional keep-backup-version +
+

This function returns filename with any file version numbers, backup version numbers, or trailing tildes discarded.

If keep-backup-version is non-nil, then true file version numbers understood as such by the file system are discarded from the return value, but backup version numbers are kept. 

(file-name-sans-versions "~rms/foo.~1~")
+     ⇒ "~rms/foo"
+
+
(file-name-sans-versions "~rms/foo~")
+     ⇒ "~rms/foo"
+
+
(file-name-sans-versions "~rms/foo")
+     ⇒ "~rms/foo"
+
+
+
Function: file-name-extension filename &optional period +
+

This function returns filename’s final extension, if any, after applying file-name-sans-versions to remove any version/backup part. The extension, in a file name, is the part that follows the last ‘.’ in the last name component (minus any version/backup part).

This function returns nil for extensionless file names such as foo. It returns "" for null extensions, as in foo.. If the last component of a file name begins with a ‘.’, that ‘.’ doesn’t count as the beginning of an extension. Thus, .emacs’s extension is nil, not ‘.emacs’.

If period is non-nil, then the returned value includes the period that delimits the extension, and if filename has no extension, the value is "".

+
+
Function: file-name-with-extension filename extension +
+

This function returns filename with its extension set to extension. A single leading dot in the extension will be stripped if there is one. For example: 

(file-name-with-extension "file" "el")
+     ⇒ "file.el"
+(file-name-with-extension "file" ".el")
+     ⇒ "file.el"
+(file-name-with-extension "file.c" "el")
+     ⇒ "file.el"
+
+

Note that this function will error if filename or extension are empty, or if the filename is shaped like a directory (i.e., if directory-name-p returns non-nil).

+
+
Function: file-name-sans-extension filename +
+

This function returns filename minus its extension, if any. The version/backup part, if present, is only removed if the file has an extension. For example, 

(file-name-sans-extension "foo.lose.c")
+     ⇒ "foo.lose"
+(file-name-sans-extension "big.hack/foo")
+     ⇒ "big.hack/foo"
+(file-name-sans-extension "/my/home/.emacs")
+     ⇒ "/my/home/.emacs"
+(file-name-sans-extension "/my/home/.emacs.el")
+     ⇒ "/my/home/.emacs"
+(file-name-sans-extension "~/foo.el.~3~")
+     ⇒ "~/foo"
+(file-name-sans-extension "~/foo.~3~")
+     ⇒ "~/foo.~3~"
+
+

Note that the ‘.~3~’ in the two last examples is the backup part, not an extension.

+
+
Function: file-name-base filename +
+

This function is the composition of file-name-sans-extension and file-name-nondirectory. For example, 

(file-name-base "/my/home/foo.c")
+    ⇒ "foo"
+
+
+
+

+ Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc.
Licensed under the GNU GPL license.
+ https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Name-Components.html +

+
-- cgit v1.2.3