Preston_PLB
/
bubbletea
forked from Mirrors/bubbletea
1
0
Fork 0
Code Pull Requests Activity

Update tutorials per new Model interface-based structure

This commit is contained in:
Christian Rocha 2020-10-15 20:26:02 -04:00
parent c72ee756dd
commit 9c5d4268ba
No known key found for this signature in database
GPG Key ID: D6CC7A16E5878018
7 changed files with 203 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

242
README.md
View File

@ -39,67 +39,63 @@ Be sure to check out [Bubbles][bubbles], a library of common UI components for B
## Tutorial
Bubble Tea is based on the functional design paradigms of [The Elm
Architecture][elm]. It might not seem very Go-like at first, but once you get
used to the general structure you'll find that most of the idomatic Go things
you know and love are still relevant and useful here.
Architecture][elm] which happens work nicely with Go.
By the way, the non-annotated source code for this program
[is also available](https://github.com/charmbracelet/bubbletea/tree/master/tutorials/basics).
By the way, the non-annotated source code for this program is available
[on GitHub](https://github.com/charmbracelet/bubbletea/tree/master/tutorials/basics).
This tutorial assumes you have a working knowledge of Go.
[elm]: https://guide.elm-lang.org/architecture/
### Enough! Let's get to it.
## Enough! Let's get to it.
For this tutorial we're making a to-do list.
We'll start by defining our package and import some libraries. Our only external
To start we'll define our package and import some libraries. Our only external
import will be the Bubble Tea library, which we'll call `tea` for short.
```go
package main
package main
import (
"fmt"
"os"
import (
"fmt"
"os"
tea "github.com/charmbracelet/bubbletea"
)
tea "github.com/charmbracelet/bubbletea"
)
```
Bubble Tea programs are comprised of a **model** that describes the application
state and three simple functions that are centered around that model:
state and three simple methods on that model:
* **Initialize**, a function that returns the model's initial state.
* **Init**, a function that returns an initial command for the application to run.
* **Update**, a function that handles incoming events and updates the model accordingly.
* **View**, a function that renders the UI based on the data in the model.
### The Model
## The Model
So let's start by defining our model which will store our application's state.
It can be any type, but a `struct` usually makes the most sense.
```go
type model struct {
choices []string // items on the to-do list
cursor int // which to-do list item our cursor is pointing at
selected map[int]struct{} // which to-do items are selected
}
type model struct {
choices []string // items on the to-do list
cursor int // which to-do list item our cursor is pointing at
selected map[int]struct{} // which to-do items are selected
}
```
### The Initialization Function
## Initialization
Next we'll define a function that will initialize our application. An
initialize function returns a model representing our application's initial
state, as well as a `Cmd` that could perform some initial I/O. For now, we
don't need to do any I/O, so for the command we'll just return `nil`, which
translates to "no command."
Next we'll define our application’s initial state. We’ll store our initial
model in a simple variable, and then define the `Init` method. `Init` can
return a `Cmd` that could perform some initial I/O. For now, we don't need to
do any I/O, so for the command we'll just return `nil`, which translates to "no
command."
```go
func initialize() (tea.Model, tea.Cmd) {
m := model{
var initialModel = model{
// Our to-do list is just a grocery list
choices: []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},
@ -109,14 +105,15 @@ func initialize() (tea.Model, tea.Cmd) {
selected: make(map[int]struct{}),
}
// Return the model and `nil`, which means "no I/O right now, please."
return m, nil
}
func (m model) Init() (tea.Cmd) {
// Just return `nil`, which means "no I/O right now, please."
return m, nil
}
```
### The Update Function
## The Update Method
Next we'll define the update function. The update function is called when
Next we'll define the update method. The update function is called when
"things happen." Its job is to look at what has happened and return an updated
model in response to whatever happened. It can also return a `Cmd` and make
more things happen, but for now don't worry about that part.
@ -135,114 +132,149 @@ For now, we'll just deal with `tea.KeyMsg` messages, which are automatically
sent to the update function when keys are pressed.
```go
func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
m, _ := mdl.(model)
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
switch msg := msg.(type) {
// Is it a key press?
case tea.KeyMsg:
// Is it a key press?
case tea.KeyMsg:
// Cool, what was the actual key pressed?
switch msg.String() {
// Cool, what was the actual key pressed?
switch msg.String() {
// These keys should exit the program.
case "ctrl+c", "q":
return m, tea.Quit
// These keys should exit the program.
case "ctrl+c", "q":
return m, tea.Quit
// The "up" and "k" keys move the cursor up
case "up", "k":
if m.cursor > 0 {
m.cursor--
}
// The "up" and "k" keys move the cursor up
case "up", "k":
if m.cursor > 0 {
m.cursor--
}
// The "down" and "j" keys move the cursor down
case "down", "j":
if m.cursor < len(m.choices)-1 {
m.cursor++
}
// The "down" and "j" keys move the cursor down
case "down", "j":
if m.cursor < len(m.choices)-1 {
m.cursor++
}
// The "enter" key and the spacebar (a literal space) toggle
// the selected state for the item that the cursor is pointing at.
case "enter", " ":
_, ok := m.selected[m.cursor]
if ok {
delete(m.selected, m.cursor)
} else {
m.selected[m.cursor] = struct{}{}
// The "enter" key and the spacebar (a literal space) toggle
// the selected state for the item that the cursor is pointing at.
case "enter", " ":
_, ok := m.selected[m.cursor]
if ok {
delete(m.selected, m.cursor)
} else {
m.selected[m.cursor] = struct{}{}
}
}
}
}
// Return the updated model to the Bubble Tea runtime for processing.
// Note that we're not returning a command.
return m, nil
}
// Return the updated model to the Bubble Tea runtime for processing.
// Note that we're not returning a command.
return m, nil
}
```
You may have noticed that "ctrl+c" and "q" above return a `tea.Quit` command
with the model. That's a special command which instructs the Bubble Tea runtime
to quit, exiting the program.
### The View Function
## The View Method
At last, it's time to render our UI. Of all the functions, the view is the
simplest. A model, in it's current state, comes in and a `string` comes out.
That string is our UI!
At last, it's time to render our UI. Of all the methods, the view is the
simplest. We look at the model in it's current state and use it to return
a `string`. That string is our UI!
Because the view describes the entire UI of your application, you don't have
to worry about redraw logic and stuff like that. Bubble Tea takes care of it
for you.
```go
func view(mdl tea.Model) string {
m, _ := mdl.(model)
func (m model) View() string {
// The header
s := "What should we buy at the market?\n\n"
// The header
s := "What should we buy at the market?\n\n"
// Iterate over our choices
for i, choice := range m.choices {
// Iterate over our choices
for i, choice := range m.choices {
// Is the cursor pointing at this choice?
cursor := " " // no cursor
if m.cursor == i {
cursor = ">" // cursor!
}
// Is the cursor pointing at this choice?
cursor := " " // no cursor
if m.cursor == i {
cursor = ">" // cursor!
// Is this choice selected?
checked := " " // not selected
if _, ok := m.selected[i]; ok {
checked = "x" // selected!
}
// Render the row
s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
}
// Is this choice selected?
checked := " " // not selected
if _, ok := m.selected[i]; ok {
checked = "x" // selected!
}
// The footer
s += "\nPress q to quit.\n"
// Render the row
s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
// Send the UI for rendering
return s
}
// The footer
s += "\nPress q to quit.\n"
// Send the UI for rendering
return s
}
```
### All Together Now
## All Together Now
The last step is to simply run our program. We pass our functions to
The last step is to simply run our program. We pass our initial model to
`tea.NewProgram` and let it rip:
```go
func main() {
p := tea.NewProgram(initialize, update, view)
if err := p.Start(); err != nil {
fmt.Printf("Alas, there's been an error: %v", err)
os.Exit(1)
func main() {
p := tea.NewProgram(initialModel)
if err := p.Start(); err != nil {
fmt.Printf("Alas, there's been an error: %v", err)
os.Exit(1)
}
}
}
```
## What's Next?
This tutorial covers the basics of building an interactive terminal UI, but
in the real world you'll also need to perform I/O. To learn about that have a
look at the [Command Tutorial][cmd]. It's pretty simple.
There are also several [Bubble Tea examples][examples] available and, of course,
there are [Go Docs][docs].
[cmd]: http://github.com/charmbracelet/bubbletea/tree/master/tutorials/commands/
[examples]: http://github.com/charmbracelet/bubbletea/tree/master/examples
[docs]: https://pkg.go.dev/github.com/charmbracelet/glow?tab=doc
### Bubble Tea in the Wild
For some Bubble Tea programs in production, see:
* [Glow](https://github.com/charmbracelet/glow): a markdown reader, browser and online markdown stash
* [The Charm Tool](https://github.com/charmbracelet/charm): the Charm user account manager
### Libraries we use with Bubble Tea
* [Bubbles][bubbles] various Bubble Tea components
* [Termenv][termenv]: Advanced ANSI styling for terminal applications
* [Reflow][reflow]: ANSI-aware methods for reflowing blocks of text
* [go-runewidth][runewidth]: Measure the physical width of strings in terms of terminal cells. Many runes, such as East Asian charcters and emojis, are two cells wide, so measuring a layout with `len()` often won't cut it.
[termenv]: https://github.com/muesli/termenv
[reflow]: https://github.com/muesli/reflow
[bubbles]: https://github.com/charmbracelet/bubbles
[runewidth]: https://github.com/mattn/go-runewidth
### Feedback
We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!
* [Twitter](https://twitter.com/charmcli)
* [The Fediverse](https://mastodon.technology/@charm)
### What's Next?
This tutorial covers the basics of building an interactive terminal UI, but

65
tutorials/basics/README.md
View File

@ -2,9 +2,7 @@ Bubble Tea Basics
=================
Bubble Tea is based on the functional design paradigms of [The Elm
Architecture][elm]. It might not seem very Go-like at first, but once you get
used to the general structure you'll find that most of the idomatic Go things
you know and love are still relevant and useful here.
Architecture][elm] which happens work nicely with Go.
By the way, the non-annotated source code for this program is available
[on GitHub](https://github.com/charmbracelet/bubbletea/tree/master/tutorials/basics).
@ -32,9 +30,9 @@ import will be the Bubble Tea library, which we'll call `tea` for short.
```
Bubble Tea programs are comprised of a **model** that describes the application
state and three simple functions that are centered around that model:
state and three simple methods on that model:
* **Initialize**, a function that returns the model's initial state.
* **Init**, a function that returns an initial command for the application to run.
* **Update**, a function that handles incoming events and updates the model accordingly.
* **View**, a function that renders the UI based on the data in the model.
@ -51,35 +49,34 @@ It can be any type, but a `struct` usually makes the most sense.
}
```
## The Initialization Function
## Initialization
Next we'll define a function that will initialize our application. An
initialize function returns a model representing our application's initial
state, as well as a `Cmd` that could perform some initial I/O. For now, we
don't need to do any I/O, so for the command we'll just return `nil`, which
translates to "no command."
Next we'll define our application’s initial state. We’ll store our initial
model in a simple variable, and then define the `Init` method. `Init` can
return a `Cmd` that could perform some initial I/O. For now, we don't need to
do any I/O, so for the command we'll just return `nil`, which translates to "no
command."
```go
func initialize() (tea.Model, tea.Cmd) {
m := model{
var initialModel = model{
// Our to-do list is just a grocery list
choices: []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},
// Our to-do list is just a grocery list
choices: []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},
// A map which indicates which choices are selected. We're using
// the map like a mathematical set. The keys refer to the indexes
// of the `choices` slice, above.
selected: make(map[int]struct{}),
}
// A map which indicates which choices are selected. We're using
// the map like a mathematical set. The keys refer to the indexes
// of the `choices` slice, above.
selected: make(map[int]struct{}),
}
// Return the model and `nil`, which means "no I/O right now, please."
func (m model) Init() (tea.Cmd) {
// Just return `nil`, which means "no I/O right now, please."
return m, nil
}
```
## The Update Function
## The Update Method
Next we'll define the update function. The update function is called when
Next we'll define the update method. The update function is called when
"things happen." Its job is to look at what has happened and return an updated
model in response to whatever happened. It can also return a `Cmd` and make
more things happen, but for now don't worry about that part.
@ -98,9 +95,7 @@ For now, we'll just deal with `tea.KeyMsg` messages, which are automatically
sent to the update function when keys are pressed.
```go
func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
m, _ := mdl.(model)
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
// Is it a key press?
@ -147,20 +142,18 @@ You may have noticed that "ctrl+c" and "q" above return a `tea.Quit` command
with the model. That's a special command which instructs the Bubble Tea runtime
to quit, exiting the program.
## The View Function
## The View Method
At last, it's time to render our UI. Of all the functions, the view is the
simplest. A model, in it's current state, comes in and a `string` comes out.
That string is our UI!
At last, it's time to render our UI. Of all the methods, the view is the
simplest. We look at the model in it's current state and use it to return
a `string`. That string is our UI!
Because the view describes the entire UI of your application, you don't have
to worry about redraw logic and stuff like that. Bubble Tea takes care of it
for you.
```go
func view(mdl tea.Model) string {
m, _ := mdl.(model)
func (m model) View() string {
// The header
s := "What should we buy at the market?\n\n"
@ -193,12 +186,12 @@ for you.
## All Together Now
The last step is to simply run our program. We pass our functions to
The last step is to simply run our program. We pass our initial model to
`tea.NewProgram` and let it rip:
```go
func main() {
p := tea.NewProgram(initialize, update, view)
p := tea.NewProgram(initialModel)
if err := p.Start(); err != nil {
fmt.Printf("Alas, there's been an error: %v", err)
os.Exit(1)

20
tutorials/basics/main.go
View File

@ -13,16 +13,16 @@ type model struct {
selected map[int]struct{}
}
func initialize() (tea.Model, tea.Cmd) {
return model{
choices: []string{"Carrots", "Celery", "Kohlrabi"},
selected: make(map[int]struct{}),
}, nil
var initialModel = model{
choices: []string{"Carrots", "Celery", "Kohlrabi"},
selected: make(map[int]struct{}),
}
func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
m, _ := mdl.(model)
func (m model) Init() tea.Cmd {
return nil
}
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
switch msg.String() {
@ -49,9 +49,7 @@ func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
return m, nil
}
func view(mdl tea.Model) string {
m, _ := mdl.(model)
func (m model) View() string {
s := "What should we buy at the market?\n\n"
for i, choice := range m.choices {
@ -74,7 +72,7 @@ func view(mdl tea.Model) string {
}
func main() {
p := tea.NewProgram(initialize, update, view)
p := tea.NewProgram(initialModel)
if err := p.Start(); err != nil {
fmt.Printf("Alas, there's been an error: %v", err)
os.Exit(1)

28
tutorials/commands/README.md
View File

@ -85,19 +85,19 @@ And notice that we've defined two new `Msg` types. They can be any type, even
an empty struct. We'll come back to them later later in our update function.
First, let's write our initialization function.
## The Initialization Function
## The Initialization Method
The initilization function is very simple. We return an empty model and the
the `Cmd` we made earlier. Note that we don't call the function; the Bubble Tea
runtime will do that when the time is right.
The initilization method is very simple: we return the `Cmd` we made earlier.
Note that we don't call the function; the Bubble Tea runtime will do that when
the time is right.
```go
func initialize() (tea.Model, tea.Cmd) {
return model{}, checkServer
func (m model) Init() (tea.Cmd) {
return checkServer
}
```
## The Update Function
## The Update Method
Internally, `Cmd`s run asynchronously in a goroutine. The `Msg` they return is
collected and sent to our update function for handling. Remember those message
@ -105,9 +105,7 @@ types we made earlier when we were making the `checkServer` command? We handle
them here. This makes dealing with many asynchronous operations very easy.
```go
func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
m, _ := mdl.(model)
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case statusMsg:
@ -144,9 +142,7 @@ Our view is very straightforward. We look at the current model and build a
string accordingly:
```go
func view(mdl tea.Model) string {
m, _ := mdl.(model)
func (m model) View() string {
// If there's an error, print it out and don't do anything else.
if m.err != nil {
return fmt.Sprintf("\nWe had some trouble: %v\n\n", m.err)
@ -167,11 +163,13 @@ func view(mdl tea.Model) string {
## Run the program
The only thing left to do is run the program, so let's do that!
The only thing left to do is run the program, so let's do that! Our initial
model doesn't need any data at all in this case, we just initialize it with
as a `struct` with defaults.
```go
func main() {
if err := tea.NewProgram(initialize, update, view).Start(); err != nil {
if err := tea.NewProgram(model{}).Start(); err != nil {
fmt.Printf("Uh oh, there was an error: %v\n", err)
os.Exit(1)
}

14
tutorials/commands/main.go
View File

@ -33,13 +33,11 @@ type errMsg struct{ err error }
// error interface on the message.
func (e errMsg) Error() string { return e.err.Error() }
func initialize() (tea.Model, tea.Cmd) {
return model{}, checkServer
func (m model) Init() tea.Cmd {
return checkServer
}
func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
m, _ := mdl.(model)
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case statusMsg:
@ -59,9 +57,7 @@ func update(msg tea.Msg, mdl tea.Model) (tea.Model, tea.Cmd) {
return m, nil
}
func view(mdl tea.Model) string {
m, _ := mdl.(model)
func (m model) View() string {
if m.err != nil {
return fmt.Sprintf("\nWe had some trouble: %v\n\n", m.err)
}
@ -74,7 +70,7 @@ func view(mdl tea.Model) string {
}
func main() {
if err := tea.NewProgram(initialize, update, view).Start(); err != nil {
if err := tea.NewProgram(model{}).Start(); err != nil {
fmt.Printf("Uh oh, there was an error: %v\n", err)
os.Exit(1)
}

2
tutorials/go.mod
View File

@ -2,6 +2,6 @@ module tutorial
go 1.14
require github.com/charmbracelet/bubbletea v0.10.3
require github.com/charmbracelet/bubbletea v0.11.1
replace github.com/charmbracelet/bubbletea => ../

15
tutorials/go.sum
View File

@ -1,3 +1,5 @@
github.com/containerd/console v1.0.1 h1:u7SFAJyRqWcG6ogaMAx3KjSTy1e3hT9QxqX7Jco7dRc=
github.com/containerd/console v1.0.1/go.mod h1:XUsP6YE/mKtz6bxc+I8UiKKTP04qjQL4qcS3XoQ5xkw=
github.com/google/goterm v0.0.0-20190703233501-fc88cf888a3f h1:5CjVwnuUcp5adK4gmY6i72gpVFVnZDP2h5TmPScB6u4=
github.com/google/goterm v0.0.0-20190703233501-fc88cf888a3f/go.mod h1:nOFQdrUlIlx6M6ODdSpBj1NVA+VgLC6kmw60mkw34H4=
github.com/lucasb-eyer/go-colorful v1.0.3 h1:QIbQXiugsb+q10B+MI+7DI1oQLdmnep86tWFlaaUAac=
@ -8,15 +10,16 @@ github.com/mattn/go-runewidth v0.0.9 h1:Lm995f3rfxdpd6TSmuVCHVb/QhupuXlYr8sCI/Qd
github.com/mattn/go-runewidth v0.0.9/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
github.com/muesli/termenv v0.7.2 h1:r1raklL3uKE7rOvWgSenmEm2px+dnc33OTisZ8YR1fw=
github.com/muesli/termenv v0.7.2/go.mod h1:ct2L5N2lmix82RaY3bMWwVu/jUFc9Ule0KGDCiKYPh8=
github.com/pkg/term v0.0.0-20200520122047-c3ffed290a03 h1:pd4YKIqCB0U7O2I4gWHgEUA2mCEOENmco0l/bM957bU=
github.com/pkg/term v0.0.0-20200520122047-c3ffed290a03/go.mod h1:Z9+Ul5bCbBKnbCvdOWbLqTHhJiYV414CURZJba6L8qA=
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/crypto v0.0.0-20200709230013-948cd5f35899 h1:DZhuSZLsGlFL4CmhA8BcRA0mnthyA/nZ00AqCUo7vHg=
golang.org/x/crypto v0.0.0-20200709230013-948cd5f35899/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20201012173705-84dcc777aaee h1:4yd7jl+vXjalO5ztz6Vc1VADv+S/80LGJmyl1ROJ2AI=
golang.org/x/crypto v0.0.0-20201012173705-84dcc777aaee/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200821140526-fda516888d29 h1:mNuhGagCf3lDDm5C0376C/sxh6V7fy9WbdEu/YDNA04=
golang.org/x/sys v0.0.0-20200821140526-fda516888d29/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200916030750-2334cc1a136f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20201009025420-dfb3f7c4e634 h1:bNEHhJCnrwMKNMmOx3yAynp5vs5/gRy+XWFtZFu7NBM=
golang.org/x/sys v0.0.0-20201009025420-dfb3f7c4e634/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=