/**
 * 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.)
 *
 * @module file
 * @since 3.2.0
 */
/// <reference types="node" />
import type { FSModule } from "browserfs/dist/node/core/FS";
/** @internal */
export declare const HANDSHAKE_FILENAME = "VpHndshk";
/** @internal */
export declare const JS_EVAL_FILENAME = "VpJSEval";
/** @internal */
export declare const JS_RETURN_VALUE_FILENAME = "VpJSRtrn";
/** @internal */
export declare const JS_RETURN_VALUE_TYPE_FILENAME = "VpJSType";
/**
 * The directory root for the extended filesystem which has more space (IndexedDB)
 * and uses asynchronous access.
 */
export declare const ASYNC_FS_ROOT = "/extended/";
/**
 *  The directory where Inform reads author-provided files (not saves or transcripts).
 */
export declare const INFORM_PATH: string;
/**
 *  The directory Vorple uses for its own files for communication between the interpreter and the game file.
 */
export declare const VORPLE_PATH: string;
/**
 * Save file directory in the extended filesystem.
 */
export declare const SAVEFILE_PATH: string;
/**
 * Transcripts directory in the extended filesystem.
 */
export declare const TRANSCRIPT_PATH: string;
/**
 * The directory for temporary files. The temporary directory is emptied after leaving the page.
 */
export declare const TMP_PATH = "/tmp";
export interface FileCopyOptions {
    /**
     * The directory where the operation takes place. Applies to both source and target parameters.
     *
     * @default "/inform"
     */
    cwd?: string;
    /**
     * If true, any existing file of the same name will be replaced. If false, the operation will not continue if the file already exists.
     *
     * @default true
     */
    replace?: boolean;
}
/**
 * Copies a file to another location or name in the filesystem.
 *
 * @param source  File to copy
 * @param target  Target directory or the new name
 * @param options  An optional options object.
 * @returns Returns true on success, false otherwise.
 */
export declare function copy(source: string, target: string, options?: FileCopyOptions): boolean;
export interface FileExistsOptions {
    /**
     * The root directory where to look for the file.
     *
     * @default "/inform"
     */
    cwd?: string;
}
/**
 * Does a file or directory exist in the virtual filesystem?
 *
 * @param filename  File or directory name to check
 * @param options  An optional options object
 * @returns Returns true if the file/directory exists, false otherwise.
 */
export declare function exists(filename: string, options?: FileExistsOptions): boolean;
/**
 * Show a modal asking the user to provide a filename.
 *
 * @param callback  The function to call with the filename as the parameter
 *   after the user has selected the filename, or null if action was canceled
 * @param filepath  The root path of the file
 */
export declare function filePrompt(callback: (filename: string | null) => void, filepath?: string): void;
/**
 * Returns the BrowserFS object for direct access to the BrowserFS API.
 *
 * @see http://jvilk.com/browserfs/1.4.1/
 * @returns Returns the FS object or null if the filesystem hasn't been initialized yet.
 */
export declare function getFS(): FSModule | null;
/**
 * 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
 * @param fullPath  Path to the file. Must be a full path, not relative.
 */
export declare function inAsyncFS(fullPath: string): boolean;
export interface I7FileHeader {
    /**
     * Project name in the header.
     */
    project: string;
    /**
     * File's ready status.
     */
    ready: boolean;
}
export interface FileInfo {
    /**
     * Contents of the text file, or files inside the directory.
     */
    contents: string | string[];
    /**
     * Parent directory.
     */
    directory: string;
    /**
     * Inform 7 header, or null if doesn't exist/apply.
     */
    header: I7FileHeader | null;
    /**
     * Base filename or directory name.
     */
    name: string;
    /**
     * True if it's a directory, false if it's a normal file.
     */
    isDirectory: boolean;
    /**
     * Full path to the file.
     */
    path: string;
}
export interface FileInfoOptions {
    /**
     * The root directory where to look for the file.
     *
     * @default "/inform"
     */
    cwd?: string;
}
/**
 * Returns an object with information about a file or directory.
 *
 * @param filename  File or directory
 * @param options  An optional options object
 * @returns Returns the FileInfo information object, or null if the file or directory doesn't exist.
 */
export declare function info(filename: string, options?: FileInfoOptions): FileInfo | null;
/**
 * Creates a header for Inform 7 files. If the story is made with Inform 6, this method returns an empty string.
 *
 * @param project  Project's name
 * @param filename  Filename, path is automatically removed
 * @param ready  If true, the file is marked "ready" for Inform 7
 * @returns Returns the Inform 7 header or an empty string for Inform 6.
 */
export declare function informHeader(project: string, filename: string, ready?: boolean): string;
/**
 * 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 Returns a promise that resolves to the filesystem object.
 */
export declare function init(): Promise<FSModule>;
export interface FileReadyOptions {
    /**
     * The root directory of the file.
     *
     * @default "/inform"
     */
    cwd?: string;
}
/**
 * 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.
 *
 * @param filename  Path to the file
 * @param options  An optional options object
 * @returns Returns true if file is ready, false on error or not ready.
 *
 * This method always returns false on Inform 6.
 */
export declare function isReady(filename: string, options?: FileReadyOptions): 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.
 *
 * @param filename  Path to the file
 * @param ready  If true, marks the file ready. Otherwise marks the file not ready.
 * @param options  An optional options object
 * @returns 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.
 */
