taigrr/bubbletea
1
0
Fork 0
mirror of https://github.com/taigrr/bubbletea.git synced 2026-04-02 02:59:09 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: link to tutorial + general README edits (#344)

Browse Source 
* docs: clean up readme

* chore: add references

* chore: set to 80 char width

* docs: remove 404 docs link for now + tidy up READMEs

* docs: small language change in README

Co-authored-by: Christian Rocha <christian@rocha.is>
This commit is contained in:
bashbunni
2022-07-19 16:23:37 -07:00
committed by GitHub
parent ae4381a892
commit 219ed4ed09
4 changed files with 49 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -18,3 +18,4 @@ tutorials/basics/basics
tutorials/commands/commands tutorials/commands/commands
.idea .idea
coverage.txt coverage.txt
README.md.*

268
README.md
View File

@@ -21,241 +21,32 @@ performance optimizations we’ve added along the way. Among those is a standard
framerate-based renderer, a renderer for high-performance scrollable framerate-based renderer, a renderer for high-performance scrollable
regions which works alongside the main renderer, and mouse support. regions which works alongside the main renderer, and mouse support.
To get started, see the tutorial below, the [examples][examples], the ## Getting Started
[docs][docs] and some common [resources](#libraries-we-use-with-bubble-tea).
## By the way We recommend starting with the [basics tutorial][basics] followed by the
[commands tutorial][commands], both of which should give you a good
understanding of how things work.
Be sure to check out [Bubbles][bubbles], a library of common UI components for Bubble Tea. There are a bunch of [examples][examples], too!
[basics]: https://github.com/charmbracelet/bubbletea/tree/master/tutorials/basics
[commands]: https://github.com/charmbracelet/bubbletea/tree/master/tutorials/commands
[documentation]: https://github.com/charmbracelet/bubbletea/tree/master/docs
[examples]: https://github.com/charmbracelet/bubbletea/tree/master/examples
## Components
For a bunch of basic user interface components check out [Bubbles][bubbles],
the official Bubble Tea component library.
<p> <p>
<a href="https://github.com/charmbracelet/bubbles"><img src="https://stuff.charm.sh/bubbles/bubbles-badge.png" width="174" alt="Bubbles Badge"></a>&nbsp;&nbsp; <a href="https://github.com/charmbracelet/bubbles"><img src="https://stuff.charm.sh/bubbles/bubbles-badge.png" width="174" alt="Bubbles Badge"></a>&nbsp;&nbsp;
<a href="https://github.com/charmbracelet/bubbles"><img src="https://stuff.charm.sh/bubbles-examples/textinput.gif" width="400" alt="Text Input Example from Bubbles"></a> <a href="https://github.com/charmbracelet/bubbles"><img src="https://stuff.charm.sh/bubbles-examples/textinput.gif" width="400" alt="Text Input Example from Bubbles"></a>
</p> </p>
* * * ## Debugging
## Tutorial ### Debugging with Delve
Bubble Tea is based on the functional design paradigms of [The Elm
Architecture][elm], which happen to work nicely with Go. It's a delightful way to
build applications.
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.
For this tutorial, we're making a shopping list.
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
import (
"fmt"
"os"
tea "github.com/charmbracelet/bubbletea"
)
```
Bubble Tea programs are comprised of a **model** that describes the application
state 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.
```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
}
```
## Initialization
Next, we’ll define our application’s initial state. In this case, we’re defining
a function to return our initial model, however, we could just as easily define
the initial model as a variable elsewhere, too.
```go
func 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 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 (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 ”things
happen.” Its job is to look at what has happened and return an updated model in
response. It can also return a `Cmd` to make more things happen, but for now
don't worry about that part.
In our case, when a user presses the down arrow, `Update`’s job is to notice
that 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, timer
tick, or a response from a server.
We usually figure out which type of `Msg` we received with a type switch, but
you could also use a type assertion.
For now, we'll just deal with `tea.KeyMsg` messages, which are automatically
sent to the update function when keys are pressed.
```go
func (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 <kbd>ctrl+c</kbd> and <kbd>q</kbd> 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 Method
At last, it’s time to render our UI. Of all the methods, the view is the
simplest. We look at the model in its 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 redrawing logic and stuff like that. Bubble Tea takes care of it
for you.
```go
func (m model) View() string {
// The header
s := "What should we buy at the market?\n\n"
// 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 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 footer
s += "\nPress q to quit.\n"
// Send the UI for rendering
return s
}
```
## All Together Now
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(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/bubbletea?tab=doc
## Debugging with Delve
Since Bubble Tea apps assume control of stdin and stdout, you’ll need to run Since Bubble Tea apps assume control of stdin and stdout, you’ll need to run
delve in headless mode and then connect to it: delve in headless mode and then connect to it:
@@ -272,6 +63,25 @@ $ dlv connect 127.0.0.1:34241
Note that the default port used will vary on your system and per run, so Note that the default port used will vary on your system and per run, so
actually watch out what address the first `dlv` run tells you to connect to. actually watch out what address the first `dlv` run tells you to connect to.
### Logging Stuff
You can log to a debug file to print debug Bubble Tea applications. To do so,
include something like…
```go
if len(os.Getenv("DEBUG")) > 0 {
f, err := tea.LogToFile("debug.log", "debug")
if err != nil {
fmt.Println("fatal:", err)
os.Exit(1)
}
defer f.Close()
}
```
…before you start your Bubble Tea program. To see what’s printed in real time,
run `tail -f debug.go` while you run your program in another window.
## Libraries we use with Bubble Tea ## Libraries we use with Bubble Tea
* [Bubbles][bubbles]: Common Bubble Tea components such as text inputs, viewports, spinners and so on * [Bubbles][bubbles]: Common Bubble Tea components such as text inputs, viewports, spinners and so on
@@ -288,9 +98,6 @@ actually watch out what address the first `dlv` run tells you to connect to.
[termenv]: https://github.com/muesli/termenv [termenv]: https://github.com/muesli/termenv
[reflow]: https://github.com/muesli/reflow [reflow]: https://github.com/muesli/reflow
## Additional utility libraries to use with Bubble Tea
## Bubble Tea in the Wild ## Bubble Tea in the Wild
For some Bubble Tea programs in production, see: For some Bubble Tea programs in production, see:
@@ -304,7 +111,7 @@ For some Bubble Tea programs in production, see:
* [gambit](https://github.com/maaslalani/gambit): play chess in the terminal * [gambit](https://github.com/maaslalani/gambit): play chess in the terminal
* [gembro](https://git.sr.ht/~rafael/gembro): a mouse-driven Gemini browser * [gembro](https://git.sr.ht/~rafael/gembro): a mouse-driven Gemini browser
* [gh-b](https://github.com/joaom00/gh-b): GitHub CLI extension to easily manage your branches * [gh-b](https://github.com/joaom00/gh-b): GitHub CLI extension to easily manage your branches
* [gh-dash](https://www.github.com/dlvhdr/gh-dash): GitHub cli extension to display a dashboard of PRs and issues * [gh-dash](https://www.github.com/dlvhdr/gh-dash): GitHub CLI extension to display a dashboard of PRs and issues
* [gitflow-toolkit](https://github.com/mritd/gitflow-toolkit): a GitFlow submission tool * [gitflow-toolkit](https://github.com/mritd/gitflow-toolkit): a GitFlow submission tool
* [Glow](https://github.com/charmbracelet/glow): a markdown reader, browser and online markdown stash * [Glow](https://github.com/charmbracelet/glow): a markdown reader, browser and online markdown stash
* [gocovsh](https://github.com/orlangure/gocovsh): explore Go coverage reports from the CLI * [gocovsh](https://github.com/orlangure/gocovsh): explore Go coverage reports from the CLI
@@ -336,6 +143,7 @@ We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!
* [Twitter](https://twitter.com/charmcli) * [Twitter](https://twitter.com/charmcli)
* [The Fediverse](https://mastodon.technology/@charm) * [The Fediverse](https://mastodon.technology/@charm)
* [Slack](https://charm.sh/slack)
## Acknowledgments ## Acknowledgments

15
tutorials/basics/README.md
View File

@@ -14,7 +14,7 @@ This tutorial assumes you have a working knowledge of Go.
## Enough! Let's get to it. ## Enough! Let's get to it.
For this tutorial we're making a shopping list. For this tutorial, we're making a shopping list.
To start we'll define 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. import will be the Bubble Tea library, which we'll call `tea` for short.
@@ -52,8 +52,8 @@ type model struct {
## Initialization ## Initialization
Next we’ll define our application’s initial state. In this case we’re defining Next, we’ll define our application’s initial state. In this case, we’re defining
a function to return our initial model, however we could just as easily define a function to return our initial model, however, we could just as easily define
the initial model as a variable elsewhere, too. the initial model as a variable elsewhere, too.
```go ```go
@@ -70,8 +70,8 @@ func initialModel() model {
} }
``` ```
Next we define the `Init` method. `Init` can return a `Cmd` that could perform Next, we 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 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." we'll just return `nil`, which translates to "no command."
```go ```go
@@ -152,7 +152,7 @@ the Bubble Tea runtime to quit, exiting the program.
## The View Method ## The View Method
At last, it’s time to render our UI. Of all the methods, the view is the 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 simplest. We look at the model in its current state and use it to return
a `string`. That string is our UI! a `string`. That string is our UI!
Because the view describes the entire UI of your application, you don’t have to Because the view describes the entire UI of your application, you don’t have to
@@ -230,11 +230,12 @@ We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!
* [Twitter](https://twitter.com/charmcli) * [Twitter](https://twitter.com/charmcli)
* [The Fediverse](https://mastodon.technology/@charm) * [The Fediverse](https://mastodon.technology/@charm)
* [Slack](https://charm.sh/slack)
*** ***
Part of [Charm](https://charm.sh). Part of [Charm](https://charm.sh).
<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a> <a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
Charm热爱开源 • Charm loves open source Charm热爱开源 • Charm loves open source

3
tutorials/commands/README.md
View File

@@ -236,11 +236,12 @@ We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!
* [Twitter](https://twitter.com/charmcli) * [Twitter](https://twitter.com/charmcli)
* [The Fediverse](https://mastodon.technology/@charm) * [The Fediverse](https://mastodon.technology/@charm)
* [Slack](https://charm.sh/slack)
*** ***
Part of [Charm](https://charm.sh). Part of [Charm](https://charm.sh).
<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a> <a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
Charm热爱开源 • Charm loves open source Charm热爱开源 • Charm loves open source