new repository

1 files changed, 77 insertions, 0 deletions

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 @@
+ <h4 class="subsection">File Name Components</h4>    <p>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 <em>directory name</em> part, and the <em>nondirectory</em> part (or <em>file name within the directory</em>). Either part may be empty. Concatenating these two parts reproduces the original file name. </p> <p>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. </p> <p>For some purposes, the nondirectory part is further subdivided into the name proper and the <em>version number</em>. On most systems, only backup files have version numbers in their names. </p> <dl> <dt id="file-name-directory">Function: <strong>file-name-directory</strong> <em>filename</em>
+</dt> <dd>
+<p>This function returns the directory part of <var>filename</var>, as a directory name (see <a href="directory-names">Directory Names</a>), or <code>nil</code> if <var>filename</var> does not include a directory part. </p> <p>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. </p> <div class="example"> <pre class="example">(file-name-directory "lewis/foo")  ; <span class="roman">GNU example</span>
+     ⇒ "lewis/"
+</pre>
+<pre class="example">(file-name-directory "foo")        ; <span class="roman">GNU example</span>
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="file-name-nondirectory">Function: <strong>file-name-nondirectory</strong> <em>filename</em>
+</dt> <dd>
+<p>This function returns the nondirectory part of <var>filename</var>. </p> <div class="example"> <pre class="example">(file-name-nondirectory "lewis/foo")
+     ⇒ "foo"
+</pre>
+<pre class="example">(file-name-nondirectory "foo")
+     ⇒ "foo"
+</pre>
+<pre class="example">(file-name-nondirectory "lewis/")
+     ⇒ ""
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="file-name-sans-versions">Function: <strong>file-name-sans-versions</strong> <em>filename &amp;optional keep-backup-version</em>
+</dt> <dd>
+<p>This function returns <var>filename</var> with any file version numbers, backup version numbers, or trailing tildes discarded. </p> <p>If <var>keep-backup-version</var> is non-<code>nil</code>, then true file version numbers understood as such by the file system are discarded from the return value, but backup version numbers are kept. </p> <div class="example"> <pre class="example">(file-name-sans-versions "~rms/foo.~1~")
+     ⇒ "~rms/foo"
+</pre>
+<pre class="example">(file-name-sans-versions "~rms/foo~")
+     ⇒ "~rms/foo"
+</pre>
+<pre class="example">(file-name-sans-versions "~rms/foo")
+     ⇒ "~rms/foo"
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="file-name-extension">Function: <strong>file-name-extension</strong> <em>filename &amp;optional period</em>
+</dt> <dd>
+<p>This function returns <var>filename</var>’s final extension, if any, after applying <code>file-name-sans-versions</code> to remove any version/backup part. The extension, in a file name, is the part that follows the last ‘<samp>.</samp>’ in the last name component (minus any version/backup part). </p> <p>This function returns <code>nil</code> for extensionless file names such as <samp>foo</samp>. It returns <code>""</code> for null extensions, as in <samp>foo.</samp>. If the last component of a file name begins with a ‘<samp>.</samp>’, that ‘<samp>.</samp>’ doesn’t count as the beginning of an extension. Thus, <samp>.emacs</samp>’s extension is <code>nil</code>, not ‘<samp>.emacs</samp>’. </p> <p>If <var>period</var> is non-<code>nil</code>, then the returned value includes the period that delimits the extension, and if <var>filename</var> has no extension, the value is <code>""</code>. </p>
+</dd>
+</dl> <dl> <dt id="file-name-with-extension">Function: <strong>file-name-with-extension</strong> <em>filename extension</em>
+</dt> <dd>
+<p>This function returns <var>filename</var> with its extension set to <var>extension</var>. A single leading dot in the <var>extension</var> will be stripped if there is one. For example: </p> <div class="example"> <pre class="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"
+</pre>
+</div> <p>Note that this function will error if <var>filename</var> or <var>extension</var> are empty, or if the <var>filename</var> is shaped like a directory (i.e., if <code>directory-name-p</code> returns non-<code>nil</code>). </p>
+</dd>
+</dl> <dl> <dt id="file-name-sans-extension">Function: <strong>file-name-sans-extension</strong> <em>filename</em>
+</dt> <dd>
+<p>This function returns <var>filename</var> minus its extension, if any. The version/backup part, if present, is only removed if the file has an extension. For example, </p> <div class="example"> <pre class="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~"
+</pre>
+</div> <p>Note that the ‘<samp>.~3~</samp>’ in the two last examples is the backup part, not an extension. </p>
+</dd>
+</dl> <dl> <dt id="file-name-base">Function: <strong>file-name-base</strong> <em>filename</em>
+</dt> <dd>
+<p>This function is the composition of <code>file-name-sans-extension</code> and <code>file-name-nondirectory</code>. For example, </p> <div class="example"> <pre class="example">(file-name-base "/my/home/foo.c")
+    ⇒ "foo"
+</pre>
+</div> </dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Name-Components.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Name-Components.html</a>
+  </p>
+</div>