Fs

The Fs module is used to interact with the filesystem of the local machine.

Requires Manatee v2.1 or greater

This version of the Fs module cannot be used with Manatee v2.0 or earlier.

System folders

Provides access to the following system folders. Every one of them ends with a trailing \, so they can be concatenated with a filename directly.

• tmpfolder: A directory for temporarily storing files
• desktop: The user’s windows desktop
• appdata: The user’s roaming application-data folder - i.e. C:\Users\<user name>\AppData\Roaming\. Applications can write user specific data here without requiring administrator privilege
• startup: The folder which contains shortcuts to applications that should start when the user logs in
• personal: The user’s documents folder - i.e. C:\Users\<user name>\Documents\
• home: Manatee’s own directory under the roaming application data - %appdata%\Sirenia\Manatee\. Not the user’s home folder

Example

var folder = Fs.tmpfolder;

List (ls)

Returns a list of files and directories found in the directory given by the path argument. The path may contain wildcards * in its last segment.

A second option argument can be passed with the following properties:

• deepMatch boolean indicating if the listing should include contents of subdirectories. Defaults to false. When this property is set to true, files matching the filename given in the path argument in any sub-folder will be returned.
• includeDirectories boolean indicating if the listing should include directories. Defaults to false. So by default only files are included. Note the wildcard in path is matched against directory names as well, so Fs.ls("c:\\dir\\*.txt", { includeDirectories: true }) adds only directories whose own name ends in .txt. Use * as the last segment to list every directory.

Default behavior is to do a shallow file listing of only the files in the given folder.

Weird behaviour with 3-letter extensions

When you use the asterisk wildcard character in a searchPattern such as *.txt, the number of characters in the specified extension affects the search as follows:

If the specified extension is exactly three characters long, the method returns files with extensions that begin with the specified extension. For example, *.xls returns both “book.xls” and “book.xlsx”. In all other cases, the method returns files that exactly match the specified extension. For example, *.ai returns " file.ai" but not “file.aif”. When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, “file1.txt” and “file1.txtother”, in a directory, a search pattern of file?.txt returns just the first file, whereas a search pattern of file*.txt returns both files.

WARNING

Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to *1*.txt may return unexpected file names. For example, using a search pattern of *1*.txt returns “longfilename.txt” because the equivalent 8.3 file name format is “LONGFI~1.TXT”.

Return value

The resulting array can be used as a string array of the paths to the files. It can also be used as an array of objects with detailed information about the files. Each such object has the following properties:

• path is the full path of the item. Corresponds to the string value of the object.
• name is the name of the item. C:\folder\file.txt has the name file.txt. C:\folder has the name folder.
• extension is the extension of the item. C:\folder\file.txt has the extension .txt.
• isFile / isDir booleans telling the two kinds of entry apart.
• owner is the account that owns the item.
• group is the item’s group.
• created is the time of creation.
• modified is the time of the last modification.
• accessed is the time of the last file access.

File entries have three more that directories do not:

• folder is the folder part of the path. C:\folder\file.txt has the folder path C:\folder.
• readonly boolean value indicating if the file is read only.
• size is the size of the file in bytes.

Files and directories are not the same shape

includeDirectories: true mixes two kinds of object into one array. Reading folder, readonly or size off a directory entry gives undefined, and only directory entries have ls(). Use isDir or isFile to tell them apart before reaching for those.

The objects further have the following methods:

• mv moves the file or directory. Pass the new path as an argument.
• cp copies the file or directory. Pass the new path as an argument, and optionally an options object as the second — the same options Fs.cp takes.
• rm deletes the file or directory, and takes the same options object as Fs.rm — so removing a non-empty directory needs rm({ recursive: true }).
• encrypt encrypts the file.
• decrypt decrypts the file.
• ls — directory entries only — lists that directory, exactly as Fs.ls would.

Example

// Get all .txt files prefixed with somefile in somedir
var files = Fs.ls("c:\\somedir\\somefile*.txt");

// Get all .txt files in any sub directory under C:\somedir - at any depth
var files = Fs.ls("c:\\somedir\\*.txt", { deepMatch: true });

// Copy readonly files to a backup sub directory
var readonlyFiles = files.filter(function (file) {
  return file.readonly;
});
_.each(readonlyFiles, function (file) {
  file.cp(file.folder + "\\backup\\" + file.name);
});

Make a new directory

Create a new directory if it does not already exist.

Fs.mkdir("C:\\some\\path");

Move file/folder

Move a file or folder to a different path.

Fs.mv("C:\\some\\path\\file.txt", "C:\\some\\other\\path\\file.txt");
// or a folder
Fs.mv("C:\\some\\path", "C:\\some\\other\\path");

