Path¶
Usage
use Path;
or
import Path;
A file utilities library, specifically related to path operations
The Path module focuses on manipulation of the path to a file or directory. Also provided are constant values representing common idioms that may vary across operating systems (though rarely in the modern era), such as general references to a parent directory or the current directory.
Note
This module is currently missing the implementation for expandUser, normCase, Once those are implemented, it will be considered complete.
Operations which occur on the files or directories referred to by these paths
may be found in FileSystem
(for operations on the file) or IO
(for operations within the file).
Path Computations¶
commonPath
normPath
realPath
file.realPath
relPath
file.relPath
Path Manipulations¶
Path Properties¶
Constant and Function Definitions¶
-
param
curDir
¶ Represents generally the current directory. This starts as the directory where the program is being executed from. On all the platforms that Chapel supports this parameter is set to “.”.
-
param
parentDir
¶ Represents generally the parent directory. On all the platforms that Chapel supports this parameter is set to “..”.
-
param
pathSep
¶ Denotes the separator between a directory and its child. On all the platforms that Chapel supports this parameter is set to “/”
-
proc
absPath
(path: string): string throws¶ Creates a normalized absolutized version of a path. On most platforms, when given a non-absolute path this function is equivalent to the following code:
normPath(joinPath(here.cwd(), path))
See
normPath()
,joinPath()
,cwd()
for details.Warning
This function is unsafe for use in a parallel environment due to its reliance on
cwd()
. Another task on the current locale may change the current working directory at any time.- Arguments
path : string – The path whose absolute path is desired.
- Returns
A normalized, absolutized version of the path specified.
- Return type
string
- Throws
SystemError – Upon failure to get the current working directory.
-
proc
file.
absPath
(): string throws¶ Creates a normalized absolutized version of the path in this
file
. On most platforms, when given a non-absolute path this function is equivalent to the following code:normPath(joinPath(here.cwd(), file.path))
See
normPath()
,joinPath()
,cwd()
,path
for details.Warning
This method is unsafe for use in a parallel environment due to its reliance on
cwd()
. Another task on the current locale may change the current working directory at any time.- Returns
A normalized, absolutized version of the path for this file.
- Return type
string
- Throws
SystemError – Upon failure to get the current working directory.
-
proc
basename
(path: string): string¶ Returns the file name portion of the path provided. For instance:
writeln(basename("/foo/bar/baz")); // Prints "baz" writeln(basename("/foo/bar/")); // Prints "", because of the empty string
Note that this is different from the Unix
basename
function.- Arguments
path : string – A string file name. Note that this string does not have to be a valid file name, as the file itself will not be affected.
-
proc
commonPath
(paths: string ...?n): string¶ Determines and returns the longest common path prefix of all the string pathnames provided.
- Arguments
paths : string – Any number of paths.
- Returns
The longest common path prefix.
- Return type
string
-
proc
commonPath
(paths: []): string Determines and returns the longest common path prefix of all the string pathnames provided.
- Arguments
paths : array – Any number of paths as an array.
- Returns
The longest common path prefix.
- Return type
string
-
proc
dirname
(path: string): string¶ Returns the parent directory portion of the path provided. For instance:
writeln(dirname("/foo/bar/baz")); // Prints "/foo/bar" writeln(dirname("/foo/bar/")); // Also prints "/foo/bar"
Note that this is different from the Unix
dirname
function.- Arguments
path : string – A string file name. Note that this string does not have to be a valid file name, as the file itself will not be affected.
-
proc
expandVars
(path: string): string¶ Expands any environment variables in the path of the form
$<name>
or${<name>}
into their values. If<name>
does not exist, they are left in place. Returns the path which includes these expansions.- Arguments
path : string – A string representation of a path, which may or may not include
$<name>
or${<name>}
.- Returns
path, having replaced all references to environment variables with their values.
- Return type
string
-
proc
file.
getParentName
(): string throws¶ Returns the parent directory of the
file
record. For instance:var myFile = open("/foo/bar/baz.txt", iomode.r); writeln(myFile.getParentName()); // Prints "/foo/bar"
- Returns
The parent directory of the file.
- Return type
string
- Throws
SystemError – If one occurs.
-
proc
isAbsPath
(path: string): bool¶ Determines whether the path specified is an absolute path.
Note
This is currently only implemented in a Unix environment. It will not behave correctly in a non-Unix environment.
- Arguments
path : string – The path to be checked.
- Returns
true if name is an absolute path, false otherwise.
- Return type
bool
-
proc
joinPath
(paths: string ...?n): string¶ Join and return one or more paths, putting precedent on the last absolute path seen. Return value is the concatenation of the paths with one directory separator following each non-empty argument except the last. Examples:
writeln(joinPath("/foo/bar", "/baz")); // Prints "/baz" writeln(joinPath("/foo", "./baz")); // Prints "/foo/./baz" writeln(joinPath("/foo/", "", "./baz")); // Prints "/foo/./baz"
- Arguments
paths : string – Any number of paths.
- Returns
The concatenation of the last absolute path with everything following it, or all the paths provided if no absolute path is present.
- Return type
string
-
proc
normPath
(path: string): string¶ Normalize a path by eliminating redundant separators and up-level references. The paths
foo//bar
,foo/bar/
,foo/./bar
, andfoo/baz/../bar
would all be changed tofoo/bar
.Warning
May alter the meaning of paths containing symbolic links.
Note
Unlike its Python counterpart, this function does not (currently) change slashes to backslashes on Windows.
- Arguments
path : string – A potential path to collapse, possibly destroying the meaning of the path if symbolic links were included.
- Returns
The collapsed version of path.
- Return type
string
-
proc
realPath
(path: string): string throws¶ Given a path
path
, attempts to determine the canonical path referenced. This resolves and removes anycurDir
andparentDir
uses present, as well as any symbolic links. Returns the result.- Arguments
path : string – A path to resolve. If the path does not refer to a valid file or directory, an error will occur.
- Returns
A canonical version of the argument.
- Return type
string
- Throws
SystemError – If one occurs.
-
proc
file.
realPath
(): string throws¶ Determines the canonical path referenced by the
file
record performing this operation. This resolves and removes anycurDir
andparentDir
uses present, as well as any symbolic links. Returns the result.
-
proc
relPath
(path: string, start: string = curDir): string throws¶ Returns a relative filepath to name either from the current directory or an optional start directory. The filesystem is not accessed to verify the existence of the named path or the specified starting location.
Warning
This method is unsafe for use in a parallel environment due to its reliance on
cwd()
. Another task on the current locale may change the current working directory at any time.- Arguments
path : string – A path which the caller would like to access.
start : string – The location from which access to path is desired. If no value is provided, defaults to
curDir
.
- Returns
The relative path to path from the current directory.
- Return type
string
- Throws
SystemError – Upon failure to get the current working directory.
-
proc
file.
relPath
(start: string = curDir): string throws¶ Returns a relative filepath to the path in this
file
either from the current directory or an optional start directory. The filesystem is not accessed to verify the existence of the named path or the specified starting location.Warning
This method is unsafe for use in a parallel environment due to its reliance on
cwd()
. Another task on the current locale may change the current working directory at any time.
-
proc
splitExt
(path: string): (string, string)¶ Splits the given path into its root and extension. Leading periods in the path are ignored.
- Arguments
path : string – A string file name, not necessarily valid.
- Returns
A tuple of the form
(root, ext)
.- Return type
(string, string)
-
proc
splitPath
(path: string): (string, string)¶ Split path into a tuple that is equivalent to (
dirname
,basename
). The second part of the tuple will never contain a slash. Examples:writeln(splitPath("foo/bar")); // Prints "(foo, bar)" writeln(splitPath("bar")); // Prints "(, bar)" writeln(splitPath("foo/")); // Prints "(foo, )" writeln(splitPath("")); // Prints "(, )" writeln(splitPath("/")); // Prints "(/, )"
With the exception of a path of the empty string or just “/”, the original path can be recreated from this function’s returned parts by joining them with the path separator character, either explicitly or by calling
joinPath
:var res = splitPath("foo/bar"); var dirnameVar = res(0); var basenameVar = res(1); writeln(dirnameVar + "/" + basenameVar); // Prints "foo/bar" writeln(joinPath(dirnameVar, basenameVar)); // Prints "foo/bar"
- Arguments
path – Path to be split.