diff --git a/src/common/commands/mod.rs b/src/common/commands/mod.rs index d4d4183..afb595c 100644 --- a/src/common/commands/mod.rs +++ b/src/common/commands/mod.rs @@ -1,4 +1,4 @@ -//! This module contains some commands that could be executed for specific task. +//! This module contains some commands that could be executed for a specific task. A `Command` is just a little wrapper. use super::super::output::TerminalOutput; use std::io; diff --git a/src/common/commands/shared_commands.rs b/src/common/commands/shared_commands.rs index ccf035e..9fcf864 100644 --- a/src/common/commands/shared_commands.rs +++ b/src/common/commands/shared_commands.rs @@ -1,4 +1,4 @@ -//! This module contains the commands that can be used for both unix and windows 10 systems because they support ANSI escape codes +//! A module which contains the commands that can be used for both unix and windows 10 systems because they support ANSI escape codes use super::{IAlternateScreenCommand, TerminalOutput}; diff --git a/src/common/commands/unix_command.rs b/src/common/commands/unix_command.rs index 6b3fe4e..e37c40e 100644 --- a/src/common/commands/unix_command.rs +++ b/src/common/commands/unix_command.rs @@ -1,9 +1,8 @@ -//! This module contains the commands that can be used for unix systems. +//! A module which contains the commands that can be used for UNIX systems. use kernel::unix_kernel::terminal; use std::io::Result; -// This command is used for enabling and disabling raw mode for the terminal. /// This command is used for enabling and disabling raw mode for the terminal. pub struct RawModeCommand; diff --git a/src/common/commands/win_commands.rs b/src/common/commands/win_commands.rs index ed14e28..4c89620 100644 --- a/src/common/commands/win_commands.rs +++ b/src/common/commands/win_commands.rs @@ -1,4 +1,4 @@ -//! This module contains the commands that can be used for windows systems. +//! A module which contains the commands that can be used for windows systems. use super::{IAlternateScreenCommand, IEnableAnsiCommand, TerminalOutput}; diff --git a/src/common/crossterm.rs b/src/common/crossterm.rs index ab492ce..36e5217 100644 --- a/src/common/crossterm.rs +++ b/src/common/crossterm.rs @@ -9,7 +9,7 @@ use std::fmt::Display; use std::sync::Arc; /// This type could be used to access the `cursor, terminal, color, input, styling` module more easily. -/// You need to pass a reference to the screen where on you want to perform the actions to the `Crossterm` type. +/// You need to pass a reference to the screen whereon you want to perform the actions to the `Crossterm` type. /// /// If you want to use the default screen you could do it like this: /// @@ -52,7 +52,7 @@ impl<'crossterm> Crossterm { } } - /// Get an `TerminalCursor` implementation whereon cursor related actions can be performed. + /// Get a `TerminalCursor` implementation whereon cursor related actions can be performed. /// /// ```rust /// extern crate crossterm; @@ -64,11 +64,11 @@ impl<'crossterm> Crossterm { pub fn cursor(&self) -> cursor::TerminalCursor { match &self.stdout { None => cursor::TerminalCursor::new(), - Some(stdout) => cursor::TerminalCursor::on_screen(&stdout), + Some(stdout) => cursor::TerminalCursor::from_output(&stdout), } } - /// Get an `TerminalInput` implementation whereon terminal related actions can be performed. + /// Get a `TerminalInput` implementation whereon terminal related actions can be performed. /// /// ```rust /// extern crate crossterm; @@ -80,11 +80,11 @@ impl<'crossterm> Crossterm { pub fn input(&self) -> input::TerminalInput { match &self.stdout { None => input::TerminalInput::new(), - Some(stdout) => input::TerminalInput::on_screen(&stdout), + Some(stdout) => input::TerminalInput::from_output(&stdout), } } - /// Get an `Terminal` implementation whereon terminal related actions can be performed. + /// Get a `Terminal` implementation whereon terminal related actions can be performed. /// /// ```rust /// extern crate crossterm; @@ -96,11 +96,11 @@ impl<'crossterm> Crossterm { pub fn terminal(&self) -> terminal::Terminal { match &self.stdout { None => terminal::Terminal::new(), - Some(stdout) => terminal::Terminal::on_screen(&stdout), + Some(stdout) => terminal::Terminal::from_output(&stdout), } } - /// Get an `TerminalColor` implementation whereon color related actions can be performed. + /// Get a `TerminalColor` implementation whereon color related actions can be performed. /// /// ```rust /// extern crate crossterm; @@ -112,11 +112,11 @@ impl<'crossterm> Crossterm { pub fn color(&self) -> style::TerminalColor { match &self.stdout { None => style::TerminalColor::new(), - Some(stdout) => style::TerminalColor::on_screen(&stdout), + Some(stdout) => style::TerminalColor::from_output(&stdout), } } - /// This could be used to style an `Displayable` type with colors and attributes. + /// This could be used to style a `Displayable` type with colors and attributes. /// /// ```rust /// extern crate crossterm; diff --git a/src/common/functions.rs b/src/common/functions.rs index 58c5291..12e82ea 100644 --- a/src/common/functions.rs +++ b/src/common/functions.rs @@ -60,6 +60,11 @@ pub fn get_module(winapi_impl: T, unix_impl: T) -> Option { term } +/// This function is used by 'ANSI' modules. Those modules are using an `Option` of `TerminalOutput`. +/// Because it is an option it could be either 'None' or 'Some'. +/// When the `TerminalOutput` is 'None' we write our 'ANSI' escape codes to the default `stdout()` if it is a `Some` +/// - which means we are in alternate screen modes or we have raw screen enabled - we should write to the screen passed by the user. +/// This way our commands or our writes will be done with the passed `TerminalOutput`. pub fn write(stdout: &Option<&Arc>, string: String) -> io::Result { match stdout { None => { @@ -74,6 +79,11 @@ pub fn write(stdout: &Option<&Arc>, string: String) -> io::Resul } } +/// This function is used by 'ANSI' modules. Those modules are using an `Option` of `TerminalOutput`. +/// Because it is an option it could be either 'None' or 'Some'. +/// When the `TerminalOutput` is 'None' we write our 'ANSI' escape codes to the default `stdout()` if it is a `Some` +/// - which means we are in alternate screen modes or we have raw screen enabled - we should write to the screen passed by the user. +/// This way our commands or our writes will be done with the passed `TerminalOutput`. pub fn write_str(stdout: &Option<&Arc>, string: &str) -> io::Result { match stdout { None => match io::stdout().flush() { diff --git a/src/common/screen/mod.rs b/src/common/screen/mod.rs index db84f07..64936c1 100644 --- a/src/common/screen/mod.rs +++ b/src/common/screen/mod.rs @@ -1,5 +1,5 @@ -//! This module provides some modules to work with the terminal screen. -//! Like allowing you to switch between raw and alternate screen. +//! A module which provides some functionalities to work with the terminal screen. +//! Like allowing you to switch between main and alternate screen or putting the terminal into raw mode. mod alternate; mod raw; diff --git a/src/common/screen/raw.rs b/src/common/screen/raw.rs index cbe35e5..8fb5c2a 100644 --- a/src/common/screen/raw.rs +++ b/src/common/screen/raw.rs @@ -21,7 +21,7 @@ use std::io; /// A wrapper for the raw terminal state. Which can be used to write to. /// /// Although this type is available for you to use I would recommend using `Screen` instead. -/// Note that when you want to use input and rawmode you should use `Screen`. +/// Note that when you want to use input and raw mode you should use `Screen`. pub struct RawScreen; impl RawScreen { diff --git a/src/common/screen/screen.rs b/src/common/screen/screen.rs index 9178e2e..d49e64a 100644 --- a/src/common/screen/screen.rs +++ b/src/common/screen/screen.rs @@ -5,9 +5,9 @@ use std::io::Result; use std::io::Write; use std::sync::Arc; -/// This type represents an screen which could be in normal, raw and alternate modes. +/// This type represents a screen which could be in normal, raw and alternate modes. /// -/// Lets talk about the different modes a bit: +/// Let's talk about the different modes a bit: /// /// - Alternate modes: /// @@ -18,13 +18,13 @@ use std::sync::Arc; /// /// - RawModes /// - No line buffering. -/// Normally the terminals uses line buffering. This means that the input will be send to the terminal line by line. -/// With raw mode the input will be send one byte at a time. +/// Normally the terminals use line buffering. This means that the input will be sent to the terminal line by line. +/// With raw mode the input will send one byte at a time. /// - Input /// All input has to be written manually by the programmer. /// - Characters -/// The characters are not processed by the terminal driver, but are sent straight through. -/// Special character have no meaning, like backspace will not be interpret as backspace but instead will be directly send to the terminal. +/// The characters are not processed by the terminal driver but are sent straight through. +/// Special character have no meaning, like backspace will not be interpreted as backspace but instead will be directly sent to the terminal. /// - Escape characters /// Note that in raw modes `\n` `\r` will move to the new line but the cursor will be at the same position as before on the new line therefor use `\n\r` to start at the new line at the first cell. /// @@ -66,8 +66,8 @@ pub struct Screen { } impl Screen { - /// Create new instance of the Screen also specify if the current screen should be in raw mode or normal mode. - /// If you are not sure what raw mode is then pass false or use the `Screen::default()` to create an instance. + /// Create a new instance of the Screen also specify if the current screen should be in raw mode or normal mode. + /// If you are not sure what raw mode is then passed false or use the `Screen::default()` to create an instance. pub fn new(raw_mode: bool) -> Screen { if raw_mode { let screen = Screen { @@ -122,14 +122,14 @@ impl Screen { Ok(()) } - /// This will disable the drop which will cause raw modes not to be undone on drop of `Screen`. + /// This will disable the drop which will cause raw modes not to be undone on the drop of `Screen`. pub fn disable_drop(&mut self) { self.drop = false; } } impl From for Screen { - /// Create an screen with the given `Stdout` + /// Create a screen with the given `Stdout` fn from(stdout: TerminalOutput) -> Self { Screen { stdout: Arc::new(stdout), @@ -140,7 +140,7 @@ impl From for Screen { } impl From> for Screen { - /// Create an screen with the given 'Arc' + /// Create a screen with the given 'Arc' fn from(stdout: Arc) -> Self { Screen { stdout, @@ -151,7 +151,7 @@ impl From> for Screen { } impl Default for Screen { - /// Create an new screen which will not be in raw mode or alternate mode. + /// Create a new screen which will not be in raw mode or alternate mode. fn default() -> Self { Screen { stdout: Arc::new(TerminalOutput::new(false)), @@ -162,7 +162,7 @@ impl Default for Screen { } impl Drop for Screen { - /// If the current screen is in raw mode whe need to disable it when the instance goes out of scope. + /// If the current screen is in raw mode we need to disable it when the instance goes out of scope. fn drop(&mut self) { if self.stdout.is_in_raw_mode && self.drop { RawScreen::disable_raw_modes(); diff --git a/src/lib.rs b/src/lib.rs index 5818797..177c0d1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,7 +1,10 @@ -//! Crossterm provides the same core functionalities for both windows and unix systems. +//! Ever got disappointed when a terminal library for rust was only written for UNIX systems? +//! Crossterm provides the same core functionalities for both Windows and UNIX systems. +//! //! Crossterm aims to be simple and easy to call in code. -//! True the simplicity of Crossterm you do not have to worry about the platform your working with. -//! You can just call the action you want to perform and under water it will check what to do based on the current platform. +//! Through the simplicity of Crossterm, you do not have to worry about the platform you are working with. +//! +//! This crate supports all UNIX and Windows terminals down to windows 7 (not all terminals are tested see [Tested Terminals] in the README. #[macro_use] mod common; @@ -9,19 +12,19 @@ mod common; mod kernel; mod modules; +pub use modules::terminal; pub use modules::cursor; pub use modules::input; pub use modules::output; pub use modules::style; -pub use modules::terminal; -pub use self::cursor::*; -pub use self::input::*; -pub use self::output::*; -pub use self::style::*; +pub use self::style::{color, style, Color, ColorType, Attribute, TerminalColor, ObjectStyle, StyledObject, DisplayableObject}; +pub use self::cursor::{cursor, TerminalCursor}; +pub use self::input::{input, TerminalInput, AsyncReader, KeyEvent}; +pub use self::terminal::{terminal, Terminal}; +pub use self::output::TerminalOutput; pub use common::screen::{AlternateScreen, Screen}; pub use common::Crossterm; -pub use output::TerminalOutput; #[cfg(unix)] extern crate libc; diff --git a/src/modules/cursor/ansi_cursor.rs b/src/modules/cursor/ansi_cursor.rs index c19fab0..e8df10a 100644 --- a/src/modules/cursor/ansi_cursor.rs +++ b/src/modules/cursor/ansi_cursor.rs @@ -1,10 +1,10 @@ //! This is an ANSI specific implementation for cursor related action. -//! This module is used for windows 10 terminals and unix terminals by default. -//! Note that the cursor position is 0 based. This means that we start counting at 0 when setting the cursor position ect. +//! This module is used for windows 10 terminals and UNIX terminals by default. +//! Note that the cursor position is 0 based. This means that we start counting at 0 when setting the cursor position etc. use super::*; -/// This struct is an ansi implementation for cursor related actions. +/// This struct is an ANSI implementation for cursor related actions. pub struct AnsiCursor {} impl AnsiCursor { diff --git a/src/modules/cursor/cursor.rs b/src/modules/cursor/cursor.rs index aa30925..11620ba 100644 --- a/src/modules/cursor/cursor.rs +++ b/src/modules/cursor/cursor.rs @@ -1,12 +1,12 @@ -//! With this module you can perform actions that are cursor related. -//! Like changing and display the position of the cursor in terminal. +//! A module that contains all the actions related to cursor movement in the terminal. +//! Like: moving the cursor position; saving and resetting the cursor position; hiding showing and control the blinking of the cursor. //! //! Note that positions of the cursor are 0 -based witch means that the coordinates (cells) starts counting from 0 use super::*; use Screen; -/// Struct that stores an specific platform implementation for cursor related actions. +/// Struct that stores a platform-specific implementation for cursor related actions. /// /// Check `/examples/cursor` in the library for more specific examples. /// @@ -34,7 +34,7 @@ pub struct TerminalCursor<'stdout> { } impl<'stdout> TerminalCursor<'stdout> { - /// Create new cursor instance whereon cursor related actions can be performed. + /// Create new `TerminalCursor` instance whereon cursor related actions can be performed. pub fn new() -> TerminalCursor<'stdout> { #[cfg(target_os = "windows")] let cursor = functions::get_module::>( @@ -51,7 +51,23 @@ impl<'stdout> TerminalCursor<'stdout> { } } - pub fn on_screen(stdout: &'stdout Arc) -> TerminalCursor<'stdout> { + /// Create a new instance of `TerminalCursor` whereon cursor related actions could be preformed on the given output. + /// + /// **Note** + /// + /// Use this function when you want your terminal to operate with a specific output. + /// This could be useful when you have a screen which is in 'alternate mode'. + /// And you want your actions from the `TerminalCursor`, created by this function, to operate on the 'alternate screen'. + /// + /// # Example + /// ``` + /// let screen = Screen::default(); + // + /// if let Ok(alternate) = screen.enable_alternate_modes(false) { + /// let terminal = TerminalCursor::from_output(&alternate.screen.stdout); + /// } + /// ``` + pub fn from_output(stdout: &'stdout Arc) -> TerminalCursor<'stdout> { #[cfg(target_os = "windows")] let cursor = functions::get_module::>( WinApiCursor::new(), @@ -206,13 +222,13 @@ impl<'stdout> TerminalCursor<'stdout> { } } -/// Get an TerminalCursor implementation whereon cursor related actions can be performed. +/// Get a `TerminalCursor` instance whereon cursor related actions can be performed. pub fn cursor() -> TerminalCursor<'static> { TerminalCursor::new() } -/// Get an TerminalCursor implementation whereon cursor related actions can be performed. -/// Pass the reference to any screen you want this type to perform actions on. +/// Get a `TerminalCursor` instance whereon cursor related actions can be performed. +/// Pass the reference to any `Screen` you want this type to perform actions on. pub fn from_screen(screen: &Screen) -> TerminalCursor { - TerminalCursor::on_screen(&screen.stdout) + TerminalCursor::from_output(&screen.stdout) } diff --git a/src/modules/cursor/mod.rs b/src/modules/cursor/mod.rs index 1eaa532..1cb550f 100644 --- a/src/modules/cursor/mod.rs +++ b/src/modules/cursor/mod.rs @@ -1,5 +1,7 @@ -//! With this module you can perform actions that are cursor related. -//! Like moving the cursor position;saving and resetting the cursor position; hiding showing and control the blinking of the cursor. +//! A module that contains all the actions related to cursor movement in the terminal. +//! Like: moving the cursor position; saving and resetting the cursor position; hiding showing and control the blinking of the cursor. +//! +//! Note that positions of the cursor are 0 -based witch means that the coordinates (cells) starts counting from 0 mod cursor; @@ -20,18 +22,18 @@ use super::functions; use std::sync::Arc; use TerminalOutput; -///! This trait defines the actions that can be preformed with the terminal cursor. -///! This trait can be implemented so that an concrete implementation of the ITerminalCursor can forfill -///! the wishes to work on an specific platform. +///! This trait defines the actions that can be performed with the terminal cursor. +///! This trait can be implemented so that a concrete implementation of the ITerminalCursor can fulfill +///! the wishes to work on a specific platform. ///! ///! ## For example: ///! -///! This trait is implemented for `WINAPI` (Windows specific) and `ANSI` (Unix specific), -///! so that cursor related actions can be preformed on both unix and windows systems. +///! This trait is implemented for `WinApi` (Windows specific) and `ANSI` (Unix specific), +///! so that cursor related actions can be performed on both UNIX and Windows systems. trait ITerminalCursor: Sync + Send { /// Goto some location (x,y) in the context. fn goto(&self, x: u16, y: u16, stdout: &Option<&Arc>); - /// Get the location (x,y) of the current cusror in the context + /// Get the location (x,y) of the current cursor in the context fn pos(&self) -> (u16, u16); /// Move cursor n times up fn move_up(&self, count: u16, stdout: &Option<&Arc>); diff --git a/src/modules/cursor/winapi_cursor.rs b/src/modules/cursor/winapi_cursor.rs index 88a0253..10b00d4 100644 --- a/src/modules/cursor/winapi_cursor.rs +++ b/src/modules/cursor/winapi_cursor.rs @@ -1,12 +1,12 @@ -//! This is an WINAPI specific implementation for cursor related action. -//! This module is used for windows terminals that do not support ANSI escape codes. -//! Note that the cursor position is 0 based. This means that we start counting at 0 when setting the cursor position ect. +//! This is a WINAPI specific implementation for cursor related actions. +//! This module is used for Windows terminals that do not support ANSI escape codes. +//! Note that the cursor position is 0 based. This means that we start counting at 0 when setting the cursor position. use kernel::windows_kernel::cursor; use super::*; -/// This struct is an windows implementation for cursor related actions. +/// This struct is a windows implementation for cursor related actions. pub struct WinApiCursor; impl WinApiCursor { diff --git a/src/modules/input/input.rs b/src/modules/input/input.rs index 75ed305..5e765b8 100644 --- a/src/modules/input/input.rs +++ b/src/modules/input/input.rs @@ -1,11 +1,11 @@ -//! With this module you can perform actions that are input related. +//! A module that contains all the actions related to reading input from the terminal. //! Like reading a line, reading a character and reading asynchronously. use super::*; use Screen; use std::{thread, time::Duration}; -/// Struct that stores an specific platform implementation for input related actions. +/// Struct that stores a platform-specific implementation for input related actions. /// /// Check `/examples/input` the examples folder on github for more info. /// @@ -17,22 +17,23 @@ use std::{thread, time::Duration}; /// let input = input(); /// let result = input.read_line(); /// let pressed_char = input.read_char(); -/// -/// ``` +///``` /// /// **!! Take note when using input with raw mode you should use the `Screen` type. !!** /// /// ``` /// let screen = Screen::new(true); -/// let input = crossterm::input::from_screen(&screen);/// +/// let input = crossterm::input::from_screen(&screen); /// ``` +/// When you want to use 'input' related actions on 'alternate screen' use the `Screen` type instead, and pass it to the `terminal::from_screen()` function. +/// By doing that terminal actions will be performed on the alternate screen. pub struct TerminalInput<'stdout> { terminal_input: Box, stdout: Option<&'stdout Arc>, } impl<'stdout> TerminalInput<'stdout> { - /// Create new instance of TerminalInput whereon input related actions could be preformed. + /// Create a new instance of `TerminalInput` whereon input related actions could be preformed. pub fn new() -> TerminalInput<'stdout> { #[cfg(target_os = "windows")] let input = Box::from(WindowsInput::new()); @@ -46,8 +47,23 @@ impl<'stdout> TerminalInput<'stdout> { } } - /// Create new instance of TerminalInput whereon input related actions could be preformed. - pub fn on_screen(stdout: &'stdout Arc) -> TerminalInput<'stdout> { + /// Create a new instance of `TerminalInput` whereon input related actions could be preformed. + /// + /// **Note** + /// + /// Use this function when you want your terminal to operate with a specific output. + /// This could be useful when you have a screen which is in 'alternate mode'. + /// And you want your actions from the `TerminalInput`, created by this function, to operate on the 'alternate screen'. + /// + /// # Example + /// ``` + /// let screen = Screen::default(); + // + /// if let Ok(alternate) = screen.enable_alternate_modes(false) { + /// let terminal = TerminalInput::from_output(&alternate.screen.stdout); + /// } + /// ``` + pub fn from_output(stdout: &'stdout Arc) -> TerminalInput<'stdout> { #[cfg(target_os = "windows")] let input = Box::from(WindowsInput::new()); @@ -162,6 +178,8 @@ impl<'stdout> TerminalInput<'stdout> { /// This will prevent the current thread from continuing until the passed `KeyEvent` has happened. /// + /// This function will put the terminal into raw mode so that any key presses will not be shown at the screen. + /// /// ``` /// use crossterm::input::{TerminalInput, KeyEvent}; /// @@ -198,13 +216,13 @@ impl<'stdout> TerminalInput<'stdout> { } } -/// Get an Terminal Input implementation whereon input related actions can be performed. +/// Get a `TerminalInput` instance whereon input related actions can be performed. pub fn input<'stdout>() -> TerminalInput<'stdout> { TerminalInput::new() } -/// Get an Terminal Input implementation whereon input related actions can be performed. -/// Pass the reference to any screen you want this type to perform actions on. +/// Get a `TerminalInput` instance whereon input related actions can be performed. +/// Pass the reference to any `Screen` you want this type to perform actions on. pub fn from_screen(screen: &Screen) -> TerminalInput { - TerminalInput::on_screen(&screen.stdout) + TerminalInput::from_output(&screen.stdout) } diff --git a/src/modules/input/mod.rs b/src/modules/input/mod.rs index 1d7eef9..95423e0 100644 --- a/src/modules/input/mod.rs +++ b/src/modules/input/mod.rs @@ -1,4 +1,4 @@ -//! With this module you can perform actions that are input related. +//! A module that contains all the actions related to reading input from the terminal. //! Like reading a line, reading a character and reading asynchronously. mod input; @@ -20,14 +20,14 @@ use std::sync::{mpsc, Arc}; use TerminalOutput; -/// This trait defines the actions that can be preformed with the terminal color. -/// This trait can be implemented so that an concrete implementation of the ITerminalColor can forfill -/// the wishes to work on an specific platform. +/// This trait defines the actions that can be preformed with the terminal input. +/// This trait can be implemented so that a concrete implementation of the ITerminalInput can fulfill +/// the wishes to work on a specific platform. /// /// ## For example: /// /// This trait is implemented for Windows and UNIX systems. -/// Unix is using the tty and windows is using libc C functions to read the input. +/// Unix is using the 'TTY' and windows is using 'libc' C functions to read the input. trait ITerminalInput { /// Read one line from the user input fn read_line(&self, stdout: &Option<&Arc>) -> io::Result; @@ -47,7 +47,7 @@ pub struct AsyncReader { recv: mpsc::Receiver>, } -// This enum represents a key event that from the user. +/// This enum represents key events which could be caused by the user. pub enum KeyEvent { /// Represents a specific key press. OnKeyPress(u8), diff --git a/src/modules/input/unix_input.rs b/src/modules/input/unix_input.rs index 1a77cf0..c4530ee 100644 --- a/src/modules/input/unix_input.rs +++ b/src/modules/input/unix_input.rs @@ -1,4 +1,4 @@ -//! This is an UNIX specific implementation for input related action. +//! This is a UNIX specific implementation for input related action. use super::*; use kernel::unix_kernel::terminal::{get_tty, read_char}; diff --git a/src/modules/input/windows_input.rs b/src/modules/input/windows_input.rs index f5c5973..4cab2ae 100644 --- a/src/modules/input/windows_input.rs +++ b/src/modules/input/windows_input.rs @@ -1,4 +1,4 @@ -//! This is an WINDOWS specific implementation for input related action. +//! This is a WINDOWS specific implementation for input related action. use super::*; diff --git a/src/modules/output/ansi_output.rs b/src/modules/output/ansi_output.rs index bdc6835..c3afb56 100644 --- a/src/modules/output/ansi_output.rs +++ b/src/modules/output/ansi_output.rs @@ -1,5 +1,5 @@ //! This is an ANSI specific implementation for the screen write -//! This module is used for windows 10 terminals and unix terminals by default. +//! This module is used for Windows 10 terminals and UNIX terminals by default. //! This module uses the stdout to write to the console. use super::IStdout; diff --git a/src/modules/output/mod.rs b/src/modules/output/mod.rs index 13314f8..772ab4e 100644 --- a/src/modules/output/mod.rs +++ b/src/modules/output/mod.rs @@ -1,4 +1,4 @@ -//! This module provides a way to work with an handle to an screen on different platforms. +//! A module provides a uniformed way to write to the output no matter if it is in main, alternate or raw mode. mod output; @@ -24,8 +24,8 @@ use super::functions; /// /// ## For example: /// -/// This trait is implemented for `WINAPI` (Windows specific) and `ANSI` (Unix specific), -/// so that color related actions can be preformed on both unix and windows systems. +/// This trait is implemented for `WinApi` (Windows specific) and `ANSI` (Unix specific), +/// so that output related actions can be preformed on both unix and windows systems. trait IStdout { /// Write an &str to the current stdout and flush the screen. fn write_str(&self, string: &str) -> io::Result; diff --git a/src/modules/output/output.rs b/src/modules/output/output.rs index ef2e04c..f6d92cb 100644 --- a/src/modules/output/output.rs +++ b/src/modules/output/output.rs @@ -1,39 +1,36 @@ //! This module provides one place to work with the screen. //! -//! In Rust we can call `stdout()` to get an handle to the current default console handle. -//! For example when in unix systems you want to print something to the main screen you can use the following code: +//! In Rust we can call `stdout()` to get a handle to the current default console handle. +//! When working with UNIX or Windows10 systems you could print some text to the screen by doing the following: //! //! ``` //! write!(std::io::stdout(), "{}", "some text"). //! ``` //! //! But things change when we are in alternate screen modes. -//! We can not simply use `stdout()` to get a handle to the alternate screen, since this call returns the current default console handle (mainscreen). +//! We can not simply use `stdout()` to get a handle to the 'alternate screen', since this call returns the current default console handle (main screen). //! -//! Instead we need to store an handle to the screen output. -//! This handle could be used to put into alternate screen modes and back into main screen modes. -//! Through this stored handle Crossterm can execute its command on the current screen whether it be alternate screen or main screen. +//! To get the handle to the `alternate screen` we first need to store this handle so that we are able to call it later on. +//! Through this stored handle, crossterm can write to or execute commands at the current screen whether it be an alternate screen or main screen. //! -//! For unix systems we store the handle gotten from `stdout()` for windows systems that are not supporting ANSI escape codes we store WinApi `HANDLE` struct witch will provide access to the current screen. -//! -//! This is the reason why this module exits: it is to provide access to the current terminal screen whether it will be the alternate screen and main screen. +//! For UNIX and Windows10 systems, we store the handle gotten from `stdout()`. For Windows systems who are not supporting ANSI escape codes, we can call `CONOUT$` to get the current screen `HANDLE`. use super::*; use std::default::Default; use std::io::Write; -/// Struct that is an handle to an terminal screen. +/// Struct that is a handle to a terminal screen. /// This handle could be used to write to the current screen /// -/// For unix and windows 10 `stdout()` will be used for handle when on windows systems with versions lower than 10 WinApi `HANDLE` will be used. +/// For UNIX and Windows 10 `stdout()` will be used as handle. And for Windows systems, not supporting ANSI escape codes, will use WinApi's `HANDLE` as handle. pub struct TerminalOutput { stdout: Box, pub is_in_raw_mode: bool, } impl TerminalOutput { - /// Create new screen write instance whereon screen related actions can be performed. + /// Create a new screen write instance whereon screen related actions can be performed. pub fn new(raw_mode: bool) -> Self { #[cfg(target_os = "windows")] let stdout: Box = diff --git a/src/modules/output/winapi_output.rs b/src/modules/output/winapi_output.rs index 78ba8d0..cfa0dea 100644 --- a/src/modules/output/winapi_output.rs +++ b/src/modules/output/winapi_output.rs @@ -3,7 +3,7 @@ use kernel::windows_kernel::{handle, writing}; use std::io; -/// This struct is a wrapper for WINAPI `HANDLE` +/// This struct is a wrapper for WinApi output. pub struct WinApiOutput; impl WinApiOutput { diff --git a/src/modules/style/ansi_color.rs b/src/modules/style/ansi_color.rs index f429c05..9641293 100644 --- a/src/modules/style/ansi_color.rs +++ b/src/modules/style/ansi_color.rs @@ -1,5 +1,5 @@ -//! This is an ANSI specific implementation for styling related action. -//! This module is used for windows 10 terminals and unix terminals by default. +//! This is a ANSI specific implementation for styling related action. +//! This module is used for Windows 10 terminals and Unix terminals by default. use super::*; diff --git a/src/modules/style/color.rs b/src/modules/style/color.rs index 247b9f7..d7711d3 100644 --- a/src/modules/style/color.rs +++ b/src/modules/style/color.rs @@ -1,11 +1,11 @@ -//! With this module you can perform actions that are color related. -//! Like styling the font, foreground color and background. +//! A module that contains all the actions related to the styling of the terminal. +//! Like applying attributes to font and changing the foreground and background. use super::*; use std::io; use Screen; -/// Struct that stores an specific platform implementation for color related actions. +/// Struct that stores a platform-specific implementation for color related actions. /// /// For styling text use the `::crossterm::style()` function. `TerminalColor` will set the colors of the screen permanently and the `style()` will only style the text given. /// @@ -50,8 +50,23 @@ impl<'stdout> TerminalColor<'stdout> { } } - /// Create new instance of `TerminalInput` whereon input related actions could be preformed. - pub fn on_screen(stdout: &'stdout Arc) -> TerminalColor<'stdout> { + /// Create a new instance of `TerminalColor` whereon coloring could be preformed on the given output. + /// + /// **Note** + /// + /// Use this function when you want your terminal to operate with a specific output. + /// This could be useful when you have a screen which is in 'alternate mode'. + /// And you want your actions from the `TerminalColor`, created by this function, to operate on the 'alternate screen'. + /// + /// # Example + /// ``` + /// let screen = Screen::default(); + // + /// if let Ok(alternate) = screen.enable_alternate_modes(false) { + /// let terminal = TerminalColor::from_output(&alternate.screen.stdout); + /// } + /// ``` + pub fn from_output(stdout: &'stdout Arc) -> TerminalColor<'stdout> { #[cfg(target_os = "windows")] let color = functions::get_module::>( Box::from(WinApiColor::new()), @@ -122,14 +137,13 @@ impl<'stdout> TerminalColor<'stdout> { } } -/// Get an Terminal Color implementation whereon color related actions can be performed. -/// Pass the reference to any screen you want this type to perform actions on. +/// Get a `TerminalColor` implementation whereon color related actions can be performed. pub fn color<'stdout>() -> TerminalColor<'stdout> { TerminalColor::new() } -/// Get an Terminal Color implementation whereon color related actions can be performed. -/// Pass the reference to any screen you want this type to perform actions on. +/// Get a `TerminalColor` instance whereon color related actions can be performed. +/// Pass the reference to any `Screen` you want this type to perform actions on. pub fn from_screen(screen: &Screen) -> TerminalColor { - TerminalColor::on_screen(&screen.stdout) + TerminalColor::from_output(&screen.stdout) } diff --git a/src/modules/style/mod.rs b/src/modules/style/mod.rs index d3a109c..4b499b3 100644 --- a/src/modules/style/mod.rs +++ b/src/modules/style/mod.rs @@ -1,4 +1,5 @@ -//! Module that contains all the actions related to the styling of the terminal. like coloring adding attributes etc. +//! A module that contains all the actions related to the styling of the terminal. +//! Like applying attributes to font and changing the foreground and background. pub mod color; pub mod objectstyle; @@ -25,14 +26,14 @@ use super::functions; use TerminalOutput; -/// This trait defines the actions that can be preformed with the terminal color. -/// This trait can be implemented so that an concrete implementation of the ITerminalColor can forfill +/// This trait defines the actions that can be preformed with terminal color. +/// This trait can be implemented so that a concrete implementation of the ITerminalColor can fulfill /// the wishes to work on an specific platform. /// /// ## For example: /// -/// This trait is implemented for `WINAPI` (Windows specific) and `ANSI` (Unix specific), -/// so that color related actions can be preformed on both unix and windows systems. +/// This trait is implemented for `WinApi` (Windows specific) and `ANSI` (Unix specific), +/// so that color-related actions can be performed on both UNIX and Windows systems. trait ITerminalColor { /// Set the foreground color to the given color. fn set_fg(&self, fg_color: Color, stdout: &Option<&Arc>); @@ -118,7 +119,7 @@ pub enum Color { AnsiValue(u8), } -/// Color types that can be used to determine if the Color enum is an Fore- or Background Color +/// Color types that can be used to determine if the Color enum is a Fore- or Background Color. #[derive(Debug, Copy, Clone)] pub enum ColorType { Background, @@ -126,14 +127,14 @@ pub enum ColorType { } impl<'a> From<&'a str> for Color { - /// Get an color from an &str like `Color::from("blue")` + /// Get an color from an &str like `Color::from("blue")`. fn from(src: &str) -> Self { src.parse().unwrap_or(Color::White) } } impl From for Color { - /// Get an color from an &str like `Color::from(String::from(blue))` + /// Get an color from an &str like `Color::from(String::from(blue))`. fn from(src: String) -> Self { src.parse().unwrap_or(Color::White) } diff --git a/src/modules/style/objectstyle.rs b/src/modules/style/objectstyle.rs index 3fc1aa7..dabcbd8 100644 --- a/src/modules/style/objectstyle.rs +++ b/src/modules/style/objectstyle.rs @@ -60,7 +60,7 @@ impl ObjectStyle { } #[cfg(unix)] - /// Add an attribute to the current text. Like italic or bold. + /// Add an `Attribute` to the current text. Like italic or bold. pub fn add_attr(&mut self, attr: Attribute) { self.attrs.push(attr); } diff --git a/src/modules/style/styledobject.rs b/src/modules/style/styledobject.rs index a6e9a46..1a8caa6 100644 --- a/src/modules/style/styledobject.rs +++ b/src/modules/style/styledobject.rs @@ -1,4 +1,4 @@ -//! This module contains the logic to style an object that contains some state witch can be styled. +//! This module contains the logic to style an object that contains some 'content' which can be styled. use super::{color, from_screen, Color, ObjectStyle}; use Screen; @@ -227,7 +227,7 @@ impl Display for StyledObject { } } -/// This is a wrapper for a styled object on alternate screen so that the styled object could be printed on the alternate screen with the standard write functions in rust. +/// This is a wrapper for a styled object on 'alternate screen' so that the styled object could be printed on the 'alternate screen' with the standard write functions in rust. /// /// ``` /// write! ("some normal text, {} <- some colored text", DisplayableObject::new(&screen, styled_object)); diff --git a/src/modules/style/winapi_color.rs b/src/modules/style/winapi_color.rs index 39eff1a..70602e5 100644 --- a/src/modules/style/winapi_color.rs +++ b/src/modules/style/winapi_color.rs @@ -1,13 +1,11 @@ -//! This is an `WINAPI` specific implementation for styling related action. -//! This module is used for non supporting `ANSI` windows terminals. -//! -//! Windows versions lower then windows 10 are not supporting ANSI codes. Those versions will use this implementation instead. +//! This is an `WinApi` specific implementation for styling related action. +//! This module is used for non supporting `ANSI` Windows terminals. use super::*; use kernel::windows_kernel::{csbi, kernel}; use winapi::um::wincon; -/// This struct is an windows implementation for color related actions. +/// This struct is a WinApi implementation for color related actions. pub struct WinApiColor { original_color: u16, } diff --git a/src/modules/terminal/mod.rs b/src/modules/terminal/mod.rs index 474e0da..d213364 100644 --- a/src/modules/terminal/mod.rs +++ b/src/modules/terminal/mod.rs @@ -1,9 +1,9 @@ -//! Module that contains all the actions related to the terminal. like clearing, resizing and scrolling the terminal. +//! A module that contains all the actions related to the terminal. like clearing, resizing, pausing and scrolling the terminal. #[cfg(test)] mod test; -pub mod terminal; +mod terminal; mod ansi_terminal; #[cfg(target_os = "windows")] @@ -13,7 +13,7 @@ use self::ansi_terminal::AnsiTerminal; #[cfg(target_os = "windows")] use self::winapi_terminal::WinApiTerminal; -pub use self::terminal::{from_screen, terminal, Terminal}; +pub use self::terminal::{terminal, from_screen, Terminal}; use super::functions; use std::sync::Arc; @@ -29,13 +29,13 @@ pub enum ClearType { } /// This trait defines the actions that can be preformed with the terminal color. -/// This trait can be implemented so that an concrete implementation of the ITerminalColor can forfill +/// This trait can be implemented so that an concrete implementation of the ITerminalColor can fulfill. /// the wishes to work on an specific platform. /// /// ## For example: /// -/// This trait is implemented for `WINAPI` (Windows specific) and `ANSI` (Unix specific), -/// so that color related actions can be preformed on both unix and windows systems. +/// This trait is implemented for `WinApi` (Windows specific) and `ANSI` (Unix specific), +/// so that terminal related actions can be preformed on both Unix and Windows systems. trait ITerminal { /// Clear the current cursor by specifying the clear type fn clear(&self, clear_type: ClearType, stdout: &Option<&Arc>); diff --git a/src/modules/terminal/terminal.rs b/src/modules/terminal/terminal.rs index 862fee0..334a306 100644 --- a/src/modules/terminal/terminal.rs +++ b/src/modules/terminal/terminal.rs @@ -1,11 +1,11 @@ -//! With this module you can perform actions that are terminal related. -//! Like clearing and scrolling in the terminal or getting the size of the terminal. +//! A module that contains all the actions related to the terminal. +//! Like clearing and scrolling in the terminal or getting the window size from the terminal. use super::*; use std::fmt; -/// Struct that stores an specific platform implementation for terminal related actions. +/// Struct that stores a platform-specific platform implementation for terminal related actions. /// /// Check `/examples/terminal` in the library for more specific examples. /// @@ -17,10 +17,9 @@ use std::fmt; /// term.scroll_down(5); /// term.scroll_up(4); /// let (with, height) = term.terminal_size(); -/// -/// When you want to use 'terminal' actions on 'alternate screen' use the `Screen` type instead, and pass it to the `terminal::from_screen()` function. -/// By doing that terminal actions will be performed on the alternate screen. /// ``` +/// When you want to use 'terminal' related actions on 'alternate screen' use the `Screen` type instead, and pass it to the `terminal::from_screen()` function. +/// By doing that terminal actions will be performed on the alternate screen. pub struct Terminal<'stdout> { terminal: Box, screen: Option<&'stdout Arc>, @@ -44,8 +43,23 @@ impl<'stdout> Terminal<'stdout> { } } - /// Create new instance of TerminalInput whereon input related actions could be preformed. - pub fn on_screen(stdout: &'stdout Arc) -> Terminal<'stdout> { + /// Create a new instance of `Terminal` whereon terminal related actions could be preformed on the given output. + /// + /// **Note** + /// + /// Use this function when you want your terminal to operate with a specific output. + /// This could be useful when you have a screen which is in 'alternate mode'. + /// And you want your actions from the `Terminal`, created by this function, to operate on the 'alternate screen'. + /// + /// # Example + /// ``` + /// let screen = Screen::default(); + // + /// if let Ok(alternate) = screen.enable_alternate_modes(false) { + /// let terminal = Terminal::from_output(&alternate.screen.stdout); + /// } + /// ``` + pub fn from_output(stdout: &'stdout Arc) -> Terminal<'stdout> { #[cfg(target_os = "windows")] let terminal = functions::get_module::>( Box::new(WinApiTerminal::new()), @@ -155,14 +169,13 @@ impl<'stdout> Terminal<'stdout> { } } -/// Get an terminal implementation whereon terminal related actions could performed. -/// Pass the reference to any screen you want this type to perform actions on. +/// Get a `Terminal` instance whereon terminal related actions could performed. pub fn terminal<'stdout>() -> Terminal<'stdout> { Terminal::new() } -/// Get an Terminal Color implementation whereon color related actions can be performed. -/// Pass the reference to any screen you want this type to perform actions on. +/// Get a `Terminal` instance whereon terminal related actions can be performed. +/// Pass the reference to any `Screen` you want this type to perform actions on. pub fn from_screen(screen: &Screen) -> Terminal { - Terminal::on_screen(&screen.stdout) + Terminal::from_output(&screen.stdout) }