If you want to allow the target file to be overwritten (if it exists):

Fs.mv("C:\\some\\path\\file.txt", "C:\\some\\other\\path\\file.txt", {
  overwrite: true,
});

Copy file/folder

Copy a file or folder to a different path

Fs.cp("C:\\some\\path\\file.txt", "C:\\some\\other\\path\\file.txt");
// and to allow overwrite of target file
Fs.cp("C:\\some\\path\\file.txt", "C:\\some\\other\\path\\file.txt", {
  overwrite: true,
});

Copying a folder behaves differently from copying a file. If the target folder already exists the copy throws, unless overwrite: true is given — in which case the existing target is deleted first. The copy itself is then a synchronise, so the target ends up matching the source rather than merging with it.

Delete file/folder

Delete a file or folder

Fs.rm("C:\\some\\path\\file.txt");

A folder is only removed if it is empty. To remove a folder along with everything inside it, pass the recursive option:

Fs.rm("C:\\some\\path", { recursive: true });

Without it, deleting a non-empty folder throws.

Check file/folder presence

Determines if a file exists at a given path

Example

if (!Fs.exists("C:\\some\\path\\file.txt")) {
  // Create the file
}

Build a path

Convenience for building a valid file system path to a file or a directory.

Example

var p = Fs.buildPath("C:\\root", "foo", "bar.txt");
// p represents the path C:\root\foo\bar.txt

Encrypt file

Activates windows file encryption for the file at the given path. Only the currently logged in user will be able to read the file.

Example

Fs.encrypt("C:\\some\\path\\file.txt");

Decrypt file

Deactivates windows file encryption for the file at the given path. Any user will be able to read the file.

Example

Fs.decrypt("C:\\some\\path\\file.txt");

Read

Read the contents of a file with the read function.

var html = Fs.read("c:\\somedir\\somefile.html");

Getting base64 encoded data

If you need to read a file as base64 encoded data, you can do so by passing the base64 option:

var base64EncodedData = Fs.read("c:\\somedir\\somefile.html", { base64: true });

Both Fs.read and Fs.write methods can take an encoding option, like:

Fs.write("C:/somewhere/test.txt", "String to write", { encoding: "UTF-16" });
// or for short
Fs.write("C:/somewhere/test.txt", "String to write", { encoding: Fs.UTF16 });
// and
Fs.read("C:/somewhere/test.txt", { encoding: "UTF-16" });
// default if no `encoding` arg is given is UTF-8 no bom

The list of encoding (names) which can be used is found at https://www.iana.org/assignments/character-sets/character-sets.xhtml. Note that not all of these may be available on your machine, to see those, run:

Debug.ger(Fs.encodings);

The following are encodings are defined on Fs;

• Fs.UTF8
• Fs.UTF16
• Fs.ASCII

If you think your file is ANSI or ASCII encoded, but none if these seem to work then you might be looking for the ISO-8859-1 encoding which sometimes does the trick.

Write

Writes arbitrary text to an arbitrary text file. If the file exists, it will be overwritten. If the file doesn’t exist, it will be created with the given contents. The contents are written using UTF-8 encoding without a byte order mark ( BOM).

Throws appropriate exceptions if the write fails.

Parameters

• path the file system path to write to
• data a string with the data to write
• options an optional options object. Supported options are;
  • base64 a boolean. If true, interprets the data argument as a base64 string and writes the data to disk as binary data. Defaults to false
  • writeBom a boolean. If true, a utf-8 byte-order-mark sequence is prepended to the file. This helps other applications detect the encoding of the file. Defaults to false. Is ignored if the base64 option is true. Note it forces UTF-8: setting writeBom overrides any encoding you also pass.
  • encoding The encoding with which to write the file (default is "UTF-8"). Ignored if base64 or writeBom is true.
  • append a boolean. If true, text is appended to the file in the path in question. Is ignored if the base64 option is true.

Example

Fs.write(
  "c:\\somedir\\somefile.html",
  "<html><body><h1>Generated html!</h1></body></html>",
);

Synchronise two directories

If you need to synchronise the files in two directories, i.e. make sure all files in the source directory are copied to the destination directory you can use the Fs.sync(...) method.

Examples

// Make sure the two directories are completely synchronised, delete superfluous files from destination
Fs.sync("C:\\MySourceDirectory", "C:\\MyDestinationDirectory");
// The same but don't delete those files in the destination directory which are not present in the source
Fs.sync("C:\\MySourceDirectory", "C:\\MyDestinationDirectory", {
  deleteSuperfluous: false,
});

Temp file

The tmpfile function will generate a random, non-conflicting filename in the temp folder.

Example

var tmpFilePath = Fs.tmpfile();