IF Commons GitHub

glob

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-formats FR-017

Path globs as regular expressions, on / paths, with the meaning @std/path's globToRegExp gives them (commons 0001-formats FR-017); fs.expandGlob walks a folder with what this gives.

The API, which fs.expandGlob builds on and which stays as it is:

  • globToRegExp(glob, { extended?, globstar?, caseInsensitive? }): the glob as a RegExp anchored at both ends, or why it is refused.
  • matchGlob(glob, path, options?): whether the path matches, or why the glob is refused.
  • isGlob(text): whether the text holds anything a glob gives a meaning to (else it names one path).
  • globRoot(glob): the leading folders (every segment but the last) with no glob character, where a walk starts (. if none).

The syntax, one segment (between /) at a time:

  • * any characters but /; ? one character but / (where @std/path lets ? and [!a] match a /, these do not);
  • ** alone in its segment (with globstar, the default): any number of segments, none included, so src/**\/*.ts matches src/a.ts and src/a/b/c.ts; elsewhere it is *;
  • [abc], [a-z], [!abc] (not one of, nor /), [[:alpha:]] and the other POSIX classes; [^a] is ^ or a, as in @std/path;
  • {a,b} either alternative (always on);
  • with extended (the default): ?(a|b) at most one, *(a|b) any number, +(a|b) at least one, @(a|b) exactly one, !(a|b) none;
  • \ takes the next character as it is.

A segment with an unclosed [, { or (, or ending in \, is taken as it is written. Separators run together (a//b is a/b), a trailing one is optional, and the empty glob matches nothing. A glob that begins with ! not followed by ( is refused: it reads as the negation of a gitignore or a shell, which a regular expression of the path cannot mean.

import { globToRegExp, matchGlob } from "./glob.ts";
matchGlob("src/**\/*.ts", "src/a/b/c.ts"); // { kind: "ok", value: true }
matchGlob("src/**\/*.ts", "srcx/a.ts"); // { kind: "ok", value: false }
globToRegExp("!x"); // { kind: "err", error: { kind: "negated", glob: "!x" } }

Source: commons/formats/src/glob.ts

6 of 14 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

globnamespace
namespace glob
glob.GlobOptionstypeno test imports it
type GlobOptions = {
  readonly extended?: boolean;
  readonly globstar?: boolean;
  readonly caseInsensitive?: boolean;
};

How a glob is read: extended (extglob groups, default true), globstar (** across segments, default true), caseInsensitive.

glob.GlobErrortypeno test imports it
type GlobError = { readonly kind: "negated"; readonly glob: string };

Why a glob is refused: it begins with a ! that negates nothing a path expression can say.

glob.formatGlobErrorfunctionno test imports it
function formatGlobError(e: GlobError): string

A refused glob as one sentence.

glob.globToRegExpfunctionno test imports it
function globToRegExp(glob: string, options?: GlobOptions): Result<RegExp, GlobError>

The glob as a regular expression of a whole / path, as @std/path's globToRegExp makes it (see the module's documentation for the syntax); refused where it begins with a ! that is not an extglob !(...).

glob.matchGlobfunctionno test imports it
function matchGlob(glob: string, path: string, options?: GlobOptions): Result<boolean, GlobError>

Whether the / path matches the glob (see globToRegExp), or why the glob is refused.

glob.isGlobfunctionno test imports it
function isGlob(text: string): boolean

Whether the text holds anything a glob gives a meaning to, not escaped: *, ?, a closed [...] or {...}, an extglob group, or a leading !. Text that is not a glob names one path, which a caller can take as it is.

glob.globRootfunctionno test imports it
function globRoot(glob: string): string

The leading segments of a glob, its last one never among them, in which nothing is a glob, joined by /: the folder a walk for its matches starts from. . where there are none; / for an absolute glob with none. Escapes in these segments are taken off.

GlobOptionstype
type GlobOptions = {
  readonly extended?: boolean;
  readonly globstar?: boolean;
  readonly caseInsensitive?: boolean;
};

How a glob is read: extended (extglob groups, default true), globstar (** across segments, default true), caseInsensitive.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

GlobErrortypeno test imports it
type GlobError = { readonly kind: "negated"; readonly glob: string };

Why a glob is refused: it begins with a ! that negates nothing a path expression can say.

formatGlobErrorfunction
function formatGlobError(e: GlobError): string

A refused glob as one sentence.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

globToRegExpfunction
function globToRegExp(glob: string, options?: GlobOptions): Result<RegExp, GlobError>

The glob as a regular expression of a whole / path, as @std/path's globToRegExp makes it (see the module's documentation for the syntax); refused where it begins with a ! that is not an extglob !(...).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

matchGlobfunction
function matchGlob(glob: string, path: string, options?: GlobOptions): Result<boolean, GlobError>

Whether the / path matches the glob (see globToRegExp), or why the glob is refused.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

isGlobfunction
function isGlob(text: string): boolean

Whether the text holds anything a glob gives a meaning to, not escaped: *, ?, a closed [...] or {...}, an extglob group, or a leading !. Text that is not a glob names one path, which a caller can take as it is.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

globRootfunction
function globRoot(glob: string): string

The leading segments of a glob, its last one never among them, in which nothing is a glob, joined by /: the folder a walk for its matches starts from. . where there are none; / for an absolute glob with none. Escapes in these segments are taken off.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.