rpian-terminal

一个用于终端操作和绘制的Rust库，专为Rajesh Patkar软件工程学院的学术目的设计。

重要通知

此库专为Rajesh Patkar软件工程学院Rust课程的探索性练习设计。它**不适用于生产环境**。主要目标是促进对与终端交互相关的Rust概念的学习和理解。鼓励学生识别库的设计和功能中的局限性和问题，并提出解决方案。

功能

• 颜色操作（前景和背景）
• 文本属性操作（粗体、下划线等）
• 光标移动和屏幕清除
• 字符和行输入
• 定时等待（秒、毫秒、微秒）
• 光标可见性控制
• 各种屏幕和行清除函数
• 绘图原语（线条、多风格盒子和阴影矩形）
• 视口管理
• 各种符号的Unicode支持（箭头、星星、数学符号、棋子、表情符号、盲文图案）
• 全局错误处理器，用于一致的错误管理
• 具有各种样式和方向的增强型线条绘制功能

安装

将以下内容添加到您的 Cargo.toml

[dependencies]
rpian-terminal = "0.8.1"

使用方法

以下是如何使用一些函数的快速示例

use rpian_terminal::*;
use rbox::{draw_box, BoxStyle};
use line::{Line, Direction, Shape};

fn main() {
    set_viewport(80, 24);
    clear_screen();
    
    set_foreground_color(Color::Green);
    set_attribute(Attribute::Bright);
    println("Welcome to rpian-terminal!");
    reset_color();
    reset_attributes();

    draw_box(5, 3, 70, 18, BoxStyle::Double);
    draw_box(10, 5, 60, 14, BoxStyle::SingleRounded);

    let mut line = Line::new();
    line.x = 15;
    line.y = 10;
    line.size = 20;
    line.direction = Direction::East;
    line.show(Some(2));

    move_cursor_to(15, 12);
    print("Enter your name: ");
    let name = read_line();

    move_cursor_to(15, 14);
    set_foreground_color(Color::Blue);
    set_attribute(Attribute::Underscore);
    println(&format!("Hello, {}!", name));

    wait_for_seconds(2);
    clear_screen();
}

注意：错误处理通过全局错误处理器内部完成。

模块

该库组织为几个模块

• arrow：提供箭头符号
• braille：实现盲文图案
• chess：提供棋子符号
• emoji：包括各种表情符号
• math：提供数学符号
• rbox：实现框绘制和阴影功能
• star：提供星星符号
• triangle：提供三角形符号
• error：实现自定义错误处理
• line：实现增强型线条绘制功能
• circle：提供圆形符号

API概述

颜色和属性

• Color 枚举：黑色、红色、绿色、黄色、蓝色、洋红色、青色、白色
• 属性 枚举：重置、亮、暗、下划线、闪烁、反向、隐藏
• 函数：set_foreground_color、set_background_color、reset_color、set_attribute、reset_attributes

光标和屏幕控制

• 函数：move_cursor_to、clear_screen、save_cursor_location、restore_cursor_location、show_cursor、hide_cursor

输入和输出

• 函数
  • read_key：读取单个按键
  • read_line：读取整行输入
  • print：输出字符串
  • println：输出字符串后跟换行符
  • put_char：输出单个字符

计时

• 函数：wait_for_seconds、wait_for_millis、wait_for_micros

屏幕清除

• 函数：clear_to_line_end、clear_to_line_start、clear_line、clear_to_screen_start、clear_to_screen_end

绘图

• BoxStyle 枚举：单线、双线、单圆角、双圆角、点状、虚线
• ShadeStyle 枚举：浅色、中等、深色、实色
• 函数
  • diagonal_line：绘制对角线
  • draw_box：绘制具有指定样式的矩形
  • draw_shaded_rectangle：绘制阴影矩形
  • hide_box：擦除先前绘制的矩形

线条绘制

• Line 结构：表示具有自定义属性的线条
• Direction 枚举：北、南、东、西、东北、西北、东南、西南
• LineStyle 结构：自定义线条外观
• 函数
  • horizontal_line：绘制水平线
  • vertical_line：绘制垂直线
  • diagonal_line：绘制对角线

视口管理

• 函数
  • set_viewport(width: u16, height: u16)：设置视口大小
  • get_viewport() -> (u16, u16)：获取当前视口大小

符号模块

每个符号模块（arrow、braille、chess、emoji、math、star、triangle、circle）提供枚举和函数以访问各种 Unicode 符号。

错误处理

• 自定义 ErrorHandler 特性以实现灵活的错误管理
• 全局错误处理器，可以使用 set_error_handler 设置
• 函数：handle_io_error、handle_boundary_error

错误处理

库使用全局错误处理器以实现所有函数的一致错误管理。大多数函数不再返回 Result 类型，简化了使用。错误使用全局错误处理器内部处理。

用户可以实现 ErrorHandler 特性以创建自定义错误处理逻辑

use rpian_terminal::{ErrorHandler, set_error_handler};
use std::io;

struct MyErrorHandler;

impl ErrorHandler for MyErrorHandler {
    fn handle_io_error(&self, error: io::Error) {
        eprintln!("Custom I/O error handling: {}", error);
    }

    fn handle_boundary_error(&self, message: &str) {
        eprintln!("Custom boundary error handling: {}", message);
    }
}

fn main() {
    unsafe {
        set_error_handler(&MyErrorHandler);
    }
    // Rest of your code...
}

文档

有关详细的 API 文档，请在项目目录中运行 cargo doc --open

贡献

由于这是一个教育项目，贡献仅限于目前正在参加拉杰什·帕特卡尔软件工程研究所Rust课程的在校学生。这种限制确保了该库与课程课程内容和学习目标保持一致。

鼓励学生

• 识别并报告库的设计和功能中的局限性或问题
• 提出并实施解决方案或改进
• 对代码进行实验并与同学分享学习经验

许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE文件。

免责声明

此库未针对性能或全面错误处理进行优化。它有意保持简单，以供教育目的使用，并使用基本的ANSI转义序列进行终端控制。对于现实世界应用，请考虑使用更强大、功能更丰富的crate，如termion、crossterm或ncurses。

变更日志

0.8.0

• 通过新的line模块增强了线绘制功能
• 添加了Line结构体以实现更灵活的线绘制
• 引入了Direction枚举以指定线方向
• 添加了LineStyle结构体以自定义线外观
• 实现了新的线绘制函数：horizontal_line、vertical_line、diagonal_line
• 添加了包含圆形符号的circle模块
• 更新现有模块以使用新的线绘制系统
• 改进文档和示例

0.7.0

• 实现了全局错误处理系统
• 添加了自定义的ErrorHandler特质以实现灵活的错误管理
• 从大多数函数中删除了Result返回类型以简化使用
• 增强了rbox模块，添加了新的框绘制和阴影功能
• 添加了hide_box函数以删除绘制的框
• 添加了put_char函数以实现单个字符输出
• 更新了视图函数以使用u16进行尺寸
• 改进文档和示例
• 更新现有模块以使用新的错误处理系统

0.6.0

• 将代码库重组为模块
• 添加了新的模块：箭头、点字、棋盘、表情符号、数学、星星、三角形
• 通过新的样式和阴影选项改进了框绘制
• 添加了对各种类别的Unicode符号的支持
• 通过自定义错误类型增强了错误处理
• 更新了文档和示例