@abdfnx/hac_k 中文文档教程

Question

来自 @abdfnx

CLI app messenger & helper

Features

• Parses arguments
• Negates flags when using the --no- prefix
• Outputs version when --version
• Outputs description and supplied help text when --help
• Sets the process title to the binary name defined in package.json

Install

$ npm i @abdfnx/hac_k

Usage

$ ./foo-app.js xbox --xbox

CommonJS

#!/usr/bin/env node
"use strict";
const hac_k = require("hac_k");
const foo = require(".");

const cli = hac_k(
    `
    Usage
      $ foo <input>

    Options
      --xbox, -x  Include a xbox

    Examples
      $ foo consoles --xbox
      consoles ????
`,
    {
        flags: {
            xbox: {
                type: "boolean",
                alias: "x",
            },
        },
    }
);
/*
{
    input: ['consoles'],
    flags: {xbox: true},
    ...
}
*/

foo(cli.input[0], cli.flags);

ES Modules

#!/usr/bin/env node
import { createRequire } from "module";
import foo from "./lib/index.js";

const hac_k = createRequire(import.meta.url)("hac_k");

const cli = hac_k(
    `
    Usage
      $ foo <input>

    Options
      --xbox, -x  Include a xbox

    Examples
      $ foo consoles --xbox
      consoles ????
`,
    {
        flags: {
            xbox: {
                type: "boolean",
                alias: "x",
            },
        },
    }
);
/*
{
    input: ['consoles'],
    flags: {xbox: true},
    ...
}
*/

foo(cli.input[0], cli.flags);

API

hac_k(helpText, options?)

hac_k(options)

返回一个 object

• input (Array) - Non-flag arguments
• flags (Object) - Flags converted to camelCase excluding aliases
• unnormalizedFlags (Object) - Flags converted to camelCase including aliases
• pkg (Object) - The package.json object
• help (string) - The help text used with --help
• showHelp([exitCode=2]) (Function) - Show the help text and exit with exitCode
• showVersion() (Function) - Show the version text and exit

helpText

类型：string

help 的快捷方式> 选项。

options

类型：object

flags

类型：object

定义参数标志。

键是标志名称，值是具有以下任何一项的对象：

• type: Type of value. (Possible values: string boolean number)
• alias: Usually used to define a short flag alias.
• default: Default value when the flag is not specified.
• isRequired: Determine if the flag is required. (Default: false)
• If it's only known at runtime whether the flag is required or not, you can pass a Function instead of a boolean, which based on the given flags and other non-flag arguments, should decide if the flag is required. Two arguments are passed to the function:
• The first argument is the flags object, which contains the flags converted to camel-case excluding aliases.
• The second argument is the input string array, which contains the non-flag arguments.
• The function should return a boolean, true if the flag is required, otherwise false.

示例：

flags: {
    xbox_ninja_cat: {
        type: 'string',
        alias: 'xnc',
        default: ['xbox', 'ninja_cat'],
        isMultiple: true,
        isRequired: (flags, input) => {
            if (flags.otherFlag) {
                return true;
            }

            return false;
        }
    }
}

警告：为 booleanDefault 显式指定 undefined 与省略键本身具有不同的含义。

示例：

const hac_k = require("hac_k");

const cli = hac_k(
    `
    Usage
      $ foo

    Options
      --xbox, -x  Include xbox
      --ninja_cat, -nc  Include a ninja_cat

    Examples
      $ foo
      consoles ????
`,
    {
        booleanDefault: undefined,
        flags: {
            xbox: {
                type: "boolean",
                default: true,
                alias: "x",
            },
            ninja_cat: {
                type: "boolean",
                default: false,
                alias: "nc",
            },
            football: {
                type: "boolean",
                alias: "f",
            },
        },
    }
);
/*
{
    flags: {
        xbox: true,
        ninja_cat: true,
        footbal: true
    },
    unnormalizedFlags: {
        xbox: true,
        x: true,
        ninja_cat: true,
        nc: true,
        f: true
    },
    …
}
*/

Promises

hac_k 将做出未处理的拒绝承诺 硬性失败 而不是默认的静默失败。 这意味着您不必在 CLI 中手动使用 .catch() promises。

---