export declare function markReady(filename: string, ready?: boolean, options?: FileReadyOptions): 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.
 *
 * @param dirname  The directory to create
 * @param options  An optional options object
 * @returns Returns true if a directory was created, false otherwise.
 */
export declare function mkdir(dirname: string, options?: DirectoryOptions): boolean;
export interface MoveFileOptions {
    /**
     * The directory where the operation takes place. Applies to both source and target parameters.
     *
     * @default "/inform"
     */
    cwd?: string;
    /**
     * 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.)
     *
     * @default true
     */
    replace?: boolean;
}
/**
 * Moves a file or directory to another directory.
 * If the target doesn't exist, the file or directory is renamed.
 *
 * @param source  File/directory to move
 * @param target  Target directory or the new name
 * @param options  An optional options object
 * @returns Returns true on success, false otherwise.
 */
export declare function move(source: string, target: string, options?: MoveFileOptions): boolean;
/**
 * 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
 * ```
 *
 * @param filename  Name of the file
 * @param path  Path where the file is appended
 * @returns Returns the full path.
 */
export declare function path(filename: any, path?: string): string;
export interface ReadFileOptions {
    /**
     * Is the file to be read a binary file.
     *
     * @default false
     */
    binary?: boolean;
    /**
     * The root directory where to look for the file.
     *
     * @default "/inform"
     */
    cwd?: string;
    /**
     * If true, return value contains the Inform 7 header if present.
     * Otherwise the header is not included in the return value.
     *
     * @default false
     */
    header?: boolean;
}
/**
 * Read a text file from the virtual filesystem
 *
 * @param filename  The file to read
 * @param options  An optional options object
 * @returns Returns the contents of the file, or null file could not be read.
 */
export declare function read(filename: string, options?: ReadFileOptions): string | null;
export interface DirectoryOptions {
    /**
     * The root directory of the file.
     *
     * @default "/inform"
     */
    cwd?: string;
}
/**
 * Reads the contents of a directory.
 *
 * @param dirname  Name of the directory
 * @param options  An optional options object
 * @returns 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.
 */
export declare function readdir(dirname: string, options?: DirectoryOptions): string[] | null;
/**
 * 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.
 *
 * @param url  URL to the resource
 * @returns Returns the URL or a data URL.
 * @since 3.2.2
 */
export declare function resourceUrl(url: string): string;
/**
 * Remove a directory from the virtual filesystem. Directory must be empty.
 *
 * @param dirname
 * @param options  An optional options object
 * @returns Returns true if a directory was removed, false otherwise.
 */
export declare function rmdir(dirname: string, options?: DirectoryOptions): boolean;
/**
 * Ask the user to choose a save file to restore.
 *
 * @param gameid The IFID of the game
 * @param callback The function to call with the filename as the parameter
 *   after the user has selected the filename, or null if action was canceled
 * @internal
 */
export declare function restoreFilePrompt(gameid: string, callback: (filename: string | null) => void): Promise<void>;
/**
 * Ask the user to provide a filename for saving the transcript.
 *
 * @param gameid  The IFID of the game
 * @param callback  The function to call with the filename as the parameter
 *   after the user has selected the filename, or null if action was canceled
 * @internal
 */
export declare function saveFilePrompt(gameid: string, callback: (filename: string | null) => void): void;
/**
 * Ask the user to provide a filename for saving the transcript.
 *
 * @param callback  The function to call with the filename as the parameter
 *   after the user has selected the filename, or null if action was canceled
 * @internal
 */
export declare function transcriptFilePrompt(callback: (filename: string | null) => void): void;
export interface UnlinkOptions {
    /**
     * The root directory of the file.
     *
     * @default "/inform"
     */
    cwd?: string;
}
/**
 * Unlink (i.e. delete) a file from the virtual filesystem.
 * Use [[rmdir]] to remove directories.
 *
 * @param filename  File to unlink
 * @param options  An optional options object
 * @returns Returns true if the file was removed, false otherwise.
 */
export declare function unlink(filename: string, options?: UnlinkOptions): boolean;
export interface WriteFileOptions {
    /**
     * If true, contents are appended to the file, otherwise the file is overwritten with the new content.
     *
     * @default false
     */
    append?: boolean;
    /**
     * If true, writes a binary file instead of a text file.
     *
     * @default false
     */
    binary?: boolean;
    /**
     * The directory where the operation takes place.
     *
     * @default "/inform"
     */
    cwd?: string;
    /**
     * If true, an Inform 7 header is added to the start of the file. On Inform 6 this option does nothing.
     *
     * @default true
     */
    header?: boolean;
    /**
     * The project name that's used in the Inform 7 header. Does nothing on Inform 6 or if the [[header]] option is not set.
     *
     * @default "VORPLE"
     */
    project?: string;
    /**
     * 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 the [[header]] option is not set.
     *
     * @default true
     */
    ready?: boolean;
}
/**
 * Write a file to the virtual filesystem.
 *
 * @param filename  Filename/path to write
 * @param contents Contents of what to write to the file, either a string or a byte array
 * @param options  An optional options object
 * @returns Returns true on success, false otherwise.
 */
export declare function write(filename: string, contents: string | Uint8Array | Buffer, options?: WriteFileOptions): boolean;