Expand description
§chaos-engine
The ChaosEngine is a useful library that helps CLI-based projects that actively take input from the user to perform actions, which is suitable for text-based games in terminals.
The way it works is you create a few Page instances, which would contain the text to be
displayed by the program, then at the bottom the user would have to give some text input. All
inputs made by the user must be handled by you, where you could exit the program/display a new
page (like progressing in a story), start a mini-game on a different page, etc.
§Features
ChaosEngine includes a few useful features, including:
- Automatic word wrapping, with respect to paddings.
- Automatic re-adjustments to word wrapping when the terminal gets resized.
- Ability to create different pages to easily print whichever one you want depending on your logic.
§Examples
Basic usage of ChaosEngine to display a hello world page, taking user input and creating a very simple exit command.
use chaos_engine::{Chaos, ChaosOptions, Page, types::Vector2};
fn main() {
let stdout = std::io::stdout();
// These are needed options to customize how your program will look.
let options = ChaosOptions {
// The input label, what text the user will see at the bottom right before the input.
input_label: "Input:",
// The X and Y paddings for the main text output section (buffer).
// X gets split into left and right (4 each), and Y is how many spaces from the top the text
// will have.
buffer_padding: Vector2::new(8, 2),
// ChaosOptions provide default values, and this would use the default X and Y paddings for
// the input line.
// X would be how many spaces to the left of the input label.
..Default::default()
};
// Instantiate chaos, passing the needed stdout and options.
// This is mostly what you will work with, whether it be printing pages, taking input, etc.
// Alternate screens are isolated terminal buffers, they are useful to restore the terminal
// state back to how it was, so activating them is very useful.
let mut chaos = Chaos::new(stdout, options);
chaos.alternate_screen(true);
// Instantiate a page where it will contain some text to display.
// A page by default is empty, therefore you need to push text to it so it gets properly
// displayed.
let mut page = Page::new();
page.push("hello, world!");
// This loop will contain the logic of the program, as ChaosEngine works by repeatedly
// taking input from the user.
// You can check the user input for specific words or patterns yourself, then execute some
// code.
loop {
// Clearing the terminal is necessary for each loop, to prevent printing over existing
// text.
chaos.clear_terminal();
// Get text input from the user.
let input = chaos.get_input(&mut page).unwrap();
// Test for what the input could possibly be, if it's "exit", then quit the program.
match input.as_str() {
"exit" => {
// Breaking the loop is how you quit the program.
// Exiting the alternate screen is necessary before exiting to restore back the
// text that was on the terminal before starting the program.
chaos.alternate_screen(false);
break;
},
_ => (),
}
}
}§Features
There is only one feature named test, and it’s only there to help with writing integrated
tests for the crate.