Deno/std
1
0
Fork 0
mirror of https://github.com/denoland/std.git synced 2024-11-21 12:40:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(fs): improve documentation (#4788)

Browse Source
This commit is contained in:
Asher Gomez 2024-06-07 15:54:50 +12:00 committed by GitHub
parent 94bb952729
commit 35c240eeed
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
17 changed files with 1162 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_tools/check_docs.ts
View File

@ -43,6 +43,7 @@ const ENTRY_POINTS = [
"../fmt/duration.ts",
"../fmt/printf.ts",
"../front_matter/mod.ts",
"../fs/mod.ts",
"../html/mod.ts",
"../http/mod.ts",
"../internal/mod.ts",

7
fs/_get_file_info_type.ts
View File

@ -6,8 +6,11 @@ export type PathType = "file" | "dir" | "symlink";
/**
* Get a human readable file type string.
*
* @param fileInfo A FileInfo describes a file and is returned by `stat`,
* `lstat`
* @param file File information, as returned by {@linkcode Deno.stat} or
* {@linkcode Deno.lstat}.
*
* @returns The file type as a string, or `undefined` if the file type is
* unknown.
*/
export function getFileInfoType(fileInfo: Deno.FileInfo): PathType | undefined {
return fileInfo.isFile

11
fs/_is_same_path.ts
View File

@ -5,14 +5,17 @@ import { resolve } from "@std/path/resolve";
import { toPathString } from "./_to_path_string.ts";
/**
* Test whether `src` and `dest` resolve to the same location
* @param src src file path
* @param dest dest file path
* Checks if two paths are the same.
*
* @param src Source file path as a string or URL.
* @param dest Destination file path as a string or URL.
*
* @returns `true` if the paths are the same, `false` otherwise.
*/
export function isSamePath(
src: string | URL,
dest: string | URL,
): boolean | void {
): boolean {
src = toPathString(src);
dest = toPathString(dest);

12
fs/_is_subdir.ts
View File

@ -5,10 +5,14 @@ import { SEPARATOR } from "@std/path/constants";
import { toPathString } from "./_to_path_string.ts";
/**
* Test whether or not `dest` is a sub-directory of `src`
* @param src src file path
* @param dest dest file path
* @param sep path separator
* Checks whether `src` is a sub-directory of `dest`.
*
* @param src Source file path as a string or URL.
* @param dest Destination file path as a string or URL.
* @param sep Path separator. Defaults to `\\` for Windows and `/` for other
* platforms.
*
* @returns `true` if `src` is a sub-directory of `dest`, `false` otherwise.
*/
export function isSubdir(
src: string | URL,

7
fs/_to_path_string.ts
View File

@ -4,8 +4,11 @@
import { fromFileUrl } from "@std/path/from-file-url";
/**
* Convert a URL or string to a path
* @param pathUrl A URL or string to be converted
* Convert a URL or string to a path.
*
* @param pathUrl A URL or string to be converted.
*
* @returns The path as a string.
*/
export function toPathString(
pathUrl: string | URL,

40
fs/copy.ts
View File

@ -255,22 +255,24 @@ function copyDirSync(
}
/**
* Asynchronously copy a file or directory. The directory can have contents.
* Like `cp -r`.
* Asynchronously copy a file or directory (along with its contents), like
* {@linkcode https://www.ibm.com/docs/en/aix/7.3?topic=c-cp-command#cp__cp_flagr | cp -r}.
*
* If `src` is a directory it will copy everything inside of this directory,
* not the entire directory itself. If `src` is a file, `dest` cannot be a
* directory.
* Both `src` and `dest` must both be a file or directory.
*
* Requires the `--allow-read` and `--allow-write` flag.
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param src The source file/directory path as a string or URL.
* @param dest The destination file/directory path as a string or URL.
* @param options Options for copying.
*
* @returns A promise that resolves once the copy operation completes.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { copy } from "@std/fs/copy";
*
* await copy("./foo", "./bar");
@ -280,7 +282,7 @@ function copyDirSync(
* overwriting.
*
* @example Overwriting files/directories
* ```ts
* ```ts no-eval
* import { copy } from "@std/fs/copy";
*
* await copy("./foo", "./bar", { overwrite: true });
@ -290,7 +292,7 @@ function copyDirSync(
* any existing files or directories.
*
* @example Preserving timestamps
* ```ts
* ```ts no-eval
* import { copy } from "@std/fs/copy";
*
* await copy("./foo", "./bar", { preserveTimestamps: true });
@ -329,22 +331,24 @@ export async function copy(
}
/**
* Synchronously copy a file or directory. The directory can have contents.
* Like `cp -r`.
* Synchronously copy a file or directory (along with its contents), like
* {@linkcode https://www.ibm.com/docs/en/aix/7.3?topic=c-cp-command#cp__cp_flagr | cp -r}.
*
* If `src` is a directory it will copy everything inside of this directory,
* not the entire directory itself. If `src` is a file, `dest` cannot be a
* directory.
* Both `src` and `dest` must both be a file or directory.
*
* Requires the `--allow-read` and `--allow-write` flag.
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param src The source file/directory path as a string or URL.
* @param dest The destination file/directory path as a string or URL.
* @param options Options for copying.
*
* @returns A void value that returns once the copy operation completes.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { copySync } from "@std/fs/copy";
*
* copySync("./foo", "./bar");
@ -354,7 +358,7 @@ export async function copy(
* overwriting.
*
* @example Overwriting files/directories
* ```ts
* ```ts no-eval
* import { copySync } from "@std/fs/copy";
*
* copySync("./foo", "./bar", { overwrite: true });
@ -364,7 +368,7 @@ export async function copy(
* any existing files or directories.
*
* @example Preserving timestamps
* ```ts
* ```ts no-eval
* import { copySync } from "@std/fs/copy";
*
* copySync("./foo", "./bar", { preserveTimestamps: true });

33
fs/empty_dir.ts
View File

@ -3,17 +3,22 @@ import { join } from "@std/path/join";
import { toPathString } from "./_to_path_string.ts";
/**
* Asynchronously ensures that a directory is empty deletes the directory
* contents it is not empty. If the directory does not exist, it is created.
* The directory itself is not deleted.
* Asynchronously ensures that a directory is empty.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the directory does not exist, it is created. The directory itself is not
* deleted.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param dir The path of the directory to empty, as a string or URL.
*
* @returns A void promise that resolves once the directory is empty.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { emptyDir } from "@std/fs/empty-dir";
*
* await emptyDir("./foo");
@ -41,16 +46,22 @@ export async function emptyDir(dir: string | URL) {
/**
* Synchronously ensures that a directory is empty deletes the directory
* contents it is not empty. If the directory does not exist, it is created.
* The directory itself is not deleted.
* contents it is not empty.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the directory does not exist, it is created. The directory itself is not
* deleted.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param dir The path of the directory to empty, as a string or URL.
*
* @returns A void value that returns once the directory is empty.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { emptyDirSync } from "@std/fs/empty-dir";
*
* emptyDirSync("./foo");

38
fs/ensure_dir.ts
View File

@ -2,16 +2,23 @@
import { getFileInfoType } from "./_get_file_info_type.ts";
/**
* Asynchronously ensures that the directory exists. If the directory structure
* does not exist, it is created. Like `mkdir -p`.
* Asynchronously ensures that the directory exists, like
* {@linkcode https://www.ibm.com/docs/en/aix/7.3?topic=m-mkdir-command#mkdir__row-d3e133766 | mkdir -p}.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the directory already exists, this function does nothing. If the directory
* does not exist, it is created.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param dir The path of the directory to ensure, as a string or URL.
*
* @returns A promise that resolves once the directory exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureDir } from "@std/fs/ensure-dir";
*
* await ensureDir("./bar");
@ -55,19 +62,26 @@ export async function ensureDir(dir: string | URL) {
}
/**
* Synchronously ensures that the directory exists. If the directory structure
* does not exist, it is created. Like `mkdir -p`.
* Synchronously ensures that the directory exists, like
* {@linkcode https://www.ibm.com/docs/en/aix/7.3?topic=m-mkdir-command#mkdir__row-d3e133766 | mkdir -p}.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the directory already exists, this function does nothing. If the directory
* does not exist, it is created.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param dir The path of the directory to ensure, as a string or URL.
*
* @returns A void value that returns once the directory exists.
*
* @example
* ```ts
* import { ensureDir } from "@std/fs/ensure-dir";
* @example Usage
* ```ts no-eval
* import { ensureDirSync } from "@std/fs/ensure-dir";
*
* await ensureDir("./bar");
* ensureDirSync("./bar");
* ```
*/
export function ensureDirSync(dir: string | URL) {

34
fs/ensure_file.ts
View File

@ -5,17 +5,22 @@ import { getFileInfoType } from "./_get_file_info_type.ts";
import { toPathString } from "./_to_path_string.ts";
/**
* Asynchronously ensures that the file exists. If the file that is requested to
* be created is in directories that do not exist, these directories are created.
* If the file already exists, it is not modified.
* Asynchronously ensures that the file exists.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the file already exists, this function does nothing. If the parent
* directories for the file do not exist, they are created.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param filePath The path of the file to ensure, as a string or URL.
*
* @returns A void promise that resolves once the file exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureFile } from "@std/fs/ensure-file";
*
* await ensureFile("./folder/targetFile.dat");
@ -45,17 +50,22 @@ export async function ensureFile(filePath: string | URL): Promise<void> {
}
/**
* Synchronously ensures that the file exists. If the file that is requested to
* be created is in directories that do not exist, these directories are created.
* If the file already exists, it is not modified.
* Synchronously ensures that the file exists.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the file already exists, this function does nothing. If the parent
* directories for the file do not exist, they are created.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param filePath The path of the file to ensure, as a string or URL.
*
* @returns A void value that returns once the file exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureFileSync } from "@std/fs/ensure-file";
*
* ensureFileSync("./folder/targetFile.dat");

30
fs/ensure_link.ts
View File

@ -4,16 +4,23 @@ import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
import { toPathString } from "./_to_path_string.ts";
/**
* Asynchronously ensures that the hard link exists. If the directory structure
* does not exist, it is created.
* Asynchronously ensures that the hard link exists.
*
* If the parent directories for the hard link do not exist, they are created.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param src The source file path as a string or URL. Directory hard links are
* not allowed.
* @param dest The destination link path as a string or URL.
*
* @returns A void promise that resolves once the hard link exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureLink } from "@std/fs/ensure-link";
*
* await ensureLink("./folder/targetFile.dat", "./folder/targetFile.link.dat");
@ -27,16 +34,23 @@ export async function ensureLink(src: string | URL, dest: string | URL) {
}
/**
* Synchronously ensures that the hard link exists. If the directory structure
* does not exist, it is created.
* Synchronously ensures that the hard link exists.
*
* If the parent directories for the hard link do not exist, they are created.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param src The source file path as a string or URL. Directory hard links are
* not allowed.
* @param dest The destination link path as a string or URL.
*
* @returns A void value that returns once the hard link exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureLinkSync } from "@std/fs/ensure-link";
*
* ensureLinkSync("./folder/targetFile.dat", "./folder/targetFile.link.dat");

39
fs/ensure_symlink.ts
View File

@ -17,19 +17,25 @@ function resolveSymlinkTarget(target: string | URL, linkName: string | URL) {
}
/**
* Asynchronously ensures that the link exists, and points to a valid file. If
* the directory structure does not exist, it is created. If the link already
* exists, it is not modified but error is thrown if it is not point to the
* given target.
* Asynchronously ensures that the link exists, and points to a valid file.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the parent directories for the link do not exist, they are created. If the
* link already exists, and it is not modified, this function does nothing. If
* the link already exists, and it does not point to the given target, an error
* is thrown.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param target The source file path as a string or URL.
* @param linkName The destination link path as a string or URL.
*
* @returns A void promise that resolves once the link exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureSymlink } from "@std/fs/ensure-symlink";
*
* await ensureSymlink("./folder/targetFile.dat", "./folder/targetFile.link.dat");
@ -75,19 +81,24 @@ export async function ensureSymlink(
}
/**
* Synchronously ensures that the link exists, and points to a valid file. If
* the directory structure does not exist, it is created. If the link already
* exists, it is not modified but error is thrown if it is not point to the
* given target.
* Synchronously ensures that the link exists, and points to a valid file.
*
* Requires the `--allow-read` and `--allow-write` flag.
* If the parent directories for the link do not exist, they are created. If the
* link already exists, and it is not modified, this function does nothing. If
* the link already exists, and it does not point to the given target, an error
* is thrown.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param target The source file path as a string or URL.
* @param linkName The destination link path as a string or URL.
* @returns A void value that returns once the link exists.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { ensureSymlinkSync } from "@std/fs/ensure-symlink";
*
* ensureSymlinkSync("./folder/targetFile.dat", "./folder/targetFile.link.dat");

14
fs/eol.ts
View File

@ -9,8 +9,8 @@ export const CRLF = "\r\n" as const;
/**
* End-of-line character evaluated for the current platform.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { EOL } from "@std/fs/eol";
*
* EOL; // "\n" on POSIX platforms and "\r\n" on Windows
@ -25,10 +25,11 @@ const regDetect = /(?:\r?\n)/g;
* character is detected, `null` is returned.
*
* @param content The input string to detect EOL characters.
*
* @returns The detected EOL character(s) or `null` if no EOL character is detected.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { detect } from "@std/fs/eol";
*
* detect("deno\r\nis not\r\nnode"); // "\r\n"
@ -52,10 +53,11 @@ export function detect(content: string): typeof EOL | null {
*
* @param content The input string to normalize.
* @param eol The EOL character(s) to normalize the input string to.
*
* @returns The input string normalized to the targeted EOL.
*
* @example
* ```ts
* @example Usage
* ```ts no-eval
* import { LF, format } from "@std/fs/eol";
*
* const CRLFinput = "deno\r\nis not\r\nnode";

50
fs/exists.ts
View File

@ -33,15 +33,22 @@ export interface ExistsOptions {
* file operation directly. This function is not recommended for this use case.
* See the recommended method below.
*
* @see https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use
* @see {@link https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use} for
* more information on the time-of-check to time-of-use bug.
*
* Requires `--allow-read` and `--allow-sys` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param path The path to the file or directory, as a string or URL.
* @param options Additional options for the check.
*
* @returns A promise that resolves with `true` if the path exists, `false`
* otherwise.
*
* @example Recommended method
* ```ts
* ```ts no-eval
* // Notice no use of exists
* try {
* await Deno.remove("./foo", { recursive: true });
@ -54,10 +61,10 @@ export interface ExistsOptions {
* ```
*
* Notice that `exists()` is not used in the above example. Doing so avoids a
* possible race condition. See the above section for details.
* possible race condition. See the above note for details.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { exists } from "@std/fs/exists";
*
* await exists("./exists"); // true
@ -65,7 +72,7 @@ export interface ExistsOptions {
* ```
*
* @example Check if a path is readable
* ```ts
* ```ts no-eval
* import { exists } from "@std/fs/exists";
*
* await exists("./readable", { isReadable: true }); // true
@ -73,7 +80,7 @@ export interface ExistsOptions {
* ```
*
* @example Check if a path is a directory
* ```ts
* ```ts no-eval
* import { exists } from "@std/fs/exists";
*
* await exists("./directory", { isDirectory: true }); // true
@ -81,7 +88,7 @@ export interface ExistsOptions {
* ```
*
* @example Check if a path is a file
* ```ts
* ```ts no-eval
* import { exists } from "@std/fs/exists";
*
* await exists("./file", { isFile: true }); // true
@ -89,7 +96,7 @@ export interface ExistsOptions {
* ```
*
* @example Check if a path is a readable directory
* ```ts
* ```ts no-eval
* import { exists } from "@std/fs/exists";
*
* await exists("./readable_directory", { isReadable: true, isDirectory: true }); // true
@ -97,7 +104,7 @@ export interface ExistsOptions {
* ```
*
* @example Check if a path is a readable file
* ```ts
* ```ts no-eval
* import { exists } from "@std/fs/exists";
*
* await exists("./readable_file", { isReadable: true, isFile: true }); // true
@ -164,14 +171,21 @@ export async function exists(
* file operation directly. This function is not recommended for this use case.
* See the recommended method below.
*
* @see https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use
* @see {@link https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use} for
* more information on the time-of-check to time-of-use bug.
*
* Requires `--allow-read` and `--allow-sys` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param path The path to the file or directory, as a string or URL.
* @param options Additional options for the check.
*
* @returns `true` if the path exists, `false` otherwise.
*
* @example Recommended method
* ```ts
* ```ts no-eval
* // Notice no use of exists
* try {
* Deno.removeSync("./foo", { recursive: true });
@ -184,10 +198,10 @@ export async function exists(
* ```
*
* Notice that `existsSync()` is not used in the above example. Doing so avoids
* a possible race condition. See the above section for details.
* a possible race condition. See the above note for details.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { existsSync } from "@std/fs/exists";
*
* existsSync("./exists"); // true
@ -195,7 +209,7 @@ export async function exists(
* ```
*
* @example Check if a path is readable
* ```ts
* ```ts no-eval
* import { existsSync } from "@std/fs/exists";
*
* existsSync("./readable", { isReadable: true }); // true
@ -203,7 +217,7 @@ export async function exists(
* ```
*
* @example Check if a path is a directory
* ```ts
* ```ts no-eval
* import { existsSync } from "@std/fs/exists";
*
* existsSync("./directory", { isDirectory: true }); // true
@ -211,7 +225,7 @@ export async function exists(
* ```
*
* @example Check if a path is a file
* ```ts
* ```ts no-eval
* import { existsSync } from "@std/fs/exists";
*
* existsSync("./file", { isFile: true }); // true
@ -219,7 +233,7 @@ export async function exists(
* ```
*
* @example Check if a path is a readable directory
* ```ts
* ```ts no-eval
* import { existsSync } from "@std/fs/exists";
*
* existsSync("./readable_directory", { isReadable: true, isDirectory: true }); // true
@ -227,7 +241,7 @@ export async function exists(
* ```
*
* @example Check if a path is a readable file
* ```ts
* ```ts no-eval
* import { existsSync } from "@std/fs/exists";
*
* existsSync("./readable_file", { isReadable: true, isFile: true }); // true

190
fs/expand_glob.ts
View File

@ -80,14 +80,20 @@ function comparePath(a: WalkEntry, b: WalkEntry): number {
/**
* Returns an async iterator that yields each file path matching the given glob
* pattern. The file paths are relative to the provided `root` directory.
* If `root` is not provided, the current working directory is used.
* The `root` directory is not included in the yielded file paths.
* pattern.
*
* Requires the `--allow-read` flag.
* The file paths are absolute paths. If `root` is not provided, the current
* working directory is used. The `root` directory is not included in the
* yielded file paths.
*
* Requires `--allow-read` permission.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param glob The glob pattern to expand.
* @param options Additional options for the expansion.
*
* @returns An async iterator that yields each walk entry matching the glob
* pattern.
*
@ -100,31 +106,163 @@ function comparePath(a: WalkEntry, b: WalkEntry): number {
* └── foo.ts
* ```
*
* ```ts
* ```ts no-eval
* // script.ts
* import { expandGlob } from "@std/fs/expand-glob";
*
* const entries = [];
* for await (const entry of expandGlob("*.ts")) {
* entries.push(entry);
* }
* await Array.fromAsync(expandGlob("*.ts"));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // {
* // path: "/Users/user/folder/foo.ts",
* // name: "foo.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // ]
* ```
*
* entries[0]!.path; // "/Users/user/folder/script.ts"
* entries[0]!.name; // "script.ts"
* entries[0]!.isFile; // false
* entries[0]!.isDirectory; // true
* entries[0]!.isSymlink; // false
* @example Define root directory
*
* entries[1]!.path; // "/Users/user/folder/foo.ts"
* entries[1]!.name; // "foo.ts"
* entries[1]!.isFile; // true
* entries[1]!.isDirectory; // false
* entries[1]!.isSymlink; // false
* Setting the `root` option to `/folder` will expand the glob pattern from the
* `/folder` directory.
*
* File structure:
* ```
* folder
* ├── subdir
* │ └── bar.ts
* ├── script.ts
* └── foo.ts
* ```
*
* ```ts no-eval
* // script.ts
* import { expandGlob } from "@std/fs/expand-glob";
*
* await Array.fromAsync(expandGlob("*.ts", { root: "./subdir" }));
* // [
* // {
* // path: "/Users/user/folder/subdir/bar.ts",
* // name: "bar.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // ]
* ```
*
* @example Exclude files
*
* Setting the `exclude` option to `["foo.ts"]` will exclude the `foo.ts` file
* from the expansion.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo.ts
* ```
*
* ```ts no-eval
* // script.ts
* import { expandGlob } from "@std/fs/expand-glob";
*
* await Array.fromAsync(expandGlob("*.ts", { exclude: ["foo.ts"] }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "true.ts",
* // isFile: false,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // ]
* ```
*
* @example Exclude directories
*
* Setting the `includeDirs` option to `false` will exclude directories from the
* expansion.
*
* File structure:
* ```
* folder
* ├── subdir
* │ └── bar.ts
* ├── script.ts
* └── foo.ts
* ```
*
* ```ts no-eval
* // script.ts
* import { expandGlob } from "@std/fs/expand-glob";
*
* await Array.fromAsync(expandGlob("*", { includeDirs: false }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // {
* // path: "/Users/user/folder/foo.ts",
* // name: "foo.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // ]
* ```
*
* @example Follow symbolic links
*
* Setting the `followSymlinks` option to `true` will follow symbolic links.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── link.ts -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* // script.ts
* import { expandGlob } from "@std/fs/expand-glob";
*
* await Array.fromAsync(expandGlob("*.ts", { followSymlinks: true }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false,
* // },
* // {
* // path: "/Users/user/folder/symlink",
* // name: "symlink",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: true,
* // },
* // ]
* ```
*/
export async function* expandGlob(
glob: string | URL,
{
options: ExpandGlobOptions = {},
): AsyncIterableIterator<WalkEntry> {
let {
root,
exclude = [],
includeDirs = true,
@ -133,8 +271,8 @@ export async function* expandGlob(
caseInsensitive,
followSymlinks,
canonicalize,
}: ExpandGlobOptions = {},
): AsyncIterableIterator<WalkEntry> {
} = options;
const {
segments,
isAbsolute: isGlobAbsolute,
@ -247,11 +385,15 @@ export async function* expandGlob(
*
* Requires the `--allow-read` flag.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param glob The glob pattern to expand.
* @param options Additional options for the expansion.
*
* @returns An iterator that yields each walk entry matching the glob pattern.
*
* @example Basic usage
* @example Usage
*
* File structure:
* ```
@ -260,7 +402,7 @@ export async function* expandGlob(
* └── foo.ts
* ```
*
* ```ts
* ```ts no-eval
* // script.ts
* import { expandGlobSync } from "@std/fs/expand-glob";
*

5
fs/mod.ts
View File

@ -3,12 +3,15 @@
/**
* Helpers for working with the filesystem.
*
* ```ts
* ```ts no-eval
* import { ensureFile, copy, ensureDir, move } from "@std/fs";
*
* await ensureFile("example.txt");
*
* await copy("example.txt", "example_copy.txt");
*
* await ensureDir("subdir");
*
* await move("example_copy.txt", "subdir/example_copy.txt");
* ```
*

61
fs/move.ts
View File

@ -5,11 +5,36 @@ import { isSamePath } from "./_is_same_path.ts";
const EXISTS_ERROR = new Deno.errors.AlreadyExists("dest already exists.");
/**
* Error thrown in {@linkcode move} or {@linkcode moveSync} when the
* destination is a subdirectory of the source.
* Error thrown in {@linkcode move} or {@linkcode moveSync} when the destination
* is a subdirectory of the source.
*
* @example Usage
* ```ts no-eval
* import { move, SubdirectoryMoveError } from "@std/fs/move";
*
* try {
* await move("./foo", "./foo/bar");
* } catch (error) {
* if (error instanceof SubdirectoryMoveError) {
* console.error(error.message);
* }
* }
* ```
*/
export class SubdirectoryMoveError extends Error {
/** Constructs a new instance. */
/**
* Constructs a new instance.
*
* @param src The source file or directory as a string or URL.
* @param dest The destination file or directory as a string or URL.
*
* @example Usage
* ```ts no-eval
* import { SubdirectoryMoveError } from "@std/fs/move";
*
* throw new SubdirectoryMoveError("./foo", "./foo/bar");
* ```
*/
constructor(src: string | URL, dest: string | URL) {
super(
`Cannot move '${src}' to a subdirectory of itself, '${dest}'.`,
@ -29,15 +54,24 @@ export interface MoveOptions {
}
/**
* Asynchronously moves a file or directory.
* Asynchronously moves a file or directory (along with its contents).
*
* If `src` is a sub-directory of `dest`, a {@linkcode SubdirectoryMoveError}
* will be thrown.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param src The source file or directory as a string or URL.
* @param dest The destination file or directory as a string or URL.
* @param options Options for the move operation.
*
* @returns A void promise that resolves once the operation completes.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { move } from "@std/fs/move";
*
* await move("./foo", "./bar");
@ -47,7 +81,7 @@ export interface MoveOptions {
* overwriting.
*
* @example Overwriting
* ```ts
* ```ts no-eval
* import { move } from "@std/fs/move";
*
* await move("./foo", "./bar", { overwrite: true });
@ -92,15 +126,24 @@ export async function move(
}
/**
* Synchronously moves a file or directory.
* Synchronously moves a file or directory (along with its contents).
*
* If `src` is a sub-directory of `dest`, a {@linkcode SubdirectoryMoveError}
* will be thrown.
*
* Requires `--allow-read` and `--allow-write` permissions.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param src The source file or directory as a string or URL.
* @param dest The destination file or directory as a string or URL.
* @param options Options for the move operation.
*
* @returns A void value that returns once the operation completes.
*
* @example Basic usage
* ```ts
* ```ts no-eval
* import { moveSync } from "@std/fs/move";
*
* moveSync("./foo", "./bar");
@ -110,7 +153,7 @@ export async function move(
* overwriting.
*
* @example Overwriting
* ```ts
* ```ts no-eval
* import { moveSync } from "@std/fs/move";
*
* moveSync("./foo", "./bar", { overwrite: true });

758
fs/walk.ts
View File

@ -11,12 +11,53 @@ import {
type WalkEntry,
} from "./_create_walk_entry.ts";
/** Error thrown in {@linkcode walk} or {@linkcode walkSync} during iteration. */
/**
* Error thrown in {@linkcode walk} or {@linkcode walkSync} during iteration.
*
* @example Usage
* ```ts no-eval
* import { walk, WalkError } from "@std/fs/walk";
*
* try {
* for await (const entry of walk("./non_existent_root")) {
* console.log(entry.path);
* }
* } catch (error) {
* if (error instanceof WalkError) {
* console.error(error.message);
* }
* }
* ```
*/
export class WalkError extends Error {
/** File path of the root that's being walked. */
/**
* File path of the root that's being walked.
*
* @example Usage
* ```ts
* import { WalkError } from "@std/fs/walk";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const error = new WalkError("error message", "./foo");
*
* assertEquals(error.root, "./foo");
* ```
*/
root: string;
/** Constructs a new instance. */
/**
* Constructs a new instance.
*
* @param cause The cause of the error.
* @param root The root directory that's being walked.
*
* @example Usage
* ```ts no-eval
* import { WalkError } from "@std/fs/walk";
*
* throw new WalkError("error message", "./foo");
* ```
*/
constructor(cause: unknown, root: string) {
super(
`${cause instanceof Error ? cause.message : cause} for path "${root}"`,
@ -121,9 +162,18 @@ export type { WalkEntry };
* Recursively walks through a directory and yields information about each file
* and directory encountered.
*
* The file paths are absolute paths. The root directory is included in the
* yielded entries.
*
* Requires `--allow-read` permission.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param root The root directory to start the walk from, as a string or URL.
* @param options The options for the walk.
* @returns An async iterable iterator that yields `WalkEntry` objects.
*
* @returns An async iterable iterator that yields the walk entry objects.
*
* @example Basic usage
*
@ -134,30 +184,339 @@ export type { WalkEntry };
* └── foo.ts
* ```
*
* ```ts
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* const entries = [];
* for await (const entry of walk(".")) {
* entries.push(entry);
* }
* await Array.fromAsync(walk("."));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/foo.ts",
* // name: "foo.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* entries[0]!.path; // "folder"
* entries[0]!.name; // "folder"
* entries[0]!.isFile; // false
* entries[0]!.isDirectory; // true
* entries[0]!.isSymlink; // false
* @example Maximum file depth
*
* entries[1]!.path; // "folder/script.ts"
* entries[1]!.name; // "script.ts"
* entries[1]!.isFile; // true
* entries[1]!.isDirectory; // false
* entries[1]!.isSymlink; // false
* Setting the `maxDepth` option to `1` will only include the root directory and
* its immediate children.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo
* └── bar.ts
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { maxDepth: 1 }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/foo",
* // name: "foo",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Exclude files
*
* Setting the `includeFiles` option to `false` will exclude files.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { includeFiles: false }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/foo",
* // name: "foo",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false,
* // },
* // ]
* ```
*
* @example Exclude directories
*
* Setting the `includeDirs` option to `false` will exclude directories.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { includeDirs: false }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Exclude symbolic links
*
* Setting the `includeSymlinks` option to `false` will exclude symbolic links.
*
* File structure:
* ```
* folder
* ├── script.ts
* ├── foo
* └── link -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { includeSymlinks: false }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Follow symbolic links
*
* Setting the `followSymlinks` option to `true` will follow symbolic links,
* affecting the `path` property of the walk entry.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── link -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { followSymlinks: true }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "link",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: true
* // },
* // ]
* ```
*
* @example Canonicalize symbolic links
*
* Setting the `canonicalize` option to `false` will canonicalize the path of
* the followed symbolic link. Meaning, the `path` property of the walk entry
* will be the path of the symbolic link itself.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── link -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { followSymlinks: true, canonicalize: true }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/link",
* // name: "link",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: true
* // },
* // ]
* ```
*
* @example Filter by file extensions
*
* Setting the `exts` option to `[".ts"]` will only include entries with the
* `.ts` file extension.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo.js
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { exts: [".ts"] }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Filter by regular expressions
*
* Setting the `match` option to `[/.s/]` will only include entries with the
* letter `s` in their name.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── README.md
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { match: [/s/] }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Exclude by regular expressions
*
* Setting the `skip` option to `[/.s/]` will exclude entries with the letter
* `s` in their name.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── README.md
* ```
*
* ```ts no-eval
* import { walk } from "@std/fs/walk";
*
* await Array.fromAsync(walk(".", { skip: [/s/] }));
* // [
* // {
* // path: "/Users/user/folder/README.md",
* // name: "README.md",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*/
export async function* walk(
root: string | URL,
{
options: WalkOptions = {},
): AsyncIterableIterator<WalkEntry> {
const {
maxDepth = Infinity,
includeFiles = true,
includeDirs = true,
@ -167,8 +526,8 @@ export async function* walk(
exts = undefined,
match = undefined,
skip = undefined,
}: WalkOptions = {},
): AsyncIterableIterator<WalkEntry> {
} = options;
if (maxDepth < 0) {
return;
}
@ -222,7 +581,360 @@ export async function* walk(
}
}
/** Same as {@linkcode walk} but uses synchronous ops */
/**
* Recursively walks through a directory and yields information about each file
* and directory encountered.
*
* The file paths are absolute paths. The root directory is included in the
* yielded entries.
*
* Requires `--allow-read` permission.
*
* @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
* for more information on Deno's permissions system.
*
* @param root The root directory to start the walk from, as a string or URL.
* @param options The options for the walk.
*
* @returns A synchronous iterable iterator that yields the walk entry objects.
*
* @example Basic usage
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo.ts
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync("."));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/foo.ts",
* // name: "foo.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Maximum file depth
*
* Setting the `maxDepth` option to `1` will only include the root directory and
* its immediate children.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo
* └── bar.ts
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { maxDepth: 1 }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/foo",
* // name: "foo",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Exclude files
*
* Setting the `includeFiles` option to `false` will exclude files.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { includeFiles: false }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/foo",
* // name: "foo",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false,
* // },
* // ]
* ```
*
* @example Exclude directories
*
* Setting the `includeDirs` option to `false` will exclude directories.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { includeDirs: false }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Exclude symbolic links
*
* Setting the `includeSymlinks` option to `false` will exclude symbolic links.
*
* File structure:
* ```
* folder
* ├── script.ts
* ├── foo
* └── link -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { includeSymlinks: false }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Follow symbolic links
*
* Setting the `followSymlinks` option to `true` will follow symbolic links,
* affecting the `path` property of the walk entry.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── link -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { followSymlinks: true }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "link",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: true
* // },
* // ]
* ```
*
* @example Canonicalize symbolic links
*
* Setting the `canonicalize` option to `false` will canonicalize the path of
* the followed symbolic link. Meaning, the `path` property of the walk entry
* will be the path of the symbolic link itself.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── link -> script.ts (symbolic link)
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { followSymlinks: true, canonicalize: true }));
* // [
* // {
* // path: "/Users/user/folder",
* // name: "folder",
* // isFile: false,
* // isDirectory: true,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // {
* // path: "/Users/user/folder/link",
* // name: "link",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: true
* // },
* // ]
* ```
*
* @example Filter by file extensions
*
* Setting the `exts` option to `[".ts"]` will only include entries with the
* `.ts` file extension.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── foo.js
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { exts: [".ts"] }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Filter by regular expressions
*
* Setting the `match` option to `[/.s/]` will only include entries with the
* letter `s` in their name.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── README.md
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { match: [/s/] }));
* // [
* // {
* // path: "/Users/user/folder/script.ts",
* // name: "script.ts",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*
* @example Exclude by regular expressions
*
* Setting the `skip` option to `[/.s/]` will exclude entries with the letter
* `s` in their name.
*
* File structure:
* ```
* folder
* ├── script.ts
* └── README.md
* ```
*
* ```ts no-eval
* import { walkSync } from "@std/fs/walk";
*
* Array.from(walkSync(".", { skip: [/s/] }));
* // [
* // {
* // path: "/Users/user/folder/README.md",
* // name: "README.md",
* // isFile: true,
* // isDirectory: false,
* // isSymlink: false
* // },
* // ]
* ```
*/
export function* walkSync(
root: string | URL,
{