Module fs
This module provides file and path related functionality as defined by the CommonJS Filesystem/A proposal.
The "fs" module provides a file system API for the manipulation of paths, directories, files, links, and the construction of file streams.
Functions
- absolute(path)
- base(path, ext)
- canonical(path)
- changeGroup(path, group)
- changeOwner(path, group)
- changePermissions(path, permissions)
- changeWorkingDirectory(path)
- copy(from, to)
- copyTree(from, to)
- directory(path)
- exists(path)
- extension(path)
- group(path)
- hardLink(source, target)
- isAbsolute(path)
- isDirectory(path)
- isFile(path)
- isLink(path)
- isReadable(path)
- isRelative(path)
- isWritable(path)
- iterate(path)
- join()
- lastModified(path)
- list(path)
- listDirectoryTree(path)
- listTree(path)
- makeDirectory(path, permissions)
- makeTree(path)
- move(source, target)
- normal(path)
- open(path, options)
- openRaw(path, options, permissions)
- owner(path)
- path()
- permissions(path)
- read(path, options)
- readLink(path)
- relative(source, target)
- remove(path)
- removeDirectory(path)
- removeTree(path)
- resolve()
- same(pathA, pathB)
- sameFilesystem(pathA, pathB)
- size(path)
- split(path)
- symbolicLink(source, target)
- touch(path, mtime)
- workingDirectory()
- write(path, content, options)
Class Path
Instance Methods
Path ()
Path constructor. Path is a chainable shorthand for working with paths.
Path.prototype. from (target)
Return the relative path from the given source path to this path. Equivalent
to fs.Path(fs.relative(source, this)).
Parameters
| null | target |
Path.prototype. join ()
Join a list of paths to this path.
Path.prototype. listPaths ()
Return the names of all files in this path, in lexically sorted order and wrapped in Path objects.
Path.prototype. resolve ()
Resolve against this path.
Path.prototype. to (target)
Return the relative path from this path to the given target path. Equivalent
to fs.Path(fs.relative(this, target)).
Parameters
| null | target |
Path.prototype. toString ()
Path.prototype. valueOf ()
This is a non-standard extension, not part of CommonJS Filesystem/A.
Permissions (permissions, constructor)
The Permissions class describes the permissions associated with a file.
Parameters
| number|object | permissions | a number or object representing the permissions. |
| null | constructor |
Permissions.prototype. toNumber ()
absolute (path)
Make the given path absolute by resolving it against the current working directory.
Parameters
| null | path |
base (path, ext)
Return the basename of the given path. That is the path with any leading directory components removed. If specified, also remove a trailing extension.
Parameters
| String | path | |
| String | ext |
Returns
| String |
canonical (path)
Returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path.
Parameters
| string | path | a file path |
Returns
the canonical path |
changeGroup (path, group)
Supports group name string as well as gid int input.
Parameters
| String | path | |
| String|Number | group |
changeOwner (path, group)
Supports user name string as well as uid int input.
Parameters
| String | path | |
| String|Number | group |
changeWorkingDirectory (path)
Set the current working directory to path.
Parameters
| string | path | the new working directory |
copy (from, to)
Read data from one file and write it into another using binary mode.
Parameters
| String | from | |
| String | to |
copyTree (from, to)
Copy files from a source path to a target path. Files of the below the source path are copied to the corresponding locations relative to the target path, symbolic links to directories are copied but not traversed into.
Parameters
| String | from | |
| String | to |
directory (path)
Return the dirname of the given path. That is the path with any trailing non-directory component removed.
Parameters
| String | path |
exists (path)
Return true if the file denoted by path exists, false otherwise.
Parameters
| string | path | the file path. |
extension (path)
Return the extension of a given path. That is everything after the last dot in the basename of the given path, including the last dot. Returns an empty string if no valid extension exists.
Parameters
| String | path |
hardLink (source, target)
Creates a hard link at the target path that refers to the source path.
Parameters
| string | source | the source file |
| string | target | the target file |
isAbsolute (path)
Check whether the given pathname is absolute.
This is a non-standard extension, not part of CommonJS Filesystem/A.
Parameters
| null | path |
isDirectory (path)
Returns true if the file specified by path exists and is a directory.
Parameters
| string | path | the file path |
Returns
| boolean | whether the file exists and is a directory |
isFile (path)
Returns true if the file specified by path exists and is a regular file.
Parameters
| string | path | the file path |
Returns
| boolean | whether the file exists and is a file |
isLink (path)
Return true if target file is a symbolic link, false otherwise.
Parameters
| string | path | the file path |
Returns
true if the given file exists and is a symbolic link |
isReadable (path)
Returns true if the file specified by path exists and can be opened for reading.
Parameters
| string | path | the file path |
Returns
| boolean | whether the file exists and is readable |
isRelative (path)
Check wheter the given pathname is relative (i.e. not absolute).
This is a non-standard extension, not part of CommonJS Filesystem/A.
Parameters
| null | path |
isWritable (path)
Returns true if the file specified by path exists and can be opened for writing.
Parameters
| string | path | the file path |
Returns
| boolean | whether the file exists and is writable |
iterate (path)
Returns a generator that produces the file names of a directory.
Parameters
| string | path | a directory path |
join ()
Join a list of paths using the local file system's path separator.
The result is not normalized, so join("..", "foo") returns "../foo".
lastModified (path)
Returns the time a file was last modified as a Date object.
Parameters
| string | path | the file path |
Returns
the date the file was last modified |
list (path)
Returns an array with all the names of files contained in the direcory path.
Parameters
| string | path | the directory path |
Returns
| Array | a list of file names |
listDirectoryTree (path)
Return an array with all directories below (and including) the given path, as discovered by depth-first traversal. Entries are in lexically sorted order within directories. Symbolic links to directories are not traversed into.
Parameters
| null | path |
listTree (path)
Return an array with all paths (files, directories, etc.) below (and including) the given path, as discovered by depth-first traversal. Entries are in lexically sorted order within directories. Symbolic links to directories are returned but not traversed into.
Parameters
| null | path |
makeDirectory (path, permissions)
Create a single directory specified by path. If the directory cannot be
created for any reason an error is thrown. This includes if the parent
directories of path are not present. If a permissions argument is passed
to this function it is used to create a Permissions instance which is
applied to the given path during directory creation.
Parameters
| string | path | the file path |
| number|object | permissions | optional permissions |
makeTree (path)
Create the directory specified by "path" including any missing parent directories.
Parameters
| null | path |
move (source, target)
Move a file from source to target.
Parameters
| string | source | the source path |
| string | target | the target path |
Throws
normal (path)
Normalize a path by removing '.' and simplifying '..' components, wherever possible.
Parameters
| null | path |
open (path, options)
Open the file corresponding to path for reading or writing,
depending on the options argument. Returns a [binary stream][io#Stream]
or a [text stream][io#TextStream].
The options argument may contain the following properties:
- read (boolean) open the file in read mode.
- write (boolean) open the file in write mode starting at the beginning of the file.
- append (boolean) open the file in write mode starting at the end of the file.
- binary (boolean) open the file in binary mode.
- charset (string) open the file in text mode using the given encoding. Defaults to "utf8".
Parameters
| String | path | the file path |
| Object | options | options |
Returns
| Stream | a stream object |
openRaw (path, options, permissions)
Opens the file corresponding to path for reading or writing in binary
mode. This function supports the same options as [open()][#open] except
for binary and charset.
Parameters
| String | path | the file path |
| Object | options | options |
| Object | permissions | not yet supported |
Returns
| Stream |
path ()
A shorthand for creating a new Path without the new keyword.
read (path, options)
Read the content of the file corresponding to path. Returns a
String or [ByteString][binary#ByteString] object depending on the options
argument. This function supports the same options as [open()][#open].
Parameters
| String | path | the file path |
| Object | options | optional options |
Returns
| String|Binary | the content of the file |
readLink (path)
Returns the immediate target of the symbolic link at the given path.
Parameters
| string | path | a file path |
relative (source, target)
Establish the relative path that links source to target by strictly traversing up ('..') to find a common ancestor of both paths. If the target is omitted, returns the path to the source from the current working directory.
Parameters
| String | source | |
| String | target |
remove (path)
Remove a file at the given path. Throws an error if path is not a file
or a symbolic link to a file.
Parameters
| string | path | the path of the file to remove. |
Throws
removeDirectory (path)
Remove a file or directory identified by path. Throws an error if
path is a directory and not empty.
Parameters
| String | path | the directory path |
Throws
removeTree (path)
Remove the element pointed to by the given path. If path points to a directory, all members of the directory are removed recursively.
Parameters
| null | path |
resolve ()
Join a list of paths by starting at an empty location and iteratively "walking" to each path given. Correctly takes into account both relative and absolute paths.
same (pathA, pathB)
Returns whether two paths refer to the same storage (file or directory), either by virtue of symbolic or hard links, such that modifying one would modify the other.
Parameters
| string | pathA | the first path |
| string | pathB | the second path |
sameFilesystem (pathA, pathB)
Returns whether two paths refer to an entity of the same file system.
Parameters
| string | pathA | the first path |
| string | pathB | the second path |
size (path)
Returns the size of a file in bytes, or throws an exception if the path does not correspond to an accessible path, or is not a regular file or a link.
Parameters
| string | path | the file path |
Returns
| number | the file size in bytes |
Throws
symbolicLink (source, target)
Creates a symbolic link at the target path that refers to the source path.
Parameters
| string | source | the source file |
| string | target | the target link |
touch (path, mtime)
Sets the modification time of a file or directory at a given path to a specified time, or the current time. Creates an empty file at the given path if no file or directory exists, using the default permissions.
Parameters
| string | path | the file path |
| Date | mtime | optional date |
workingDirectory ()
Return the path name of the current working directory.
Returns
| string | the current working directory |
write (path, content, options)
Open, write, flush, and close a file, writing the given content. If content is a binary.ByteArray or binary.ByteString, binary mode is implied.
Parameters
| String | path | |
| binary.Binary|String | content | |
| Object | options |