Skip to content

Commit

Permalink
add go module
Browse files Browse the repository at this point in the history
  • Loading branch information
abiosoft committed Jun 2, 2021
1 parent 1b6ad7e commit 1c52a1a
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 32 deletions.
92 changes: 63 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,10 @@
# ishell

ishell is an interactive shell library for creating interactive cli applications.

[![Documentation](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://godoc.org/github.com/abiosoft/ishell)
[![Go Report Card](https://goreportcard.com/badge/github.com/abiosoft/ishell)](https://goreportcard.com/report/github.com/abiosoft/ishell)

## Older version
The current master is not backward compatible with older version. Kindly change your import path to `gopkg.in/abiosoft/ishell.v1`.

Older version of this library is still available at [https://gopkg.in/abiosoft/ishell.v1](https://gopkg.in/abiosoft/ishell.v1).

However, you are advised to upgrade to v2 [https://gopkg.in/abiosoft/ishell.v2](https://gopkg.in/abiosoft/ishell.v2).

## Usage

```go
Expand Down Expand Up @@ -38,7 +32,9 @@ func main(){
shell.Run()
}
```

Execution

```
Sample Interactive Shell
>>> help
Expand All @@ -56,6 +52,7 @@ $
```

### Reading input

```go
// simulate an authentication
shell.AddCmd(&ishell.Cmd{
Expand All @@ -80,7 +77,9 @@ shell.AddCmd(&ishell.Cmd{
},
})
```

Execution

```
>>> login
Username: someusername
Expand All @@ -89,7 +88,9 @@ Authentication Successful.
```

### Multiline input

Builtin support for multiple lines.

```
>>> This is \
... multi line
Expand All @@ -99,7 +100,9 @@ Builtin support for multiple lines.
... as a single argument.
... EOF
```

User defined

```go
shell.AddCmd(&ishell.Cmd{
Name: "multi",
Expand All @@ -112,7 +115,9 @@ shell.AddCmd(&ishell.Cmd{
},
})
```

Execution

```
>>> multi
Input multiple lines and end with semicolon ';'.
Expand All @@ -122,16 +127,21 @@ You wrote:
this is user defined
multiline input;
```

### Keyboard interrupt

Builtin interrupt handler.

```
>>> ^C
Input Ctrl-C once more to exit
>>> ^C
Interrupted
exit status 1
```

Custom

```go
shell.Interrupt(func(count int, c *ishell.Context) { ... })
```
Expand All @@ -153,7 +163,9 @@ func(c *ishell.Context) {
}
},
```

Output

```
What are Go programmers called ?
Golangers
Expand All @@ -163,7 +175,9 @@ What are Go programmers called ?
You got it!
```

### Checklist

```go
func(c *ishell.Context) {
languages := []string{"Python", "Go", "Haskell", "Rust"}
Expand All @@ -173,7 +187,9 @@ func(c *ishell.Context) {
c.Println("Your choices are", strings.Join(out(), ", "))
}
```

Output

```
What are your favourite programming languages ?
Python
Expand All @@ -185,7 +201,9 @@ Your choices are Go, Rust
```

### Progress Bar

Determinate

```go
func(c *ishell.Context) {
c.ProgressBar().Start()
Expand All @@ -197,12 +215,15 @@ func(c *ishell.Context) {
c.ProgressBar().Stop()
}
```

Output

```
[==========> ] 50%
```

Indeterminate

```go

func(c *ishell.Context) {
Expand All @@ -212,12 +233,15 @@ func(c *ishell.Context) {
c.ProgressBar().Stop()
}
```

Output

```
[ ==== ]
```

Custom display using [briandowns/spinner](https://github.com/briandowns/spinner).

```go
display := ishell.ProgressDisplayCharSet(spinner.CharSets[11])
func(c *Context) { c.ProgressBar().Display(display) ... }
Expand All @@ -227,13 +251,14 @@ ishell.ProgressBar().Display(display)
```

### Durable history

```go
// Read and write history to $HOME/.ishell_history
shell.SetHomeHistoryPath(".ishell_history")
```


### Non-interactive execution

In some situations it is desired to exit the program directly after executing a single command.

```go
Expand All @@ -256,8 +281,8 @@ $ go run main.go exit greet Someusername
Hello Someusername
```


### Output with Color

You can use [fatih/color](https://github.com/fatih/color).

```go
Expand All @@ -266,56 +291,65 @@ func(c *ishell.Context) {
c.Println(yellow("This line is yellow"))
}
```

Execution

```sh
>>> color
This line is yellow
```


### Example

Available [here](https://github.com/abiosoft/ishell/blob/master/example/main.go).

```sh
go run example/main.go
```

## Supported Platforms
* [x] Linux
* [x] OSX
* [x] Windows [Not tested but should work]

- [x] Linux
- [x] OSX
- [x] Windows [Not tested but should work]

## Note

ishell is in active development and can still change significantly.

## Roadmap (in no particular order)
* [x] Multiline inputs
* [x] Command history
* [x] Customizable tab completion
* [x] Handle ^C interrupts
* [x] Subcommands and help texts
* [x] Scrollable paged output
* [x] Progress bar
* [x] Multiple choice prompt
* [x] Checklist prompt
* [x] Support for command aliases
* [ ] Multiple line progress bars
* [ ] Testing, testing, testing

- [x] Multiline inputs
- [x] Command history
- [x] Customizable tab completion
- [x] Handle ^C interrupts
- [x] Subcommands and help texts
- [x] Scrollable paged output
- [x] Progress bar
- [x] Multiple choice prompt
- [x] Checklist prompt
- [x] Support for command aliases
- [ ] Multiple line progress bars
- [ ] Testing, testing, testing

## Contribution

1. Create an issue to discuss it.
2. Send in Pull Request.

## License

MIT

## Credits
Library | Use
------- | -----
[github.com/flynn-archive/go-shlex](https://github.com/flynn-archive/go-shlex) | splitting input into command and args.
[github.com/chzyer/readline](https://github.com/chzyer/readline) | readline capabilities.

| Library | Use |
| ------------------------------------------------------------------------------ | -------------------------------------- |
| [github.com/flynn-archive/go-shlex](https://github.com/flynn-archive/go-shlex) | splitting input into command and args. |
| [github.com/chzyer/readline](https://github.com/chzyer/readline) | readline capabilities. |

## Donate

```
bitcoin: 1GTHYEDiy2C7RzXn5nY4wVRaEN2GvLjwZN
paypal: a@abiosoft.com
Expand Down
6 changes: 3 additions & 3 deletions example/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ func main() {
// display info.
shell.Println("Sample Interactive Shell")

//Consider the unicode characters supported by the users font
//shell.SetMultiChoicePrompt(" >>"," - ")
//shell.SetChecklistOptions("[ ] ","[X] ")
// Consider the unicode characters supported by the users font
// shell.SetMultiChoicePrompt(" >>"," - ")
// shell.SetChecklistOptions("[ ] ","[X] ")

// handle login.
shell.AddCmd(&ishell.Cmd{
Expand Down
12 changes: 12 additions & 0 deletions go.mod
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
module github.com/abiosoft/ishell

go 1.16

require (
github.com/abiosoft/readline v0.0.0-20180607040430-155bce2042db
github.com/chzyer/logex v1.1.10 // indirect
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1 // indirect
github.com/fatih/color v1.12.0
github.com/flynn-archive/go-shlex v0.0.0-20150515145356-3f9db97f8568
github.com/stretchr/testify v1.7.0
)
28 changes: 28 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
github.com/abiosoft/readline v0.0.0-20180607040430-155bce2042db h1:CjPUSXOiYptLbTdr1RceuZgSFDQ7U15ITERUGrUORx8=
github.com/abiosoft/readline v0.0.0-20180607040430-155bce2042db/go.mod h1:rB3B4rKii8V21ydCbIzH5hZiCQE7f5E9SzUb/ZZx530=
github.com/chzyer/logex v1.1.10 h1:Swpa1K6QvQznwJRcfTfQJmTE72DqScAa40E+fbHEXEE=
github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1 h1:q763qf9huN11kDQavWsoZXJNW3xEE4JJyHa5Q25/sd8=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/fatih/color v1.12.0 h1:mRhaKNwANqRgUBGKmnI5ZxEk7QXmjQeCcuYFMX2bfcc=
github.com/fatih/color v1.12.0/go.mod h1:ELkj/draVOlAH/xkhN6mQ50Qd0MPOk5AAr3maGEBuJM=
github.com/flynn-archive/go-shlex v0.0.0-20150515145356-3f9db97f8568 h1:BMXYYRWTLOJKlh+lOBt6nUQgXAfB7oVIQt5cNreqSLI=
github.com/flynn-archive/go-shlex v0.0.0-20150515145356-3f9db97f8568/go.mod h1:rZfgFAXFS/z/lEd6LJmf9HVZ1LkgYiHx5pHhV5DR16M=
github.com/mattn/go-colorable v0.1.8 h1:c1ghPdyEDarC70ftn0y+A/Ee++9zz8ljHG1b13eJ0s8=
github.com/mattn/go-colorable v0.1.8/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
github.com/mattn/go-isatty v0.0.12 h1:wuysRhFDzyxgEmMf5xjvJ2M9dZoWAXNNr5LSBS7uHXY=
github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae h1:/WDfKMnPU+m5M4xB+6x4kaepxRw6jWvR5iDRdvjHgy8=
golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

0 comments on commit 1c52a1a

Please sign in to comment.