README

一个比 Hack/HHVM 内置的 getopt 更好的命令行参数解析器。

它之所以得名，是因为它解析 CLI opt ions。

安装

您可以使用 Composer 安装此库

$ composer require appertly/cleopatra

• 此项目的 master 分支（版本 0.x）需要 HHVM 3.12，并且没有依赖项。

合规性

此库的版本将符合 语义版本控制。

我们的代码旨在符合 PSR-1、PSR-2 和 PSR-4。如果您发现与标准合规性相关的问题，请提交一个 pull request！

功能

用户可以指定命令行选项，基本上与典型的 shell 习惯一致。

• 短选项
  • 可以将多个短选项组合在一起（例如，-abcdef）
  • 带值的短选项可以用空格或没有空格指定（例如，-d2 或 -d 2）
  • 带可选值的短选项必须不带空格指定（例如，-d2）
  • 不带值的短选项可以与带值的选项组合在一起（例如，-abcd 2）
• 长选项
  • 带值的长期选项可以用等号或空格指定（例如，--foo bar 或 --foo="bar"）
  • 带可选值的长期选项必须用等号指定（例如，--foo 或 --foo="bar"）
• 普通参数
  • 选项可以在常规参数之间以任何顺序指定（例如，command -a value -b argument1 --opt="value" -c argument2 argument3）
    • 这是一个现实世界的示例：aws --profile mine ec2 start-instances --instance-ids i-123456
  • 可以使用双横线将参数与所有选项分开（例如，command -a value -xyz -- argument1 argument2 argument3）
• 自动帮助文档

用法

规范

为了简单起见，我们坚持使用 PHP 自身的 getopt 函数 和 Perl 的 Getopt::Long。

[label][约束][类型]

• 标签包含选项的别名，用管道（|）分隔，例如 l|length
  • 标签只能由字母数字字符和破折号组成（例如，[a-zA-Z0-9\-]）
• 约束规定了如何使用选项
  • 加号（+）表示选项为增量（例如，-vvv）
  • 冒号（:）表示选项需要有值
  • 两个冒号（::）表示选项为非必需的；可以用等号指定值（例如 --option="foo"）
• 类型可以用来指定如何评估参数值
  • s = 字符串，i = 整数，f = 浮点数，d = DateTimeImmutable
  • 尾部带符号（@）将多个参数存储在 Vector 中（例如，-d 1.txt -d 2.txt -d 3.txt）

示例

l|length    = Boolean parameter with no argument (-l or --length)
v|verbose+  = Incremental option; value increased each time used
d|dir:      = Option with required value (-d stuff, --dir stuff)
d|dir::     = Option with optional value (--dir, --dir="stuff")
f|file:@    = Required option with multiple values (-f a.txt -f b.txt -f c.txt)
dir:s       = Required option will be evaluated as a string
dir::i      = Optional option will be evaluated as an integer
dir:f       = Option will be evaluated as a float
dir:d       = Option will be evaluated as a `DateTimeImmutable`
dir:s@      = Multiple options will result in a `Vector<string>`

样本

这里有一个快速示例。

test.hh 的内容

<?hh
require "vendor/autoload.php";

use Cleopatra\Parser;
use Cleopatra\OptionSet;
use Cleopatra\Option;

$optionSet = new OptionSet(
    new Option("help", "Display this help"),
    new Option("version", "Shows version information"),
    new Option("v|verbose+", "Enables verbose output; use multiple times to increase verbosity"),
    new Option("e|exclude:s@", "Excludes files and folders from processing"),
    new Option("nice:i", "Sets the process nice value"),
    new Option("profile:", "Specifies which profile to use"),
    new Option("q|quiet", "Disables all output to stdout"),
    new Option("x|experimental", "Enables experimental features"),
    new Option("log::", "Enables log output; default is syslog, but you can specify a log filename")
);
$parser = new Parser($optionSet);
$cmd = $parser->parse($_SERVER['argv']);
$options = $cmd->getOptions(); // ImmMap<string,mixed>
$arguments = $cmd->getArguments(); // ImmVector<string>
if ($arguments->isEmpty() || $options->containsKey('help')) {
    echo $optionSet->getHelp(), PHP_EOL;
} else {
    echo "You executed: " . $cmd->getProgram(), PHP_EOL;
    echo "With options: " . json_encode($options), PHP_EOL;
    echo "With arguments: " . implode(", ", $arguments), PHP_EOL;
}

您运行

hhvm test.hh -qe foo -e bar --nice 123 run-tests -vvv -v --log=errors.log -v -xebaz src

您得到

You executed: test.hh
With options: {"q":true,"e":["foo","bar","baz"],"nice":123,"v":5,"log":"errors.log","x":true}
With arguments: run-tests, src

您运行

hhvm test.hh --help

您得到

  --help             Display this help
  --version          Shows version information
  -v --verbose       Enables verbose output; use multiple times to increase
                     verbosity
  -e --exclude       Excludes files and folders from processing
  --nice             Sets the process nice value
  --profile          Specifies which profile to use
  -q --quiet         Disables all output to stdout
  -x --experimental  Enables experimental features
  --log              Enables log output; default is syslog, but you can specify
                     a log filename