模块 fs

该模块提供了一个文件系统API,用于处理路径,目录,文件,链接以及输入和输出流的构造。 它遵循 CommonJS Filesystem/A 提议。

Example

// Writes a simple text file
var fs = require('fs');
if (!fs.exists('test.txt')) {
  var textStream = fs.open('test.txt', {
    write: true,
    binary: false
  });
  try {
    textStream.write('Hello World!');
    textStream.flush();
  } finally {
    textStream.close();
  }
  console.log('Wrote test.txt');
} else {
  console.error('test.txt already exists.');
}

Functions

Class Path

Instance Methods


Path ()

Path构造函数。 Path是用于处理路径的可链接速记。


Path.prototype. from (target)

将给定源路径的相对路径返回到此路径。 等同于 fs.Path(fs.relative(source, this)).

Parameters

String target

Path.prototype. join ()

加入这个path的路径列表。


Path.prototype. listPaths ()

返回此路径中所有文件的名称,按词汇顺序排列并包装在Path对象中。


Path.prototype. resolve ()

解决这个path.


Path.prototype. to (target)

将此路径的相对路径返回给定的目标路径。 等同于 fs.Path(fs.relative(this, target)).

Parameters

String target

Path.prototype. toString ()


Path.prototype. valueOf ()

这是一个非标准扩展,不是 CommonJS Filesystem/A 的一部分。


absolute (path)

通过针对当前工作目录解析给定路径绝对路径。

Example

>> fs.absolute('foo/bar/test.txt');
'/Users/username/Desktop/working-directory/foo/bar/test.txt'

Parameters

String path

the path to resolve

Returns

String

the absolute path


base (path, ext)

返回给定路径的基本名称。 这是删除了任何主要目录组件的路径。 如果指定,则还要删除尾随扩展。

Example

>> fs.base('/a/b/c/foosomeext', 'someext');
'foo'

Parameters

String path

the full path

String ext

an optional extension to remove

Returns

String

the basename


canonical (path)

返回给定抽象路径的规范路径。 规范路径既是绝对路径又是内在路径,所有引用给定文件的路径(无论是否存在)都具有相同的相应规范路径。

Parameters

String path

a file path

Returns

String

the canonical path


changeGroup (path, group)

更改指定文件的组。

Parameters

String path
String group

group name string


changeOwner (path, owner)

更改指定文件的所有者。

Parameters

String path
String owner

the user name string


changePermissions (path, permissions)

更改指定文件的权限。

Parameters

String path
Number|String|java.util.Set<PosixFilePermission> permissions

the POSIX permissions


changeWorkingDirectory (path)

Deprecated!
工作目录始终与JVM进程相关。因此,运行时不能更改工作目录。此功能已弃用,可能会在未来版本的RingoJS中删除。

使用 changeWorkingDirectory() 会引发异常并记录错误。

Parameters

String path

the new working directory


copy (from, to)

从一个文件读取数据并使用二进制模式将其写入另一个文件。如果存在,则替换现有文件。

Example

// Copies file from a temporary upload directory into /var/www
fs.copy('/tmp/uploads/fileA.txt', '/var/www/fileA.txt');

Parameters

String from

original file

String to

copy to create


copyTree (from, to)

将文件从源路径复制到目标路径。源路径下面的文件被复制到相对于目标路径的相应位置,到目录的符号链接被复制但不被传入。

Example

Before:
└── foo
    ├── bar
    │   └── example.m4a
    └── baz

// Copy foo
fs.copyTree('./foo', './foo2');

After:
├── foo
│   ├── bar
│   │   └── example.m4a
│   └── baz
└── foo2
    ├── bar
    │   └── example.m4a
    └── baz

Parameters

String from

the original tree

String to

the destination for the copy


directory (path)

返回给定路径的 dirname。这是删除了任何尾随非目录组件的路径。

Example

>> fs.directory('/Users/username/Desktop/example/test.txt');
'/Users/username/Desktop/example'

