asamaru7/ansi-php

PHP CLI 应用程序的 ANSI 控制函数和 ANSI 控制序列（颜色、清除等）

维护者

详情

github.com/asamaru7/ansi-php

源代码

安装: 108

依赖者: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 10

3.0.3 2019-10-29 12:00 UTC

Requires

  • php: >=5.4.0

Requires (Dev)

MIT d4285f76ab9768d3ee6ab1166987ca3103b66665

This package is auto-updated.

Last update: 2024-08-29 04:49:14 UTC

README

Build Status Source Version Downloads License

PHP CLI 应用程序的 ANSI 控制函数和 ANSI 控制序列

由 Bramus 构建! - https://www.bram.us/

关于

bramus/ansi-php 是一套用于在基于文本的终端上处理 ANSI 控制函数和 ANSI 控制序列的类。

  • ANSI 控制函数控制诸如行间距、分页或数据流等操作。
  • ANSI 控制序列允许清除屏幕、移动光标、设置文本颜色等。

(备注：ANSI 转义序列是一种特殊的“ANSI 控制序列”，它以 ESC ANSI 控制函数开始。这两个术语不可互换。)

功能

在处理 ANSI 控制函数时，bramus/ansi-php 支持

  • BS: 退格
  • BEL: 铃声
  • CR: 换行
  • ESC: 转义
  • LF: 换行
  • TAB: 制表符

在处理 ANSI 转义序列时，bramus/ansi-php 支持

  • SGR (选择图形表现)：操作文本样式（加粗、下划线、闪烁、颜色等）。
  • ED (清除显示)：清除（部分）显示。
  • EL (清除当前行)：清除（部分）当前行。

其他控制序列（如移动光标）目前不支持。

使用 bramus/ansi-php 的示例库是 bramus/monolog-colored-line-formatter。它使用 bramus/ansi-php 的 SGR 支持来着色输出。

Monolog Colored Line Formatter

先决条件/需求

  • PHP 5.4.0 或更高版本

安装

可以使用 Composer 进行安装

composer require asamaru7/ansi-php

使用方法

使用 ANSI PHP 最简单的方法是使用捆绑的 Ansi 辅助类，该类提供易于使用的快捷方式来处理 bramus/ansi-php。Ansi 类的设计允许调用之间链式调用。

如果您愿意尝试，当然可以自由地使用原始的 ControlFunction 和 ControlSequence 类。

快速示例

use \Bramus\Ansi\Ansi;
use \Bramus\Ansi\Writers\StreamWriter;
use \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR;

// Create Ansi Instance
$ansi = new Ansi(new StreamWriter('php://stdout'));

// Output some styled text on screen, along with a Line Feed and a Bell
$ansi->color(array(SGR::COLOR_FG_RED, SGR::COLOR_BG_WHITE))
     ->blink()
     ->text('I will be blinking red on a white background.')
     ->nostyle()
     ->text(' And I will be normally styled.')
     ->lf()
     ->text('Ooh, a bell is coming ...')
     ->bell();

下面将进一步展示如何使用这些示例。

概念

从 v3.0 版本开始，bramus/ansi-php 使用了写入器的概念来写入数据。默认情况下，使用写入到 php://stdout 的 StreamWriter。

以下提供了以下写入器

  • StreamWriter：将数据写入流。只需传递文件的路径，它将为您打开一个流。默认情况下写入到 php://stdout。
  • BufferWriter：将数据写入缓冲区。调用 flush() 时，将返回缓冲区的内容。
  • ProxyWriter：作为另一个写入器的代理。将数据写入内部缓冲区。调用 flush() 时，写入器将首先将数据写入另一个写入器，然后再返回。

Ansi 辅助类的功能

核心函数

  • text($text)：将数据写入写入器
  • setWriter(\Bramus\Ansi\Writers\WriterInterface $writer)：设置写入器
  • getWriter()：获取写入器

ANSI 控制函数快捷方式

这些快捷方式将控制字符写入写入器。

  • bell()：铃声控制字符 (\a)
  • backspace(): 退格控制字符 (\b)
  • tab(): 制表符控制字符 (\t)
  • lf(): 换行控制字符 (\n)
  • cr(): 回车控制字符 (\r)
  • esc(): ESC 控制字符

SGR ANSI 转义序列缩写

