README

目录

• 安装
• 简介
• 解析参数
• 匹配参数
• 严格模式

安装

composer require weew/console-arguments

简介

此包允许您轻松构建具有特定预期的命令，然后将其与一组命令行参数进行匹配。它主要由两部分组成，一个 ArgumentsParser 和 ArgumentsMatcher。

注意：此包尚未在Windows上测试。

解析参数

参数解析器允许您解析命令行参数，并处理许多令人烦恼的事情，如引号、等号、组合标志等。解析过程包括两个步骤。第一步是参数的规范化和将参数分割成片段。第二步是分组标志和选项。让我们看看这个例子

$parser = new ArgumentsParser();
// returns ['command:name', 'arg1', 'arg2', '--flag', 'custom "value', '-f', '1+1=2', '-v', '-v', '-v'];
$args = $parser->parse('command:name arg1 arg2 --flag="custom \"value" -f="1+1=2" -vvv');

现在您可以对这些参数进行分组。

// returns ['arguments' => ['command:name', 'arg1', 'arg2'], 'options' => ['--flag' => 1, '-f' => 1, '-v' => 1], '--flag' => ['custom "value'], '-f' => ['1+1=2'], '-v' => []]
$parser->group($args);

根据您正在处理的参数类型，您可能需要分组或未分组的参数来提取所有必要的信息。

如果您的参数以数组形式而不是字符串形式存在，只需简单地做 implode(' ', $args)。注意 $argv 参数。数组中的第一个值是脚本的路径，您需要将其删除 array_unshift($args)。

匹配参数

因此，现在您有了参数。但是，使用纯数组工作，确保某些值被设置等，是非常烦人的。让我们使它变得简单。

$command = new Command('name', 'description');

// create an arguments
$command->argument(ArgumentType::SINGLE, 'argument');

// create an option
$command->option(OptionType::SINGLE_OPTIONAL, '--color', '-c')
    ->setDefaultValue('red')
    ->setDescription('your favorite color');

您也可以这样创建参数和选项。

$argument = new Argument(ArgumentType::SINGLE, 'argument');
$command->addArgument($argument);

$option = new Option(OptionType::SINGLE, '--color', '-c');
$option
    ->setDefaultValue('red')
    ->setDescription('your favorite color');
$command->addOption($option);

有多种参数和选项类型。

// a single argument that must be set
// throws an error otherwise
ArgumentType::SINGLE;

// an optional argument
// no error will be thrown if missing
ArgumentType::SINGLE_OPTIONAL;

// takes a flexible amount of values
// at least one value must be set
// throws an error otherwise
ArgumentType::MULTIPLE;

// takes a flexible amount of values
// wont throw any errors
ArgumentType::MULTIPLE_OPTIONAL;

// a single argument is expected
// throws an error if option or value is missing
// can be used like this:
// -o arg results in -o=arg
OptionType::SINGLE;

// a single argument is expected
// will not throw any errors if option
// or value is missing
// -o results in -o=null
// -o arg results in -o=arg
OptionType::SINGLE_OPTIONAL;

// flexible amount of arguments is expected
// will throw an error if option
// or at least one value is missing
// can be used like this:
// -o arg1 arg2 arg3 results in -o=[arg1, arg2, arg3]
OptionType::MULTIPLE;

// flexible amount of arguments is expected
// will not throw any errors if option or
// value is missing
// can be used like this:
// -o results in -o=[]
// -o arg1 arg2 arg3 results in -o=[arg1, arg2, arg3]
OptionType::MULTIPLE_OPTIONAL;

// expects no value or one of these values:
// true, false, 0 or 1
// defaults to false
// will not throw any errors if missing
// can be used like this:
// -o results in -o=true
// -o=true|false|0|1 results in true or false
OptionType::BOOLEAN;

// expects a numeric value or no value at all
// defaults to 0
// wont throw any errors
// can be used like this:
// -ooo results in -o=3
// -o -oo results in -o=3
// -o=3 results in -o=3
OptionType::INCREMENTAL;

一旦定义了一些命令，您就可以将它们与参数进行匹配。如果命令的预期没有匹配，匹配器将抛出异常。

$args = $parser->parse('command arg1 arg2 --option');
$groupedArgs = $parser->group($args);
$matcher = new ArgumentsMatcher();

$command = $matcher->matchCommand($command, $groupedArgs);

$command->findArgument('arg')->getValue();
$command->findOption('--option')->getValue();

如果您有多个命令，不知道应该使用哪个，可以让匹配器根据命令名称来找到它。参数数组中的第一个值假设是命令名称。命令名称将智能匹配。因此，名为 command 的命令将匹配 command、c 和 com。如果多个命令符合相同的名称，将抛出异常。

list($command, $groupedArgs) = $matcher->matchCommands($commands, $groupedArgs);

您也可以像匹配命令一样匹配选项或参数，只需使用 matchArgument 和 matchOption 方法。

严格模式

默认情况下，参数匹配器以严格模式运行。这意味着如果命令收到了太多的参数或未知选项，将抛出异常。但是，可以禁用此行为。

list($command, $groupedArgs) = $matcher->matchCommands($commands, $groupedArgs, false);