diff options
Diffstat (limited to 'devdocs/elisp/file-name-expansion.html')
| -rw-r--r-- | devdocs/elisp/file-name-expansion.html | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/devdocs/elisp/file-name-expansion.html b/devdocs/elisp/file-name-expansion.html new file mode 100644 index 00000000..5dd6fa4e --- /dev/null +++ b/devdocs/elisp/file-name-expansion.html @@ -0,0 +1,74 @@ + <h4 class="subsection">Functions that Expand Filenames</h4> <p><em>Expanding</em> a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory as well as the file name to be expanded. It also involves expanding abbreviations like <samp>~/</samp> (see <a href="directory-names#abbreviate_002dfile_002dname">abbreviate-file-name</a>), and eliminating redundancies like <samp>./</samp> and <samp><var>name</var>/../</samp>. </p> <dl> <dt id="expand-file-name">Function: <strong>expand-file-name</strong> <em>filename &optional directory</em> +</dt> <dd> +<p>This function converts <var>filename</var> to an absolute file name. If <var>directory</var> is supplied, it is the default directory to start with if <var>filename</var> is relative and does not start with ‘<samp>~</samp>’. (The value of <var>directory</var> should itself be an absolute directory name or directory file name; it may start with ‘<samp>~</samp>’.) Otherwise, the current buffer’s value of <code>default-directory</code> is used. For example: </p> <div class="example"> <pre class="example">(expand-file-name "foo") + ⇒ "/xcssun/users/rms/lewis/foo" +</pre> +<pre class="example">(expand-file-name "../foo") + ⇒ "/xcssun/users/rms/foo" +</pre> +<pre class="example">(expand-file-name "foo" "/usr/spool/") + ⇒ "/usr/spool/foo" +</pre> +</div> <p>If the part of <var>filename</var> before the first slash is ‘<samp>~</samp>’, it expands to your home directory, which is typically specified by the value of the <code>HOME</code> environment variable (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/General-Variables.html#General-Variables">General Variables</a> in <cite>The GNU Emacs Manual</cite>). If the part before the first slash is ‘<samp>~<var>user</var></samp>’ and if <var>user</var> is a valid login name, it expands to <var>user</var>’s home directory. If you do not want this expansion for a relative <var>filename</var> that might begin with a literal ‘<samp>~</samp>’, you can use <code>(concat +(file-name-as-directory directory) filename)</code> instead of <code>(expand-file-name filename directory)</code>. </p> <p>File names containing ‘<samp>.</samp>’ or ‘<samp>..</samp>’ are simplified to their canonical form: </p> <div class="example"> <pre class="example">(expand-file-name "bar/../foo") + ⇒ "/xcssun/users/rms/lewis/foo" +</pre> +</div> <p>In some cases, a leading ‘<samp>..</samp>’ component can remain in the output: </p> <div class="example"> <pre class="example">(expand-file-name "../home" "/") + ⇒ "/../home" +</pre> +</div> <p>This is for the sake of filesystems that have the concept of a superroot above the root directory <samp>/</samp>. On other filesystems, <samp>/../</samp> is interpreted exactly the same as <samp>/</samp>. </p> <p>Expanding <samp>.</samp> or the empty string returns the default directory: </p> <div class="example"> <pre class="example">(expand-file-name "." "/usr/spool/") + ⇒ "/usr/spool" +(expand-file-name "" "/usr/spool/") + ⇒ "/usr/spool" +</pre> +</div> <p>Note that <code>expand-file-name</code> does <em>not</em> expand environment variables; only <code>substitute-in-file-name</code> does that: </p> <div class="example"> <pre class="example">(expand-file-name "$HOME/foo") + ⇒ "/xcssun/users/rms/lewis/$HOME/foo" +</pre> +</div> <p>Note also that <code>expand-file-name</code> does not follow symbolic links at any level. This results in a difference between the way <code>file-truename</code> and <code>expand-file-name</code> treat ‘<samp>..</samp>’. Assuming that ‘<samp>/tmp/bar</samp>’ is a symbolic link to the directory ‘<samp>/tmp/foo/bar</samp>’ we get: </p> <div class="example"> <pre class="example">(file-truename "/tmp/bar/../myfile") + ⇒ "/tmp/foo/myfile" +</pre> +<pre class="example">(expand-file-name "/tmp/bar/../myfile") + ⇒ "/tmp/myfile" +</pre> +</div> <p>If you may need to follow symbolic links preceding ‘<samp>..</samp>’, you should make sure to call <code>file-truename</code> without prior direct or indirect calls to <code>expand-file-name</code>. See <a href="truenames">Truenames</a>. </p> +</dd> +</dl> <dl> <dt id="default-directory">Variable: <strong>default-directory</strong> +</dt> <dd> +<p>The value of this buffer-local variable is the default directory for the current buffer. It should be an absolute directory name; it may start with ‘<samp>~</samp>’. This variable is buffer-local in every buffer. </p> <p><code>expand-file-name</code> uses the default directory when its second argument is <code>nil</code>. </p> <p>The value is always a string ending with a slash. </p> <div class="example"> <pre class="example">default-directory + ⇒ "/user/lewis/manual/" +</pre> +</div> </dd> +</dl> <dl> <dt id="substitute-in-file-name">Function: <strong>substitute-in-file-name</strong> <em>filename</em> +</dt> <dd> +<p>This function replaces environment variable references in <var>filename</var> with the environment variable values. Following standard Unix shell syntax, ‘<samp>$</samp>’ is the prefix to substitute an environment variable value. If the input contains ‘<samp>$$</samp>’, that is converted to ‘<samp>$</samp>’; this gives the user a way to quote a ‘<samp>$</samp>’. </p> <p>The environment variable name is the series of alphanumeric characters (including underscores) that follow the ‘<samp>$</samp>’. If the character following the ‘<samp>$</samp>’ is a ‘<samp>{</samp>’, then the variable name is everything up to the matching ‘<samp>}</samp>’. </p> <p>Calling <code>substitute-in-file-name</code> on output produced by <code>substitute-in-file-name</code> tends to give incorrect results. For instance, use of ‘<samp>$$</samp>’ to quote a single ‘<samp>$</samp>’ won’t work properly, and ‘<samp>$</samp>’ in an environment variable’s value could lead to repeated substitution. Therefore, programs that call this function and put the output where it will be passed to this function need to double all ‘<samp>$</samp>’ characters to prevent subsequent incorrect results. </p> <p>Here we assume that the environment variable <code>HOME</code>, which holds the user’s home directory, has value ‘<samp>/xcssun/users/rms</samp>’. </p> <div class="example"> <pre class="example">(substitute-in-file-name "$HOME/foo") + ⇒ "/xcssun/users/rms/foo" +</pre> +</div> <p>After substitution, if a ‘<samp>~</samp>’ or a ‘<samp>/</samp>’ appears immediately after another ‘<samp>/</samp>’, the function discards everything before it (up through the immediately preceding ‘<samp>/</samp>’). </p> <div class="example"> <pre class="example">(substitute-in-file-name "bar/~/foo") + ⇒ "~/foo" +</pre> +<pre class="example">(substitute-in-file-name "/usr/local/$HOME/foo") + ⇒ "/xcssun/users/rms/foo" + ;; <span class="roman"><samp>/usr/local/</samp> has been discarded.</span> +</pre> +</div> </dd> +</dl> <p>Sometimes, it is not desired to expand file names. In such cases, the file name can be quoted to suppress the expansion, and to handle the file name literally. Quoting happens by prefixing the file name with ‘<samp>/:</samp>’. </p> <dl> <dt id="file-name-quote">Macro: <strong>file-name-quote</strong> <em>name</em> +</dt> <dd> +<p>This macro adds the quotation prefix ‘<samp>/:</samp>’ to the file <var>name</var>. For a local file <var>name</var>, it prefixes <var>name</var> with ‘<samp>/:</samp>’. If <var>name</var> is a remote file name, the local part of <var>name</var> (see <a href="magic-file-names">Magic File Names</a>) is quoted. If <var>name</var> is already a quoted file name, <var>name</var> is returned unchanged. </p> <div class="example"> <pre class="example">(substitute-in-file-name (file-name-quote "bar/~/foo")) + ⇒ "/:bar/~/foo" +</pre> + +<pre class="example">(substitute-in-file-name (file-name-quote "/ssh:host:bar/~/foo")) + ⇒ "/ssh:host:/:bar/~/foo" +</pre> +</div> <p>The macro cannot be used to suppress file name handlers from magic file names (see <a href="magic-file-names">Magic File Names</a>). </p> +</dd> +</dl> <dl> <dt id="file-name-unquote">Macro: <strong>file-name-unquote</strong> <em>name</em> +</dt> <dd><p>This macro removes the quotation prefix ‘<samp>/:</samp>’ from the file <var>name</var>, if any. If <var>name</var> is a remote file name, the local part of <var>name</var> is unquoted. </p></dd> +</dl> <dl> <dt id="file-name-quoted-p">Macro: <strong>file-name-quoted-p</strong> <em>name</em> +</dt> <dd><p>This macro returns non-<code>nil</code>, when <var>name</var> is quoted with the prefix ‘<samp>/:</samp>’. If <var>name</var> is a remote file name, the local part of <var>name</var> is checked. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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-Expansion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Name-Expansion.html</a> + </p> +</div> |