README

Hoa 是一套 模块化、可扩展 和 结构化 的 PHP 库。
此外，Hoa 致力于成为工业界和学术界之间的桥梁。

Hoa\Console

此库允许轻松与终端进行交互：getoption、光标、窗口、进程、readline 等。

了解更多.

安装

使用 Composer，将此库包含到依赖中，需要要求 hoa/console

$ composer require hoa/console '~3.0'

有关更多安装说明，请参阅 源代码页面。

测试

在运行测试套件之前，必须安装开发依赖项

$ composer install

然后，运行所有测试套件

$ vendor/bin/hoa test:run

有关更多信息，请参阅 贡献者指南。

快速使用

我们提供了一些功能的快速概述：光标、窗口、readline、进程和最终的 getoption。

光标

Hoa\Console\Cursor 类允许操作光标。以下是一些操作的列表

• 移动,
• 移动到,
• 保存,
• 恢复,
• 清除,
• 隐藏,
• 显示,
• 获取位置,
• 着色,
• 等。

API 非常简单。例如，我们可以使用 l、left 或 ← 将光标移动到左侧列。因此，我们将光标向左移动 3 次，然后向上移动 2 次

Hoa\Console\Cursor::move('left left left up up');

… 或者使用 Unicode 符号

Hoa\Console\Cursor::move('← ← ← ↑ ↑');

此方法将光标从当前位置相对移动，但我们能够将光标移动到绝对坐标

Hoa\Console\Cursor::moveTo(13, 42);

我们还可以保存当前光标位置，进行移动、清除等操作，然后恢复保存的位置

Hoa\Console\Cursor::save();     // save
Hoa\Console\Cursor::move('↓');  // move below
Hoa\Console\Cursor::clear('↔'); // clear the line
echo 'Something below…';        // write something
Hoa\Console\Cursor::restore();  // restore

另一个带有颜色的示例

Hoa\Console\Cursor::colorize(
    'underlined foreground(yellow) background(#932e2e)'
);

请阅读 API 文档获取更多信息。

鼠标

Hoa\Console\Mouse 类允许监听鼠标动作，并提供以下监听器：mouseup、mousedown、wheelup 和 wheeldown。示例

$mouse = Hoa\Console\Mouse::getInstance();
$mouse->on('mousedown', function ($bucket) {
    print_r($bucket->getData());
});

$mouse::track();

然后，当我们左击时，我们将看到

Array
(
    [x] => 69
    [y] => 30
    [button] => left
    [shift] =>
    [meta] =>
    [ctrl] =>
)

当我们按住 shift 键时左击，我们将看到

Array
(
    [x] => 71
    [y] => 32
    [button] => left
    [shift] => 1
    [meta] =>
    [ctrl] =>
)

这是一个实验性 API。

窗口

Hoa\Console\Window 类允许操作窗口。以下是一些操作的列表

• 设置大小,
• 获取大小,
• 移动到,
• 获取位置,
• 滚动,
• 最小化,
• 恢复,
• 提升,
• 设置标题,
• 获取标题,
• 复制,
• 等。

此外，我们还有一个用于监听窗口大小调整事件的 hoa://Event/Console/Window:resize 事件通道。

例如，我们将窗口调整为40行和80列，然后将窗口水平移动400px，垂直移动100px。

Hoa\Console\Window::setSize(40, 80);
Hoa\Console\Window::moveTo(400, 100);

如果我们不喜欢我们的用户，我们可以最小化其窗口。

Hoa\Console\Window::minimize();
sleep(2);
Hoa\Console\Window::restore();

我们还可以设置或获取窗口的标题。

Hoa\Console\Window::setTitle('My awesome application');

最后，如果我们有一个复杂的应用程序布局，我们可以通过监听 hoa://Event/Console/Window:resize 事件通道来在窗口大小调整时重新绘制它。

Hoa\Event\Event::getEvent('hoa://Event/Console/Window:resize')
    ->attach(function (Hoa\Event\Bucket $bucket) {
        $data = $bucket->getData();
        $size = $data['size'];

        echo
            'New dimensions: ', $size['x'], ' lines x ',
            $size['y'], ' columns.', "\n";
    });

请阅读API文档以获取更多信息。

Readline

Hoa\Console\Readline\Readline 类提供了一个高级的 readline，允许以下操作

• 编辑，
• 历史记录，
• 自动完成。

它支持UTF-8。它基于绑定，以下是一些

• 箭头向上 和 箭头向下：在历史记录中移动，
• 箭头向左 和 箭头向右：左右移动光标，
• Ctrl-A：移动到行首，
• Ctrl-E：移动到行尾，
• Ctrl-B：向后移动一个单词，
• Ctrl-F：向前移动一个单词，
• Ctrl-W：删除第一个后退单词，
• 退格键：删除第一个后退字符，
• Enter：提交行，
• Tab：自动完成。

因此，要读取一行

$readline = new Hoa\Console\Readline\Readline();
$line     = $readline->readLine('> '); // “> ” is the prefix of the line.

Hoa\Console\Readline\Password 允许相同的操作，但不打印到 STDOUT。

$password = new Hoa\Console\Readline\Password();
$line     = $password->readLine('password: ');

