Update README and Add DEVELOPER_GUIDE
This commit is contained in:
c-bata
parent
81ee67c776
commit
88e628532c
@ -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:
|
||||
|
||||
|
||||
|
||||
|
||||
* **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 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**
|
||||
65
README.md
65
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
|
||||
|
||||
|
||||
* [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
|
||||
|
||||
|
||||
go-prompt provides many options. All options are listed in [Developer Guide](./DEVELOPER_GUIDE.md).
|
||||
|
||||
(This is a GIF animation of kube-prompt.)
|
||||
|
||||
|
||||
#### Keyboard Shortcuts
|
||||
### Keyboard Shortcuts
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### Easy to use
|
||||
KeyBinding | Description
|
||||
--------------------|---------------------------------------------------------
|
||||
<kbd>Ctrl + A</kbd> | Go to the beginning of the line (Home)
|
||||
<kbd>Ctrl + E</kbd> | Go to the End of the line (End)
|
||||
<kbd>Ctrl + P</kbd> | Previous command (Up arrow)
|
||||
<kbd>Ctrl + N</kbd> | Next command (Down arrow)
|
||||
<kbd>Ctrl + F</kbd> | Forward one character
|
||||
<kbd>Ctrl + B</kbd> | Backward one character
|
||||
<kbd>Ctrl + D</kbd> | Delete character under the cursor
|
||||
<kbd>Ctrl + H</kbd> | Delete character before the cursor (Backspace)
|
||||
<kbd>Ctrl + W</kbd> | Cut the Word before the cursor to the clipboard.
|
||||
<kbd>Ctrl + K</kbd> | Cut the Line after the cursor to the clipboard.
|
||||
<kbd>Ctrl + U</kbd> | 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
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
@ -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 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**
|
||||
Loading…
Reference in New Issue
Block a user