Parameters

String path

Returns

String

the parent directory path


exists (path)

如果 path 指定的文件存在,则返回true;否则返回false。

Parameters

String path

the file path.


extension (path)

返回给定路径的扩展名。这就是给定路径的基本名称中最后一个点的后面的所有内容,包括最后一个点。如果不存在有效的扩展名,则返回空字符串。

Example

>> fs.extension('test.txt');
'.txt'

Parameters

String path

Returns

String

the file's extension


group (path)

返回给定文件的组名。

Parameters

String path

Returns

String

the group's name, or null if not possible to determine


hardLink (existing, link)

在引用源路径的目标路径上创建一个硬链接。具体实现取决于文件系统和操作系统。

Parameters

String existing

path to an existing file, therefore the target of the link

String link

the link to create pointing to an existing path

Returns

String

the path to the link


isAbsolute (path)

检查给定的路径名​​是否是绝对的。这是一个非标准扩展,不是 CommonJS Filesystem/A 的一部分。

Example

>> fs.isAbsolute('../../');
false
>> fs.isAbsolute('/Users/username/Desktop/example.txt');
true

Parameters

String path

the path to check

Returns

Boolean

true if path is absolute, false if not


isDirectory (path)

如果 path 指定的文件存在并且是一个目录,则返回 true。

Parameters

String path

the file path

Returns

Boolean

whether the file exists and is a directory


isFile (path)

如果 path 指定的文件存在并且是常规文件,则返回 true。

Parameters

String path

the file path

Returns

Boolean

whether the file exists and is a file


isLink (path)

如果目标文件是符号链接,则返回true,否则返回false。

Parameters

String path

the file path

Returns

Boolean

true if the given file exists and is a symbolic link


isReadable (path)

如果path指定的文件存在并且可以打开以供读取,则返回true。

Parameters

String path

the file path

Returns

Boolean

whether the file exists and is readable


isRelative (path)

检查给定的路径名​​是否相对(即不是绝对的)。这是一个非标准扩展,不是 CommonJS Filesystem/A 的一部分。

Parameters

String path

the path to check

Returns

Boolean

true if path is relative, false if not


isWritable (path)

如果 path 指定的文件存在并且可以打开以写入,则返回 true。

Parameters

String path

the file path

Returns

Boolean

whether the file exists and is writable


iterate (path)

返回一个生成目录文件名的 Rhino 特定的生成器。不能保证生成的字符串是以任何特定的顺序。

Example

// Iterates over the current working directory
for (var name in fs.iterate(".")) {
  console.log(name);
}

Parameters

String path

a directory path


join ()

使用本地文件系统的路径分隔符加入路径元素列表。空路径元素(空,未定义和空字符串)将被跳过。所有非字符串路径元素都将被转换为字符串。结果没有标准化,所以 join("..", "foo") 返回 "../foo"

Example

// build path to the config.json file
var fullPath = fs.join(configDir, "config.json");

Returns

String

the joined path


lastModified (path)

返回文件上次修改为Date对象的时间。

Parameters

String path

the file path

Returns

Date

the date the file was last modified


list (path)

返回给定目录中命名文件和目录的字符串数组。不能保证字符串是以任何特定的顺序。

Example

var names = fs.list('/usr/local/');
names.forEach(function(name) {
  var fullPath = fs.join(dir, name);
  if (fs.isFile(fullPath)) {
    // do something with the file
  }
});

Parameters

String path

the directory path

Returns

Array

an array of strings with the files, directories, or symbolic links


listDirectoryTree (path)

如深度优先遍历发现的那样,返回包含给定路径下面(包括)所有目录的数组。目录中的条目按字词顺序排序。不会遍历到目录的符号链接。

Example

// File system tree of the current working directory:
.
└── foo
    └── bar
        └── baz

fs.listDirectoryTree('.');
// returned array:
[ '', 'foo', 'foo/bar', 'foo/bar/baz' ]

