files

老猫10/22/22About 4 min

Stability: 2 - Stable

The files module provides common file operations such as read/write, move, copy, delete, and more.
The files module provides common file operations including reading/writing, moving, copying, deleting, and more.

For one-off reads/writes you can use helpers like files.read(), files.write(), and files.append(). If you need frequent or random access, use open() to get a file handle, and call close() when done.

files.isFile(path)

path {string} Path
Returns {boolean}

Returns whether path is a file.

log(files.isDir("/sdcard/folder/")); // false
log(files.isDir("/sdcard/file.txt")); // true

files.isDir(path)

path {string} Path
Returns {boolean}

Returns whether path is a directory.

log(files.isDir("/sdcard/folder/")); // true
log(files.isDir("/sdcard/file.txt")); // false

files.isEmptyDir(path)

path {string} Path
Returns {boolean}

Returns whether directory path is empty. If the path is not a directory, returns false.

files.join(parent, child)

parent {string} Parent directory path
child {string} Child path
Returns {string}

Joins two path parts and returns the result. For example, files.join("/sdcard/", "1.txt") returns "/sdcard/1.txt".

files.create(path)

path {string} Path
Returns {boolean}

Creates a file or directory and returns whether creation succeeded. If it already exists, returns false.

files.create("/sdcard/new-folder/");

files.createWithDirs(path)

path {string} Path
Returns {boolean}

Creates a file or directory and returns whether creation succeeded. If parent directories do not exist, they will be created. If the path already exists, returns false.

files.createWithDirs("/sdcard/new-folder/new-folder/new-folder/1.txt");

files.exists(path)

path {string} Path
Returns {boolean}

Returns whether the file/directory at path exists.

files.ensureDir(path)

path {string} Path

Ensures the parent directory for path exists. If not, it will be created.

For example, for "/sdcard/Download/ABC/1.txt", if /Download/ does not exist, it will create Download first, then ABC.

files.read(path[, encoding = "utf-8"])

path {string} Path
encoding {string} Optional character encoding, default utf-8
Returns {string}

Reads the entire text file at path and returns it. If the file does not exist, throws FileNotFoundException.

log(files.read("/sdcard/1.txt"));

files.readBytes(path)

path {string} Path
Returns {byte[]}

Reads the entire file at path and returns a byte array. If the file does not exist, throws FileNotFoundException.

Note: the returned array is a Java array, so it does not have JavaScript array methods like forEach or slice.

Example: print a file in hexadecimal:

var data = files.readBytes("/sdcard/1.png");
var sb = new java.lang.StringBuilder();
for(var i = 0; i < data.length; i++){
    sb.append(data[i].toString(16));
}
log(sb.toString());

files.write(path, text[, encoding = "utf-8"])

path {string} Path
text {string} Text content to write
encoding {string} Character encoding

Writes text to file path. Overwrites if the file exists; creates it if it does not.

var text = "File content";
// Write file
files.write("/sdcard/1.txt", text);
// View file with another app
app.viewFile("/sdcard/1.txt");

files.writeBytes(path, bytes)

path {string} Path
bytes {byte[]} Byte array to write

Writes bytes to file path. Overwrites if the file exists; creates it if it does not.

files.append(path, text[, encoding = 'utf-8'])

path {string} Path
text {string} Text content to append
encoding {string} Character encoding

Appends text to the end of file path. Creates the file if it does not exist.

var text = "Appended content";
files.append("/sdcard/1.txt", text);
files.append("/sdcard/1.txt", text);
// View file with another app
app.viewFile("/sdcard/1.txt");

files.appendBytes(path, text[, encoding = 'utf-8'])

path {string} Path
bytes {byte[]} Byte array to append

Appends bytes to the end of file path. Creates the file if it does not exist.

files.copy(fromPath, toPath)

fromPath {string} Source file path
toPath {string} Destination file path
Returns {boolean}

Copies a file and returns whether the copy succeeded. Example: files.copy("/sdcard/1.txt", "/sdcard/Download/1.txt").

files.move(fromPath, toPath)

fromPath {string} Source file path
toPath {string} Destination file path
Returns {boolean}

Moves a file and returns whether the move succeeded. For example, files.move("/sdcard/1.txt", "/sdcard/Download/1.txt") moves 1.txt from the SD card root into the Download folder.

files.rename(path, newName)

path {string} Original file path
newName {string} New file name
Returns {boolean}

Renames a file and returns whether it succeeded. Example: files.rename("/sdcard/1.txt", "2.txt").

files.renameWithoutExtension(path, newName)

path {string} Original file path
newName {string} New file name
Returns {boolean}

Renames a file without specifying an extension. Returns whether it succeeded. Example: files.renameWithoutExtension("/sdcard/1.txt", "2") renames "1.txt" to "2.txt".

files.getName(path)

path {string} Path
Returns {string}

Returns the file name. Example: files.getName("/sdcard/1.txt") returns "1.txt".

files.getNameWithoutExtension(path)

path {string} Path
Returns {string}

Returns the file name without extension. Example: files.getNameWithoutExtension("/sdcard/1.txt") returns "1".

files.getExtension(path)

path {string} Path
Returns {string}

Returns the file extension. Example: files.getExtension("/sdcard/1.txt") returns "txt".

files.remove(path)

path {string} Path
Returns {boolean}

Deletes a file or an empty directory, and returns whether deletion succeeded.

files.removeDir(path)

path {string} Path
Returns {boolean}

Deletes a directory. If it is not empty, all contents will be deleted first. Returns whether everything was deleted successfully.

files.getSdcardPath()

Returns {string}

Returns the SD card path (i.e. external storage path).

files.cwd()

Returns {string}

Returns the script’s current working directory. If the script is a file, it returns the directory containing that file; otherwise it may return null depending on runtime context.

For example, for "/sdcard/scripts/1.js", files.cwd() returns "/sdcard/scripts/".

files.path(relativePath)

relativePath {string} Relative path
Returns {string}

Returns an absolute path for the given relative path. For example, if the script is under "/sdcard/scripts/", then files.path("./1.png") returns "/sdcard/scripts/1.png".

files.listDir(path[, filter])

path {string} Path
filter {Function} Optional filter function. Receives a string (file name) and returns a boolean.

Lists names of files and directories under path. If filter is provided, only returns items that match.

List everything under /sdcard/:

var arr = files.listDir("/sdcard/");
log(arr);

List all .js files under the script directory:

var dir = "/sdcard/scripts/";
var jsFiles = files.listDir(dir, function(name){
    return name.endsWith(".js") && files.isFile(files.join(dir, name));
});
log(jsFiles);

open(path[, mode = "r", encoding = "utf-8", bufferSize = 8192])

path {string} File path, e.g. "/sdcard/1.txt".
mode {string} Open mode, including:
- "r": read-only text mode. Only text read operations are allowed.
- "w": write-only text mode. Overwrites the file with text content.
- "a": append text mode. Appends written text to the end of the file.
- "rw": random read/write text mode. Currently it appends written text to the end of the file.
  Binary mode and true random-access mode are not supported at the moment.
encoding {string} Character encoding.
bufferSize {number} Read/write buffer size.

Opens a file and returns a file object depending on the mode:

"r": returns a ReadableTextFile.
"w" / "a": returns a WritableTextFile.

For "w" mode, the file will be created if it does not exist, and truncated if it already exists.
For other modes, if the file does not exist, it throws FileNotFoundException.