chaos_engine/

lib.rs

//! # 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.
//!
//! ```no_run
//! 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.

pub mod chaos;
pub mod text;
pub mod types;

pub use chaos::*;
pub use text::*;