Use cargo-generate for hello-world tutorial

code/tutorials/hello-world/hello.tape → code/tutorials/hello-ratatui.tape

@@ -1,12 +1,12 @@
 # A VHS tape. See https://github.com/charmbracelet/vhs
 Output hello.gif
 Set Theme "Aardvark Blue"
-Set Width 800
+Set Width 1200
 Set Height 450
-Type "cargo run"
+Type "cargo run -p hello-ratatui"
 Enter
 Sleep 7s
-Screenshot hello.png
+Screenshot hello-ratatui.png
 Sleep 1s
 Type q
 Sleep 2s

code/tutorials/hello-ratatui/.github/dependabot.yml

@@ -0,0 +1,17 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+ # Maintain dependencies for Cargo
+ - package-ecosystem: "cargo"
+ directory: "/" # Location of package manifests
+ schedule:
+ interval: "weekly"
+ # Maintain dependencies for GitHub Actions
+ - package-ecosystem: github-actions
+ directory: "/"
+ schedule:
+ interval: weekly

code/tutorials/hello-ratatui/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+ pull_request:
+ push:
+ branches:
+ - main
+ - master
+ - develop
+
+env:
+ CARGO_TERM_COLOR: always
+
+# ensure that the workflow is only triggered once per PR, subsequent pushes to the PR will cancel
+# and restart the workflow. See https://docs.github.com/en/actions/using-jobs/using-concurrency
+concurrency:
+ group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+ cancel-in-progress: true
+
+jobs:
+ fmt:
+ name: fmt
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Install Rust stable
+ uses: dtolnay/rust-toolchain@stable
+ with:
+ components: rustfmt
+ - name: check formatting
+ run: cargo fmt -- --check
+ - name: Cache Cargo dependencies
+ uses: Swatinem/rust-cache@v2
+ clippy:
+ name: clippy
+ runs-on: ubuntu-latest
+ permissions:
+ checks: write
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Install Rust stable
+ uses: dtolnay/rust-toolchain@stable
+ with:
+ components: clippy
+ - name: Run clippy action
+ uses: clechasseur/rs-clippy-check@v3
+ - name: Cache Cargo dependencies
+ uses: Swatinem/rust-cache@v2
+ doc:
+ # run docs generation on nightly rather than stable. This enables features like
+ # https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html which allows an
+ # API be documented as only available in some specific platforms.
+ name: doc
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Install Rust nightly
+ uses: dtolnay/rust-toolchain@nightly
+ - name: Run cargo doc
+ run: cargo doc --no-deps --all-features
+ env:
+ RUSTDOCFLAGS: --cfg docsrs
+ test:
+ runs-on: ${{ matrix.os }}
+ name: test ${{ matrix.os }}
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [macos-latest, windows-latest]
+ steps:
+ # if your project needs OpenSSL, uncomment this to fix Windows builds.
+ # it's commented out by default as the install command takes 5-10m.
+ # - run: echo "VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT" | Out-File -FilePath $env:GITHUB_ENV -Append
+ # if: runner.os == 'Windows'
+ # - run: vcpkg install openssl:x64-windows-static-md
+ # if: runner.os == 'Windows'
+ - uses: actions/checkout@v4
+ - name: Install Rust
+ uses: dtolnay/rust-toolchain@stable
+ # enable this ci template to run regardless of whether the lockfile is checked in or not
+ - name: cargo generate-lockfile
+ if: hashFiles('Cargo.lock') == ''
+ run: cargo generate-lockfile
+ - name: cargo test --locked
+ run: cargo test --locked --all-features --all-targets
+ - name: Cache Cargo dependencies
+ uses: Swatinem/rust-cache@v2

code/tutorials/hello-ratatui/.gitignore

@@ -0,0 +1 @@
+/target

code/tutorials/hello-ratatui/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "hello-ratatui"
+version = "0.1.0"
+authors = ["Josh McKinney <[email protected]>"]
+license = "MIT"
+edition = "2021"
+
+[dependencies]
+crossterm = "0.28.1"
+ratatui = "0.28.1"
+color-eyre = "0.6.3"

code/tutorials/hello-ratatui/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Josh McKinney <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code/tutorials/hello-ratatui/README.md

