Path¶

Usage

use Path;

or

import Path;

A file utilities library focusing on 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 relPath

Path Manipulations¶

absPath expandVars joinPath replaceBasename replaceDirname replaceExt splitExt splitPath

Path Properties¶

basename dirname isAbsPath

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 absPath(f: file) : string throws

Creates a normalized absolutized version of the path of a file. On most platforms, when given a non-absolute path this function is equivalent to the following code:

normPath(joinPath(here.cwd(), f.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.

Arguments:: f : file – The file whose absolute path is desired.
Returns:: A normalized, absolutized version of the path for the file argument.
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 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, and foo/baz/../bar would all be changed to foo/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 any curDir and parentDir 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 realPath(f: file) : string throws

Determines the canonical path referenced by a given file record. This resolves and removes any curDir and parentDir uses present, as well as any symbolic links. Returns the result.

Arguments:: f : file – A file whose path should be resolved.
Returns:: A canonical path to the file referenced by the given file record. If the file record is not valid, an error will occur.
Return type:: string
Throws:: SystemError – If one occurs.

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 relPath(f: file, start: string = curDir) : string throws

Returns a relative filepath to the path in a given 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.

Arguments:

f : file – The file
start : string – The location from which access to the path in this file is desired. If no value is provided, defaults to curDir.

Returns:

The relative filepath to the path in the given file.

Return type:

string

Throws:

SystemError – Upon failure to get the current working directory.

proc replaceBasename(path: string, newBasename: string) : string¶

Returns a new path with basename in path replaced with newBasename. If path had no basename then newBasename is added to the path or if the newBasename is an empty string then basename is removed from path.

Arguments:

path : string – A path which the caller would like to access.
newBasename : string – A basename to replace the current one

Returns:

a new path after replacing the basename.

Return type:

string

proc replaceDirname(path: string, newDirname: string) : string¶

Returns a new path with the dirname in path replaced with newDirname. If path had no dirname newDirname is added to the path or if the newDirname is an empty string then dirname is removed from the path.

Arguments:

path : string – A path which the caller would like to access.
newDirname : string – dirname to replace the current one

Returns:

The new path after replacing dirname.

Return type:

string

proc replaceExt(path: string, newExt: string) : string throws¶

Returns a new path with extension in path replaced with newExt. If path had no extension newExt is added to the path or if newExt is an empty string then extension is removed from the path. Extension has to be of form .name,`name` or it can be an empty string and shouldn’t contain spaces.

Arguments:

path : string – A path which the caller would like to access.
newExt : string – extension to replace the current one

Returns:

The new path after replacing extension if a valid newExt is provided.

Return type:

string

Throws:

IllegalArgumentError – Upon failure to provide a valid newExt or if the path had no basename.

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.