我们可以使用 Hoa\Console\Readline\Readline::addMapping 方法添加映射。我们使用 \e[… 表示 \033[，使用 \C-… 表示 Ctrl-…，其余的用字符表示。我们可以关联一个字符或一个可调用对象

$readline->addMapping('a', 'z'); // crazy, we replace “a” by “z”.
$readline->addMapping('\C-R', function ($readline) {
    // do something when pressing Ctrl-R.
});

我们还可以使用 Hoa\Console\Readline\Readline 类上的 addHistory、clearHistory、getHistory、previousHistory 和 nextHistory 方法来操作历史记录。

最后，我们有一些在 Tab 上启用的自动完成功能。如果提出一个解决方案，它将直接插入。如果有多个解决方案，我们可以通过键盘箭头、Enter、Esc 等导航菜单来选择解决方案。我们还可以组合自动完成功能。以下示例将 Word 和 Path 自动完成功能组合在一起

$functions = get_defined_functions();
$readline->setAutocompleter(
    new Hoa\Console\Readline\Autocompleter\Aggregate([
        new Hoa\Console\Readline\Autocompleter\Path(),
        new Hoa\Console\Readline\Autocompleter\Word($functions['internal'])
    ])
);

以下是结果示例

在 Windows 上，readline 等同于简单的 fgets(STDIN)。

Processus

Hoa\Console\Processus 类允许将进程作为实现了 Hoa\Stream\IStream\In、Hoa\Stream\IStream\Out 和 Hoa\Stream\IStream\Pathable 接口的流来操作（请参阅Hoa\Stream 库）。

基本上，我们可以这样读取 STDOUT

$processus = new Hoa\Console\Processus('ls');
$processus->open();
echo $processus->readAll();

我们可以这样写入 STDIN

$processus->writeAll('foobar');

等等。这是非常经典的。

Hoa\Console\Processus 还提供了许多事件：start、stop、input、output 和 timeout。因此

$processus = new Hoa\Console\Processus('ls');
$processus->on('output', function (Hoa\Event\Bucket $bucket) {
    $data = $bucket->getData();
    echo '> ', $data['line'], "\n";
});
$processus->run();

我们还可以读取和写入比 0（STDOUT）、1（STDIN）和 2（STDERR）更多的管道。同样，我们还可以设置进程的当前工作目录及其环境。

我们可以使用 Hoa\Console\Processus::execute 方法快速执行进程，而无需使用流。

GetOption

Hoa\Console\Parser 和 Hoa\Console\GetOption 类允许轻松解析命令行并获取选项和输入值。

首先，我们需要解析一个命令行，例如

$parser = new Hoa\Console\Parser();
$parser->parse('-s --long=value input');

其次，我们需要定义我们的选项

$options = new Hoa\Console\GetOption(
    [
        // long name              type                  short name
        //  ↓                      ↓                         ↓
        ['short', Hoa\Console\GetOption::NO_ARGUMENT,       's'],
        ['long',  Hoa\Console\GetOption::REQUIRED_ARGUMENT, 'l']
    ],
    $parser
);

最后，我们遍历选项

$short = false;
$long  = null;

//          short name                  value
//               ↓                        ↓
while (false !== $c = $options->getOption($v)) {
    switch ($c) {
        case 's':
            $short = true;

            break;

        case 'l':
            $long = $v;

            break;
    }
}

var_dump($short, $long); // bool(true) and string(5) "value".

请参阅 Hoa\Console\Parser 的 API 文档，以了解所有支持选项的形式（标志或开关、长或短选项、输入等）。

它还支持选项中的拼写错误。在这种情况下，我们需要添加

    case '__ambiguous':
        $options->resolveOptionAmbiguity($v);

        break;

如果找到一个解决方案，它将自动选择此解决方案，否则将引发异常。当使用 hoa 脚本时，Hoa\Console\Dispatcher\Kit 将捕获此异常，并提出提示。

得益于 Hoa\Router 库 和 Hoa\Dispatcher 库（及其专用工具 Hoa\Console\Dispatcher\Kit），我们能够轻松构建命令。请参阅不同库中的所有 Bin/ 目录（例如 Hoa\Cli\Bin\Resolve）和 Hoa/Cli/Bin/Hoa.php，以了解更多信息。

Awecode

以下 awecodes 展示了该库的使用示例

• Hoa\Console\Readline: 为什么以及如何使用 Hoa\Console\Readline？简单的示例将帮助我们使用默认快捷键，我们甚至将看到自动完成功能。
• Hoa\Websocket: 为什么以及如何使用 Hoa\Websocket\Server 和 Hoa\Websocket\Client？一个简单的示例将说明 WebSocket 协议。

文档

Hoa\Console 的黑客手册 包含有关如何使用此库及其工作原理的详细信息。

要本地生成文档，请执行以下命令

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

更多文档可以在项目的网站上找到： hoa-project.net。

获取帮助

主要有两种获取帮助的方式

• 在 #hoaproject IRC 频道中
• 在 users.hoa-project.net 的论坛上

贡献

你想贡献吗？谢谢！详细的 贡献指南 解释了你需要知道的一切。

许可

Hoa 采用新 BSD 许可证 (BSD-3-Clause)。请参阅 LICENSE 以获取详细信息。

相关项目

以下项目正在使用此库

• PsySH，一个运行时开发者控制台、交互式调试器和 PHP 的 REPL。