blasthavers/minicrossterm
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor and grammer check for all comments.

Browse Source
This commit is contained in:
Timon 2018-11-28 16:42:05 +01:00
parent 387c088318
commit f369a686ee
30 changed files with 219 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/common/commands/mod.rs
View File

@ -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;

2
src/common/commands/shared_commands.rs
View File

@ -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};

3
src/common/commands/unix_command.rs
View File

@ -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;

2
src/common/commands/win_commands.rs
View File

@ -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};

18
src/common/crossterm.rs
View File

@ -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;

10
src/common/functions.rs
View File

@ -60,6 +60,11 @@ pub fn get_module<T>(winapi_impl: T, unix_impl: T) -> Option<T> {
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<TerminalOutput>>, string: String) -> io::Result<usize> {
match stdout {
None => {
@ -74,6 +79,11 @@ pub fn write(stdout: &Option<&Arc<TerminalOutput>>, 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<TerminalOutput>>, string: &str) -> io::Result<usize> {
match stdout {
None => match io::stdout().flush() {

4
src/common/screen/mod.rs
View File

@ -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;

26
src/common/screen/screen.rs
View File

@ -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<TerminalOutput> 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<TerminalOutput> for Screen {
}
impl From<Arc<TerminalOutput>> for Screen {
/// Create an screen with the given 'Arc<Stdout>'
/// Create a screen with the given 'Arc<Stdout>'
fn from(stdout: Arc<TerminalOutput>) -> Self {
Screen {
stdout,
@ -151,7 +151,7 @@ impl From<Arc<TerminalOutput>> 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();

21
src/lib.rs
View File

@ -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;

6
src/modules/cursor/ansi_cursor.rs
View File

@ -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 {

34
src/modules/cursor/cursor.rs
View File

@ -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::<Box<ITerminalCursor + Sync + Send>>(
@ -51,7 +51,23 @@ impl<'stdout> TerminalCursor<'stdout> {
}
}
pub fn on_screen(stdout: &'stdout Arc<TerminalOutput>) -> 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<TerminalOutput>) -> TerminalCursor<'stdout> {
#[cfg(target_os = "windows")]
let cursor = functions::get_module::<Box<ITerminalCursor + Sync + Send>>(
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)
}

18
src/modules/cursor/mod.rs
View File

@ -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<TerminalOutput>>);
/// 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<TerminalOutput>>);

8
src/modules/cursor/winapi_cursor.rs
View File

@ -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 {

40
src/modules/input/input.rs
View File

@ -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<ITerminalInput + Sync + Send>,
stdout: Option<&'stdout Arc<TerminalOutput>>,
}
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<TerminalOutput>) -> 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<TerminalOutput>) -> 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)
}

12
src/modules/input/mod.rs
View File

@ -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<TerminalOutput>>) -> io::Result<String>;
@ -47,7 +47,7 @@ pub struct AsyncReader {
recv: mpsc::Receiver<io::Result<u8>>,
}
// 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),

2
src/modules/input/unix_input.rs
View File

@ -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};

2
src/modules/input/windows_input.rs
View File

@ -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::*;

2
src/modules/output/ansi_output.rs
View File

@ -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;

6
src/modules/output/mod.rs
View File

@ -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<usize>;

21
src/modules/output/output.rs
View File

@ -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<IStdout + Send + Sync>,
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<IStdout + Send + Sync> =

2
src/modules/output/winapi_output.rs
View File

@ -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 {

4
src/modules/style/ansi_color.rs
View File

@ -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::*;

34
src/modules/style/color.rs
View File

@ -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<TerminalOutput>) -> 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<TerminalOutput>) -> TerminalColor<'stdout> {
#[cfg(target_os = "windows")]
let color = functions::get_module::<Box<ITerminalColor + Sync + Send>>(
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)
}

17
src/modules/style/mod.rs
View File

@ -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<TerminalOutput>>);
@ -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<String> 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)
}

2
src/modules/style/objectstyle.rs
View File

@ -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);
}

4
src/modules/style/styledobject.rs
View File

@ -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<D: Display> Display for StyledObject<D> {
}
}
/// 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));

8
src/modules/style/winapi_color.rs
View File

@ -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,
}

12
src/modules/terminal/mod.rs
View File

@ -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<TerminalOutput>>);

39
src/modules/terminal/terminal.rs
View File

@ -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<ITerminal + Sync + Send>,
screen: Option<&'stdout Arc<TerminalOutput>>,
@ -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<TerminalOutput>) -> 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<TerminalOutput>) -> Terminal<'stdout> {
#[cfg(target_os = "windows")]
let terminal = functions::get_module::<Box<ITerminal + Sync + Send>>(
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)
}