Parameters

String path

the path to discover

Returns

Array

array of strings with all directories lexically sorted


listTree (path)

如深度优先遍历所发现的,返回包含给定路径下面(包括)所有路径(文件,目录等)的数组。目录中的条目按字词顺序排序。符号链接到目录被返回,但没有遍历到。

Example

// File system tree of the current working directory:
.
├── foo
│   └── bar
│       └── baz
├── musicfile.m4a
└── test.txt

fs.listTree('.');
// returned array:
['', 'foo', 'foo/bar', 'foo/bar/baz', 'musicfile.m4a', 'test.txt']

Parameters

String path

the path to list

Returns

Array

array of strings with all discovered paths


makeDirectory (path, permissions)

创建一个由 path 指定的单个目录。如果因任何原因无法创建目录,则会引发错误。这包括如果路径的父目录不存在。如果将权限参数传递给此函数,则它将用于创建在创建目录期间应用于给定路径的 Permissions 实例。

Parameters

String path

the file path

Number|String|java.util.Set<PosixFilePermission> permissions

optional the POSIX permissions


makeTree (path)

创建由 path 指定的目录,包括任何缺少的父目录。

Example

Before:
└── foo

fs.makeTree('foo/bar/baz/');

After:
└── foo
   └── bar
      └── baz

Parameters

String path

the path of the tree to create


move (source, target)

将文件从源文件移动到目标文件。如果目标已经存在,则将其替换为源文件。

Example

// Moves file from a temporary upload directory into /var/www
fs.move('/tmp/uploads/fileA.txt', '/var/www/fileA.txt');

Parameters

String source

the source path

String target

the target path

Throws

Error

normal (path)

通过删除'.'来标准化路径尽可能简化'..'组件。

Example

>> fs.normal('../redundant/../foo/./bar.txt');
'../foo/bar.txt'

Parameters

String path

Returns

String

the normalized path


open (path, options)

根据选项参数打开与读取或写入路径对应的文件。返回二进制流或文本流。

options参数可能包含以下属性:

  • read (boolean) 以只读模式打开文件。
  • write (boolean) 从文件开始处以写模式打开文件。
  • append (boolean) 从文件末尾开始以写模式打开文件。
  • binary (boolean) 以二进制模式打开文件。
  • charset (string) 使用给定的编码以文本模式打开文件。默认为 UTF-8。

而不是选项对象,可以提供具有以下模式的字符串:

  • r (string) 相当于只读
  • w (string) 相当于写
  • a (string) 相当于追加
  • b (string) 相当于二进制

所以一个选项对象 {read:true,binary:true} 和模式字符串 'rb' 在功能上是等效的。注意:不支持 CommonJS提出的选项 canonical 和 exclusive。

Example

// Opens a m4a file in binary mode
var m4aStream = fs.open('music.m4a', {
   binary: true,
   read: true
});

// The equivalent call with options as string
var m4aStream = fs.open('music.m4a', 'br');

// Opens a text file
var textStream = fs.open('example.txt', { read: true });

// The equivalent call with options as string
var textStream = fs.open('example.txt', 'r');

Parameters

String path

the file path

Object|String options

options as object properties or as mode string

Returns

Stream|TextStream

a Stream object in binary mode, otherwise a TextStream


openRaw (path, options)

以二进制模式打开与读取或写入路径对应的文件。 options 参数可能包含以下属性:

  • read (boolean) 以只读模式打开文件。 (默认)
  • write (boolean) 从文件开始处以写模式打开文件。
  • append (boolean) 从文件末尾开始以写模式打开文件。

Parameters

String path

the file path

Object options

options

Returns

Stream

See


owner (path)

返回给定文件的所有者的用户名。

Parameters

String path

Returns

String

the username of the owner, or null if not possible to determine


path ()

创建没有new关键字的新Path的简写。


permissions (path)

如果文件系统支持 POSIX,则返回给定路径的 POSIX 文件权限。

