From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/filename.xml | 385 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 lib/stdlib/doc/src/filename.xml (limited to 'lib/stdlib/doc/src/filename.xml') diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml new file mode 100644 index 0000000000..3a6c5e0b60 --- /dev/null +++ b/lib/stdlib/doc/src/filename.xml @@ -0,0 +1,385 @@ + + + + +
+ + 19972009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + filename + Kenneth Lundin + 1 + 97-11-13 + B +
+ 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.

+

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.

+ + +
+ DATA TYPES + +name() = string() | atom() | DeepList + DeepList = [char() | atom() | DeepList] +
+ + + absname(Filename) -> string() + Convert a filename to an absolute name, relative the working directory + + Filename = 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.

+

Unix examples:

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

Windows examples:

+ 
+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) -> string() + Convert a filename to an absolute name, relative a specified directory + + Filename = name() + Dir = string() + + +

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.

+ + + + absname_join(Dir, Filename) -> string() + Join an absolute directory with a relative filename + + Dir = string() + Filename = 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.

+ + + + basename(Filename) -> string() + Return the last component of a filename + + Filename = name() + + +

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

+ 
+5> filename:basename("foo").
+"foo"
+6> filename:basename("/usr/foo").
+"foo"
+7> filename:basename("/").
+[]
+ + + + basename(Filename, Ext) -> string() + Return the last component of a filename, stripped of the specified extension + + Filename = Ext = 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.

+ 
+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) -> string() + Return the directory part of a path name + + Filename = name() + + +

Returns the directory part of 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) -> string() + Return the file extension + + Filename = name() + + +

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

+ 
+15> filename:extension("foo.erl").
+".erl"
+16> filename:extension("beam.src/kalle").
+[]
+ + + + flatten(Filename) -> string() + Convert a filename to a flat string + + Filename = name() + + +

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

+ + + + join(Components) -> string() + Join a list of filename components with directory separators + + Components = [string()] + + +

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.

+

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. + + 
+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) -> string() + Join two filename components with directory separators + + Name1 = Name2 = string() + + +

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

+ + + + nativename(Path) -> string() + Return the native form of a file path + + Path = string() + + +

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.

+ 
+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 + Return the type of a path + +

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

+ + absolute + +

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

+

Unix example: /usr/local/bin

+

Windows example: D:/usr/local/bin

+ + relative + +

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

+

Example: 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

+ + + + + + rootname(Filename) -> string() + rootname(Filename, Ext) -> string() + Remove a filename extension + + Filename = Ext = name() + + +

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

+ 
+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 + Split a filename into its path components + + Filename = name() + Components = [string()] + + +

Returns a list whose elements are the path components of + 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}} + find_src(Beam, Rules) -> {SourceFile, Options} | {error,{ErrorReason,Module}} + Find the filename and compiler options for a module + + Beam = Module | Filename +  Module = atom() +  Filename = string() | atom() + SourceFile = string() + Options = [Opt] +  Opt = {i, string()} | {outdir, 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.

+

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.

+

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.

+ + + + + + -- cgit v1.2.3