discovernamespacenamespace discoverPrograms 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 commandsdiscovernamespacenamespace discoverdiscover.SearchPlatformtypeno test imports ittype SearchPlatform = "windows" | "posix";The rules a search follows: Windows' (;, \, PATHEXT) or POSIX's (:, /, the mode's execute bits).
discover.DiscoverOptionstypeno test imports ittype 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 ittype 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 ittype 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 ittype SkippedProgram = { readonly file: string; readonly why: SkipReason };A file passed over, and why.
discover.Discoveredtypeno test imports ittype 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 itfunction searchPlatform(): SearchPlatformThe platform this process runs on, as the search names it.
discover.pathExtensionsfunctionno test imports itfunction pathExtensions(pathext: string | undefined): readonly string[]The extensions of PATHEXT, upper case, in their order.
discover.skipReasonTextfunctionno test imports itfunction skipReasonText(why: SkipReason): stringA reason as words, for a --verbose line.
discover.discoverProgramsfunctionno test imports itfunction 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 ittype SearchPlatform = "windows" | "posix";The rules a search follows: Windows' (;, \, PATHEXT) or POSIX's (:, /, the mode's execute bits).
DiscoverOptionstypeno test imports ittype 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 ittype 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 ittype 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 ittype SkippedProgram = { readonly file: string; readonly why: SkipReason };A file passed over, and why.
Discoveredtypeno test imports ittype 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 itfunction searchPlatform(): SearchPlatformThe platform this process runs on, as the search names it.
pathExtensionsfunctionfunction pathExtensions(pathext: string | undefined): readonly string[]The extensions of PATHEXT, upper case, in their order.
skipReasonTextfunctionfunction skipReasonText(why: SkipReason): stringA reason as words, for a --verbose line.
discoverProgramsfunctionfunction 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.