サセザキ/ドコプト

Pythonのドコプトのポート

维护者

详情

github.com/sasezaki/docopt.php

主页

源代码

安装: 11

依赖: 0

建议: 0

安全: 0

星级: 0

关注者: 2

分支: 27

1.0.3 2017-03-28 08:43 UTC

Requires

  • php: >=5.3.0
  • hhvm: >=3.3.0

Requires (Dev)

MIT b5074c51ce5a9c52e586f7a86a0107c8eb899935

clidocs

This package is auto-updated.

Last update: 2024-09-06 15:52:43 UTC

README

docopt 创建 漂亮的 命令行界面

https://travis-ci.org/docopt/docopt.php.svg?branch=master

这是Vladimir Keleshevの優れたPythonライブラリ docopt のPHPへの直接翻訳です。コードにはいくつかの非効率でPHP非直感的なアートファクトがありますが、変更を統合するために効率的になるように行われました。

結果として、PHPバージョンでのバグのみが存在する場合を除いて、Pythonバージョンのバグフィックスの直接翻訳ではない場合、プルリクエストは受け入れられません。

このポートはバージョン1.0と指定されています。これはコミット a093f938b7f26564434f3c15a1dcc39e017ad638（ラベル 0.6.2）に基づいています。

これは長い間非常に安定しており、ほとんど変わっていません。Pythonバージョンは時折バグフィックスを受け取りますが、バージョン番号を固定することは価値よりも多くの問題をもたらしました。

いくつかの主要な後方互換性の破壊もあります。0.xのsemverヘルに留まるよりも、BCの破壊が原因でそれ以降大きな番号を自由に増やすことを許可します。

  • PHP APIは少し変更されました。《code>Docopt\docopt()《code>は《code>Docopt::handle()《code>に改名され、オートローダーサポートを修正しました。 issue #3 を参照してください。
  • Docopt.pyも重要なBCの破壊があります。既存のユーザーは、使用法およびオプションセクションに関する以下の情報を読むべきです。詳細については issue 102 を参照してください。

新しいおよび破壊的な変更の詳細については、PHPバージョンに特化していない場合、PythonバージョンのREADME を参照してください。

optparseとargparseがコードに基づいてヘルプメッセージを生成するのは素晴らしいですね？！

まったく違うですね！素晴らしいのは、オプションパーサーがあなた自身が書いた美しいヘルプメッセージに基づいて生成されることです。この方法で、この愚かな再利用可能なパーサーコードを書かなくても、ヘルプメッセージ（あなたが望むように）だけを書くことができます。

ドコプトは、簡単に最も美しいコマンドラインインターフェースを作成します

<?php
$doc = <<<DOC
Naval Fate.

Usage:
  naval_fate.php ship new <name>...
  naval_fate.php ship <name> move <x> <y> [--speed=<kn>]
  naval_fate.php ship shoot <x> <y>
  naval_fate.php mine (set|remove) <x> <y> [--moored | --drifting]
  naval_fate.php (-h | --help)
  naval_fate.php --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

DOC;

require('path/to/src/docopt.php');
$args = Docopt::handle($doc, array('version'=>'Naval Fate 2.0'));
foreach ($args as $k=>$v)
    echo $k.': '.json_encode($v).PHP_EOL;

これを超える！オプションパーサーは、docopt関数に渡されるドキュメントストリングに基づいて生成されます。docoptは、使用パターン（"Usage: ..."）およびオプションの説明（ダッシュ"-"で始まる行）を解析し、プログラムの起動が使用パターンに一致することを確実にします。それに基づいて、オプション、引数およびコマンドを解析します。基本的なアイデアは、良いヘルプメッセージにはパーサーを作成するのに必要なすべての情報があるということです。

インストール

docopt.phpをComposerを使用してインストールします

composer require docopt/docopt

または、docopt.phpファイルをプロジェクトに配置するだけで済みます。これは自己完結型です。githubでソースを取得。

docopt.phpはPHP 5.4およびPHP 5.3でテストされています。

テスト

テストを実行するためのリポジトリを構成します

./dev-setup

次のコマンドを使用してユニットテストを実行できます

php test.php

これにより、Python言語無関係のテストおよびPHPドコプトテストが実行されます。

API

<?php
require('/path/to/src/docopt.php');

// short form, simple API
$args = Docopt::handle($doc);

// short form (5.4 or better)
$args = (new \Docopt\Handler)->handle($sdoc);

// long form, simple API (equivalent to short)
$params = array(
    'argv'=>array_slice($_SERVER['argv'], 1),
    'help'=>true,
    'version'=>null,
    'optionsFirst'=>false,
);
$args = Docopt::handle($doc, $params);

// long form, full API
$handler = new \Docopt\Handler(array(
    'help'=>true,
    'optionsFirst'=>false,
));
$handler->handle($doc, $argv);

