A Rust library for terminal manipulation and drawing, designed for educational purposes at Rajesh Patkar Institute of Software Engineering.
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.
- 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
Add this to your Cargo.toml
:
[dependencies]
rpian-terminal = "0.8.1"
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.
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
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
- Functions:
move_cursor_to
,clear_screen
,save_cursor_location
,restore_cursor_location
,show_cursor
,hide_cursor
- 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
- Functions:
wait_for_seconds
,wait_for_millis
,wait_for_micros
- Functions:
clear_to_line_end
,clear_to_line_start
,clear_line
,clear_to_screen_start
,clear_to_screen_end
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
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
- Functions:
set_viewport(width: u16, height: u16)
: Sets the viewport sizeget_viewport() -> (u16, u16)
: Gets the current viewport size
Each symbol module (arrow
, braille
, chess
, emoji
, math
, star
, triangle
, circle
) provides enums and functions to access various Unicode symbols.
- 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
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...
}
For detailed API documentation, run cargo doc --open
in your project directory.
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
This project is licensed under the MIT License - see the LICENSE file for details.
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
.
- 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
- 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
- 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