github.com-charmbracelet-bubbletea_-_2022-01-25_13-36-53
Item Preview
Share or Embed This Item
Flag this item for
- Publication date
- 2022-01-25
A powerful little TUI framework š
Bubble Tea
The fun, functional and stateful way to build terminal apps. A Go frameworkbased on The Elm Architecture. Bubble Tea is well-suited for simple andcomplex terminal applications, either inline, full-window, or a mix of both.
Bubble Tea is in use in production and includes a number of features andperformance optimizations weāve added along the way. Among those is a standardframerate-based renderer, a renderer for high-performance scrollableregions which works alongside the main renderer, and mouse support.
To get started, see the tutorial below, the examples, thedocs and some common resources.
By the way
Be sure to check out Bubbles, a library of common UI components for Bubble Tea.
Tutorial
Bubble Tea is based on the functional design paradigms of The ElmArchitecture which happens to work nicely with Go. It's a delightful way tobuild applications.
By the way, the non-annotated source code for this program is availableon GitHub.
This tutorial assumes you have a working knowledge of Go.
Enough! Let's get to it.
For this tutorial we're making a shopping list.
To start we'll define our package and import some libraries. Our only externalimport will be the Bubble Tea library, which we'll call tea
for short.
```gopackage main
import ( "fmt" "os"
tea "github.com/charmbracelet/bubbletea"
)```
Bubble Tea programs are comprised of a model that describes the applicationstate and three simple methods on that model:
- 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
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.
gotype 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}
Initialization
Next weāll define our applicationās initial state. In this case weāre defininga function to return our initial model, however we could just as easily definethe initial model as a variable elsewhere, too.
```gofunc initialModel() model { return model{ // Our shopping list is 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{}),}
}```
Next we define the Init
method. Init
can return a Cmd
that could performsome initial I/O. For now, we don't need to do any I/O, so for the commandwe'll just return nil
, which translates to "no command."
gofunc (m model) Init() tea.Cmd { // Just return `nil`, which means "no I/O right now, please." return nil}
The Update Method
Next up is the update method. The update function is called when āthingshappen.ā Its job is to look at what has happened and return an updated model inresponse. It can also return a Cmd
to make more things happen, but for nowdon't worry about that part.
In our case, when a user presses the down arrow, Update
ās job is to noticethat the down arrow was pressed and move the cursor accordingly (or not).
The āsomething happenedā comes in the form of a Msg
, which can be any type.Messages are the result of some I/O that took place, such as a keypress, timertick, or a response from a server.
We usually figure out which type of Msg
we received with a type switch, butyou could also use a type assertion.
For now, we'll just deal with tea.KeyMsg
messages, which are automaticallysent to the update function when keys are pressed.
```gofunc (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { switch msg := msg.(type) {
// Is it a key press?case tea.KeyMsg: // Cool, what was the actual key pressed? switch msg.String() { // 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 "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{}{} } }}// 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 returna tea.Quit
command with the model. Thatās a special command which instructsthe Bubble Tea runtime to quit, exiting the program.
The View Method
At last, itās time to render our UI. Of all the methods, the view is thesimplest. We look at the model in it's current state and use it to returna string
. That string is our UI!
Because the view describes the entire UI of your application, you donāt have toworry about redrawing logic and stuff like that. Bubble Tea takes care of itfor you.
```gofunc (m model) View() string { // The header s := "What should we buy at the market?\n\n"
// Iterate over our choicesfor i, choice := range m.choices { // 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)}// The footers += "\nPress q to quit.\n"// Send the UI for renderingreturn s
}```
All Together Now
The last step is to simply run our program. We pass our initial model totea.NewProgram
and let it rip:
gofunc 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, butin the real world you'll also need to perform I/O. To learn about that have alook at the Command Tutorial. It's pretty simple.
There are also several Bubble Tea examples available and, of course,there are Go Docs.
Libraries we use with Bubble Tea
- Bubbles: Common Bubble Tea components such as text inputs, viewports, spinners and so on
- Lip Gloss: Style, format and layout tools for terminal applications
- Harmonica: A spring animation library for smooth, natural motion
- Termenv: Advanced ANSI styling for terminal applications
- Reflow: Advanced ANSI-aware methods for working with text
Bubble Tea in the Wild
For some Bubble Tea programs in production, see:
- Glow: a markdown reader, browser and online markdown stash
- The Charm Tool: the Charm user account manager
- kboard: a typing game
- tasktimer: a dead-simple task timer
- fork-cleaner: cleans up old and inactive forks in your GitHub account
- STTG: teletext client for SVT, Swedenās national public television station
- gitflow-toolkit: a GitFlow submission tool
- ticker: a terminal stock watcher and stock position tracker
- tz: an aid for scheduling across multiple time zones
- httpit: a rapid http(s) benchmark tool
- gembro: a mouse-driven Gemini browser
- fm: a terminal-based file manager
- StormForge Optimize ā Controller: a tool for experimenting with application configurations in Kubernetes
- Slides: a markdown-based presentation tool
- Typer: a typing test
- AT CLI: a utility to for executing AT Commands via serial port connections
- Canard: an RSS client
- termdbms: a keyboard and mouse driven database browser
- gh-prs: gh cli extension to display a dashboard of PRs
Feedback
We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!
Acknowledgments
Bubble Tea is based on the paradigms of The Elm Architecture by EvanCzaplicki et alia and the excellent go-tea by TJ Holowaychuk.
License
Part of Charm.
Charmēē±å¼ęŗ ⢠Charm loves open source
To restore the repository download the bundle
wget https://archive.org/download/github.com-charmbracelet-bubbletea_-_2022-01-25_13-36-53/charmbracelet-bubbletea_-_2022-01-25_13-36-53.bundle
and run: git clone charmbracelet-bubbletea_-_2022-01-25_13-36-53.bundle
Source: https://github.com/charmbracelet/bubbletea
Uploader: charmbracelet
Upload date: 2022-01-25
- Addeddate
- 2022-01-25 14:32:46
- Identifier
- github.com-charmbracelet-bubbletea_-_2022-01-25_13-36-53
- Originalurl
-
https://github.com/charmbracelet/bubbletea
- Pushed_date
- 2022-01-25 13:36:53
- Scanner
- Internet Archive Python library 1.9.9
- Uploaded_with
- iagitup - v1.6.2
- Year
- 2022