README

ZerusTech 终端组件

ZerusTech 终端组件 是一个轻量级的库，用于控制 PHP 命令行应用程序中的光标、字体样式以及颜色。虽然使用 ncurses 库会更简单，但我们希望尽可能保持其依赖性最小，以便在更广泛范围内使用。

此外，我们希望以对我们来说最舒适的方式封装类和方法，我们觉得学习新事物很有趣，比如终端的历史、ANSI 标准、ANSI、VT100 与其他终端之间的区别，一些之前几乎未曾触及的 tty 相关命令和主题，以及 terminfo 和 termcap（该库不支持）以及如何从编译的 terminfo 文件中解析终端规范。

这个库受到了 hoa/console 项目的启发，这个项目非常好，但它与 symfony/console 在许多功能上重叠，我们更倾向于后者用于 CLI 应用程序开发。因此，我们将从 `symfony/console` 中缺失的终端功能重新实现到这个库中。

::: info-box note

此库不支持任何 Windows 平台！

:::

安装

您可以通过两种不同的方式安装此组件

• 通过 Composer 安装

  $ cd <project-root-directory>
  $ composer require zerustech/terminal
  

• 使用官方 Git 仓库 (https://github.com/zerustech/terminal)

示例

创建终端实例

终端类是虚拟终端的抽象，因此这是您获得访问各种资源的入口点。

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\Terminal\Terminal;

$terminal = Terminal::instance();

// Or creates a terminal instance for specific tty and terminal names
// $terminal = Terminal::instance('/dev/ttys001', 'ansi');

光标

光标由光标工具控制，可以从终端实例中获取。以下是如何操作光标的示例

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\Terminal\Terminal;

$terminal = Terminal::instance(); // Creates a terminal instance

$cursor = $terminal->getCursor(); // Obtains the cursor tool

$cursor->moveTo(30, 40); // Moves cursor to row 30 and column 40.

$position = $cursor->getPosition(); // ['row' => 30,'col' => 40]

$cursor->move('up'); 
// Moves cursor 1 row upward: (29, 40)
// Valid directions include: 
// up, right, down, left, home and bol (beginning of line)

$cursor->save(); // Saves current cursor position: (29, 40)

$cursor->move('up', 2); // Moves cursor 2 rows upward: (27, 40)

$cursor->restore(); // Restores cursor position: (29, 40)

$cursor->hide(); // Hides cursor

$cursor->show(); // Reveals cursor

// Method chaining is also supported
$terminal
    ->getCursor()                  // Obtains the cursor tool 
        ->moveTo(30, 40)           // Moves to (30, 40)
        ->move('up')               // Moves 1 row upward
        ->save()                   // Saves cursor position
        ->move('up', 2)            // Moves 2 rows upward
        ->restore()                // Restores cursor position
        ->hide()                   // Hides cursor
        ->show()                   // Reveals cursor
    ->terminal();                  // Obtains the terminal instance

::: info-box tip

此组件中的大多数方法都支持方法链，以生成流畅的代码。

:::

屏幕

屏幕、字体样式和颜色由终端实例中的屏幕工具控制。以下是如何使用的示例

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\Terminal\Terminal;

$terminal = Terminal::instance();

$screen = $terminal->getScreen(); // Obtains the screen tool

$screen->clear();         // Clears the full screen.

$screen->clear('bol');    
// Clears characters from current cursor position to the beginning of line.
// Valid parts of the clear() method include: 
//     - all (the default value)
//     - bol (beginning of line)
//     - eol (end of line)
//     - eos (end of screen)

$screen->delete('line'); //  Deletes 1 line upward.

$screen->delete('line', 2); // Deletes 2 lines upward.

$screen->delete('character'); // Deletes 1 character rightward.

$screen->delete('character', 2); // Deletes 2 characters rightward.

$screen->insert('line'); // Inserts 1 line upward.

$screen->insert('line', 2); // Inserts 2 lines upward.

$screen->mode('bold'); // Turns on bold font style.

$screen->mode('bold', false); // Turns off bold font style.

// Valid font styles include:
//     - none (resets all styles)
//     - hide
//     - bold
//     - underscore
//     - blink 
//     - inverse 

$screen->foregroundColor('red'); // Sets foreground color by alias.
// Valid aliases include: 
// black, red, green, yellow, blue, magenta, cyan and white.

$screen->foregroundColor('87ff87'); // Sets foreground color by RGB

$screen->backgroundColor('blue'); // Sets background color by alias.

$screen->backgroundColor('d78700'); // Sets background color by RGB

Terminfo

如果您想访问完整的终端规范（所有布尔、字符串和数字能力），可以从终端实例中获取 terminfo 对象

<?php

require_once __DIR__.'/vendor/autoload.php';

use ZerusTech\Component\Terminal\Terminal;

$terminal = Terminal::instance();

$terminfo = $terminal->getTerminfo();

$string = $terminfo->getString('cursor_home'); 
// Gets the value of a string capability.

$boolean = $terminfo->getBoolean('auto_left_margin'); 
// Gets the value of a boolean capability.

$number = $terminfo->getNumber('max_colors');
// Gets the value of a numberic capability.

::: info-box tip

此组件仅支持 terminfo 中的长能力名称（不支持 termcap 名称）。有关 terminfo 中按字母顺序排列的完整能力名称列表，请参阅 terminfo(5)。

如果您想了解每个能力的原始顺序，请参阅最新 ncurses 源代码 中的 `include/Caps` 文件。

:::

参考文献

• term(5) 手册页
• ANSI/VT100 终端控制转义序列
• 终端的非规范模式
• stty(1) 手册页
• infocmp(1) 手册页
• xterm 256 色调板
• zerustech/io 项目
• zerustech/threaded 项目
• zerustech/terminal 项目

许可

ZerusTech 终端组件 根据 MIT 许可证 发布。