IF Commons GitHub

discover

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

Programs found by the prefix of their name on a search path, as Git finds git-<word> (commons 0001-system FR-012): each folder of the path in order, the first program of a name winning; a directory, a file that may not be run and a program shadowed by an earlier one of the same name each kept with why it was not taken. On Windows a program is a file whose extension PATHEXT lists, compared without regard to case, and its name is given without that extension.

The search path, the extensions and the platform can be given rather than read from this process, so that Windows' rules are proven on any system; the separator between folders is that platform's (path.win32 or path.posix), and a folder and a name are joined by the running system's rules, since the files are this system's. A folder of the path that cannot be read is passed over, as a shell passes it over.

import { discoverPrograms } from "./discover.ts";
const { found } = await discoverPrograms("git-");
found.map((p) => p.name); // ["lfs", ...]: the words `git` would take as commands

Source: commons/system/src/discover.ts

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

discovernamespace
namespace discover
discover.SearchPlatformtypeno test imports it
type SearchPlatform = "windows" | "posix";

The rules a search follows: Windows' (;, \, PATHEXT) or POSIX's (:, /, the mode's execute bits).

discover.DiscoverOptionstypeno test imports it
type DiscoverOptions = {
  /** The search path, `PATH` by default. */
  readonly path?: string;
  /** The extensions of programs on Windows, `PATHEXT` by default, `.EXE;.CMD;.BAT;.COM` where that is not set. */
  readonly pathext?: string;
  /** The platform whose rules apply, this one's by default. */
  readonly platform?: SearchPlatform;
};

What a search is given; each is read from this process where it is not.

discover.FoundProgramtypeno test imports it
type FoundProgram = { readonly name: string; readonly file: string };

A program found: its name after the prefix (on Windows without its extension) and its file.

discover.SkipReasontypeno test imports it
type SkipReason =
  { readonly kind: "directory" } | { readonly kind: "not-executable" } | { readonly kind: "shadowed"; readonly by: string };

Why a file whose name begins with the prefix was not taken.

discover.SkippedProgramtypeno test imports it
type SkippedProgram = { readonly file: string; readonly why: SkipReason };

A file passed over, and why.

discover.Discoveredtypeno test imports it
type Discovered = { readonly found: readonly FoundProgram[]; readonly skipped: readonly SkippedProgram[] };

What a search found, in the order of the path and then of the names in each folder.

discover.searchPlatformfunctionno test imports it
function searchPlatform(): SearchPlatform

The platform this process runs on, as the search names it.

discover.pathExtensionsfunctionno test imports it
function pathExtensions(pathext: string | undefined): readonly string[]

The extensions of PATHEXT, upper case, in their order.

discover.skipReasonTextfunctionno test imports it
function skipReasonText(why: SkipReason): string

A reason as words, for a --verbose line.

discover.discoverProgramsfunctionno test imports it
function discoverPrograms(prefix: string, options?: DiscoverOptions): Promise<Discovered>

Every program on the search path whose name begins with prefix, and every file of that name passed over.

SearchPlatformtypeno test imports it
type SearchPlatform = "windows" | "posix";

The rules a search follows: Windows' (;, \, PATHEXT) or POSIX's (:, /, the mode's execute bits).

DiscoverOptionstypeno test imports it
type DiscoverOptions = {
  /** The search path, `PATH` by default. */
  readonly path?: string;
  /** The extensions of programs on Windows, `PATHEXT` by default, `.EXE;.CMD;.BAT;.COM` where that is not set. */
  readonly pathext?: string;
  /** The platform whose rules apply, this one's by default. */
  readonly platform?: SearchPlatform;
};

What a search is given; each is read from this process where it is not.

FoundProgramtypeno test imports it
type FoundProgram = { readonly name: string; readonly file: string };

A program found: its name after the prefix (on Windows without its extension) and its file.

SkipReasontypeno test imports it
type SkipReason =
  { readonly kind: "directory" } | { readonly kind: "not-executable" } | { readonly kind: "shadowed"; readonly by: string };

Why a file whose name begins with the prefix was not taken.

SkippedProgramtypeno test imports it
type SkippedProgram = { readonly file: string; readonly why: SkipReason };

A file passed over, and why.

Discoveredtypeno test imports it
type Discovered = { readonly found: readonly FoundProgram[]; readonly skipped: readonly SkippedProgram[] };

What a search found, in the order of the path and then of the names in each folder.

searchPlatformfunctionno test imports it
function searchPlatform(): SearchPlatform

The platform this process runs on, as the search names it.

pathExtensionsfunction
function pathExtensions(pathext: string | undefined): readonly string[]

The extensions of PATHEXT, upper case, in their order.

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

skipReasonTextfunction
function skipReasonText(why: SkipReason): string

A reason as words, for a --verbose line.

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

discoverProgramsfunction
function discoverPrograms(prefix: string, options?: DiscoverOptions): Promise<Discovered>

Every program on the search path whose name begins with prefix, and every file of that name passed over.

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

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