args-tokens/lib/parser-C6MbpZjd.d.ts

parseArgs tokens compatibility and more high-performance parser

//#region src/parser.d.ts
/**
 * Entry point of argument parser.
 *
 * @module
 */
/**
 * forked from `nodejs/node` (`pkgjs/parseargs`)
 * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
 * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
 *
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
/**
 * Argument token Kind.
 *
 * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
 * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
 * - `positional`: positional token
 */
type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
/**
 * Argument token.
 */
interface ArgToken {
  /**
   * Argument token kind.
   */
  kind: ArgTokenKind;
  /**
   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
   */
  index: number;
  /**
   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
   */
  name?: string;
  /**
   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
   */
  rawName?: string;
  /**
   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
   */
  value?: string;
  /**
   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
   */
  inlineValue?: boolean;
}
/**
 * Parser Options.
 */
interface ParserOptions {
  /**
   * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode.
   *
   * @default false
   */
  allowCompatible?: boolean;
}
/**
 * Parse command line arguments.
 *
 * @param args - command line arguments
 * @param options - parse options, about details see {@link ParserOptions}
 * @returns Argument tokens.
 *
 * @example
 * ```js
 * import { parseArgs } from 'args-tokens' // for Node.js and Bun
 * // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
 *
 * const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
 * // do something with using tokens
 * // ...
 * console.log('tokens:', tokens)
 * ```
 */
declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
/**
 * Check if `arg` is a short option (e.g. `-f`).
 *
 * @param arg - An argument to check
 * @returns Whether `arg` is a short option.
 */
declare function isShortOption(arg: string): boolean;
/**
 * Check if `arg` is a long option prefix (e.g. `--`).
 *
 * @param arg - An argument to check
 * @returns Whether `arg` is a long option prefix.
 */
declare function hasLongOptionPrefix(arg: string): boolean;
//#endregion
export { ArgToken, ParserOptions, hasLongOptionPrefix, isShortOption, parseArgs };