Refactoring and docs

.travis.yml

@@ -1,3 +1,9 @@
+# Build only pushed (merged) master or any pull request. This avoids the
+# pull request to be build twice.
+branches:
+  only:
+    - master
+
 language: rust
 
 rust:

CHANGELOG.md

@@ -1,3 +1,9 @@
+# Version master
+
+- Improve the documentation
+  - Public API
+  - Include the book content in the documentation
+
 # Version 0.3.1
 
 - Maintenance release only

README.md

@@ -3,100 +3,72 @@
 # Crossterm Screen
 
 This crate allows you to work with alternate and raw screen cross-platform. 
-It supports all UNIX and windows terminals down to windows 7 (not all terminals are tested
-see [Tested Terminals](#tested-terminals) for more info)
+It supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested
+see [Tested Terminals](https://github.com/crossterm-rs/crossterm/blob/master/README.md#tested-terminals) for more info)
 
 `crossterm_screen` is a sub-crate of the [crossterm](https://crates.io/crates/crossterm) crate. You can use it
 directly, but it's **highly recommended** to use the [crossterm](https://crates.io/crates/crossterm) crate with
 the `screen` feature enabled (see [feature flags](https://crossterm-rs.github.io/crossterm/docs/feature_flags.html)
 for more info).
 
-## Future
-
-> The `crossterm_screen` crate code will be moved to the `crossterm` crate (it's reexported there now).
-> Date is not set yet, but it doesn't make a lot of sense to start a new project with it. Please, use
-> the `crossterm` crate with the `screen` feature enabled.
-
-Issues in this repository are disabled for the same reason. Please, report all issues in the
-[crossterm-rs/crossterm](https://github.com/crossterm-rs/crossterm/issues) repository.
-
-## Table of contents:
-
-- [Getting started](#getting-started)
-- [Useful links](#useful-links)
-- [Features](#features)
-- [Examples](#examples)
-- [Tested Terminals](#tested-terminals)
-- [Authors](#authors)
-- [License](#license)
-
 ## Getting Started
 
-All examples of how `crossterm_input` works can be found in the [examples](https://github.com/crossterm-rs/examples)
-repository. You might consider reading the [book](https://crossterm-rs.github.io/crossterm/docs/screen.html) which
-has a dedicated section on alternate and raw modes.
-
-Add the `crossterm_screen` package to your `Cargo.toml` file.
+<details>
+<summary>
+Click to show Cargo.toml.
+</summary>
 
-```
+```toml
 [dependencies]
-crossterm_screen = "0.3"
+# All crossterm features are enabled by default.
+crossterm = "0.11"
 ```
 
-And import the `crossterm_screen` modules you want to use.
+</details>
+<p></p>
+
+```rust
+use crossterm::RawScreen;
+
+fn main() -> Result<()> {
+    // Enable raw mode
+    let _raw = RawScreen::into_raw_mode()?;
 
-```rust  
-pub use crossterm_screen::{AlternateScreen, RawScreen};
+    // Do something in the raw mode
+} // `_raw` dropped here <- raw mode is disabled
 ```
 
-### Useful Links
+## Future
 
-- [Documentation](https://docs.rs/crossterm_screen/)
-- [Crates.io](https://crates.io/crates/crossterm_screen)
-- [Book](https://crossterm-rs.github.io/crossterm/docs/screen.html)
-- [Examples](https://github.com/crossterm-rs/examples)
+> The `crossterm_screen` crate code will be moved to the `crossterm` crate (it's reexported there now).
+> Date is not set yet, but it doesn't make a lot of sense to start a new project with it. Please, use
+> the `crossterm` crate with the `screen` feature enabled.
 
+Issues in this repository are disabled for the same reason. Please, report all issues in the
+[crossterm-rs/crossterm](https://github.com/crossterm-rs/crossterm/issues) repository.
+
 ## Features
 
-These are the features of this crate:
-
 - Cross-platform
 - Multi-threaded (send, sync)
-- Detailed Documentation
-- Few Dependencies
+- Detailed documentation
+- Few dependencies
 - Alternate screen
 - Raw screen   
-
-Planned features:
-- make is possible to switch between multiple buffers.
-
-## Examples
-
-The [examples](https://github.com/crossterm-rs/examples) repository has more complete and verbose examples.
 
-## Tested terminals
-
-- Windows Powershell
-    - Windows 10 (pro)
-- Windows CMD
-    - Windows 10 (pro)
-    - Windows 8.1 (N)
-- Ubuntu Desktop Terminal
-    - Ubuntu 17.10
-- (Arch, Manjaro) KDE Konsole
-- Linux Mint
-
-This crate supports all Unix terminals and windows terminals down to Windows 7 but not all of them have been tested.
-If you have used this library for a terminal other than the above list without issues feel free to add it to
-the above list, I really would appreciate it.
+## Other Resources
 
+- [API documentation](https://docs.rs/crossterm_screen/) (with other examples)
+- [Examples repository](https://github.com/crossterm-rs/examples)
+- [The Book](https://crossterm-rs.github.io/crossterm/docs/index.html)
+
 ## Authors
 
 * **Timon Post** - *Project Owner & creator*
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE.md](./LICENSE) file for details
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details
 
 [s1]: https://img.shields.io/crates/v/crossterm_screen.svg
 [l1]: https://crates.io/crates/crossterm_screen

src/lib.rs

@@ -1,7 +1,69 @@
-#![deny(unused_imports)]
+#![deny(unused_imports, unused_must_use)]
+
+//! # Screen
+//!
+//! The `crossterm_screen` crate provides a functionality to work with the terminal screen.
+//!
+//! This documentation does not contain a lot of examples. The reason is that it's fairly
+//! obvious how to use this crate. Although, we do provide
+//! [examples](https://github.com/crossterm-rs/examples) repository
+//! to demonstrate the capabilities.
+//!
+//! ## Screen Buffer
+//!
+//! A screen buffer is a two-dimensional array of characters and color data to be output in a console window.
+//! A terminal can have multiple of those screen buffers, and the active screen buffer is the one that is
+//! displayed on the screen.
+//!
+//! Crossterm allows you to switch between those buffers; the screen you are working in is called the
+//! 'main screen'. We call the other screen the 'alternate screen'. One note to take is that crossterm
+//! does not support the creation and switching between several buffers.
+//!
+//! ### Alternate Screen
+//!
+//! Normally you are working on the main screen but an alternate screen is somewhat different from a
+//! normal screen. For example, it has the exact dimensions of the terminal window, without any
+//! scroll back region. An example of this is vim when it is launched from bash.
+//!
+//! Vim uses the entirety of the screen to edit the file, then exits to bash leaving the original buffer unchanged.
+//!
+//! Crossterm provides the ability to switch to the alternate screen, make some changes, and then go back
+//! to the main screen. The main screen will still have its original data since we made all the edits on
+//! the alternate screen.
+//!
+//! ### Raw Mode
+//!
+//! To understand the concept of a 'raw mode' let's look at the following points:
+//!
+//! **No line buffering.**
+//!
+//! 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 to the screen buffer manually by the programmer.
+//!
+//! **Characters**
+//!
+//! The characters are not processed by the terminal driver. Also, special character has no meaning.
+//! For example, backspace will not be interpreted as backspace but instead will be sent directly to
+//! the terminal.
+//!
+//! **Escape Characters**
+//!
+//! Note that in raw mode `\n` `\r` will move the cursor to a new line but it will be at the
+//! same position as it was on the previous line.
+//!
+//! Example:
+//!
+//! ```text
+//! some text
+//!          some text
+//!```
+//!
+//! To start at the beginning of the next line, use `\n\r`.
 
-//! A module which provides some functionalities to work with the terminal screen.
-//! Like allowing you to switch between the main and alternate screen or putting the terminal into raw mode.
 pub use self::screen::{AlternateScreen, IntoRawMode, RawScreen};
 
 mod screen;

src/screen/alternate.rs

@@ -15,10 +15,30 @@ use crate::sys::{self, IAlternateScreenCommand};
 
 use super::RawScreen;
 
-/// With this type you will be able to switch to the alternate screen and then back to the main screen.
-/// Check also the Screen type for switching to alternate mode.
+/// An alternate screen.
 ///
-/// Although this type is available for you to use I would recommend using `Screen` instead.
+/// With this type you will be able to switch to the alternate screen and then back to
+/// the main screen.
+///
+/// Be aware that you'll be switched back to the main screen when you drop the
+/// `AlternateScreen` value.
+///
+/// # Examples
+///
+/// Alternate screen with raw mode enabled:
+///
+/// ```no_run
+/// use crossterm_screen::AlternateScreen;
+/// use crossterm_utils::Result;
+///
+/// fn main() -> Result<()> {
+///     let _alternate = AlternateScreen::to_alternate(true)?;
+///
+///     // Do something on the alternate screen in the raw mode
+///
+///     Ok(())
+/// } // `_alternate` dropped here <- raw mode disabled & back to main screen
+/// ```
 pub struct AlternateScreen {
     #[cfg(windows)]
     command: Box<(dyn IAlternateScreenCommand + Sync + Send)>,
@@ -28,15 +48,16 @@ pub struct AlternateScreen {
 }
 
 impl AlternateScreen {
-    /// Switch to the alternate screen. This function will return an `AlternateScreen` instance if everything went well. This type will give you control over the `AlternateScreen`.
+    /// Switches to the alternate screen.
+    ///
+    /// # Arguments
+    ///
+    /// * `raw_mode` - `true` enables the raw mode as well
     ///
-    /// The bool specifies whether the screen should be in raw mode or not.
+    /// # Notes
     ///
-    /// # What is Alternate screen?
-    /// *Nix style applications often utilize an alternate screen buffer, so that they can modify the entire contents of the buffer without affecting the application that started them.
-    /// The alternate buffer dimensions are exactly the same as the window, without any scrollback region.
-    /// For an example of this behavior, consider when vim is launched from bash.
-    /// Vim uses the entirety of the screen to edit the file, then returning to bash leaves the original buffer unchanged.
+    /// You'll be automatically switched to the main screen if this function
+    /// fails.
     pub fn to_alternate(raw_mode: bool) -> Result<AlternateScreen> {
         #[cfg(windows)]
         let command = if supports_ansi() {
@@ -66,14 +87,13 @@ impl AlternateScreen {
         Ok(alternate)
     }
 
-    /// Switch the alternate screen back to the main screen.
+    /// Switches to the main screen.
     pub fn to_main(&self) -> Result<()> {
         self.command.disable()
     }
 }
 
 impl Drop for AlternateScreen {
-    /// This will switch back to the main screen on drop.
     fn drop(&mut self) {
         let _ = self.to_main();
     }