files

Stability: 2-Stable

The files module provides some common file processing, including file read and write, move, copy, delete, etc.

One-time file reading and writing can directly use convenient functions such as files.read(), files.write(), files.append(), but if you need to read and write frequently or randomly, use The open() function opens a file object to manipulate the file, and calls the close() function to close the file after the operation is completed.

files.isFile(path)

• path {string} path
• Return {boolean}

Returns whether the path path is a file.

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

files.isDir(path)

• path {string} path
• Return {boolean}

Returns whether the path path is a folder.

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

files.isEmptyDir(path)

• path {string} path
• Return {boolean}

Returns whether the folder path is an empty folder. If the path is not a folder, it will directly return false.

files.join(parent, child)

• parent {string} Parent directory path
• child {string} sub path
• Return {string}

Connect two paths and return, for example, files.join("/sdcard/", "1.txt") returns "/sdcard/1.txt".

files.create(path)

• path {string} path
• Return {boolean}

Create a file or folder and return whether it was created successfully. If the file already exists, it will directly return false.

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

files.createWithDirs(path)

• path {string} path
• Return {boolean}

Create a file or folder and return whether it was created successfully. If the folder where the file is located does not exist, first create a series of folders where it is located. If the file already exists, it will directly return false.

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

files.exists(path)

• path {string} path
• Return {boolean}

Returns whether the file at path path exists.

files.ensureDir(path)

• path {string} path

Make sure that the folder where path is located exists. If the folder where the path is located does not exist, create the folder.

For example, for the path "/sdcard/Download/ABC/1.txt", if the /Download/ folder does not exist, the Download will be created first, and then the ABC folder will be created.

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

• path {string} path
• encoding {string} character encoding, optional, default is utf-8
• Return {string}

Read all the contents of the text file path and return. If the file does not exist, a FileNotFoundException is thrown.

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

files.readBytes(path)

• path {string} path
• Return {byte[]}

Read all the contents of the file path and return a byte array. If the file does not exist, a FileNotFoundException is thrown.

Note that this array is a Java array and does not have JavaScript array forEach, slice and other functions.

An example of printing a file in hexadecimal format is as follows:

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} The text content to be written
• encoding {string} character encoding

Write text to the file path. If the file exists, it will be overwritten, and if it does not exist, it will be created.

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

files.writeBytes(path, bytes)

• path {string} path
• bytes {byte[]} byte array, binary data to be written

Write bytes to the file path. If the file exists, it will be overwritten, and if it does not exist, it will be created.

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

• path {string} path
• text {string} The text content to be written
• encoding {string} character encoding

Append text to the end of the file path. If the file does not exist, create it.

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

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

• path {string} path
• bytes {byte[]} byte array, binary data to be written

Append bytes to the end of the file path. If the file does not exist, create it.

files.copy(fromPath, toPath)

• fromPath {string} The path of the original file to be copied
• toPath {string} The file path to copy to
• Return {boolean}

Copy the file and return whether the copy was successful. For example, files.copy("/sdcard/1.txt", "/sdcard/Download/1.txt").

files.move(fromPath, toPath)

• fromPath {string} The original file path to be moved
• toPath {string} The file path to move to
• Return {boolean}

Move the file and return whether the move was successful. For example, files.move("/sdcard/1.txt", "/sdcard/Download/1.txt") will move the 1.txt file from the root directory of the sd card to the Download folder.

files.rename(path, newName)

• path {string} The original file path to be renamed
• newName {string} The new file name to be renamed
• Return {boolean}

Rename the file and return whether the rename was successful. For example, files.rename("/sdcard/1.txt", "2.txt").

files.renameWithoutExtension(path, newName)

• path {string} The original file path to be renamed
• newName {string} The new file name to be renamed
• Return {boolean}

Rename the file without the extension, and return whether the rename is successful. For example, files.rename("/sdcard/1.txt", "2") will rename "1.txt" to "2.txt".

files.getName(path)

• path {string} path
• Return {string}

Returns the file name of the file. For example, files.getName("/sdcard/1.txt") returns "1.txt".

files.getNameWithoutExtension(path)

• path {string} path
• Return {string}

Returns the file name of the file without extension. For example, files.getName("/sdcard/1.txt") returns "1".

files.getExtension(path)

• path {string} path
• Return {string}

Returns the extension of the file. For example, files.getExtension("/sdcard/1.txt") returns "txt".

files.remove(path)

• path {string} path
• Return {boolean}

Delete a file or empty folder, and return whether the deletion was successful.

files.removeDir(path)

• path {string} path
• path {string} path
• Return {boolean}

Delete the folder. If the folder is not empty, delete all the contents of the folder and then delete the folder, and return whether the deletion is successful.

files.getSdcardPath()

• Return {string}

Return the SD card path. The so-called SD card, that is, external memory.

files.cwd()

• Return {string}

Returns the "current working folder path" of the script. The path refers to, if the script itself is a script file, return the directory where the script file is located; otherwise, return null to obtain other set paths.

For example, for the script file "/sdcard/script/1.js", running files.cwd() returns "/sdcard/script/".

files.path(relativePath)

• relativePath {string} relative path
• Return {string}

Returns the absolute path corresponding to the relative path. For example, files.path("./1.png"), if the script that runs this statement is located in the folder "/sdcard/script/", then "/sdcard/script/1.png" will be returned.

files.listDir(path[, filter])

• path {string} path
• filter {Function} Filter function, optional. Receive a string parameter (file name) and return a boolean value.

Lists an array of the names of the files and folders that meet the conditions under the folder path. If the filter parameter is not added, all files and folders are returned.

List all files and folders in the sdcard directory as:

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

List all js script files in the script directory as:

var dir = "/sdcard/script/";
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, such as "/sdcard/1.txt".
• mode {string} File opening mode, including:
  • "r": Read only text mode. In this mode, only text read operations can be performed on files.
  • "w": Only write text mode. In this mode, only text overwrite operations can be performed on files.
  • "a": Additional text mode. In this mode, the written text will be appended to the end of the file.
  • "rw": Random read and write text mode. In this mode, the written text will be appended to the end of the file. Currently, binary mode and random read/write mode are not supported.
• encoding {string} Character encoding.
• bufferSize {number} The buffer size for file reading and writing.

Open a file. Different file objects are returned according to the open mode. include:

• "r": Return a ReadableTextFile object.
• "w", "a": returns a WritableTextFile object.

For "w" mode, if the file does not exist, one will be created, and the content of the file will be cleared if it already exists; FileNotFoundException will be thrown if files in other modes do not exist.

ReadableTextFile

Readable file object.

ReadableTextFile.read()

Returns a string of all remaining contents of the file.

ReadableTextFile.read(maxCount)

• maxCount {Number} Maximum number of characters read

Read the file and return the string up to maxCount. There is no error even if the remaining content of the file is less than maxCount.

ReadableTextFile.readline()

Read a line and return (not including line breaks).

ReadableTextFile.readlines()

Read all the remaining rows and return an array of strings composed of them in order.

close()

Close the file.

Open a file and close it when it is no longer in use

PWritableTextFile

Writable file object.

PWritableTextFile.write(text)

• text {string} text

Write the text content text to the file.

PWritableTextFile.writeline(line)

• text {string} text

Write the text line to the file and write a newline character.

PWritableTextFile.writelines(lines)

• lines {Array} string array

Write many lines into the file....

PWritableTextFile.flush()

Output the contents of the buffer to a file.

PWritableTextFile.close()

Close the file. At the same time, the contents of the buffer will be output to the file.

After opening a file for writing, it must be closed when it is no longer used, otherwise the file may be lost