@@ -0,0 +1,14 @@
+# hello-ratatui
+
+This is a [Ratatui] app generated by the [Simple template].
+
+[Ratatui]: https://ratatui.rs
+[Simple Template]: https://github.com/ratatui/templates/tree/main/simple
+
+## License
+
+Copyright (c) Josh McKinney <[email protected]>
+
+This project is licensed under the MIT license ([LICENSE] or <http://opensource.org/licenses/MIT>)
+
+[LICENSE]: ./LICENSE

code/tutorials/hello-ratatui/src/app.rs

@@ -0,0 +1,82 @@
+use color_eyre::Result;
+use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
+use ratatui::{
+ style::Stylize,
+ text::Line,
+ widgets::{Block, Paragraph},
+ DefaultTerminal, Frame,
+};
+
+#[derive(Debug, Default)]
+pub struct App {
+ /// Is the application running?
+ running: bool,
+}
+
+impl App {
+ /// Construct a new instance of [`App`].
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Run the application's main loop.
+ pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+ self.running = true;
+ while self.running {
+ terminal.draw(|frame| self.draw(frame))?;
+ self.handle_crossterm_events()?;
+ }
+ Ok(())
+ }
+
+ /// Renders the user interface.
+ ///
+ /// This is where you add new widgets. See the following resources for more information:
+ /// - <https://docs.rs/ratatui/latest/ratatui/widgets/index.html>
+ /// - <https://github.com/ratatui/ratatui/tree/master/examples>
+ fn draw(&mut self, frame: &mut Frame) {
+ let title = Line::from("Ratatui Simple Template")
+ .bold()
+ .blue()
+ .centered();
+ let text = "Hello, Ratatui!\n\n\
+ Created using https://github.com/ratatui/templates\n\
+ Press `Esc`, `Ctrl-C` or `q` to stop running.";
+ frame.render_widget(
+ Paragraph::new(text)
+ .block(Block::bordered().title(title))
+ .centered(),
+ frame.area(),
+ )
+ }
+
+ /// Reads the crossterm events and updates the state of [`App`].
+ ///
+ /// If your application needs to perform work in between handling events, you can use the
+ /// [`event::poll`] function to check if there are any events available with a timeout.
+ fn handle_crossterm_events(&mut self) -> Result<()> {
+ match event::read()? {
+ // it's important to check KeyEventKind::Press to avoid handling key release events
+ Event::Key(key) if key.kind == KeyEventKind::Press => self.on_key_event(key),
+ Event::Mouse(_) => {}
+ Event::Resize(_, _) => {}
+ _ => {}
+ }
+ Ok(())
+ }
+
+ /// Handles the key events and updates the state of [`App`].
+ fn on_key_event(&mut self, key: KeyEvent) {
+ match (key.modifiers, key.code) {
+ (_, KeyCode::Esc | KeyCode::Char('q'))
+ | (KeyModifiers::CONTROL, KeyCode::Char('c') | KeyCode::Char('C')) => self.quit(),
+ // Add other key handlers here.
+ _ => {}
+ }
+ }
+
+ /// Set running to false to quit the application.
+ fn quit(&mut self) {
+ self.running = false;
+ }
+}

code/tutorials/hello-ratatui/src/main.rs

@@ -0,0 +1,11 @@
+pub use app::App;
+
+pub mod app;
+
+fn main() -> color_eyre::Result<()> {
+ color_eyre::install()?;
+ let terminal = ratatui::init();
+ let result = App::new().run(terminal);
+ ratatui::restore();
+ result
+}

src/content/docs/developer-guide/website.mdx

@@ -86,14 +86,14 @@ Use the `remark-include-code` plugin to include code from a test file:
 
 ````markdown include=ignore
 ```rust
-{{#include @code/tutorials/hello-world/src/main.rs:imports}}
+{{#include @code/tutorials/hello-ratatui/src/main.rs}}
 ```
 ````
 
 This renders as:
 
 ```rust
-{{#include @code/tutorials/hello-world/src/main.rs:imports}}
+{{#include @code/tutorials/hello-ratatui/src/main.rs}}
 ```
 
 ### svgbob