From 8b5d34c8661c0ede5b35602179871bc8b8e255a5 Mon Sep 17 00:00:00 2001 From: T Date: Tue, 9 Jan 2018 20:36:48 +0100 Subject: [PATCH] Created better documentation and formatted code --- examples/bin.rs | 22 ++++- examples/color/examples.rs | 0 examples/terminal/examples.rs | 24 +++++ src/kernel/linux_kernel/terminal.rs | 2 +- src/kernel/windows_kernel/terminal.rs | 2 +- src/terminal/terminal.rs | 34 +++++++ src/terminal_cursor/cursor.rs | 109 ++++++++++++++++------ src/terminal_style/color/color.rs | 28 +----- src/terminal_style/styles/objectstyle.rs | 4 +- src/terminal_style/styles/styledobject.rs | 36 ++----- 10 files changed, 175 insertions(+), 86 deletions(-) create mode 100644 examples/color/examples.rs create mode 100644 examples/terminal/examples.rs diff --git a/examples/bin.rs b/examples/bin.rs index a3c9a8e..25aff3f 100644 --- a/examples/bin.rs +++ b/examples/bin.rs @@ -22,10 +22,28 @@ fn main() { let mut curs = cursor::get(); { curs.goto(4, 1).print("@"); - + } - terminal::get().clear(ClearType::UntilNewLine); + let mut terminal = terminal::get(); + + // clear all cells in terminal. + terminal.clear(ClearType::All); + // clear all cells after the cursor position in terminal. + terminal.clear(ClearType::AfterCursor); + // clear all cells before cursor in terminal. + terminal.clear(ClearType::BeforeCursor); + // clear current line cells in terminal. + terminal.clear(ClearType::CurrentLine); + // clear all cells until new line in terminal. + terminal.clear(ClearType::UntilNewLine); + + let size = terminal.terminal_size(); + println!("{:?}", size); + + // scrolling in terminal + terminal.scroll_up(1); + terminal.scroll_down(); cursor::get().goto(0,30); } diff --git a/examples/color/examples.rs b/examples/color/examples.rs new file mode 100644 index 0000000..e69de29 diff --git a/examples/terminal/examples.rs b/examples/terminal/examples.rs new file mode 100644 index 0000000..e602920 --- /dev/null +++ b/examples/terminal/examples.rs @@ -0,0 +1,24 @@ +fn main() +{ + let mut terminal = terminal::get(); + + // clear all cells in terminal. + terminal.clear(ClearType::All); + // clear all cells after the cursor position in terminal. + terminal.clear(ClearType::AfterCursor); + // clear all cells before cursor in terminal. + terminal.clear(ClearType::BeforeCursor); + // clear current line cells in terminal. + terminal.clear(ClearType::CurrentLine); + // clear all cells until new line in terminal. + terminal.clear(ClearType::UntilNewLine); + + // get terminal size (x,y) + let size = terminal.terminal_size(); + println!("{:?}", size); + + // scrolling in terminal + terminal.scroll_up(); + terminal.scroll_down(); + +} \ No newline at end of file diff --git a/src/kernel/linux_kernel/terminal.rs b/src/kernel/linux_kernel/terminal.rs index f0244be..c86d453 100644 --- a/src/kernel/linux_kernel/terminal.rs +++ b/src/kernel/linux_kernel/terminal.rs @@ -20,7 +20,7 @@ pub fn terminal_size() -> Option<(u16, u16)> { let mut winsize: libc::winsize = mem::zeroed(); libc::ioctl(libc::STDOUT_FILENO, libc::TIOCGWINSZ, &mut winsize); if winsize.ws_row > 0 && winsize.ws_col > 0 { - Some((winsize.ws_row as u16, winsize.ws_col as u16)) + Some((winsize.ws_col as u16, winsize.ws_row as u16)) } else { None } diff --git a/src/kernel/windows_kernel/terminal.rs b/src/kernel/windows_kernel/terminal.rs index bdecfa3..b8a4030 100644 --- a/src/kernel/windows_kernel/terminal.rs +++ b/src/kernel/windows_kernel/terminal.rs @@ -7,8 +7,8 @@ pub fn terminal_size() -> Option<(u16, u16)> { let csbi = kernel::get_console_screen_buffer_info(); Some(( - (csbi.srWindow.Bottom - csbi.srWindow.Top) as u16, (csbi.srWindow.Right - csbi.srWindow.Left) as u16, + (csbi.srWindow.Bottom - csbi.srWindow.Top) as u16, )) } diff --git a/src/terminal/terminal.rs b/src/terminal/terminal.rs index 7287562..011ac9d 100644 --- a/src/terminal/terminal.rs +++ b/src/terminal/terminal.rs @@ -15,6 +15,26 @@ impl Terminal { } } + /// Clear the current cursor by specifying the clear type + /// + /// #Example + /// + /// ```rust + /// + /// let mut terminal = terminal::get(); + /// + /// // clear all cells in terminal. + /// terminal.clear(ClearType::All); + /// //clear all cells after the cursor position in terminal. + /// terminal.clear(ClearType::AfterCursor); + /// // clear all cells before cursor in terminal. + /// terminal.clear(ClearType::BeforeCursor); + /// // clear current line cells in terminal. + /// terminal.clear(ClearType::CurrentLine); + /// // clear all cells from cursor position until new line in terminal. + /// terminal.clear(ClearType::UntilNewLine); + /// + /// ``` pub fn clear(&mut self, clear_type: ClearType) { &self.init(); if let Some(ref terminal) = self.terminal { @@ -22,6 +42,18 @@ impl Terminal { } } + /// Get the terminal size (x,y). + /// + /// #Example + /// + /// ```rust + /// + /// let mut terminal = terminal::get(); + /// + /// let size = terminal.terminal_size(); + /// println!("{:?}", size); + /// + /// ``` pub fn terminal_size(&mut self) -> Option<(u16, u16)> { &self.init(); if let Some(ref terminal) = self.terminal { @@ -32,6 +64,7 @@ impl Terminal { } } + /// Scroll `n` lines up in the current terminal. pub fn scroll_up(&mut self, count: i16) { for i in 0..100 { println!("Ik ben timon en dit is een test {}", i) @@ -43,6 +76,7 @@ impl Terminal { } } + /// Scroll `n` lines up in the current terminal. pub fn scroll_down(&self) {} } diff --git a/src/terminal_cursor/cursor.rs b/src/terminal_cursor/cursor.rs index dbaa823..2bc0e8f 100644 --- a/src/terminal_cursor/cursor.rs +++ b/src/terminal_cursor/cursor.rs @@ -3,36 +3,27 @@ use Construct; use super::base_cursor::ITerminalCursor; use super::{AnsiCursor, NoCursor, WinApiCursor}; -/// Struct with the cursor on wits cursor realated actions can be performed. +/// Struct on wits cursor realated actions can be performed. pub struct TerminalCursor { terminal_cursor: Option>, } -// impl Clone for TerminalCursor { -// fn clone(&self) -> TerminalCursor { *self } -// } - impl TerminalCursor { - /// Instantiate an cursor implementation whereon cursor related actions can be performed. + /// Instantiates an platform specific cursor implementation whereon cursor related actions can be performed. pub fn init(&mut self) { if let None = self.terminal_cursor { self.terminal_cursor = get_cursor_options(); } } - /// Goto some location (x,y) in the terminal. + /// Goto some position (x,y) in the terminal. /// /// #Example /// /// ```rust - /// extern crate crossterm; /// - /// use self::crossterm::terminal_cursor::{cursor,TerminalCursor}; - - /// fn main() - /// { /// cursor::get().goto(10,10); - /// } + /// /// ``` pub fn goto(&mut self, x: u16, y: u16) -> &mut TerminalCursor { &self.init(); @@ -42,7 +33,17 @@ impl TerminalCursor { self } - pub fn pos(mut self) -> (i16, i16) { + /// Get current cursor position (x,y) in the terminal. + /// + /// #Example + /// + /// ```rust + /// + /// let pos = cursor::get().pos(); + /// println!("{:?}", pos); + /// + /// ``` + pub fn pos(&mut self) -> (i16, i16) { &self.init(); if let Some(ref terminal_cursor) = self.terminal_cursor { terminal_cursor.pos() @@ -51,24 +52,17 @@ impl TerminalCursor { } } - /// Print an value at the current cursor location. + /// Move the current cursor position `n` times up. /// /// #Example /// /// ```rust - /// extern crate crossterm; - /// - /// use self::crossterm::terminal_cursor::{cursor,TerminalCursor}; - - /// fn main() - /// { - /// // of course we can just do this. - /// print!("@"). - /// // but now we can chain the methods so it looks cleaner. - /// cursor::get() - /// .goto(10,10) - /// .print("@"); - /// } + /// + /// // move 1 time up + /// cursor::get().move_up(1); + /// + /// // move 2 time up + /// cursor::get().move_up(2); /// /// ``` pub fn move_up(&mut self, count: u16) -> &mut TerminalCursor { &self.init(); @@ -78,6 +72,19 @@ impl TerminalCursor { self } + /// Move the current cursor position `n` times right. + /// + /// #Example + /// + /// ```rust + /// + /// // move 1 time right + /// cursor::get().move_right(1); + /// + /// // move 2 time right + /// cursor::get().move_right(2); + /// + /// ``` pub fn move_right(&mut self, count: u16) -> &mut TerminalCursor { &self.init(); if let Some(ref terminal_cursor) = self.terminal_cursor { @@ -86,6 +93,19 @@ impl TerminalCursor { self } + /// Move the current cursor position `n` times down. + /// + /// #Example + /// + /// ```rust + /// + /// // move 1 time down + /// cursor::get().move_down(1); + /// + /// // move 2 time down + /// cursor::get().move_down(2); + /// + /// ``` pub fn move_down(&mut self, count: u16) -> &mut TerminalCursor { &self.init(); if let Some(ref terminal_cursor) = self.terminal_cursor { @@ -94,6 +114,19 @@ impl TerminalCursor { self } + /// Move the current cursor position `n` times left. + /// + /// #Example + /// + /// ```rust + /// + /// // move 1 time left + /// cursor::get().move_left(1); + /// + /// // move 2 time left + /// cursor::get().move_left(2); + /// + /// ``` pub fn move_left(&mut self, count: u16) -> &mut TerminalCursor { &self.init(); if let Some(ref terminal_cursor) = self.terminal_cursor { @@ -102,10 +135,30 @@ impl TerminalCursor { self } + /// Print an value at the current cursor position. + /// + /// This method prints an value and clears the buffer. + /// If you do not clear the buffer the character will not be printed at the wished position. + /// #Example + /// + /// ```rust + /// + /// // of course we can just do this. + /// cursor::get().goto(10,10); + /// print!("@"); + /// std::io::stdout().flush(); + /// + /// // but now we can chain the methods so it looks cleaner and it automatically flushes the buffer. + /// cursor::get() + /// .goto(10,10) + /// .print("@"); + /// + /// ``` pub fn print(&mut self, value: D) -> &mut TerminalCursor { print!("{}", value); use std; use std::io::Write; + // rust is line buffered so we need to flush the buffer in order to print it at the current cursor position. std::io::stdout().flush(); self } diff --git a/src/terminal_style/color/color.rs b/src/terminal_style/color/color.rs index 98f2fdb..ce10535 100644 --- a/src/terminal_style/color/color.rs +++ b/src/terminal_style/color/color.rs @@ -41,34 +41,12 @@ pub enum ColorType { Foreground, } -/// Enables an user to pass in an color as str. -/// *Default color if cannot be parsed will be white.* -/// -/// # Example -/// -/// ``` rust -/// let fg_color = Color::from("red"); -/// let bg_color = Color::from("blue"); -/// -/// println!("{}",paint("■").with(fg_color).on(bg_color)); -/// ``` impl<'a> From<&'a str> for Color { fn from(src: &str) -> Self { src.parse().unwrap_or(Color::White) } } -/// Enables an user to pass in an color as String. -/// *Default color if cannot be parsed will be white.* -/// -/// # Example -/// -/// ``` rust -/// let fg_color = Color::from(String::from("red")); -/// let bg_color = Color::from(String::from("blue")); -/// -/// println!("{}",paint("■").with(fg_color).on(bg_color)); -/// ``` impl From for Color { fn from(src: String) -> Self { src.parse().unwrap_or(Color::White) @@ -102,7 +80,7 @@ impl FromStr for Color { } } -/// Struct on wits the color realated actions can be performed. +/// Struct on wits color realated actions can be performed. pub struct TerminalColor { terminal_color: Option>, } @@ -149,7 +127,7 @@ impl TerminalColor { } } - /// Reset the terminal colors to default. + /// Reset the terminal colors and attributes to default. /// # Example /// /// ```rust @@ -166,7 +144,7 @@ impl TerminalColor { } } -/// Get the concrete ITerminalColor implementation based on the current operating system. +/// Get an concrete ITerminalColor implementation based on the current operating system. fn get_color_options() -> Option> { if cfg!(target_os = "linux") { Some(ANSIColor::new()) diff --git a/src/terminal_style/styles/objectstyle.rs b/src/terminal_style/styles/objectstyle.rs index fc99b18..fe83450 100644 --- a/src/terminal_style/styles/objectstyle.rs +++ b/src/terminal_style/styles/objectstyle.rs @@ -18,7 +18,7 @@ impl Default for ObjectStyle { } impl ObjectStyle { - /// Get an `StyledObject` from the passed displayable object. + /// Apply an `StyledObject` to the passed displayable object. pub fn apply_to(&self, val: D) -> StyledObject where D: Display, @@ -29,7 +29,7 @@ impl ObjectStyle { } } - /// Get an instance of `ObjectStyle` + /// Get an new instance of `ObjectStyle` pub fn new() -> ObjectStyle { return ObjectStyle { fg_color: None, diff --git a/src/terminal_style/styles/styledobject.rs b/src/terminal_style/styles/styledobject.rs index 43e72ba..21f4211 100644 --- a/src/terminal_style/styles/styledobject.rs +++ b/src/terminal_style/styles/styledobject.rs @@ -16,23 +16,17 @@ impl StyledObject { /// #Example /// /// ```rust - /// extern crate crossterm; - /// - /// use self::crossterm::terminal_style::{paint,Color}; - /// - /// fn main() - /// { /// // create an styled object with the foreground color red. /// let styledobject = paint("I am colored red").with(Color::Red); /// // create an styled object with the foreground color blue. /// let styledobject1 = paint("I am colored blue").with(Color::Blue); /// - /// // print the styled objects + /// // print the styledobject to see the result /// println!("{}", styledobject); /// println!("{}", styledobject1); - /// // or print an styled object directly. - /// println!("{}", paint("I am colored green").with(Color::Green)) - /// } + /// // print an styled object directly. + /// println!("{}", paint("I am colored green").with(Color::Green)); + /// /// ``` pub fn with(mut self, foreground_color: Color) -> StyledObject { self.object_style = self.object_style.fg(foreground_color); @@ -44,23 +38,18 @@ impl StyledObject { /// #Example /// /// ```rust - /// extern crate crossterm; - /// - /// use self::crossterm::terminal_style::{paint,Color}; - /// - /// fn main() - /// { + /// /// // create an styled object with the background color red. /// let styledobject = paint("I am colored red").on(Color::Red); /// // create an styled object with the background color blue. /// let styledobject1 = paint("I am colored blue").on(Color::Blue); /// - /// // print the styled objects + /// // print the styledobjects /// println!("{}", styledobject); /// println!("{}", styledobject1); - /// // or print an styled object directly. + /// // print an styled object directly. /// println!("{}", paint("I am colored green").on(Color::Green)) - /// } + /// /// ``` pub fn on(mut self, background_color: Color) -> StyledObject { self.object_style = self.object_style.bg(background_color); @@ -69,8 +58,7 @@ impl StyledObject { } /// This is used to make StyledObject able to be displayed. -/// This macro will set the styled stored in Styled Object - +/// This macro will set the styles stored in Styled Object macro_rules! impl_fmt { ($name:ident) => { @@ -104,11 +92,5 @@ macro_rules! impl_fmt } } -/// This inplements Display for StyledObject -/// Notice that more implementations can be maked. -/// # Example -/// ```rust -/// example impl_fmt!(Debug); -/// ``` impl_fmt!(Debug); impl_fmt!(Display);