From 0938f6e561ceccf572018c9adc97844d8c8d258e Mon Sep 17 00:00:00 2001
From: gwenn <gtreguier@gmail.com>
Date: Sat, 22 Apr 2017 13:10:21 +0200
Subject: [PATCH] Add some doc
---
src/completion.rs | 2 +-
src/config.rs | 4 ++++
src/consts.rs | 6 +++---
src/history.rs | 2 ++
src/keymap.rs | 14 ++++++++++----
src/lib.rs | 4 +++-
src/line_buffer.rs | 12 ++++++++++++
7 files changed, 35 insertions(+), 9 deletions(-)
diff --git a/src/completion.rs b/src/completion.rs
index 9c07c4d2..93f09fe2 100644
--- a/src/completion.rs
+++ b/src/completion.rs
@@ -124,7 +124,7 @@ pub fn unescape(input: &str, esc_char: Option<char>) -> Cow<str> {
/// Escape any `break_chars` in `input` string with `esc_char`.
/// For example, '/User Information' becomes '/User\ Information'
-/// when space is a breaking char and '\' the escape char.
+/// when space is a breaking char and '\\' the escape char.
pub fn escape(input: String, esc_char: Option<char>, break_chars: &BTreeSet<char>) -> String {
if esc_char.is_none() {
return input;
diff --git a/src/config.rs b/src/config.rs
index 3be614c8..5b8261c7 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,6 +1,7 @@
//! Customize line editor
use std::default::Default;
+/// User preferences
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Config {
/// Maximum number of entries in History.
@@ -73,6 +74,7 @@ impl Default for Config {
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum HistoryDuplicates {
AlwaysAdd,
+ /// a line will not be added to the history if it matches the previous entry
IgnoreConsecutive,
}
@@ -86,12 +88,14 @@ pub enum CompletionType {
List,
}
+/// Style of editing / Standard keymaps
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum EditMode {
Emacs,
Vi,
}
+/// Configuration builder
#[derive(Debug, Default)]
pub struct Builder {
p: Config,
diff --git a/src/consts.rs b/src/consts.rs
index 130ebc1b..ce9258a4 100644
--- a/src/consts.rs
+++ b/src/consts.rs
@@ -37,7 +37,7 @@ pub fn char_to_key_press(c: char) -> KeyPress {
'\x06' => KeyPress::Ctrl('F'),
'\x07' => KeyPress::Ctrl('G'),
'\x08' => KeyPress::Backspace, // '\b'
- '\x09' => KeyPress::Tab,
+ '\x09' => KeyPress::Tab, // '\t'
'\x0a' => KeyPress::Ctrl('J'), // '\n' (10)
'\x0b' => KeyPress::Ctrl('K'),
'\x0c' => KeyPress::Ctrl('L'),
@@ -53,9 +53,9 @@ pub fn char_to_key_press(c: char) -> KeyPress {
'\x18' => KeyPress::Ctrl('X'),
'\x19' => KeyPress::Ctrl('Y'),
'\x1a' => KeyPress::Ctrl('Z'),
- '\x1b' => KeyPress::Esc,
+ '\x1b' => KeyPress::Esc, // Ctrl-[
'\x1f' => KeyPress::Ctrl('_'),
- '\x7f' => KeyPress::Backspace,
+ '\x7f' => KeyPress::Backspace, // Rubout
_ => KeyPress::Null,
}
}
diff --git a/src/history.rs b/src/history.rs
index 9b3e6dbd..0f925c13 100644
--- a/src/history.rs
+++ b/src/history.rs
@@ -12,6 +12,7 @@ use libc;
use super::Result;
use config::{Config, HistoryDuplicates};
+/// Search direction
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Direction {
Forward,
@@ -155,6 +156,7 @@ impl History {
self.search_match(term, start, dir, test)
}
+ /// Anchored search
pub fn starts_with(&self, term: &str, start: usize, dir: Direction) -> Option<usize> {
let test = |entry: &String| entry.starts_with(term);
self.search_match(term, start, dir, test)
diff --git a/src/keymap.rs b/src/keymap.rs
index 6d215a06..753cb677 100644
--- a/src/keymap.rs
+++ b/src/keymap.rs
@@ -9,8 +9,10 @@ use consts::KeyPress;
use tty::RawReader;
use super::Result;
+/// The number of times one command should be repeated.
pub type RepeatCount = usize;
+/// Commands
#[derive(Debug, Clone, PartialEq)]
pub enum Cmd {
Abort, // Miscellaneous Command
@@ -101,16 +103,18 @@ fn repeat_count(previous: RepeatCount, new: Option<RepeatCount>) -> RepeatCount
}
}
+/// Different word definitions
#[derive(Debug, Clone, PartialEq, Copy)]
pub enum Word {
- // non-blanks characters
+ /// non-blanks characters
Big,
- // alphanumeric characters
+ /// alphanumeric characters
Emacs,
- // alphanumeric (and '_') characters
+ /// alphanumeric (and '_') characters
Vi,
}
+/// Where to move with respect to word boundary
#[derive(Debug, Clone, PartialEq, Copy)]
pub enum At {
Start,
@@ -118,12 +122,14 @@ pub enum At {
AfterEnd,
}
+/// Where to paste (relative to cursor position)
#[derive(Debug, Clone, PartialEq, Copy)]
pub enum Anchor {
After,
Before,
}
+/// Vi charecter search
#[derive(Debug, Clone, PartialEq)]
pub enum CharSearch {
Forward(char),
@@ -145,7 +151,7 @@ impl CharSearch {
}
}
-
+// Where to move
#[derive(Debug, Clone, PartialEq)]
pub enum Movement {
WholeLine, // not really a movement
diff --git a/src/lib.rs b/src/lib.rs
index d3ecc1f5..8b677376 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -72,7 +72,7 @@ pub type Result<T> = result::Result<T, error::ReadlineError>;
struct State<'out, 'prompt> {
out: &'out mut Write,
prompt: &'prompt str, // Prompt to display
- prompt_size: Position, // Prompt Unicode width and height
+ prompt_size: Position, // Prompt Unicode/visible width and height
line: LineBuffer, // Edited line buffer
cursor: Position, // Cursor position (relative to the start of the prompt for `row`)
cols: usize, // Number of columns in terminal
@@ -566,6 +566,7 @@ fn edit_history_next(s: &mut State, history: &History, prev: bool) -> Result<()>
s.refresh_line()
}
+// Non-incremental, anchored search
fn edit_history_search(s: &mut State, history: &History, dir: Direction) -> Result<()> {
if history.is_empty() {
return beep();
@@ -1274,6 +1275,7 @@ impl<C: Completer> fmt::Debug for Editor<C> {
}
}
+/// Edited lines iterator
pub struct Iter<'a, C: Completer>
where C: 'a
{
diff --git a/src/line_buffer.rs b/src/line_buffer.rs
index c6b1bbcd..637079cd 100644
--- a/src/line_buffer.rs
+++ b/src/line_buffer.rs
@@ -12,12 +12,14 @@ use keymap::{At, CharSearch, Movement, RepeatCount, Word};
/// Maximum buffer size for the line read
pub static MAX_LINE: usize = 4096;
+/// Word's case change
pub enum WordAction {
CAPITALIZE,
LOWERCASE,
UPPERCASE,
}
+/// Delete (kill) direction
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Direction {
Forward,
@@ -30,16 +32,19 @@ impl Default for Direction {
}
}
+/// Listener to be notified when the some text is deleted.
pub trait DeleteListener {
fn delete(&mut self, idx: usize, string: &str, dir: Direction);
}
+/// Listener to be notified when the line is modified.
pub trait ChangeListener: DeleteListener {
fn insert_char(&mut self, idx: usize, c: char);
fn insert_str(&mut self, idx: usize, string: &str);
fn replace(&mut self, idx: usize, old: &str, new: &str);
}
+/// Line buffer
pub struct LineBuffer {
buf: String, // Edited line buffer
pos: usize, // Current cursor position (byte position)
@@ -508,6 +513,8 @@ impl LineBuffer {
}
}
+ /// Move cursor to the matching character position.
+ /// Return `true` when the search succeeds.
pub fn move_to(&mut self, cs: CharSearch, n: RepeatCount) -> bool {
if let Some(pos) = self.search_char_pos(&cs, n) {
self.pos = pos;
@@ -639,6 +646,8 @@ impl LineBuffer {
self.pos = start + text.len();
}
+ /// Insert the `s`tring at the specified position.
+ /// Return `true` if the text has been inserted at the end of the line.
pub fn insert_str(&mut self, idx: usize, s: &str) -> bool {
for cl in &self.cl {
cl.borrow_mut().insert_str(idx, s);
@@ -652,6 +661,7 @@ impl LineBuffer {
}
}
+ /// Remove the specified `range` in the line.
pub fn delete_range(&mut self, range: Range<usize>) {
self.set_pos(range.start);
self.drain(range, Direction::default());
@@ -669,6 +679,8 @@ impl LineBuffer {
self.buf.drain(range)
}
+ /// Return the content between current cursor position and `mvt` position.
+ /// Return `None` when the buffer is empty or when the movement fails.
pub fn copy(&self, mvt: Movement) -> Option<String> {
if self.is_empty() {
return None;
--
GitLab