11 releases (7 breaking)
0.8.1 | Aug 11, 2024 |
---|---|
0.7.1 | Jul 31, 2024 |
#108 in Command-line interface
542 downloads per month
70KB
1.5K
SLoC
rpian-terminal
A Rust library for terminal manipulation and drawing, designed for educational purposes at Rajesh Patkar Institute of Software Engineering.
IMPORTANT NOTICE
This library is designed specifically for exploratory exercises in the Rust course at Rajesh Patkar Institute of Software Engineering. It is NOT intended for use in production environments. The primary goal is to facilitate learning and understanding of Rust concepts related to terminal interactions. Students are encouraged to identify limitations and problems in the design and features of the library and suggest solutions.
Features
- Color manipulation (foreground and background)
- Text attribute manipulation (bold, underline, etc.)
- Cursor movement and screen clearing
- Character and line input
- Timed waits (seconds, milliseconds, microseconds)
- Cursor visibility control
- Various screen and line clearing functions
- Drawing primitives (lines, boxes with multiple styles, shaded rectangles)
- Viewport management
- Unicode support for various symbols (arrows, stars, math symbols, chess pieces, emojis, Braille patterns)
- Global error handler for consistent error management
- Enhanced line drawing capabilities with various styles and directions
Installation
Add this to your Cargo.toml
:
[dependencies]
rpian-terminal = "0.8.1"
Usage
Here's a quick example of how to use some of the functions:
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();
}
Note: Error handling is done internally using the global error handler.
Modules
The library is organized into several modules:
arrow
: Provides arrow symbolsbraille
: Implements Braille patternschess
: Offers chess piece symbolsemoji
: Includes various emoji symbolsmath
: Provides mathematical symbolsrbox
: Implements box drawing and shading functionsstar
: Offers star symbolstriangle
: Provides triangle symbolserror
: Implements custom error handlingline
: Implements enhanced line drawing capabilitiescircle
: Provides circle symbols
API Overview
Colors and Attributes
Color
enum: Black, Red, Green, Yellow, Blue, Magenta, Cyan, WhiteAttribute
enum: Reset, Bright, Dim, Underscore, Blink, Reverse, Hidden- Functions:
set_foreground_color
,set_background_color
,reset_color
,set_attribute
,reset_attributes
Cursor and Screen Control
- Functions:
move_cursor_to
,clear_screen
,save_cursor_location
,restore_cursor_location
,show_cursor
,hide_cursor
Input and Output
- Functions:
read_key
: Reads a single keypressread_line
: Reads a full line of inputprint
: Outputs a stringprintln
: Outputs a string followed by a newlineput_char
: Outputs a single character
Timing
- Functions:
wait_for_seconds
,wait_for_millis
,wait_for_micros
Screen Clearing
- Functions:
clear_to_line_end
,clear_to_line_start
,clear_line
,clear_to_screen_start
,clear_to_screen_end
Drawing
BoxStyle
enum: Single, Double, SingleRounded, DoubleRounded, Dotted, DashedShadeStyle
enum: Light, Medium, Dark, Solid- Functions:
diagonal_line
: Draws a diagonal linedraw_box
: Draws a box with specified styledraw_shaded_rectangle
: Draws a shaded rectanglehide_box
: Erases a previously drawn box
Line Drawing
Line
struct: Represents a line with customizable propertiesDirection
enum: North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWestLineStyle
struct: Customizes line appearance- Functions:
horizontal_line
: Draws a horizontal linevertical_line
: Draws a vertical linediagonal_line
: Draws a diagonal line
Viewport Management
- Functions:
set_viewport(width: u16, height: u16)
: Sets the viewport sizeget_viewport() -> (u16, u16)
: Gets the current viewport size
Symbol Modules
Each symbol module (arrow
, braille
, chess
, emoji
, math
, star
, triangle
, circle
) provides enums and functions to access various Unicode symbols.
Error Handling
- Custom
ErrorHandler
trait for flexible error management - Global error handler that can be set using
set_error_handler
- Functions:
handle_io_error
,handle_boundary_error
Error Handling
The library uses a global error handler for consistent error management across all functions. Most functions no longer return Result
types, simplifying usage. Errors are handled internally using the global error handler.
Users can implement the ErrorHandler
trait to create custom error handling logic:
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...
}
Documentation
For detailed API documentation, run cargo doc --open
in your project directory.
Contributing
As this is an educational project, contributions are limited to students currently participating in the Rust course at Rajesh Patkar Institute of Software Engineering. This restriction ensures that the library remains aligned with the course curriculum and learning objectives.
Students are encouraged to:
- Identify and report limitations or issues in the library's design and features
- Propose and implement solutions or improvements
- Experiment with the code and share learnings with classmates
License
This project is licensed under the MIT License - see the LICENSE file for details.
Disclaimer
This library is not optimized for performance or comprehensive error handling. It is intentionally kept simple for educational purposes and uses basic ANSI escape sequences for terminal control. For real-world applications, consider using more robust and feature-rich crates like termion
, crossterm
, or ncurses
.
Changelog
0.8.0
- Enhanced line drawing capabilities with the new
line
module - Added
Line
struct for more flexible line drawing - Introduced
Direction
enum for specifying line directions - Added
LineStyle
struct for customizing line appearance - Implemented new line drawing functions:
horizontal_line
,vertical_line
,diagonal_line
- Added
circle
module with circle symbols - Updated existing modules to use the new line drawing system
- Improved documentation and examples
0.7.0
- Implemented a global error handler system
- Added custom
ErrorHandler
trait for flexible error management - Removed
Result
return types from most functions for simplified usage - Enhanced
rbox
module with new box drawing and shading functions - Added
hide_box
function for removing drawn boxes - Added
put_char
function for single character output - Updated viewport functions to use
u16
for dimensions - Improved documentation and examples
- Updated existing modules to use the new error handling system
0.6.0
- Reorganized codebase into modules
- Added new modules: arrow, braille, chess, emoji, math, star, triangle
- Improved box drawing with new styles and shading options
- Added Unicode symbol support for various categories
- Enhanced error handling with custom error types
- Updated documentation and examples