.. default-domain:: chpl .. module:: Path :synopsis: A file utilities library focusing on path operations. Path ==== **Usage** .. code-block:: chapel use Path; or .. code-block:: chapel 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 :mod:`FileSystem` (for operations *on* the file) or :mod:`IO` (for operations *within* the file). Path Computations ----------------- :proc:`commonPath` :proc:`normPath` :proc:`realPath` :proc:`relPath` Path Manipulations ------------------ :proc:`absPath` :proc:`expandVars` :proc:`joinPath` :proc:`replaceBasename` :proc:`replaceDirname` :proc:`replaceExt` :proc:`splitExt` :proc:`splitPath` Path Properties --------------- :proc:`basename` :proc:`dirname` :proc:`isAbsPath` Constant and Function Definitions --------------------------------- .. data:: 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 ".". .. data:: param parentDir Represents generally the parent directory. On all the platforms that Chapel supports this parameter is set to "..". .. data:: param pathSep Denotes the separator between a directory and its child. On all the platforms that Chapel supports this parameter is set to "/" .. function:: 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: .. code-block:: Chapel normPath(joinPath(here.cwd(), path)) See :proc:`normPath()`, :proc:`joinPath()`, :proc:`~FileSystem.locale.cwd()` for details. .. warning:: This function is unsafe for use in a parallel environment due to its reliance on :proc:`~FileSystem.locale.cwd()`. Another task on the current locale may change the current working directory at any time. :arg path: The path whose absolute path is desired. :type path: `string` :return: A normalized, absolutized version of the path specified. :rtype: `string` :throws SystemError: Upon failure to get the current working directory. .. function:: proc absPath(f: file): string throws Creates a normalized absolutized version of the path of a :type:`~IO.file`. On most platforms, when given a non-absolute path this function is equivalent to the following code: .. code-block:: Chapel normPath(joinPath(here.cwd(), f.path)) See :proc:`normPath()`, :proc:`joinPath()`, :proc:`~FileSystem.locale.cwd()`, :proc:`~IO.file.path` for details. .. warning:: This method is unsafe for use in a parallel environment due to its reliance on :proc:`~FileSystem.locale.cwd()`. Another task on the current locale may change the current working directory at any time. :arg f: The file whose absolute path is desired. :type f: :type:`~IO.file` :return: A normalized, absolutized version of the path for the file argument. :rtype: `string` :throws SystemError: Upon failure to get the current working directory. .. function:: proc basename(path: string): string Returns the file name portion of the path provided. For instance: .. code-block:: Chapel 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. :arg path: 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. :type path: `string` .. function:: proc commonPath(paths: string ...?n): string Determines and returns the longest common path prefix of all the string pathnames provided. :arg paths: Any number of paths. :type paths: `string` :return: The longest common path prefix. :rtype: `string` .. function:: proc commonPath(paths: []): string Determines and returns the longest common path prefix of all the string pathnames provided. :arg paths: Any number of paths as an array. :type paths: `array` :return: The longest common path prefix. :rtype: `string` .. function:: proc dirname(path: string): string Returns the parent directory portion of the path provided. For instance: .. code-block:: Chapel 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. :arg path: 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. :type path: `string` .. function:: proc expandVars(path: string): string Expands any environment variables in the path of the form ``$`` or ``${}`` into their values. If ```` does not exist, they are left in place. Returns the path which includes these expansions. :arg path: A string representation of a path, which may or may not include ``$`` or ``${}``. :type path: `string` :return: `path`, having replaced all references to environment variables with their values. :rtype: `string` .. function:: 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. :arg path: The path to be checked. :type path: `string` :return: `true` if `name` is an absolute path, `false` otherwise. :rtype: `bool` .. function:: 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: .. code-block:: chapel writeln(joinPath("/foo/bar", "/baz")); // Prints "/baz" writeln(joinPath("/foo", "./baz")); // Prints "/foo/./baz" writeln(joinPath("/foo/", "", "./baz")); // Prints "/foo/./baz" :arg paths: Any number of paths. :type paths: `string` :return: The concatenation of the last absolute path with everything following it, or all the paths provided if no absolute path is present. :rtype: `string` .. function:: 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. :arg path: A potential path to collapse, possibly destroying the meaning of the path if symbolic links were included. :type path: `string` :return: The collapsed version of `path`. :rtype: `string` .. function:: proc realPath(path: string): string throws Given a path ``path``, attempts to determine the canonical path referenced. This resolves and removes any :data:`curDir` and :data:`parentDir` uses present, as well as any symbolic links. Returns the result. :arg path: A path to resolve. If the path does not refer to a valid file or directory, an error will occur. :type path: `string` :return: A canonical version of the argument. :rtype: `string` :throws SystemError: If one occurs. .. function:: proc realPath(f: file): string throws Determines the canonical path referenced by a given :type:`~IO.file` record. This resolves and removes any :data:`curDir` and :data:`parentDir` uses present, as well as any symbolic links. Returns the result. :arg f: A file whose path should be resolved. :type f: :type:`~IO.file` :return: A canonical path to the file referenced by the given :type:`~IO.file` record. If the :type:`~IO.file` record is not valid, an error will occur. :rtype: `string` :throws SystemError: If one occurs. .. function:: 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 :proc:`~FileSystem.locale.cwd()`. Another task on the current locale may change the current working directory at any time. :arg path: A path which the caller would like to access. :type path: `string` :arg start: The location from which access to path is desired. If no value is provided, defaults to :const:`curDir`. :type start: `string` :return: The relative path to `path` from the current directory. :rtype: `string` :throws SystemError: Upon failure to get the current working directory. .. function:: proc relPath(f: file, start: string = curDir): string throws Returns a relative filepath to the path in a given :type:`~IO.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 :proc:`~FileSystem.locale.cwd()`. Another task on the current locale may change the current working directory at any time. :arg f: The file :type f: :type:`~IO.file` :arg start: The location from which access to the path in this :type:`~IO.file` is desired. If no value is provided, defaults to :const:`curDir`. :type start: `string` :return: The relative filepath to the path in the given :type:`~IO.file`. :rtype: `string` :throws SystemError: Upon failure to get the current working directory. .. function:: 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`. :arg path: A path which the caller would like to access. :type path: `string` :arg newBasename: A basename to replace the current one :type newBasename: `string` :returns: a new path after replacing the basename. :rtype: `string` .. function:: 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`. :arg path: A path which the caller would like to access. :type path: `string` :arg newDirname: dirname to replace the current one :type newDirname: `string` :returns: The new path after replacing dirname. :rtype: `string` .. function:: 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. :arg path: A path which the caller would like to access. :type path: `string` :arg newExt: extension to replace the current one :type newExt: `string` :returns: The new path after replacing extension if a valid `newExt` is provided. :rtype: `string` :throws IllegalArgumentError: Upon failure to provide a valid `newExt` or if the `path` had no basename. .. function:: proc splitExt(path: string): (string, string) Splits the given path into its root and extension. Leading periods in the path are ignored. :arg path: A string file name, not necessarily valid. :type path: `string` :returns: A tuple of the form ``(root, ext)``. :rtype: `(string, string)` .. function:: proc splitPath(path: string): (string, string) Split path into a tuple that is equivalent to (:proc:`dirname`, :proc:`basename`). The second part of the tuple will never contain a slash. Examples: .. code-block:: Chapel 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 :proc:`joinPath`: .. code-block:: Chapel 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" :arg path: Path to be split. :type name: `string`