45path Module

45.1Overview

The path module provides functions related to path operations. This is a built-in module, so you can use it without being imported.

Below is an example to list path names that exist in the current directory.

println(path.dir('.'))

Below is an example to list path names that exist in the current directory and its child directories.

println(path.walk('.'))

Below is an example to list path names that matches a wild card pattern "*.txt".

println(path.glob('*.txt'))

45.2Module Function

path.absname(name:string):map:[uri]

Returns an absolute path name of the given name.

path.basename(pathname:string):map

Removes a suffix part of a path name. This is complementary to path.extname().

Example:

path.basename('/foo/bar/file.txt')  # Returns '/foo/bar/file'

path.bottom(pathname:string):map

Returns the last part of a path name (cf. path.filename()).This is complementary to path.cutbottom().

Example:

path.bottom('/foo/bar/file.txt')  # Returns 'file.txt'
path.bottom('/foo/bar/dir/')      # Returns 'dir'

path.cutbottom(pathname:string):map

Returns a path name after eliminating its bottom part (cf. path.dirname()).This is complementary to path.bottom().

Example:

path.cutbottom('/foo/bar/file.txt')  # Returns '/foo/bar/'
path.cutbottom('/foo/bar/dir/')      # Returns '/foo/bar/'

path.dir(directory?:directory, pattern*:string):flat:map:[case,dir,file,icase,stat] {block?}

Creates an iterator that lists item names in the specified directory. If pathname is omitted, the current directory shall be listed.

Though the default sensitiveness of character cases during pattern matching depends on the target directory, it can be changed by attributes :case for case-sensitive and :icase for case-insensitive.

In default, this returns an iterator as its result value. Specifying the following attributes would customize the returned value:

:iter .. An iterator. This is the default behavior.
:xiter .. An iterator that eliminates nil from its elements.
:list .. A list.
:xlist .. A list that eliminates nil from its elements.
:set .. A list that eliminates duplicated values from its elements.
:xset .. A list that eliminates duplicated values and nil from its elements.

See the chapter of Mapping Process in Gura Language Manual for the detail.

If a block is specified, it would be evaluated repeatingly with block parameters |value, idx:number| where value is the iterated value and idx the loop index starting from zero. In this case, the last evaluated value of the block would be the result value. If one of the attributes listed above is specified, an iterator or a list of the evaluated value would be returned.

path.dirname(pathname:string):map

Splits a pathname by a directory separator and returns a directory name part (cf. path.cutbottom()).This is complementary to path.filename().

Example:

path.dirname('/foo/bar/file.txt')  # Returns '/foo/bar/'
path.dirname('/foo/bar/dir/')      # Returns '/foo/bar/dir/'

path.exists(pathname:string):map

Returns true if the specified file exists in a file system.

path.extname(pathname:string):map

Extracts a suffix part of a path name. It returns an empty string when the given pathname has no suffix. This is complementary to path.basename().

Example:

path.extname('/foo/bar/file.txt')  # Returns 'txt'
path.extname('/foo/bar/file')      # Returns ''

path.filename(pathname:string):map

Splits a pathname by a directory separator and returns a file name part (cf. path.bottom()). This is complementary to path.dirname().

Example:

path.filename('/foo/bar/file.txt')  # Returns 'file.txt'
path.filename('/foo/bar/dir/')      # Returns ''

path.glob(pattern:string):flat:map:[case,dir,file,icase,stat] {block?}

Creates an iterator for item names that match with a pattern supporting UNIX shell-style wild cards. In default, case of characters is distinguished.

Though the default sensitiveness of character cases during pattern matching depends on the current platform, it can be changed by attributes :case for case-sensitive and :icase for case-insensitive.

In default, this returns an iterator as its result value. Specifying the following attributes would customize the returned value:

:iter .. An iterator. This is the default behavior.
:xiter .. An iterator that eliminates nil from its elements.
:list .. A list.
:xlist .. A list that eliminates nil from its elements.
:set .. A list that eliminates duplicated values from its elements.
:xset .. A list that eliminates duplicated values and nil from its elements.

See the chapter of Mapping Process in Gura Language Manual for the detail.

path.join(paths+:string):map:[uri]

Returns a path name that joins given strings with directory separators.

path.match(pattern:string, name:string):map:[case,icase]

Returns true if a name matches with a pattern that supports UNIX shell-style wild cards.

Though the default sensitiveness of character cases depends on the current platform, it can be changed by attributes :case for case-sensitive and :icase for case-insensitive.

path.regulate(name:string):map:[uri]

Removes redundant relative directories.

path.split(pathname:string):map:[bottom]

Splits a pathname by a directory separator and returns a list containing a directory name as the first element and a base name as the second one.

Calling this function has the same result as calling path.dirname() and path.filename().

Calling this function with :bottom attribute has the same result as calling path.cutbottom() and path.bottom().

Example:

path.split('/foo/bar/file.txt')         # Returns ['/foo/bar/', 'file.txt']
path.split('/foo/bar/dir/')             # Returns ['/foo/bar/dir/', '']

path.split('/foo/bar/file.txt'):bottom  # Returns ['/foo/bar/', 'file.txt']
path.split('/foo/bar/dir/'):bottom      # Returns ['/foo/bar/', 'dir']

path.splitext(pathname:string):map

Splits a pathname by a dot character indicating a beginning of an extension and returns a list containing a path name without an extention and an extention part.

path.stat(directory:directory):map

Returns a stat object associated with the specified item.

path.walk(directory?:directory, maxdepth?:number, pattern*:string):flat:map:[case,dir,file,icase,stat] {block?}

Creates an iterator that recursively lists item names under the specified directory. If directory is omitted, search starts at the current directory.

In default, this returns an iterator as its result value. Specifying the following attributes would customize the returned value:

:iter .. An iterator. This is the default behavior.
:xiter .. An iterator that eliminates nil from its elements.
:list .. A list.
:xlist .. A list that eliminates nil from its elements.
:set .. A list that eliminates duplicated values from its elements.
:xset .. A list that eliminates duplicated values and nil from its elements.

See the chapter of Mapping Process in Gura Language Manual for the detail.