file | vorple

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/1.4.1/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

Variables

Const ASYNC_FS_ROOT

ASYNC_FS_ROOT: "/extended/" = "/extended/"

The directory root for the extended filesystem which has more space (IndexedDB) and uses asynchronous access.

Const HANDSHAKE_FILENAME

HANDSHAKE_FILENAME: "VpHndshk" = "VpHndshk"

internal

Const INFORM_PATH

INFORM_PATH: string = ...

The directory where Inform reads author-provided files (not saves or transcripts).

Const JS_EVAL_FILENAME

JS_EVAL_FILENAME: "VpJSEval" = "VpJSEval"

internal

Const JS_RETURN_VALUE_FILENAME

JS_RETURN_VALUE_FILENAME: "VpJSRtrn" = "VpJSRtrn"

internal

Const JS_RETURN_VALUE_TYPE_FILENAME

JS_RETURN_VALUE_TYPE_FILENAME: "VpJSType" = "VpJSType"

internal

Const SAVEFILE_PATH

SAVEFILE_PATH: string = ...

Save file directory in the extended filesystem.

Const TMP_PATH

TMP_PATH: "/tmp" = "/tmp"

The directory for temporary files. The temporary directory is emptied after leaving the page.

Const TRANSCRIPT_PATH

TRANSCRIPT_PATH: string = ...

Transcripts directory in the extended filesystem.

Const VORPLE_PATH

VORPLE_PATH: string = ...

The directory Vorple uses for its own files for communication between the interpreter and the game file.

Functions

copy

copy(source: string, target: string, options?: FileCopyOptions): boolean

- Defined in vorple/file.ts:111
Copies a file to another location or name in the filesystem.

Parameters
- source: string
  
  File to copy
- target: string
  
  Target directory or the new name
- options: FileCopyOptions = ...
  
  An optional options object.
Returns boolean
Returns true on success, false otherwise.

exists

exists(filename: string, options?: FileExistsOptions): boolean

- Defined in vorple/file.ts:177
Does a file or directory exist in the virtual filesystem?

Parameters
- filename: string
  
  File or directory name to check
- options: FileExistsOptions = ...
  
  An optional options object
Returns boolean
Returns true if the file/directory exists, false otherwise.

filePrompt

filePrompt(callback: ((filename: null | string) => void), filepath?: string): void

- Defined in vorple/file.ts:194
Show a modal asking the user to provide a filename.

Parameters
- callback: ((filename: null | string) => void)
  
  The function to call with the filename as the parameter after the user has selected the filename, or null if action was canceled
  - - (filename: null | string): void
    - Parameters
      - filename: null | string
      Returns void
- filepath: string = INFORM_PATH
  
  The root path of the file
Returns void

getFS

getFS(): FSModule | null

- Defined in vorple/file.ts:295
Returns the BrowserFS object for direct access to the BrowserFS API.

see
http://jvilk.com/browserfs/1.4.1/

Returns FSModule | null
Returns the FS object or null if the filesystem hasn't been initialized yet.

inAsyncFS

inAsyncFS(fullPath: string): boolean

- Defined in vorple/file.ts:308
Check if a file is in a filesystem that requires asynchronous access.