这些缩写将 SGR ANSI 转义序列写入到写入器中。

  • nostyle() 或 reset(): 移除所有文本样式（颜色、粗体等）
  • color(): 设置文本的前景色和/或背景色。 (参见以下内容)
  • bold() 或 bright(): 粗体：开。在某些系统中“强度：明亮”
  • normal(): 粗体：关。在某些系统中“强度：正常”
  • faint(): 强度：微弱。 (不支持广泛)
  • italic(): 斜体：开。 (不支持广泛)
  • underline(): 下划线：开。
  • blink(): 闪烁：开。
  • negative(): 反转或颠倒。交换前景和背景。
  • strikethrough(): 删除线：开。 (不支持广泛)

重要：选择图形渲染方式工作方式，您设置的文本样式将保持激活状态，直到您调用 nostyle() 或 reset() 以返回到默认样式。

ED ANSI 转义序列缩写

这些缩写将 ED ANSI 转义序列写入到写入器中。

  • eraseDisplay(): 删除整个屏幕并将光标移动到起始位置。
  • eraseDisplayUp(): 从当前行向上删除屏幕。
  • eraseDisplayDown(): 从当前行向下删除屏幕。

EL ANSI 转义序列缩写

这些缩写将 EL ANSI 转义序列写入到写入器中。

  • eraseLine(): 删除整个当前行。
  • eraseLineToEOL(): 从当前光标位置删除到当前行末。
  • eraseLineToSOL(): 从当前光标位置删除到当前行开头。

额外功能

  • flush() 或 get(): 获取 FlushableWriter 写入器的内容。
  • e(): 反射 FlushableWriter 写入器的包含内容。

示例

基础知识

// Create Ansi Instance
$ansi = new \Bramus\Ansi\Ansi();

// This will output a Bell
$ansi->bell();

// This will output some text
$ansi->text('Hello World!');

注意：由于没有 $writer 传递给 \Bramus\Ansi\Ansi 构造函数，因此使用默认的 StreamWriter 将数据写入 php://stdout。

使用 FlushableWriter

可刷新写入器是缓存数据的写入器，并且只有在使用其 flush() 函数刷新时才会输出数据。 BufferWriter 和 ProxyWriter 实现了此接口。

// Create Ansi Instance
$ansi = new \Bramus\Ansi\Ansi(new \Bramus\Ansi\Writers\BufferWriter());

// This will append a bell to the buffer. It will not output it.
$ansi->bell();

// This will append a bell to the buffer. It will not output it.
$ansi->text('Hello World!');

// Now we'll output it
echo $ansi->get();

链式操作

bramus/ansi-php 的包装类 Ansi 支持链式操作。

// Create Ansi Instance
$ansi = new \Bramus\Ansi\Ansi();

// This will output a Line Feed, some text, a Bell, and a Line Feed
$ansi->lf()->text('hello')->bell()->lf();

文本样式：基础知识

$ansi = new \Bramus\Ansi\Ansi();
$ansi->bold()->underline()->text('I will be bold and underlined')->lf();

注意：选择图形渲染方式工作方式，您设置的文本样式将保持激活状态，直到您调用 nostyle() 或 reset() 以返回到默认样式。

$ansi = new \Bramus\Ansi\Ansi();

$ansi->bold()->underline()->text('I will be bold and underlined')->lf();
$ansi->text('I will also be bold because nostyle() has not been called yet')->lf();
$ansi->nostyle()->blink()->text('I will be blinking')->nostyle()->lf();
$ansi->text('I will be normal because nostyle() was called on the previous line');

文本样式：颜色

颜色和其他文本样式选项定义在 \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR 上的常量中。

