filename

Filename Manipulation Functions

The module filename provides a number of useful functions for analyzing and manipulating file names. These functions are designed so that the Erlang code can work on many different platforms with different formats for file names. With file name is meant all strings that can be used to denote a file. They can be short relative names like foo.erl, very long absolute name which include a drive designator and directory names like D:\usr/local\bin\erl/lib\tools\foo.erl, or any variations in between.

filename模块提供了一系有用的分析和管理文件名的函数.设计这些函数是为了让Erlang编写的代码在各种文件名格式不同的平台上 正常工作.文件名字面值可以用来代表文件.它们可以是像foo.erl 一样简短的相对路径文件名，或是像D:\usr/local\bin\erl/lib\tools\foo.erl 这样长的绝对路径文件名，或者是其他介于两者之间的形式.

In Windows, all functions return file names with forward slashes only, even if the arguments contain back slashes. Use join/1 to normalize a file name by removing redundant directory separators.

在Windows操作系统上, 即便参数带有反斜杠，所有函数都只返回带有斜杠的文件名. 使用join/1来规格化文件名，可以避免自己指定文件夹分隔符.

The module supports raw file names in the way that if a binary is present, or the file name cannot be interpreted according to the return value of file:native_name_encoding/0, a raw file name will also be returned. For example filename:join/1 provided with a path component being a binary (and also not being possible to interpret under the current native file name encoding) will result in a raw file name being returned (the join operation will have been performed of course). For more information about raw file names, see the file module.

The module supports raw file names in the way that if a binary is present, or the file name cannot be interpreted according to the return value of file:native_name_encoding/0, a raw file name will also be returned. For example filename:join/1 provided with a path component being a binary (and also not being possible to interpret under the current native file name encoding) will result in a raw file name being returned (the join operation will have been performed of course). For more information about raw file names, see the file module.

Functions:

absname(Filename) -> file:filename()

Filename = file:name()

Converts a relative Filename and returns an absolute name. No attempt is made to create the shortest absolute name, because this can give incorrect results on file systems which allow links.

把相对路径Filename转换成绝对路径. [TODO]不要企图创建最简绝对路径，在支持链接的系统上也样可能会给出错误结果.

Unix examples:

Unix 示例:

1> pwd().
"/usr/local"
2> filename:absname("foo").
"/usr/local/foo"
3> filename:absname("../x").
"/usr/local/../x"
4> filename:absname("/").
"/"

Windows examples:

Windows 示例:

1> pwd().
"D:/usr/local"
2> filename:absname("foo").
"D:/usr/local/foo"
3> filename:absname("../x").
"D:/usr/local/../x"
4> filename:absname("/").
"D:/"

absname(Filename, Dir) -> file:filename()

Filename = file:name(),
Dir = file:filename()

This function works like absname/1, except that the directory to which the file name should be made relative is given explicitly in the Dir argument.

除了与文件名相关的文件夹在参数Dir中显式给出, 该函数与absname/1相似.

absname_join(Dir, Filename) -> file:filename()

Dir = file:filename(),
Filename = file:name()

Joins an absolute directory with a relative filename. Similar to join/2, but on platforms with tight restrictions on raw filename length and no support for symbolic links (read: VxWorks), leading parent directory components in Filename are matched against trailing directory components in Dir so they can be removed from the result - minimizing its length.

连接一个绝对路径文件夹和相对路径文件名. 与join/2相似, 但是在严格限制原始文件长度以及不支持符号链接的平台上 (read: VxWorks), 导致Filename中的父文件夹组件 are matched against trailing directory components in Dir so they can be从结果中删除 - 以最小化它的长度minimizing its length.

basename(Filename) -> file:filename()

Filename = file:name()

Returns the last component of Filename, or Filename itself if it does not contain any directory separators.

返回Filename的最后组成部分, 或者当Filename不包含文件夹分隔符时返回Filename自身>.

5> filename:basename("foo").
"foo"
6> filename:basename("/usr/foo").
"foo"
7> filename:basename("/").
[]

basename(Filename, Ext) -> file:filename()

