21fs Module

21.1Overview

The fs module provides measures to access and modify information in file systems. This is a built-in module, so you can use it without being imported.

21.2Module Function

The fs modules provides following functions:

fs.chdir(pathname:string) {block?}

Changes the current working directory to pathname.

The block would be evaluated if specified, and the working directory would be changed only during that evaluation period.

fs.chmod(mode, pathname:string):map:void:[follow_link]

Changes the access mode of a file specified by pathname.

There are two formats to specify the mode: one is by a number, and another in a string.

When specified in a number, following bits are associated with access permissions:

  • b8 b7 b6 .. Read, write and executable permissions for owners
  • b5 b4 b3 .. Read, write and executable permissions for groups
  • b2 b1 b0 .. Read, write and executable permissions for others

When set to one, each permission is validated.

When specified in a string, it accepts a permission directive in a format of following regular expression 

[ugoa]+([-+=][rwx]+)+

It starts with characters that represent target which permissions are modified as described below:

  • u .. owners
  • g .. groups
  • o .. others
  • a .. all users

Then, follows an operation:

  • - .. remove
  • + .. append
  • = .. set

At last, permission attributes are specified as below:

  • r .. read permission
  • w .. write permission
  • x .. executable permission

If the modification target is a link file, each platform would have different result:

  • Linux .. Modifies permissions of the link file itself. Specifying :follow_link attribute would modify permsisions of the target file instead.
  • MacOS .. Modifies permissions of the target file. Attribute :follow_link has no effect.
  • Windows .. Modifies permissions of the link file. Attribute :follow_link has no effect.
fs.copy(src:string, dst:string):map:void:[overwrite]

Copies a file.

An argument src needs to specify a path name of a file that is to be copied while dst can specify a path name of either a file or a directory. If dst is a directory, the file would be copied into that. Otherwise, it would create a copy of src that has a name specified by dst.

If a destination file already exists, an error occurs. Specifying an attribute :overwrite would overwrite an existing one.

fs.cpdir(src:string, dst:string):map:void:[tree]

Copies a directory.

Arguments src and dst specify source directory and destination directory respectively. In default, sub directories are not copied.Specifying :tree attribute would copy all the sub directories in the source.

fs.getcwd()
Returns the current working directory.
fs.mkdir(pathname:string):map:void:[tree]

Creates a directory.

If pathname consists of multiple sub directories and some of them still doesn't exist, an error occurs. Specifying :tree attribute would create such directories.

fs.remove(pathname:string):map:void
Removes a file from the file system.
fs.rename(src:string, dst:string):map:void
Renames a file or directory.
fs.rmdir(pathname:string):map:void:[tree]

Removes a directory.

If the directory contains sub directories, an error occurs. Specifying :tree attribute would delete such a directory.

21.3fs.stat Class

An instance of fs.stat class contains information about a file or directory on the file system, which includes its full path name, size, creation time and file attributes. A stream instance has a property named stat that is a fs.stat instance when it comes from a file or directory in a file system. You can also get the instance using fs.stat() function.

21.3.1Constructor

fs.stat(pathname:string) {block?}

21.3.2Property

A fs.stat instance has the following properties:

Property Type R/W Explanation
pathname string R
dirname string R
filename string R
size number R
uid number R
gid number R
atime datetime R
mtime datetime R
ctime datetime R
isdir boolean R
ischr boolean R
isblk boolean R
isreg boolean R
isfifo boolean R
islnk boolean R
issock boolean R