前景（文本）颜色

  • SGR::COLOR_FG_BLACK: 黑色前景颜色
  • SGR::COLOR_FG_RED: 红色前景颜色
  • SGR::COLOR_FG_GREEN: 绿色前景颜色
  • SGR::COLOR_FG_YELLOW: 黄色前景颜色
  • SGR::COLOR_FG_BLUE: 蓝色前景颜色
  • SGR::COLOR_FG_PURPLE: 紫色前景颜色
  • SGR::COLOR_FG_CYAN: 青色前景颜色
  • SGR::COLOR_FG_WHITE: 白色前景颜色
  • SGR::COLOR_FG_BLACK_BRIGHT: 黑色前景颜色（明亮）
  • SGR::COLOR_FG_RED_BRIGHT: 红色前景颜色（明亮）
  • SGR::COLOR_FG_GREEN_BRIGHT: 绿色前景颜色（明亮）
  • SGR::COLOR_FG_YELLOW_BRIGHT: 黄色前景颜色（明亮）
  • SGR::COLOR_FG_BLUE_BRIGHT: 蓝色前景颜色（明亮）
  • SGR::COLOR_FG_PURPLE_BRIGHT: 紫色前景颜色（明亮）
  • SGR::COLOR_FG_CYAN_BRIGHT: 青色前景颜色（明亮）
  • SGR::COLOR_FG_WHITE_BRIGHT: 白色前景颜色（明亮）
  • SGR::COLOR_FG_RESET: 默认前景颜色

背景颜色

  • SGR::COLOR_BG_BLACK：黑色背景颜色
  • SGR::COLOR_BG_RED：红色背景颜色
  • SGR::COLOR_BG_GREEN：绿色背景颜色
  • SGR::COLOR_BG_YELLOW：黄色背景颜色
  • SGR::COLOR_BG_BLUE：蓝色背景颜色
  • SGR::COLOR_BG_PURPLE：紫色背景颜色
  • SGR::COLOR_BG_CYAN：青色背景颜色
  • SGR::COLOR_BG_WHITE：白色背景颜色
  • SGR::COLOR_BG_BLACK_BRIGHT：黑色背景颜色（亮色）
  • SGR::COLOR_BG_RED_BRIGHT：红色背景颜色（亮色）
  • SGR::COLOR_BG_GREEN_BRIGHT：绿色背景颜色（亮色）
  • SGR::COLOR_BG_YELLOW_BRIGHT：黄色背景颜色（亮色）
  • SGR::COLOR_BG_BLUE_BRIGHT：蓝色背景颜色（亮色）
  • SGR::COLOR_BG_PURPLE_BRIGHT：紫色背景颜色（亮色）
  • SGR::COLOR_BG_CYAN_BRIGHT：青色背景颜色（亮色）
  • SGR::COLOR_BG_WHITE_BRIGHT：白色背景颜色（亮色）
  • SGR::COLOR_BG_RESET：默认背景颜色

将这些中的一个传递给 $ansi->color()，颜色将被设置。

use \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR;

$ansi = new \Bramus\Ansi\Ansi();

$ansi->color(SGR::COLOR_FG_RED)
     ->text('I will be red')
     ->nostyle();

要在一次调用中设置前景和背景颜色，使用数组将它们传递给 $ansi->color()

use \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\SGR;

$ansi = new \Bramus\Ansi\Ansi();

$ansi->color(array(SGR::COLOR_FG_RED, SGR::COLOR_BG_WHITE))
     ->blink()
     ->text('I will be blinking red on a wrhite background.')
     ->nostyle();

使用原始类

由于所有原始的 ControlFunction 和 ControlSequence 类都提供了 __toString() 函数，所以可以直接 echo 一些 bramus/ansi-php 实例。

// Output a Bell Control Character
echo new \Bramus\Ansi\ControlFunctions\Bell();

// Output an ED instruction, to erase the entire screen
echo new \Bramus\Ansi\ControlSequences\EscapeSequences\ED(
    \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\ED::ALL
);

要获取它们的内容，使用 get() 函数

// Get ANSI string for a Bell Control Character
$bell = (new \Bramus\Ansi\ControlFunctions\Bell())->get();

// Get ANSI string for an ED instruction, to erase the entire screen
$eraseDisplay = (new \Bramus\Ansi\ControlSequences\EscapeSequences\ED(
    \Bramus\Ansi\ControlSequences\EscapeSequences\Enums\ED::ALL
))->get();

echo $bell . $bell . $eraseDisplay . $bell;

单元测试

bramus/ansi-php 随附单元测试，使用 PHPUnit。

  • 如果 PHPUnit 已全局安装，运行 phpunit 来运行测试。

  • 如果没有全局安装 PHPUnit，可以通过运行 composer install --dev 在本地安装它。通过调用 vendor/bin/phpunit 或 composer test 来运行测试。

单元测试还会在 Travis CI 上自动运行

许可证

bramus/ansi-php 在 MIT 公共许可证下发布。有关详细信息，请参阅所附的 LICENSE 文件。

ANSI 参考