From 7e00b646fcca58d00ec5b142f71d2b46acb43819 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Orhun=20Parmaks=C4=B1z?= Date: Fri, 7 Feb 2025 04:43:18 +0300 Subject: [PATCH] docs(examples): move panic example to examples folder (#1655) --- Cargo.lock | 9 +++ examples/README.md | 4 ++ examples/apps/panic/Cargo.toml | 14 ++++ examples/apps/panic/README.md | 9 +++ .../apps/panic/src/main.rs | 71 ++++++++----------- ratatui/Cargo.toml | 5 -- 6 files changed, 67 insertions(+), 45 deletions(-) create mode 100644 examples/apps/panic/Cargo.toml create mode 100644 examples/apps/panic/README.md rename ratatui/examples/panic.rs => examples/apps/panic/src/main.rs (51%) diff --git a/Cargo.lock b/Cargo.lock index 4c52a5f9..5ad72b29 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2102,6 +2102,15 @@ dependencies = [ "syn 2.0.98", ] +[[package]] +name = "panic" +version = "0.0.0" +dependencies = [ + "color-eyre", + "crossterm", + "ratatui", +] + [[package]] name = "parking_lot" version = "0.12.3" diff --git a/examples/README.md b/examples/README.md index f873d011..4e26e843 100644 --- a/examples/README.md +++ b/examples/README.md @@ -118,6 +118,10 @@ Shows how to handle mouse events. [Source](./apps/mouse-drawing/). Shows how to create a minimal application. [Source](./apps/minimal/). +## Panic demo + +Shows how to handle panics in your application. [Source](./apps/panic/). + ## Popup demo Shows how to handle popups. [Source](./apps/popup/). diff --git a/examples/apps/panic/Cargo.toml b/examples/apps/panic/Cargo.toml new file mode 100644 index 00000000..987004db --- /dev/null +++ b/examples/apps/panic/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "panic" +publish = false +license.workspace = true +edition.workspace = true +rust-version.workspace = true + +[dependencies] +color-eyre.workspace = true +crossterm.workspace = true +ratatui.workspace = true + +[lints] +workspace = true diff --git a/examples/apps/panic/README.md b/examples/apps/panic/README.md new file mode 100644 index 00000000..6dacb310 --- /dev/null +++ b/examples/apps/panic/README.md @@ -0,0 +1,9 @@ +# Panic demo + +This example shows how to handle panics in your application. + +To run this demo: + +```shell +cargo run -p panic +``` diff --git a/ratatui/examples/panic.rs b/examples/apps/panic/src/main.rs similarity index 51% rename from ratatui/examples/panic.rs rename to examples/apps/panic/src/main.rs index a0f91501..42785893 100644 --- a/ratatui/examples/panic.rs +++ b/examples/apps/panic/src/main.rs @@ -1,43 +1,34 @@ -//! # [Ratatui] Panic Hook example -//! -//! The latest version of this example is available in the [examples] folder in the repository. -//! -//! Please note that the examples are designed to be run against the `main` branch of the Github -//! repository. This means that you may not be able to compile with the latest release version on -//! crates.io, or the one that you have installed locally. -//! -//! See the [examples readme] for more information on finding examples that match the version of the -//! library you are using. -//! -//! [Ratatui]: https://github.com/ratatui/ratatui -//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples -//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md -//! -//! Prior to Ratatui 0.28.1, a panic hook had to be manually set up to ensure that the terminal was -//! reset when a panic occurred. This was necessary because a panic would interrupt the normal -//! control flow and leave the terminal in a distorted state. -//! -//! Starting with Ratatui 0.28.1, the panic hook is automatically set up by the new `ratatui::init` -//! function, so you no longer need to manually set up the panic hook. This example now demonstrates -//! how the panic hook acts when it is enabled by default. -//! -//! When exiting normally or when handling `Result::Err`, we can reset the terminal manually at the -//! end of `main` just before we print the error. -//! -//! Because a panic interrupts the normal control flow, manually resetting the terminal at the end -//! of `main` won't do us any good. Instead, we need to make sure to set up a panic hook that first -//! resets the terminal before handling the panic. This both reuses the standard panic hook to -//! ensure a consistent panic handling UX and properly resets the terminal to not distort the -//! output. -//! -//! That's why this example is set up to show both situations, with and without the panic hook, to -//! see the difference. -//! -//! For more information on how to set this up manually, see the [Color Eyre recipe] in the Ratatui -//! website. -//! -//! [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre - +/// A Ratatui example that demonstrates how to handle panics in your application. +/// +/// Prior to Ratatui 0.28.1, a panic hook had to be manually set up to ensure that the terminal +/// was reset when a panic occurred. This was necessary because a panic would interrupt the +/// normal control flow and leave the terminal in a distorted state. +/// +/// Starting with Ratatui 0.28.1, the panic hook is automatically set up by the new +/// `ratatui::init` function, so you no longer need to manually set up the panic hook. This +/// example now demonstrates how the panic hook acts when it is enabled by default. +/// +/// When exiting normally or when handling `Result::Err`, we can reset the terminal manually at +/// the end of `main` just before we print the error. +/// +/// Because a panic interrupts the normal control flow, manually resetting the terminal at the +/// end of `main` won't do us any good. Instead, we need to make sure to set up a panic hook +/// that first resets the terminal before handling the panic. This both reuses the standard +/// panic hook to ensure a consistent panic handling UX and properly resets the terminal to not +/// distort the output. +/// +/// That's why this example is set up to show both situations, with and without the panic hook, +/// to see the difference. +/// +/// For more information on how to set this up manually, see the [Color Eyre recipe] in the +/// Ratatui website. +/// +/// This example runs with the Ratatui library code in the branch that you are currently +/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui +/// release. +/// +/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest +/// [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre use color_eyre::{eyre::bail, Result}; use ratatui::{ crossterm::event::{self, Event, KeyCode}, diff --git a/ratatui/Cargo.toml b/ratatui/Cargo.toml index b4f389c2..55b8be37 100644 --- a/ratatui/Cargo.toml +++ b/ratatui/Cargo.toml @@ -147,11 +147,6 @@ bench = false name = "main" harness = false -[[example]] -name = "panic" -required-features = ["crossterm"] -doc-scrape-examples = true - [[example]] name = "scrollbar-widget" required-features = ["crossterm"]