(Asynchronous file access isn't officially supported so this is for internal use only.)

internal
Parameters
- fullPath: string
  
  Path to the file. Must be a full path, not relative.
Returns boolean

info

info(filename: string, options?: FileInfoOptions): FileInfo | null

- Defined in vorple/file.ts:366
Returns an object with information about a file or directory.

Parameters
- filename: string
  
  File or directory
- options: FileInfoOptions = ...
  
  An optional options object
Returns FileInfo | null
Returns the FileInfo information object, or null if the file or directory doesn't exist.

informHeader

informHeader(project: string, filename: string, ready?: boolean): string

- Defined in vorple/file.ts:425
Creates a header for Inform 7 files. If the story is made with Inform 6, this method returns an empty string.

Parameters
- project: string
  
  Project's name
- filename: string
  
  Filename, path is automatically removed
- ready: boolean = true
  
  If true, the file is marked "ready" for Inform 7
Returns string
Returns the Inform 7 header or an empty string for Inform 6.

init

init(): Promise<FSModule>

- Defined in vorple/file.ts:458
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.
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");
}
```
Returns Promise<FSModule>
Returns a promise that resolves to the filesystem object.

isReady

isReady(filename: string, options?: FileReadyOptions): boolean

- Defined in vorple/file.ts:535
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.

Parameters
- filename: string
  
  Path to the file
- options: FileReadyOptions = {}
  
  An optional options object
Returns boolean
Returns true if file is ready, false on error or not ready.

This method always returns false on Inform 6.

markReady

markReady(filename: string, ready?: boolean, options?: FileReadyOptions): boolean

- Defined in vorple/file.ts:580
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
- filename: string
  
  Path to the file
- ready: boolean = true
  
  If true, marks the file ready. Otherwise marks the file not ready.
- options: FileReadyOptions = {}
  
  An optional options object
Returns boolean
Returns true if operation was successful, false otherwise. Returns true even if no change was made to the file (was already marked ready.) Always returns false on Inform 6.

mkdir

mkdir(dirname: string, options?: DirectoryOptions): boolean

- Defined in vorple/file.ts:621
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
- dirname: string
  
  The directory to create
- options: DirectoryOptions = {}
  
  An optional options object
Returns boolean
Returns true if a directory was created, false otherwise.

move

move(source: string, target: string, options?: MoveFileOptions): boolean

- Defined in vorple/file.ts:673
Moves a file or directory to another directory. If the target doesn't exist, the file or directory is renamed.

Parameters
- source: string
  
  File/directory to move
- target: string
  
  Target directory or the new name
- options: MoveFileOptions = {}
  
  An optional options object
Returns boolean
Returns true on success, false otherwise.

path

path(filename: any, path?: string): string

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.

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

Parameters

filename: any

Name of the file
path: string = "."

Path where the file is appended

Returns string

Returns the full path.

read

read(filename: string, options?: ReadFileOptions): string | null

- Defined in vorple/file.ts:783
Read a text file from the virtual filesystem

Parameters
- filename: string
  
  The file to read
- options: ReadFileOptions = {}
  
  An optional options object
Returns string | null
Returns the contents of the file, or null file could not be read.

readdir

readdir(dirname: string, options?: DirectoryOptions): string[] | null

- Defined in vorple/file.ts:835
Reads the contents of a directory.

Parameters
- dirname: string
  
  Name of the directory
- options: DirectoryOptions = {}
  
  An optional options object
Returns string[] | null
Returns the list of files and directories as an array of strings. Returns null if the directory doesn't exist or if trying to read a file.

resourceUrl

resourceUrl(url: string): string

- Defined in vorple/file.ts:859
Get the URL to a resource, which can be a normal URL or a data URL containing the resource itself. This is used to get the resource files from the Borogove editor.

since
3.2.2

Parameters
- url: string
  
  URL to the resource
Returns string
Returns the URL or a data URL.

restoreFilePrompt

restoreFilePrompt(gameid: string, callback: ((filename: null | string) => void)): Promise<void>

- Defined in vorple/file.ts:912
Ask the user to choose a save file to restore.

internal
Parameters
- gameid: string
  
  The IFID of the game
- callback: ((filename: null | string) => void)
  
  The function to call with the filename as the parameter after the user has selected the filename, or null if action was canceled
  - - (filename: null | string): void
    - Parameters
      - filename: null | string
      Returns void
Returns Promise<void>

rmdir

rmdir(dirname: string, options?: DirectoryOptions): boolean

- Defined in vorple/file.ts:888
Remove a directory from the virtual filesystem. Directory must be empty.

Parameters
- dirname: string
- options: DirectoryOptions = {}
  
  An optional options object
Returns boolean
Returns true if a directory was removed, false otherwise.

saveFilePrompt

saveFilePrompt(gameid: string, callback: ((filename: null | string) => void)): void

- Defined in vorple/file.ts:976
Ask the user to provide a filename for saving the transcript.

internal
Parameters
- gameid: string
  
  The IFID of the game
- callback: ((filename: null | string) => void)
  
  The function to call with the filename as the parameter after the user has selected the filename, or null if action was canceled
  - - (filename: null | string): void
    - Parameters
      - filename: null | string
      Returns void
Returns void

transcriptFilePrompt

transcriptFilePrompt(callback: ((filename: null | string) => void)): void

- Defined in vorple/file.ts:988
Ask the user to provide a filename for saving the transcript.

internal
Parameters
- callback: ((filename: null | string) => void)
  
  The function to call with the filename as the parameter after the user has selected the filename, or null if action was canceled
  - - (filename: null | string): void
    - Parameters
      - filename: null | string
      Returns void
Returns void

unlink

unlink(filename: string, options?: UnlinkOptions): boolean

- Defined in vorple/file.ts:1016
Unlink (i.e. delete) a file from the virtual filesystem. Use rmdir to remove directories.

Parameters
- filename: string
  
  File to unlink
- options: UnlinkOptions = {}
  
  An optional options object
Returns boolean
Returns true if the file was removed, false otherwise.

write

write(filename: string, contents: string | Uint8Array | Buffer, options?: WriteFileOptions): boolean

- Defined in vorple/file.ts:1085
Write a file to the virtual filesystem.

Parameters
- filename: string
  
  Filename/path to write
- contents: string | Uint8Array | Buffer
  
  Contents of what to write to the file, either a string or a byte array
- options: WriteFileOptions = {}
  
  An optional options object
Returns boolean
Returns true on success, false otherwise.

Index

Interfaces

Variables

Functions

Variables

Const ASYNC_FS_ROOT

Const HANDSHAKE_FILENAME

Const INFORM_PATH

Const JS_EVAL_FILENAME

Const JS_RETURN_VALUE_FILENAME

Const JS_RETURN_VALUE_TYPE_FILENAME

Const SAVEFILE_PATH

Const TMP_PATH

Const TRANSCRIPT_PATH

Const VORPLE_PATH

Functions

copy

Parameters

source: string

target: string

options: FileCopyOptions = ...

Returns boolean

exists

Parameters

filename: string

options: FileExistsOptions = ...

Returns boolean

filePrompt

Parameters

callback: ((filename: null | string) => void)

Parameters

filename: null | string

Returns void

filepath: string = INFORM_PATH

Returns void

getFS

Returns FSModule | null

inAsyncFS

Parameters

fullPath: string

Returns boolean

info

Parameters

filename: string

options: FileInfoOptions = ...

Returns FileInfo | null

informHeader

Parameters

project: string

filename: string

ready: boolean = true

Returns string

init

Returns Promise<FSModule>

isReady

Parameters

filename: string

options: FileReadyOptions = {}

Returns boolean

markReady

Parameters

filename: string

ready: boolean = true

options: FileReadyOptions = {}

Returns boolean

mkdir

Parameters

dirname: string

options: DirectoryOptions = {}

Returns boolean

move

Parameters

source: string

target: string

options: MoveFileOptions = {}

Returns boolean

path

Parameters

filename: any

path: string = "."