Formatador 技术文档

1. 安装指南

1.1 安装环境要求

• Ruby 版本：2.0 及以上
• 操作系统：支持所有主流操作系统（Windows、macOS、Linux）

1.2 安装步骤

1. 打开终端或命令行工具。
2. 使用 gem 命令安装 formatador：

   gem install formatador
   

3. 安装完成后，可以通过以下命令确认安装是否成功：

   gem list formatador
   

2. 项目的使用说明

2.1 基本用法

formatador 提供了多种方法来格式化并输出文本到标准输出（STDOUT）。以下是一些基本用法示例：

2.1.1 输出单行文本

Formatador.display_line('Hello World')

2.1.2 使用标签设置格式

Formatador.display_line('[green]Hello World[/]')

[/] 用于重置格式，颜色支持通过 [_color_] 设置背景颜色。

2.2 标准选项

• format：如果 STDOUT.tty? 为真，则添加颜色代码。
• display：调用 format 并打印输出。
• display_line：调用 display，并在末尾添加换行符 \n。
• redisplay：显示文本，并在前面添加 \r，以覆盖最后一行。

2.3 扩展功能

2.3.1 显示表格

table_data = [
  { :name => "Joe",  :food => "Burger" },
  { :name => "Bill", :food => "French fries" }
]
Formatador.display_table(table_data)

2.3.2 显示紧凑表格

table_data = [
  { :name => "Joe",  :food => "Burger" },
  { :name => "Bill", :food => "French fries" }
]
Formatador.display_compact_table(table_data)

2.3.3 显示进度条

total    = 1000
progress = Formatador::ProgressBar.new(total)

1000.times do
  progress.increment
end

3. 项目API使用文档

3.1 Formatador.display_line(text)

• 功能：输出单行文本，并在末尾添加换行符。
• 参数：
  • text：要输出的文本字符串。
• 示例：

  Formatador.display_line('Hello World')
  

3.2 Formatador.display_table(data, headers = nil)

• 功能：显示表格。
• 参数：
  • data：包含表格数据的数组，每个元素是一个哈希，键为表头，值为数据。
  • headers：可选参数，指定要显示的表头及其顺序。
• 示例：

  table_data = [
    { :name => "Joe",  :food => "Burger" },
    { :name => "Bill", :food => "French fries" }
  ]
  Formatador.display_table(table_data)
  

3.3 Formatador::ProgressBar.new(total, opts = {})

• 功能：创建一个进度条对象。
• 参数：
  • total：总进度值。
  • opts：可选参数，用于设置进度条的选项，如颜色。
• 示例：

  total    = 1000
  progress = Formatador::ProgressBar.new(total, :color => "light_blue")
  

4. 项目安装方式

4.1 使用 gem 安装

gem install formatador

4.2 在项目中引入

在 Ruby 项目中，可以通过以下方式引入 formatador：

require 'formatador'

通过以上步骤，您可以顺利安装并使用 formatador 项目，享受其强大的文本格式化功能。