Filename = file:name(),
Ext = file:name()

Returns the last component of Filename with the extension Ext stripped. This function should be used to remove a specific extension which might, or might not, be there. Use rootname(basename(Filename)) to remove an extension that exists, but you are not sure which one it is.

返回去除了扩展名Ext后Filename的最后组成部分. 这个函数被用于去除特定的有或没有的后缀名. 使用rootname(basename(Filename))可以删除你不知道的后缀.

8> filename:basename("~/src/kalle.erl", ".erl").
"kalle"
9> filename:basename("~/src/kalle.beam", ".erl").
"kalle.beam"
10> filename:basename("~/src/kalle.old.erl", ".erl").
"kalle.old"
11> filename:rootname(filename:basename("~/src/kalle.erl")).
"kalle"
12> filename:rootname(filename:basename("~/src/kalle.beam")).
"kalle"

dirname(Filename) -> file:filename()

Filename = file:name()

Returns the directory part of Filename.

返回Filename的文件夹部分.

13> filename:dirname("/usr/src/kalle.erl").
"/usr/src"
14> filename:dirname("kalle.erl").
"."

5> filename:dirname("\\usr\\src/kalle.erl"). % Windows
"/usr/src"

extension(Filename) -> file:filename()

Filename = file:name()

Returns the file extension of Filename, including the period. Returns an empty string if there is no extension.

返回Filename的后缀名（包括点号). 如果没有后缀名返回空字符串.

15> filename:extension("foo.erl").
".erl"
16> filename:extension("beam.src/kalle").
[]

flatten(Filename) -> file:filename()

Filename = file:name()

Converts a possibly deep list filename consisting of characters and atoms into the corresponding flat string filename.

将包含原子和字符的深层列表转换成相应平整化的字符串文件名.

join(Components) -> file:filename()

Components = [file:filename()]

Joins a list of file name Components with directory separators. If one of the elements of Components includes an absolute path, for example "/xxx", the preceding elements, if any, are removed from the result.

使用文件夹分隔符连接文件名列表Components. 如果Components的其中一个元素包含绝对路径名, 例如"/xxx", 那么之前的元素将会从结果中删除.

The result is "normalized":

结果是"规格化的":

Redundant directory separators are removed.

多余的文件夹分隔符将被删除.

In Windows, all directory separators are forward slashes and the drive letter is in lower case.

在Windows平台上, 所有的文件夹分隔符是斜线并且盘符为小写.

 
17> filename:join(["/usr", "local", "bin"]).
"/usr/local/bin"
18> filename:join(["a/b///c/"]).
"a/b/c"

6> filename:join(["B:a\\b///c/"]). % Windows
"b:a/b/c"

join(Name1, Name2) -> file:filename()

Name1 = file:filename(),
Name2 = file:filename()

Joins two file name components with directory separators. Equivalent to join([Name1, Name2]).

使用文件夹分隔符链接两个文件名组件. 等同于join([Name1, Name2]).

nativename(Path) -> file:filename()

Path = file:filename()

Converts Path to a form accepted by the command shell and native applications on the current platform. On Windows, forward slashes is converted to backward slashes. On all platforms, the name is normalized as done by join/1.

将 Path转换成命令行和当前平台本地程序可接受的形式. 在Windows平台上斜线会被转换成反斜线. 在所有平台上, 文件名都像使用join/1似的被规格化.

19> filename:nativename("/usr/local/bin/"). % Unix
"/usr/local/bin"

7> filename:nativename("/usr/local/bin/"). % Windows
"\\usr\\local\\bin"

pathtype(Path) -> 'absolute' | 'relative' | 'volumerelative'

Path = file:name()

Returns the type of path, one of absolute, relative, or volumerelative.

返回路径类型, absolute, relative, 或 volumerelative中其一.

absolute

The path name refers to a specific file on a specific volume.

路径指向特定卷上的特定文件.

Unix example: /usr/local/bin

Unix 示例: /usr/local/bin

Windows example: D:/usr/local/bin

Windows 示例: D:/usr/local/bin

