@black-flag/core/dist/src/util.d.ts

A declarative framework for building fluent, deeply hierarchical command line interfaces with yargs

import { $executionContext } from "./constant.js";
import type { Arguments, ExecutionContext, NullArguments, PreExecutionContext } from "./types/program.js";
type StringOrRegExp = string | RegExp;
type Lines = (StringOrRegExp | [name: StringOrRegExp | RegExp, description: string | RegExp])[];
/**
 * Type-guard for {@link PreExecutionContext}.
 */
export declare function isPreExecutionContext(obj: unknown): obj is PreExecutionContext;
/**
 * Type-guard for {@link NullArguments}.
 */
export declare function isNullArguments(obj: unknown): obj is NullArguments;
/**
 * Type-guard for {@link Arguments}.
 */
export declare function isArguments(obj: unknown): obj is Arguments;
/**
 * Type-guard for Node's "ERR_ASSERTION" so-called `SystemError`.
 */
export declare function isAssertionSystemError(error: unknown): error is NodeJS.ErrnoException & {
  generatedMessage: boolean;
  code: 'ERR_ASSERTION';
  actual?: unknown;
  expected?: unknown;
  operator: string;
};
/**
 * Creates an object with a "hidden" `[$executionContext]` property.
 *
 * @internal
 */
export declare function wrapExecutionContext(context: ExecutionContext): {
  [$executionContext]: ExecutionContext;
};
/**
 * Uppercase the first letter of a string.
 */
export declare function capitalize(str: string): string;
/**
 * Accepts an `error` and returns the value of its `.cause` property if (1)
 * `error` extends `Error` and (2) the `.cause` property exists and is not
 * falsy; otherwise, `error` itself is returned. This action is performed
 * recursively (.e.g. `error.cause.cause.cause...`) until a value without a
 * non-falsy `.cause` property is encountered.
 *
 * This function can be used to extract the true cause of a `CliError` and/or
 * nested `Error`s.
 */
export declare function getDeepestErrorCause(error: unknown): unknown;
/**
 * `expectedHelpTextRegExp` is a testing helper function that returns a regular
 * expression capable of matching standard Black Flag help text output with high
 * fidelity. Use this function to easily match the result of calling `--help` on
 * a command or otherwise examining a command's help text output, such as when
 * an error occurs that shows help text.
 *
 * You can pass `false` to `usage`, or `undefined` to
 * `commandGroups`/`optionGroups` to omit that property from the regular
 * expression entirely. You can also pass `true` to `usage`, which will add an
 * expression matching the rest of the line (including the final newline).
 *
 * Any strings given will have any regular expression characters escaped via
 * `RegExp.escape`.
 *
 * Any RegExps given will have their flags (`/.../g`, `/.../i`, etc) and other
 * properties stripped, leaving only their source. The expression returned by
 * this function will similarly use no flags.
 *
 * Newlines will be inserted between sections/groups automatically.
 */
export declare function expectedHelpTextRegExp({
  parentFullName,
  usage,
  commandGroups,
  optionGroups,
  startsWith: start,
  endsWith: end
}: {
  /**
   * The full name of the parent command as a string or regular expression. It
   * will be appended to the beginning of each child command name in
   * `commandGroups`.
   */
  parentFullName?: StringOrRegExp;
  /**
   * Accepts a usage string or regular expression, `false` to skip matching the
   * usage section entirely, or `true` to match at least one character
   * non-greedily.
   *
   * @default true
   */
  usage?: boolean | string | RegExp;
  /**
   * `commandGroups` is an mapping of command groups (e.g. `"Positionals"`,
   * `"Commands"`) to their lines and accepts an array of: strings, regular
   * expressions, or arrays of tuples of the form `[expectedName: string/RegExp,
   * expectedDescription: string/RegExp]`, each matching a line. If a line's
   * description is omitted, an expression matching to the end of the line
   * (including the final newline) will be appended.
   *
   * If `parentFullName` is given, command names will have `parentFullName + '
   * '` prepended to them.
   *
   * If `commandGroups` is undefined, no additional characters will be added to
   * the resulting regular expression.
   *
   * @default undefined
   */
  commandGroups?: Record<string, Lines>;
  /**
   * `optionGroups` is an mapping of option groups (e.g. `"Options"`) to their
   * lines and accepts an array of: strings, regular expressions, or arrays of
   * tuples of the form `[expectedName: string/RegExp, expectedDescription:
   * string/RegExp]`, each matching a line. If a line's description is omitted,
   * an expression matching to the end of the line (including the final newline)
   * will be appended.
   *
   * If `optionGroups` is undefined, no additional characters will be added to
   * the resulting regular expression.
   *
   * @default undefined
   */
  optionGroups?: Record<string, Lines>;
  /**
   * `startsWith` describes the characters that must exist at the very start of
   * the text. This can be used to make an expression that partially matches.
   *
   * Note that the assembled regular expression, before `startsWith` is
   * prepended to it, is trimmed.
   *
   * @default /^/
   */
  startsWith?: StringOrRegExp;
  /**
   * `endsWith` describes the characters that must exist at the very end of the
   * text. This can be used to make an expression that partially matches.
   *
   * Note that the assembled regular expression, before `endsWith` is appended
   * to it, is trimmed.
   *
   * @default /$/
   */
  endsWith?: StringOrRegExp;
}): RegExp;
export {};