Parameters

String path

Returns

PosixFilePermission the POSIX permissions for the given path


read (path, options)

读取与路径相对应的文件的内容。根据 options 参数返回一个 String 或 ByteString 对象。该功能支持与 open() 相同的选项。

Parameters

String path

the file path

Object options

optional options

Returns

String|Binary

the content of the file


readLink (path)

返回给定path的符号链接的直接目标。

Parameters

String path

a file path


relative (source, target)

通过严格遍历('..')来找到两个路径的共同祖先,从而建立链接源与目标的相对路径。如果省略目标,则将路径返回到当前工作目录中的源。

Example

>> fs.relative('foo/bar/', 'foo/baz/');
'../baz/'
>> fs.relative('foo/bar/', 'foo/bar/baz/');
'baz/'

Parameters

String source
String target

Returns

String

the path needed to change from source to target


remove (path)

删除给定路径中的文件。如果路径不是文件或文件的符号链接,则会引发错误。

Parameters

String path

the path of the file to remove.

Throws

Error if path is not a file or could not be removed.

removeDirectory (path)

删除由路径标识的文件或目录。如果路径是目录而不是空的,则会引发错误。

Parameters

String path

the directory path

Throws

如果文件或目录无法删除,则会出错。

removeTree (path)

删除指定路径指向的元素。如果路径指向一个目录,则该目录的所有成员都会递归移除。

Example

// File system tree of the current working directory:
├── foo
│   └── bar
│       └── baz
├── musicfile.m4a
└── test.txt

fs.removeTree('foo');

After:
├── musicfile.m4a
└── test.txt

Parameters

String path

the element to delete recursively


resolve (paths...)

加入一个路径列表,从一个空的位置开始,迭代地“行走”到每个给定的路径。正确地考虑相对路径和绝对路径。

Example

>> fs.resolve('../.././foo/file.txt', 'bar/baz/', 'test.txt');
'../../foo/bar/baz/test.txt'

Parameters

String... paths...

the paths to resolve

Returns

String

the joined path


same (pathA, pathB)

返回两个路径是否通过符号链接或硬链接引用同一存储(文件或目录),以便修改其中一个会修改另一个。

Parameters

String pathA

the first path

String pathB

the second path

Returns

Boolean

true iff the two paths locate the same file


sameFilesystem (pathA, pathB)

返回两个路径是否引用同一文件系统的实体。

Parameters

String pathA

the first path

String pathB

the second path

Returns

Boolean

true if same file system, otherwise false


size (path)

以字节为单位返回文件的大小,如果路径不对应于可访问的路径,或者不是常规文件或链接,则返回异常。

Parameters

String path

the file path

Returns

Number

the file size in bytes

Throws

如果路径不是文件,则会出错

split (path)

将给定路径拆分为路径组件数组。

Example

>> fs.split('/Users/someuser/Desktop/subdir/test.txt');
[ '', 'Users', 'someuser', 'Desktop', 'subdir', 'test.txt' ]

Parameters

String path

Returns

Array

the path components


symbolicLink (existing, link)

在引用源路径的目标路径上创建符号链接。具体实现取决于文件系统和操作系统。

Parameters

String existing

path to an existing file, therefore the target of the link

String link

the link to create pointing to an existing path

Returns

String

the path to the symbolic link


touch (path, mtime)

将给定路径上文件或目录的修改时间设置为指定时间或当前时间。如果没有文件或目录存在,使用默认权限在给定路径创建一个空文件。

Parameters

String path

the file path

Date mtime

optional date


workingDirectory ()

返回当前工作目录的路径名称。

Returns

String

the current working directory


write (path, content, options)

打开,写入,刷新和关闭文件,编写给定的内容。 如果内容是来自二进制模块的 ByteArray 或 ByteString,则隐含二进制模式。

Parameters

String path
ByteArray|ByteString|String content
Object options

See

ByteArray or ByteString for binary data