parseArgs

Since v8.0.75

util/parseArgsモジュールは、コマンドライン形式の引数配列を解析します。 require('util/parseArgs')で読み込んで使用します。

parseArgs()

1つ以上の設定オブジェクトを使って引数配列を解析します。

構文

parseArgs(args, ...configs)

パラメーター

args String[]: 解析する引数配列
...configs Object: 1つ以上のパーサー設定

複数の設定を渡し、その一部にcommandがある場合、パーサーはargs[0]とコマンド名を比較し、一致する設定を選択します。

設定フィールド

フィールド	型	既定値	説明
`command`	String		`args[0]`と照合するサブコマンド名
`options`	Object	`{}`	オプション定義
`strict`	Boolean	`true`	不明なオプションや想定外の位置引数で例外を発生
`allowNegative`	Boolean	`false`	ブール型の長いオプションに`--no-`形式を許可
`tokens`	Boolean	`false`	結果にトークン情報を含める
`allowPositionals`	Boolean	`positionals`に基づいて決定	位置引数を許可するかどうか
`positionals`	Array		位置引数の定義一覧
`usage`	String		`formatHelp()`で使用
`description`	String		`formatHelp()`で使用
`longDescription`	String		複数コマンドのヘルプで使用

オプション定義

config.optionsの各項目のキーは、JavaScriptのプロパティ名です。パーサーは、camelCaseの名前をkebab-caseのCLIフラグに自動変換します。

たとえば、maxRetryCountは--max-retry-countに変換されます。

フィールド	型	説明
`type`	String	`boolean`、`string`、`integer`、`float`のいずれか
`short`	String	`-v`の`v`のような1文字の短いフラグ
`multiple`	Boolean	繰り返し指定した値を配列に格納
`default`	any	解析前に適用する既定値
`description`	String	`formatHelp()`で使用する説明

対応する入力形式：

--output file.txtのような長いオプション
--output=file.txtのような長いオプションへのインライン値
-o file.txtのような短いオプション
-o=file.txtのような短いオプションへのインライン値
-abcのような短いブール型オプションのグループ
オプション終端記号--

位置引数の定義

positionalsには、単純な文字列配列または詳細なオブジェクト配列を指定できます。

簡単な形式：

positionals: ['inputFile', 'outputFile']

詳細な形式：

positionals: [
    { name: 'input-file' },
    { name: 'output-file', optional: true, default: 'stdout' },
    { name: 'files', variadic: true }
]

規則：

可変長の位置引数は、最後に指定する必要があります。
必須の位置引数がない場合は、TypeErrorが発生します。
result.namedPositionalsのキーは、kebab-caseからcamelCaseに変換されます。

戻り値

parseArgs()は、以下のフィールドを持つオブジェクトを返します。

フィールド	型	説明
`values`	Object	解析したオプション値
`positionals`	String[]	順に格納した位置引数の値
`namedPositionals`	Object	`positionals`の設定がある場合に含む
`tokens`	Object[]	`tokens: true`の場合に含む
`command`	String	サブコマンドの設定が一致した場合に含む

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
const parseArgs = require('util/parseArgs');

const result = parseArgs(['-v', '--output', 'file.txt', 'input.sql'], {
    options: {
        verbose: { type: 'boolean', short: 'v' },
        output: { type: 'string' }
    },
    allowPositionals: true,
    positionals: ['input-file']
});

console.println(JSON.stringify(result.values));
console.println(JSON.stringify(result.namedPositionals));

数値の解析

整数にはinteger、小数にはfloatを使用します。

integerは、小数点を含む値を許可しません。
integerとfloatは、どちらもJavaScriptのnumberを返します。

1
2
3
4
5
6
7
8
const parseArgs = require('util/parseArgs');

const result = parseArgs(['--port', '8080', '--ratio', '0.75'], {
    options: {
        port: { type: 'integer' },
        ratio: { type: 'float' }
    }
});

ブール型オプションの否定

allowNegative: trueを指定すると、ブール型の長いオプションに--no-...形式を使用できます。

1
2
3
4
5
6
7
8
9
const parseArgs = require('util/parseArgs');

const result = parseArgs(['--no-color', '--verbose'], {
    options: {
        color: { type: 'boolean' },
        verbose: { type: 'boolean' }
    },
    allowNegative: true
});

サブコマンドの解析

複数の設定を渡すと、最初の引数でコマンド別の設定を選択できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
const parseArgs = require('util/parseArgs');

const commitConfig = {
    command: 'commit',
    options: {
        message: { type: 'string', short: 'm' },
        all: { type: 'boolean', short: 'a' }
    }
};

const pushConfig = {
    command: 'push',
    options: {
        force: { type: 'boolean', short: 'f' }
    },
    allowPositionals: true,
    positionals: ['remote', { name: 'branch', optional: true }]
};

const result = parseArgs(['push', '-f', 'origin', 'main'], commitConfig, pushConfig);
console.println(result.command);
console.println(JSON.stringify(result.namedPositionals));

parseArgs.formatHelp()

parseArgs()と同じ設定構造を受け取り、読みやすいヘルプテキストを生成します。

構文

parseArgs.formatHelp(...configs)

次の両方に対応しています。

単一コマンドのヘルプ出力
コマンドの概要とコマンド別の詳細を含む、複数コマンドのヘルプ出力

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const parseArgs = require('util/parseArgs');

const help = parseArgs.formatHelp({
    usage: 'Usage: myapp [options] <file>',
    options: {
        userName: { type: 'string', short: 'u', description: 'User name', default: 'guest' },
        enableDebug: { type: 'boolean', short: 'd', description: 'Enable debug mode', default: false }
    },
    positionals: [
        { name: 'file', description: 'Input file to process' }
    ]
});

console.println(help);

parseArgs.toKebabCase()

JavaScriptのcamelCaseのオプション名を、CLI用のkebab-case文字列に変換します。

構文

parseArgs.toKebabCase(name)

使用例

1
2
3
const parseArgs = require('util/parseArgs');

console.println(parseArgs.toKebabCase('maxRetryCount'));

動作に関する注意

第1引数は配列である必要があります。それ以外はTypeErrorが発生します。
strictモードでは、不明なオプションと想定外の位置引数に対してTypeErrorが発生します。
multiple: trueは、繰り返し指定した値を配列に格納します。
既定値は、明示的なオプション値の解析前に適用します。

最終更新日 9月 10, 2026

splitFields