relative

The path name is relative to the current working directory on the current volume.

路径名相对于当前卷上的当前工作目录.

Example: foo/bar, ../src

示例: foo/bar, ../src

volumerelative

The path name is relative to the current working directory on a specified volume, or it is a specific file on the current working volume.

路径名相对于特定卷上的当前目录, 或者它是当前工作卷上的特定文件.

Windows example: D:bar.erl, /bar/foo.erl

Windows 示例: D:bar.erl, /bar/foo.erl

rootname(Filename) -> file:filename()

Filename = file:name()

rootname(Filename, Ext) -> file:filename()

Filename = file:name(),
Ext = file:name()

Remove a filename extension. rootname/2 works as rootname/1, except that the extension is removed only if it is Ext.

删除文件名中的扩展名. rootname/2 除了只删除特定的后缀名Ext以外和rootname/1效果一样 .

20> filename:rootname("/beam.src/kalle").
/beam.src/kalle"
21> filename:rootname("/beam.src/foo.erl").
"/beam.src/foo"
22> filename:rootname("/beam.src/foo.erl", ".erl").
"/beam.src/foo"
23> filename:rootname("/beam.src/foo.beam", ".erl").
"/beam.src/foo.beam"

split(Filename) -> Components

Filename = file:name(),
Components = [file:filename()]

Returns a list whose elements are the path components of Filename.

返回由Filename路径组件构成的列表.

24> filename:split("/usr/local/bin").
["/","usr","local","bin"]
25> filename:split("foo/bar").
["foo","bar"]
26> filename:split("a:\\msdev\\include").
["a:/","msdev","include"]

find_src(Beam) -> {SourceFile, Options} | {error, {ErrorReason, Module}}

Beam = Module | Filename,
Filename = atom() | string(),
Module = module(),
SourceFile = string(),
Options = [Option],
Option = {'i', Path = string()}
| {'outdir', Path = string()}
| {'d', atom()},
ErrorReason = 'non_existing' | 'preloaded' | 'interpreted'

find_src(Beam, Rules) -> {SourceFile, Options} | {error, {ErrorReason, Module}}

Beam = Module | Filename,
Filename = atom() | string(),
Rules = [{BinSuffix = string(), SourceSuffix = string()}],
Module = module(),
SourceFile = string(),
Options = [Option],
Option = {'i', Path = string()}
| {'outdir', Path = string()}
| {'d', atom()},
ErrorReason = 'non_existing' | 'preloaded' | 'interpreted'

Finds the source filename and compiler options for a module. The result can be fed to compile:file/2 in order to compile the file again.

为模块搜索源文件名和编译选项.结果可以传递给compile:file/2来重新编译文件.

Warning:

We don't recommend using this function. If possible, use beam_lib(3) to extract the abstract code format from the BEAM file and compile that instead.

我们不建议使用这个函数. 如果可能的话, 使用 beam_lib(3) 从BEAN文件中提取抽象代码并且编译.

The Beam argument, which can be a string or an atom, specifies either the module name or the path to the source code, with or without the ".erl" extension. In either case, the module must be known by the code server, i.e. code:which(Module) must succeed.

参数Beam(字符串或者原子) 指定模块名或源代码路径 code, with or without the ".erl" extension. In either case, the module must be known by the code server, i.e. code:which(Module) must succeed.

Rules describes how the source directory can be found, when the object code directory is known. It is a list of tuples {BinSuffix, SourceSuffix} and is interpreted as follows: If the end of the directory name where the object is located matches BinSuffix, then the source code directory has the same name, but with BinSuffix replaced by SourceSuffix. Rules defaults to:

[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]

If the source file is found in the resulting directory, then the function returns that location together with Options. Otherwise, the next rule is tried, and so on.

The function returns {SourceFile, Options} if it succeeds. SourceFile is the absolute path to the source file without the ".erl" extension. Options include the options which are necessary to recompile the file with compile:file/2, but excludes options such as report or verbose which do not change the way code is generated. The paths in the {outdir, Path} and {i, Path} options are guaranteed to be absolute.