diff options
Diffstat (limited to 'cli/js/files.ts')
| -rw-r--r-- | cli/js/files.ts | 145 |
1 files changed, 72 insertions, 73 deletions
diff --git a/cli/js/files.ts b/cli/js/files.ts index 54c1f26bf..d66870309 100644 --- a/cli/js/files.ts +++ b/cli/js/files.ts @@ -21,19 +21,23 @@ import { OPS_CACHE } from "./runtime.ts"; let OP_READ = -1; let OP_WRITE = -1; -/** Open a file and return an instance of the `File` object - * synchronously. +/** Synchronously open a file and return an instance of the `File` object. * * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); + * + * Requires `allow-read` and `allow-write` permissions depending on mode. */ -export function openSync(filename: string, capability?: OpenOptions): File; -/** Open a file and return an instance of the `File` object - * synchronously. +export function openSync(filename: string, mode?: OpenOptions): File; + +/** Synchronously open a file and return an instance of the `File` object. * * const file = Deno.openSync("/foo/bar.txt", "r"); + * + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export function openSync(filename: string, mode?: OpenMode): File; +/**@internal*/ export function openSync( filename: string, modeOrOptions: OpenOptions | OpenMode = "r" @@ -52,18 +56,22 @@ export function openSync( return new File(rid); } -/** Open a file and return an instance of the `File` object. +/** Open a file and resolve to an instance of the `File` object. * * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); + * + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export async function open( filename: string, options?: OpenOptions ): Promise<File>; -/** Open a file and return an instance of the `File` object. +/** Open a file and resolves to an instance of `Deno.File`. * * const file = await Deno.open("/foo/bar.txt, "w+"); + * + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export async function open(filename: string, mode?: OpenMode): Promise<File>; @@ -91,32 +99,35 @@ export async function open( } /** Creates a file if none exists or truncates an existing file and returns - * an instance of the `File` object synchronously. + * an instance of `Deno.File`. * * const file = Deno.createSync("/foo/bar.txt"); + * + * Requires `allow-read` and `allow-write` permissions. */ export function createSync(filename: string): File { return openSync(filename, "w+"); } -/** Creates a file if none exists or truncates an existing file and returns - * an instance of the `File` object. +/** Creates a file if none exists or truncates an existing file and resolves to + * an instance of `Deno.File`. * * const file = await Deno.create("/foo/bar.txt"); + * + * Requires `allow-read` and `allow-write` permissions. */ export function create(filename: string): Promise<File> { return open(filename, "w+"); } -/** Read synchronously from a file ID into an array buffer. +/** Synchronously read from a file ID into an array buffer. * - * Return `number | EOF` for the operation. + * Returns `number | EOF` for the operation. * * const file = Deno.openSync("/foo/bar.txt"); * const buf = new Uint8Array(100); * const nread = Deno.readSync(file.rid, buf); * const text = new TextDecoder().decode(buf); - * */ export function readSync(rid: number, p: Uint8Array): number | EOF { if (p.length == 0) { @@ -135,9 +146,9 @@ export function readSync(rid: number, p: Uint8Array): number | EOF { } } -/** Read from a file ID into an array buffer. +/** Read from a resource ID into an array buffer. * - * Resolves with the `number | EOF` for the operation. + * Resolves to the `number | EOF` for the operation. * * const file = await Deno.open("/foo/bar.txt"); * const buf = new Uint8Array(100); @@ -161,9 +172,9 @@ export async function read(rid: number, p: Uint8Array): Promise<number | EOF> { } } -/** Write synchronously to the file ID the contents of the array buffer. +/** Synchronously write to the resource ID the contents of the array buffer. * - * Resolves with the number of bytes written. + * Resolves to the number of bytes written. * * const encoder = new TextEncoder(); * const data = encoder.encode("Hello world\n"); @@ -182,15 +193,14 @@ export function writeSync(rid: number, p: Uint8Array): number { } } -/** Write to the file ID the contents of the array buffer. +/** Write to the resource ID the contents of the array buffer. * - * Resolves with the number of bytes written. + * Resolves to the number of bytes written. * * const encoder = new TextEncoder(); * const data = encoder.encode("Hello world\n"); * const file = await Deno.open("/foo/bar.txt", {create: true, write: true}); * await Deno.write(file.rid, data); - * */ export async function write(rid: number, p: Uint8Array): Promise<number> { if (OP_WRITE < 0) { @@ -204,7 +214,7 @@ export async function write(rid: number, p: Uint8Array): Promise<number> { } } -/** Seek a file ID synchronously to the given offset under mode given by `whence`. +/** Synchronously seek a file ID to the given offset under mode given by `whence`. * * const file = Deno.openSync("/foo/bar.txt"); * Deno.seekSync(file.rid, 0, 0); @@ -226,7 +236,7 @@ export async function seek( await sendAsyncJson("op_seek", { rid, offset, whence }); } -/** Close the file ID. */ +/** Close the given resource ID. */ export function close(rid: number): void { sendSyncJson("op_close", { rid }); } @@ -272,68 +282,57 @@ export class File } } -/** An instance of `File` for stdin. */ +/** An instance of `Deno.File` for `stdin`. */ export const stdin = new File(0); -/** An instance of `File` for stdout. */ +/** An instance of `Deno.File` for `stdout`. */ export const stdout = new File(1); -/** An instance of `File` for stderr. */ +/** An instance of `Deno.File` for `stderr`. */ export const stderr = new File(2); export interface OpenOptions { - /** Sets the option for read access. This option, when true, will indicate that the file should be read-able if opened. */ + /** Sets the option for read access. This option, when `true`, means that the + * file should be read-able if opened. */ read?: boolean; - /** Sets the option for write access. - * This option, when true, will indicate that the file should be write-able if opened. - * If the file already exists, any write calls on it will overwrite its contents, without truncating it. - */ + /** Sets the option for write access. This option, when `true`, means that + * the file should be write-able if opened. If the file already exists, + * any write calls on it will overwrite its contents, by default without + * truncating it. */ write?: boolean; - /** Sets the option for creating a new file. - * This option indicates whether a new file will be created if the file does not yet already exist. - * In order for the file to be created, write or append access must be used. - */ - create?: boolean; - /** Sets the option for truncating a previous file. - * If a file is successfully opened with this option set it will truncate the file to 0 length if it already exists. - * The file must be opened with write access for truncate to work. - */ - truncate?: boolean; - /**Sets the option for the append mode. - * This option, when true, means that writes will append to a file instead of overwriting previous contents. - * Note that setting { write: true, append: true } has the same effect as setting only { append: true }. - */ + /**Sets the option for the append mode. This option, when `true`, means that + * writes will append to a file instead of overwriting previous contents. + * Note that setting `{ write: true, append: true }` has the same effect as + * setting only `{ append: true }`. */ append?: boolean; - /** Sets the option to always create a new file. - * This option indicates whether a new file will be created. No file is allowed to exist at the target location, also no (dangling) symlink. - * If { createNew: true } is set, create and truncate are ignored. - */ + /** Sets the option for truncating a previous file. If a file is + * successfully opened with this option set it will truncate the file to `0` + * length if it already exists. The file must be opened with write access + * for truncate to work. */ + truncate?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path. Requires write or append access to be + * used. */ + create?: boolean; + /** Defaults to `false`. If set to `true`, no file, directory, or symlink is + * allowed to exist at the target location. Requires write or append + * access to be used. When createNew is set to `true`, create and truncate + * are ignored. */ createNew?: boolean; } -export type OpenMode = - /** Read-only. Default. Starts at beginning of file. */ - | "r" - /** Read-write. Start at beginning of file. */ - | "r+" - /** Write-only. Opens and truncates existing file or creates new one for - * writing only. - */ - | "w" - /** Read-write. Opens and truncates existing file or creates new one for - * writing and reading. - */ - | "w+" - /** Write-only. Opens existing file or creates new one. Each write appends - * content to the end of file. - */ - | "a" - /** Read-write. Behaves like "a" and allows to read from file. */ - | "a+" - /** Write-only. Exclusive create - creates new file only if one doesn't exist - * already. - */ - | "x" - /** Read-write. Behaves like `x` and allows to read from file. */ - | "x+"; +/** A set of string literals which specify the open mode of a file. + * + * |Value |Description | + * |------|--------------------------------------------------------------------------------------------------| + * |`"r"` |Read-only. Default. Starts at beginning of file. | + * |`"r+"`|Read-write. Start at beginning of file. | + * |`"w"` |Write-only. Opens and truncates existing file or creates new one for writing only. | + * |`"w+"`|Read-write. Opens and truncates existing file or creates new one for writing and reading. | + * |`"a"` |Write-only. Opens existing file or creates new one. Each write appends content to the end of file.| + * |`"a+"`|Read-write. Behaves like `"a"` and allows to read from file. | + * |`"x"` |Write-only. Exclusive create - creates new file only if one doesn't exist already. | + * |`"x+"`|Read-write. Behaves like `x` and allows reading from file. | + */ +export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+"; /** Check if OpenOptions is set to valid combination of options. * @returns Tuple representing if openMode is valid and error message if it's not |