Module: file

This module is the access point to the virtual filesystem. The system uses BrowserFS to handle the virtual filesystem in browser's localstorage. See https://jvilk.com/browserfs/2.0.0-beta/classes/_backend_localstorage_.localstoragefilesystem.html for the full API. The getFS() method can be used to retrieve the filesystem object that can be used to access the BrowserFS API directly. All methods in this module use the synchronous versions of the filesystem methods (readFileSync, writeFileSync etc.)
Since:
  • 3.2.0
Source:

Members

(static, constant) ASYNC_FS_ROOT :string

The directory root for the extended filesystem which has more space (IndexedDB) and uses asynchronous access.
Type:
  • string
Source:

(static, constant) INFORM_PATH :string

The directory where Inform reads author-provided files (not saves or transcripts).
Type:
  • string
Source:

(static, constant) SAVEFILE_PATH :string

Save file directory in the extended filesystem.
Type:
  • string
Source:

(static, constant) TMP_PATH :string

The directory for temporary files. The temporary directory is emptied after leaving the page.
Type:
  • string
Source:

(static, constant) TRANSCRIPT_PATH :string

Transcripts directory in the extended filesystem.
Type:
  • string
Source:

(static, constant) VORPLE_PATH :string

The directory Vorple uses for its own files for communication between the interpreter and the game file.
Type:
  • string
Source:

Methods

(static) copy(source, target, optionsopt) → {boolean}

Copies a file.
Parameters:
Name Type Attributes Default Description
source * File to copy
target * Target directory or the new name
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place. Applies to both source and target parameters.
replace boolean <optional>
true If true, any existing file of the same name will be replaced. If false, the operation will not continue if the file already exists.
Source:
Returns:
True on success, false otherwise
Type
boolean

(static) exists(filename, optionsopt) → {boolean}

Does a file or directory exist in the virtual filesystem?
Parameters:
Name Type Attributes Default Description
filename string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
True if the file/directory exists, false otherwise
Type
boolean

(static) filePrompt(callback, filepathopt)

Show a modal asking the user to provide a filename.
Parameters:
Name Type Attributes Default Description
callback function The function to call with the filename as the parameter after the user has selected the filename, or null if action was canceled
filepath string <optional>
/inform The root path of the file
Source:

(static) getFS() → {object|null}

Returns the BrowserFS object for direct access to the BrowserFS API.
Source:
Returns:
The FS object or null if the filesystem hasn't been initialized yet
Type
object | null

(static) info(filename, optionsopt) → {object|null}

Returns an object with information about a file or directory: ``` { contents: string | Array, // Contents of text file, or files inside the directory directory: string, // Parent directory header: null | { // Inform 7 header, or null if doesn't exist/apply project: string, // Project name in the header ready: boolean // File's ready status }, name: string, // Base filename or directory name isDirectory: boolean, // True if it's a directory, false if it's a normal file path: string // Full path to the file } ``` Returns null if the file or directory doesn't exist.
Parameters:
Name Type Attributes Default Description
filename string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
Type
object | null

(static) informHeader(project, filename, readyopt) → {string}

Creates a header for Inform 7 files. If the story is Inform 6, returns an empty string.
Parameters:
Name Type Attributes Default Description
project string Project's name
filename string Filename, path is automatically removed
ready boolean <optional>
true If true, the file is marked "ready" for Inform 7
Source:
Returns:
Inform 7 header or an empty string for Inform 6
Type
string

(static) init() → {Promise.<object>}

Initialize the filesystem. This gets called automatically when calling vorple.init() but it can be called manually before that to get access to the filesystem earlier. The method returns a promise that resolves into the BrowserJS filesystem object, but after the promise has resolved all vorple.file.* are also available.
Source:
Returns:
A promise that resolves to the filesystem object
Type
Promise.<object>
Example
async function getAccessToFS() {
  const fs = await vorple.file.init();
  
  // fs is now the BrowserFS filesystem object (what you'd get from vorple.file.getFS())
  // also all vorple.file.* methods are now available
  vorple.file.write("info.txt", "Filesystem is now available");
}

(static) isReady(filename, optionsopt) → {boolean}

Check if a file has been marked ready for Inform 7 to read. If the file doesn't exist, it doesn't have a header, or it can't be read, the method returns false. Error conditions must be checked manually if it's important to make a difference between invalid operation and a file that has been marked not ready. This method always returns false on Inform 6.
Parameters:
Name Type Attributes Default Description
filename string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
True if file is ready, false on error or not ready
Type
boolean

(static) markReady(filename, readyopt, optionsopt) → {boolean}