Docopt::handle()は1つの必須引数と1つのオプション引数を受け取ります

  • doc 是一个包含 帮助信息 的字符串，该信息将被解析以创建选项解析器。接下来几节将给出如何编写此类帮助信息的简单规则。以下是一个此类字符串的快速示例：
<?php
$doc = <<<DOC
Usage: my_program.php [-hso FILE] [--quiet | --verbose] [INPUT ...]

Options:
  -h --help    show this
  -s --sorted  sorted output
  -o FILE      specify output file [default: ./test.txt]
  --quiet      print less text
  --verbose    print more text

DOC;

  • params 是一个可选的数组，包含影响 docopt 的附加数据。以下键被支持：

    • argv 是一个可选的参数向量；默认情况下，docopt 使用传递给程序的参数向量（$_SERVER['argv']）。或者，你可以提供一个字符串列表，如 array('--verbose', '-o', 'hai.txt')。

    • help，默认为 true，指定解析器是否

      在遇到 -h 或 --help 选项时自动打印帮助信息（作为 doc 提供）并终止。如果你想手动处理 -h 或 --help 选项（如其他选项），将 help 设置为 false。

    • version，默认为 null，是一个可选的参数，用于指定程序的版本。如果提供，则在（假设在用法模式中提到了 --version 选项）解析器遇到 --version 选项时，它将打印提供的版本并终止。version 可以是任何可打印的对象，但最可能是字符串，例如 "2.1.0rc1"。

      注意，当 docopt 被设置为自动处理 -h、--help 和 --version 选项时，你仍然需要在用法模式中提及它们，这样才能正常工作。同时，为了让用户了解它们。

    • optionsFirst，默认为 false。如果设置为 true，将不允许混合选项和位置参数。即，在第一个位置参数之后，所有参数都将被解释为位置参数，即使它们看起来像选项。这可以用于与 POSIX 严格兼容，或者如果你希望将参数发送到其他程序。

Docopt\Handler->handle() 接收一个必需的参数：

  • doc 是一个包含 帮助信息 的字符串，该信息将被解析以创建选项解析器。接下来几节将给出如何编写此类帮助信息的简单规则。以下是一个此类字符串的快速示例：
<?php
$doc = <<<DOC
Usage: my_program.php [-hso FILE] [--quiet | --verbose] [INPUT ...]

-h --help    show this
-s --sorted  sorted output
-o FILE      specify output file [default: ./test.txt]
--quiet      print less text
--verbose    print more text

DOC;

handle() 的返回值是一个简单的关联数组，具有选项、参数和命令作为键，拼写方式与你的帮助信息中完全相同。长选项版本优先。例如，如果你按以下方式调用顶级示例：

naval_fate.php ship Guardian move 100 150 --speed=15

返回的字典将是：

<?php
array(
  '--drifting'=>false,         'mine'=>false,
  '--help'=>false,             'move'=>true,
  '--moored'=>false,           'new'=>true,
  '--speed'=>'15',             'remove'=>true,
  '--version'=>false,          'set'=>true,
  '<name>'=>array('Guardian'), 'ship'=>true,
  '<x>'=>'100',                'shoot'=>false,
  '<y>'=>'150'
);

帮助信息格式

帮助信息由 2 个部分组成：

  • 用法部分，以 Usage: 开头，例如：

    Usage: my_program.php [-hso FILE] [--quiet | --verbose] [INPUT ...]

  • 选项部分，以 Options: 开头，例如：

    Options:
  -h --help    show this
  -s --sorted  sorted output
  -o FILE      specify output file [default: ./test.txt]
  --quiet      print less text
  --verbose    print more text

部分由标题和主体组成。部分主体可以从标题的同一行开始，但如果它跨越多行，则必须缩进。部分由一个空行或一个没有缩进的字符串终止。

Section header: Section body

Section header:
  Section body, which is indented at least
  one space or tab from the section header

Section header: Section body, which is indented at least
  one space or tab from the section header

用法部分格式

最小示例

Usage: my_program.php

在 usage: 之后的第一词被解释为你的程序名称。你可以多次指定你的程序名称，以表示几个互斥模式。

Usage: my_program.php FILE
       my_program.php COUNT FILE

每个模式可以由以下元素组成：

  • <arguments>、ARGUMENTS。参数指定为上标单词，例如 my_program.php CONTENT-PATH 或由尖括号包围的单词：my_program.php <content-path>。
  • --options。选项是以破折号（-）开始的单词，例如 --output、-o。你可以“堆叠”多个单字母选项，例如 -oiv，它将等同于 -o -i -v。选项可以有参数，例如 --input=FILE 或 -i FILE 或甚至 -iFILE。但是，如果你想让你的选项具有参数、默认值或指定选项的短/长同义词（参见下一节关于选项描述），则必须指定选项描述。
  • commands 是不遵循上述 --options 或 <arguments> 或 ARGUMENTS 规范的单词，加上两个特殊命令：破折号 "-" 和双破折号 "--"（见下文）。

