From 88e628532c2572b08dbc3fe89970f9102001f7b7 Mon Sep 17 00:00:00 2001 From: c-bata Date: Sun, 13 Aug 2017 16:52:27 +0900 Subject: [PATCH] Update README and Add DEVELOPER_GUIDE --- _example/README.md => DEVELOPER_GUIDE.md | 85 ++++++++++++++++++++---- README.md | 65 +++++++++--------- _tools/README.md | 52 --------------- 3 files changed, 107 insertions(+), 95 deletions(-) rename _example/README.md => DEVELOPER_GUIDE.md (58%) delete mode 100644 _tools/README.md diff --git a/_example/README.md b/DEVELOPER_GUIDE.md similarity index 58% rename from _example/README.md rename to DEVELOPER_GUIDE.md index 4e01877..8ccdf2f 100644 --- a/_example/README.md +++ b/DEVELOPER_GUIDE.md @@ -1,12 +1,8 @@ -# Getting started +# Developer Guide -#### Download +## Getting Started -``` -$ go get -u github.com/c-bata/go-prompt -``` - -#### Usage +Most simple example is below. ```go package main @@ -23,14 +19,14 @@ func executor(in string) { } // completer returns the completion items from user input. -func completer(in string) []prompt.Suggest { +func completer(d prompt.Document) []prompt.Suggest { s := []prompt.Suggest{ {Text: "users", Description: "user table"}, {Text: "sites", Description: "sites table"}, {Text: "articles", Description: "articles table"}, {Text: "comments", Description: "comments table"}, } - return prompt.FilterHasPrefix(s, in, true) + return prompt.FilterHasPrefix(s, d.GetWordBeforeCursor(), true) } func main() { @@ -44,13 +40,16 @@ func main() { } ``` +If you want to create CLI using go-prompt, I recommend you to look at the [source code of kube-prompt](https://github.com/c-bata/kube-prompt). +It is the most practical example. -## Color Options + +## Options go-prompt has many color options. -It is difficult to describe by text. So please see below: +It is difficult to describe by text. So please see below figure: -![options](../_resources/prompt-options.png) +![options](https://github.com/c-bata/assets/raw/master/go-prompt/prompt-options.png) * **OptionPrefixTextColor(prompt.Color)** : default `prompt.Blue` * **OptionPrefixBackgroundColor(prompt.Color)** : default `prompt.DefaultColor` @@ -67,7 +66,7 @@ It is difficult to describe by text. So please see below: * **OptionSelectedDescriptionTextColor(prompt.Color)** : default `prompt.White` * **OptionSelectedDescriptionBGColor(prompt.Color)** : default `prompt.Cyan` -## Other Options +**Other Options** #### `OptionTitle(string)` : default `""` Option to set title displayed at the header bar of terminal. @@ -89,3 +88,63 @@ An argument should implement ConsoleParser interface. To set a custom ConsoleWriter object. An argument should implement ConsoleWriter interace. +#### `SwitchKeyBindMode(prompt.KeyBindMode)` : default `prompt.EmacsKeyBindMode` +To set a key bind mode. + +#### `OptionAddKeyBind(...KeyBind)` : default `[]KeyBind{}` +To set a custom key bind. + +## Architecture of go-prompt + +*Caution: This section is WIP.* + +This is a short description of go-prompt implementation. +go-prompt consists of three parts. + +1. Input parser +2. Emulate user input with Buffer object. +3. Render buffer object. + +### Input Parser + +![input-parser animation](https://github.com/c-bata/assets/raw/master/go-prompt/input-parser.gif) + +Input Parser only supports only vt100 compatible console now. + +* Set raw mode. +* Read standard input. +* Parse byte array + +### Emulate user input + +go-prompt contains Buffer class. +It represents input state by handling user input key. + +`Buffer` object has text and cursor position. + +**TODO prepare the sample of buffer** + +```go +package main + +import "github.com/c-bata/go-prompt" + +func main() { + b := prompt.NewBuffer() + ... wip +} +``` + +### Renderer + +`Renderer` object renders a buffer object. + +**TODO prepare the sample of brender** + +```go +package main +``` + +the output is below: + +**TODO prepare a screen shot** diff --git a/README.md b/README.md index 744a953..29b3cfe 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ # go-prompt -Library for building a powerful interactive prompt, inspired by python-prompt-toolkit. +Library for building a powerful interactive prompt, inspired by [python-prompt-toolkit](https://github.com/jonathanslenders/python-prompt-toolkit). Easy building a multi-platform binary of the command line tools because built with Golang. -#### Similar Projects +![demo](https://github.com/c-bata/assets/raw/master/go-prompt/kube-prompt.gif) -* [jonathanslenders/python-prompt-toolkit](https://github.com/jonathanslenders/python-prompt-toolkit): go-prompt is inspired by this library. -* [peterh/liner](https://github.com/peterh/liner): The most similar project in golang is **liner** that I've ever seen. +(This is a GIF animation of kube-prompt.) #### Projects using go-prompt @@ -14,19 +13,35 @@ Easy building a multi-platform binary of the command line tools because built wi ## Features -#### Powerful auto completion +### Flexible options -![demo](./_resources/kube-prompt.gif) +go-prompt provides many options. All options are listed in [Developer Guide](./DEVELOPER_GUIDE.md). -(This is a GIF animation of kube-prompt.) +![options](https://github.com/c-bata/assets/raw/master/go-prompt/prompt-options.png) -#### Keyboard Shortcuts +### Keyboard Shortcuts -![Keyboard shortcuts](./_resources/keyboard-shortcuts.gif) +Emacs-like keyboard shortcut is available by default (it's also default shortcuts in Bash shell). +You can customize and expand these shortcuts. -You can customize keyboard shortcuts. More details are available from 'KeyBoard Shortcuts' section in Developer Guide. +![keyboard shortcuts](https://github.com/c-bata/assets/raw/master/go-prompt/keyboard-shortcuts.gif) -#### Easy to use +KeyBinding | Description +--------------------|--------------------------------------------------------- +Ctrl + A | Go to the beginning of the line (Home) +Ctrl + E | Go to the End of the line (End) +Ctrl + P | Previous command (Up arrow) +Ctrl + N | Next command (Down arrow) +Ctrl + F | Forward one character +Ctrl + B | Backward one character +Ctrl + D | Delete character under the cursor +Ctrl + H | Delete character before the cursor (Backspace) +Ctrl + W | Cut the Word before the cursor to the clipboard. +Ctrl + K | Cut the Line after the cursor to the clipboard. +Ctrl + U | Cut/delete the Line before the cursor to the clipboard. + + +### Easy to use Usage is like this: @@ -38,13 +53,13 @@ import ( "github.com/c-bata/go-prompt" ) -func completer(buf prompt.Buffer) []prompt.Suggest { +func completer(d prompt.Document) []prompt.Suggest { s := []prompt.Suggest{ - {Text: "users", Description: "user table"}, - {Text: "sites", Description: "sites table"}, - {Text: "articles", Description: "articles table"}, + {Text: "users", Description: "Store the username and age"}, + {Text: "articles", Description: "Store the article text posted by user"}, + {Text: "comments", Description: "Store the text commented to articles"}, } - return prompt.FilterHasPrefix(s, buf.Text(), true) + return prompt.FilterHasPrefix(s, d.GetWordBeforeCursor(), true) } func main() { @@ -54,25 +69,15 @@ func main() { } ``` -More practical example is avairable from `_example` directory or [kube-prompt](https://github.com/c-bata/kube-prompt). +More practical example is available from `_example` directory and [a source code of kube-prompt](https://github.com/c-bata/kube-prompt). -#### Flexible customization -![options](./_resources/prompt-options.png) -go-prompt has many color options. All options are listed in [Developer Guide](./example/README.md). +## Links -#### History -**up-arrow** and **down-arrow** to walk through the command line history. - -![History](./_resources/history.gif) - -## Other Information - -* If you want to create projects using go-prompt, you might want to look at the [Getting Started](./example/README.md). -* If you want to contribute go-prompt, you might want to look at the [Developer Guide](./_tools/README.md). +* If you want to create CLI using go-prompt, you might want to look at the [Developer Guide](./DEVELOPER_GUIDE.md). +* If you want to contribute, you might want to look at the [ *Architecture of go-prompt* section in Developer Guide](./DEVELOPER_GUIDE.md). * If you want to know internal API, you might want to look at the [GoDoc](http://godoc.org/github.com/c-bata/go-prompt). - ## Author Masashi Shibata diff --git a/_tools/README.md b/_tools/README.md deleted file mode 100644 index d1ea00f..0000000 --- a/_tools/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# Internals of `go-prompt` - -This is a short description of go-prompt implementation. -go-prompt consists of three parts. - -1. Input parser -2. Emulate user input with Buffer object. -3. Render buffer object. - -### Input Parser - -![input-parser animation](./_resources/input-parser.gif) - -Input Parser only supports only vt100 compatible console now. - -* Set raw mode. -* Read standard input. -* Parse byte array - -### Emulate user input - -go-prompt contains Buffer class. -It represents input state by handling user input key. - -`Buffer` object has text and cursor position. - -**TODO prepare the sample of buffer** - -```go -package main - -import "github.com/c-bata/go-prompt" - -func main() { - b := prompt.NewBuffer() - ... wip -} -``` - -### Renderer - -`Renderer` object renders a buffer object. - -**TODO prepare the sample of brender** - -```go -package main -``` - -the output is below: - -**TODO prepare a screen shot**