Marks a file ready to read (or not ready to read) for Inform 7. This is equivalent of the phrases "mark (external file) as ready to read" and "mark (external file) as not ready to read" in Inform 7. If the file doesn't have an Inform 7 header the method does nothing and returns false. In Inform 6 this method does nothing and always returns false.
Parameters:
Name Type Attributes Default Description
filename string
ready boolean <optional>
true If true, marks the file ready. Otherwise marks the file not ready.
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
True if operation was successful, false otherwise. Returns true even if no change was made to the file (was already marked ready.)
Type
boolean

(static) mkdir(dirname, optionsopt) → {boolean}

Create a new directory in the virtual filesystem. This does not create missing subdirectories, e.g. mkdir( 'foo/bar' ) won't work if directory 'foo' doesn't exist.
Parameters:
Name Type Attributes Default Description
dirname string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
True if directory was created, false otherwise
Type
boolean

(static) move(source, target, optionsopt) → {boolean}

Moves a file or directory to another directory. If the target doesn't exist, the file or directory is renamed.
Parameters:
Name Type Attributes Default Description
source * File/directory to move
target * Target directory or the new name
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place. Applies to both source and target parameters.
replace boolean <optional>
true If true, any existing file of the same name will be replaced. If false, the operation will not continue if the file already exists. This option is ignored if the source is a directory (a directory will never overwrite a file.)
Source:
Returns:
True on success, false otherwise
Type
boolean

(static) path(filename, path)

Adds a path to a given filename. See https://nodejs.org/api/path.html#path_path_resolve_paths for rules on how path joining works. The default root directory is /inform so `vorple.file.path( "foo.txt", "bar" )` will resolve to `/inform/bar/foo.txt`.
Parameters:
Name Type Description
filename string
path string
Source:
Example
vorple.file.path( "foo.txt" );                   // --> /inform/foo.txt
vorple.file.path( "foo.txt", "bar" );            // --> /inform/bar/foo.txt
vorple.file.path( "foo.txt", "/bar" );           // --> /bar/foo.txt
vorple.file.path( "../foo.txt", "/bar/xyz" );    // --> /bar/foo.txt
vorple.file.path( "foo.txt", "/" );              // --> /foo.txt
vorple.file.path( "/foo.txt", "/bar/xyz" );      // --> /foo.txt

(static) read(filename, optionsopt) → {string|null}

Read a text file from the virtual filesystem
Parameters:
Name Type Attributes Default Description
filename string
options object <optional>
{}
Properties
Name Type Attributes Default Description
binary boolean <optional>
false Is it a binary file?
cwd string <optional>
/inform The directory where the operation takes place
header boolean <optional>
false If true, return value contains the Inform 7 header if present. Otherwise the header is not included in the return value.
Source:
Returns:
The contents of the file, or null file could not be read
Type
string | null

(static) readdir(dirname, optionsopt) → {array|null}

Returns the contents of a directory. Returns null if the directory doesn't exist or the directory is actually a file.
Parameters:
Name Type Attributes Default Description
dirname string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
The list of files in the directory, or null on error
Type
array | null

(static) rmdir(dirname, optionsopt) → {boolean}

Remove a directory from the virtual filesystem. Directory must be empty.
Parameters:
Name Type Attributes Default Description
dirname string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
True if directory was removed, false otherwise
Type
boolean
Unlink (i.e. delete) a file from the virtual filesystem. Use rmdir() to remove directories.
Parameters:
Name Type Attributes Default Description
filename string
options object <optional>
{}
Properties
Name Type Attributes Default Description
cwd string <optional>
/inform The directory where the operation takes place
Source:
Returns:
True if file was removed, false otherwise
Type
boolean

(static) write(filename, contents, optionsopt) → {boolean}

Write a file to the virtual filesystem.
Parameters:
Name Type Attributes Default Description
filename string
contents string | array Contents of what to write to the file, either a string or a byte array
options object <optional>
{}
Properties
Name Type Attributes Default Description
append boolean <optional>
false If true, contents are appended to the file, otherwise the file is overwritten with the new content
binary boolean <optional>
false If true, writes a binary file instead of a text file
cwd string <optional>
/inform The directory where the operation takes place
header boolean <optional>
true If true, an Inform 7 header is added to the start of the file. On Inform 6 this option does nothing.
project string <optional>
VORPLE The project name that's used in the Inform 7 header. Does nothing on Inform 6 or if `options.header` is false.
ready boolean <optional>
true If true, the header gets a "ready" mark (`*`) to signal Inform 7 that the file can be read. Otherwise the header is marked not ready (`-`). Does nothing on Inform 6 or if `options.header` is false.
Source:
Returns:
True on success, false otherwise
Type
boolean