使用以下结构来指定模式

  • []（括号）可选元素。例如：my_program.php [-hvqo 文件]
  • ()（括号）必选元素。所有未放入[]中的元素也都是必选的，例如：my_program.php --path=<路径> <文件>...与my_program.php (--path=<路径> <文件>...)相同。（注意，“必选选项”可能对用户来说不是一个好主意）。
  • |（管道）互斥元素。如果互斥元素中有一个是必选的，请使用()分组：my_program.php (--clockwise | --counter-clockwise) 时间。如果互斥元素都不是必选的，请使用[]分组：my_program.php [--left | --right]。
  • ...（省略号）一个或多个元素。为了指定可以接受任意数量的重复元素，请使用省略号（...），例如：my_program.php 文件 ...表示接受一个或多个文件。如果您想接受零个或多个元素，请使用方括号，例如：my_program.php [文件 ...]。省略号在表达式中作为一元运算符。
  • [选项]（区分大小写）任何选项的快捷方式。如果您想指定使用模式可以提供以下在选项说明中定义的任何选项，而不想在使用模式中列举它们，请使用它。"[--]"。双横杠"----"是惯例，用于分隔可能被误认为是选项的位置参数。为了支持此惯例，请在您的使用模式中添加"[--]"。"-"（单横杠）是惯例，表示使用标准输入而不是文件。为了支持此，请将"-"添加到您的使用模式中。"-"作为正常命令。

如果您的模式允许匹配无参数选项（标志）多次

Usage: my_program.php [-v | -vv | -vvv]

则选项的出现次数将被计数。即如果程序以my_program -vv的方式调用，则args['-v']将是2。同样适用于命令。

如果您的使用模式允许匹配具有参数或位置参数的同一名称选项多次，则匹配的参数将被收集到列表中

Usage: my_program.php <file> <file> --path=<path>...

例如，调用my_program.php 文件1 文件2 --path=./here --path=./there后，返回的字典将包含args['<文件>'] == ['file1', 'file2']和args['--path'] == ['./here', './there']。

选项部分格式

选项部分是一个可选部分，包含可以记录或补充您的使用模式的选项列表。

列出选项描述是必要的，以便指定

  • 同义词短选项和长选项，
  • 如果选项有一个参数，
  • 如果选项的参数有一个默认值。

规则如下

  • 选项部分主体中每行以一个或多个水平空白字符开头，后跟-或--的行被处理为选项描述，例如。

    Options:
  --verbose   # GOOD
  -o FILE     # GOOD
Other: --bad  # BAD, line does not start with dash "-"

  • 为了指定选项有一个参数，在空格后（或等于"="符号）放置描述该参数的单词，如下所示。使用逗号可以分隔选项。在下面的示例中，两行都是有效的，但是建议您坚持一种风格。

    -o FILE --output=FILE       # without comma, with "=" sign
-i <file>, --input <file>   # with comma, wihtout "=" sign

  • 使用两个空格将选项与其非正式描述分开

    --verbose More text.   # BAD, will be treated as if verbose option had
                       # an argument "More", so use 2 spaces instead
-q        Quit.        # GOOD
-o FILE   Output file. # GOOD
--stdout  Use stdout.  # GOOD, 2 spaces

  • 如果您想为具有参数的选项设置默认值，请将其放入选项描述中，形式为[默认值: <我的默认值>]

    --coefficient=K  The K coefficient [default: 2.95]
--output=FILE    Output file [default: test.txt]
--directory=DIR  Some directory [default: ./]

  • 如果选项不可重复，则[默认值: ...]中的值将被解释为字符串。如果是可重复的，它将根据空白拆分为列表

    Usage: my_program.php [--repeatable=<arg> --repeatable=<arg>]
                      [--another-repeatable=<arg>]...
                      [--not-repeatable=<arg>]

# will be ['./here', './there']
--repeatable=<arg>          [default: ./here ./there]

# will be ['./here']
--another-repeatable=<arg>  [default: ./here]

# will be './here ./there', because it is not repeatable
--not-repeatable=<arg>      [default: ./here ./there]

示例

我们有一份详尽的示例列表，涵盖了 docopt 功能的各个方面。[点击这里](https://github.com/docopt/docopt/tree/master/examples) 查看示例，如有疑问，请阅读源代码。

子解析器、多层帮助和 大型 应用程序（如 git）

如果您想将使用模式拆分为几个部分，实现多层帮助（每个子命令都有单独的帮助屏幕），或者要与不使用 docopt 的现有脚本接口，或者您正在构建下一个“git”，您将需要新的 options_first 参数（在上面的 API 部分中有描述）。为了快速入门，我们实现了一个 git 命令行界面的子集作为示例：[点击这里](https://github.com/docopt/docopt/tree/master/examples/git)

数据验证

docopt 做了一件事情并且做得很好：它实现了您的命令行界面。然而，它并不验证输入数据。当您的验证要求超出输入是否可选或必填之外时，您应该使用验证库来补充 docopt。

开发

有关开发信息，请参阅 [Python 版本的页面](http://github.com/docopt/docopt)