Adds a variety of metrics to the terminal and backend modules.
Run the metrics example to see the metrics in action.
```shell
cargo run --example metrics
cargo run --example metrics --release
```
🧀
The current release steps in reference to #1337
- Bump version in `Cargo.toml`
- `git cliff -u -p CHANGELOG.md -t v0.28.1`
- Merge the PR
- `git tag v0.28.1`
- `git push origin v0.28.1`
We can probably automate away most of these with `release-plz` when it
fully supports `git-cliff`'s GitHub integration.
closes#1232
Now we can trigger point releases by pushing a tag (follow the
instructions in `RELEASE.md`). This will create a release with generated
changelog.
There is still a lack of automation (e.g. updating `CHANGELOG.md`), but
this PR is a good start towards improving that.
Reimplement Terminal::insert_before. The previous implementation would
insert the new lines in chunks into the area between the top of the
screen and the top of the (new) viewport. If the viewport filled the
screen, there would be no area in which to insert lines, and the
function would crash.
The new implementation uses as much of the screen as it needs to, all
the way up to using the whole screen.
This commit:
- adds a scrollback buffer to the `TestBackend` so that tests can
inspect and assert the state of the scrollback buffer in addition to the
screen
- adds functions to `TestBackend` to assert the state of the scrollback
- adds and updates `TestBackend` tests to test the behavior of the
scrollback and the new asserting functions
- reimplements `Terminal::insert_before`, including adding two new
helper functions `Terminal::draw_lines` and `Terminal::scroll_up`.
- updates the documentation for `Terminal::insert_before` to clarify
some of the edge cases
- updates terminal tests to assert the state of the scrollback buffer
- adds a new test for the condition that causes the bug
- adds a conversion constructor `Cell::from(char)`
Fixes: https://github.com/ratatui/ratatui/issues/999
This new example documents the various ways to implement widgets in
Ratatui. It demonstrates how to implement the `Widget` trait on a type,
a reference, and a mutable reference. It also shows how to use the
`WidgetRef` trait to render boxed widgets.
These are simple opinionated methods for creating a terminal that is
useful to use in most apps. The new init method creates a crossterm
backend writing to stdout, enables raw mode, enters the alternate
screen, and sets a panic handler that restores the terminal on panic.
A minimal hello world now looks a bit like:
```rust
use ratatui::{
crossterm::event::{self, Event},
text::Text,
Frame,
};
fn main() {
let mut terminal = ratatui::init();
loop {
terminal
.draw(|frame: &mut Frame| frame.render_widget(Text::raw("Hello World!"), frame.area()))
.expect("Failed to draw");
if matches!(event::read().expect("failed to read event"), Event::Key(_)) {
break;
}
}
ratatui::restore();
}
```
A type alias `DefaultTerminal` is added to represent this terminal
type and to simplify any cases where applications need to pass this
terminal around. It is equivalent to:
`Terminal<CrosstermBackend<Stdout>>`
We also added `ratatui::try_init()` and `try_restore()`, for situations
where you might want to handle initialization errors yourself instead
of letting the panic handler fire and cleanup. Simple Apps should
prefer the `init` and `restore` functions over these functions.
Corresponding functions to allow passing a `TerminalOptions` with
a `Viewport` (e.g. inline, fixed) are also available
(`init_with_options`,
and `try_init_with_options`).
The existing code to create a backend and terminal will remain and
is not deprecated by this approach. This just provides a simple one
line initialization using the common options.
---------
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
If the amount of characters in the screen above the viewport was greater
than u16::MAX, a multiplication would overflow. The multiply was used to
compute the maximum chunk size. The fix is to just do the multiplication
as a usize and also do the subsequent division as a usize.
There is currently another outstanding issue that limits the amount of
characters that can be inserted when calling Terminal::insert_before to
u16::MAX. However, this bug can still occur even if the viewport and the
amount of characters being inserted are both less than u16::MAX, since
it's dependant on how large the screen is above the viewport.
Fixes#1322
Termion is not supported on Windows, so we need to avoid building it.
Adds a conditional dependency to the Cargo.toml file to only include
termion when the target is not Windows. This allows contributors to
build using the `--all-features` flag on Windows rather than needing
to specify the features individually.
On large paragraphs (~1MB), this saves hundreds of thousands of
allocations.
TL;DR: reuse as much memory as possible across `next_line` calls.
Instead of allocating new buffers each time, allocate the buffers once
and clear them before reuse.
Signed-off-by: Alex Saveau <saveau.alexandre@gmail.com>
Consolidates the benchmarks into a single executable rather than having
to create a new cargo.toml setting per and makes it easier to rearrange
these when adding new benchmarks.
The new methods return/accept `Into<Position>` which can be either a Position or a (u16, u16) tuple.
```rust
backend.set_cursor_position(Position { x: 0, y: 20 })?;
let position = backend.get_cursor_position()?;
terminal.set_cursor_position((0, 20))?;
let position = terminal.set_cursor_position()?;
```
The `barchart` example has been split into two examples: `barchart` and
`barchart-grouped`. The `barchart` example now shows a simple barchart
with random data, while the `barchart-grouped` example shows a grouped
barchart with fake revenue data.
This simplifies the examples a bit so they don't cover too much at once.
- Simplify the rendering functions
- Fix several clippy lints that were marked as allowed
---------
Co-authored-by: EdJoPaTo <rfc-conform-git-commit-email@funny-long-domain-label-everyone-hates-as-it-is-too-long.edjopato.de>
Code which previously called `buf.get(x, y)` or `buf.get_mut(x, y)`
should now use index operators, or be transitioned to `buff.cell()` or
`buf.cell_mut()` for safe access that avoids panics by returning
`Option<&Cell>` and `Option<&mut Cell>`.
The new methods accept `Into<Position>` instead of `x` and `y`
coordinates, which makes them more ergonomic to use.
```rust
let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));
let cell = buf[(0, 0)];
let cell = buf[Position::new(0, 0)];
let symbol = buf.cell((0, 0)).map(|cell| cell.symbol());
let symbol = buf.cell(Position::new(0, 0)).map(|cell| cell.symbol());
buf[(0, 0)].set_symbol("🐀");
buf[Position::new(0, 0)].set_symbol("🐀");
buf.cell_mut((0, 0)).map(|cell| cell.set_symbol("🐀"));
buf.cell_mut(Position::new(0, 0)).map(|cell| cell.set_symbol("🐀"));
```
The existing `get()` and `get_mut()` methods are marked as deprecated.
These are fairly widely used and we will leave these methods around on
the buffer for a longer time than our normal deprecation approach (2
major release)
Addresses part of: https://github.com/ratatui-org/ratatui/issues/1011
---------
Co-authored-by: EdJoPaTo <rfc-conform-git-commit-email@funny-long-domain-label-everyone-hates-as-it-is-too-long.edjopato.de>
This notice was useful when the `Cargo.toml` had no standardized field
for this. Now it's easier to look it up in the `Cargo.toml` and it's
also a single point of truth. Updating the README was overlooked for
quite some time so it's better to just omit it rather than having
something wrong that will be forgotten again in the future.
Updates the requirements on [rstest](https://github.com/la10736/rstest)
to permit the latest version.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/la10736/rstest/releases">rstest's
releases</a>.</em></p>
<blockquote>
<h2>Version 0.22.0</h2>
<p>Destructuring input data</p>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/la10736/rstest/blob/master/CHANGELOG.md">rstest's
changelog</a>.</em></p>
<blockquote>
<h2>[0.22.0] 2024/8/4</h2>
<h3>Changed</h3>
<ul>
<li>Now it's possible destructuring input values both for cases, values
and fixtures. See <a
href="https://redirect.github.com/la10736/rstest/issues/231">#231</a>
for details</li>
</ul>
<h3>Add</h3>
<ul>
<li>Implemented <code>#[ignore]</code> attribute to ignore test
parameters during fixtures resolution/injection. See <a
href="https://redirect.github.com/la10736/rstest/issues/228">#228</a>
for details</li>
</ul>
<h3>Fixed</h3>
<ul>
<li>Lot of typo in code</li>
</ul>
<h2>[0.21.0] 2024/6/1</h2>
<h3>Changed</h3>
<ul>
<li>Add feature <code>crate-name</code> enabled by default to opt-in
crate rename
support. See <a
href="https://redirect.github.com/la10736/rstest/issues/258">#258</a></li>
</ul>
<h2>[0.20.0] 2024/5/30</h2>
<h3>Add</h3>
<ul>
<li>Implemented <code>#[by_ref]</code> attribute to take get a local
lifetime for test arguments.
See <a
href="https://redirect.github.com/la10736/rstest/issues/241">#241</a>
for more details. Thanks to
<a href="https://github.com/narpfel"><code>@narpfel</code></a> for
suggesting it and useful discussions.</li>
<li>Support for import <code>rstest</code> with another name. See <a
href="https://redirect.github.com/la10736/rstest/issues/221">#221</a></li>
</ul>
<h3>Fixed</h3>
<ul>
<li>Don't remove Lifetimes from test function if any. See <a
href="https://redirect.github.com/la10736/rstest/issues/230">#230</a>
<a href="https://redirect.github.com/la10736/rstest/issues/241">#241</a>
for more details.</li>
<li><a
href="https://doc.rust-lang.org/std/path/struct.PathBuf.html"><code>PathBuf</code></a>
does no longer need to be
in scope when using <code>#[files]</code> (see <a
href="https://redirect.github.com/la10736/rstest/pull/242">#242</a>)</li>
<li><code>#[from(now:🉑:also::path::for::fixture)]</code> See <a
href="https://redirect.github.com/la10736/rstest/issues/246">#246</a>
for more details</li>
</ul>
<h2>[0.19.0] 2024/4/9</h2>
<h3>Changed</h3>
<ul>
<li>Defined <code>rust-version</code> for each crate (see <a
href="https://redirect.github.com/la10736/rstest/issues/227">#227</a>)</li>
</ul>
<h3>Fixed</h3>
<ul>
<li><code>#[once]</code> fixtures now require the returned type to be
<a
href="https://doc.rust-lang.org/std/marker/trait.Sync.html"><code>Sync</code></a>
to prevent UB
when tests are executed in parallel. (see <a
href="https://redirect.github.com/la10736/rstest/issues/235">#235</a></li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="62134281cf"><code>6213428</code></a>
Prepare 0.22.0</li>
<li><a
href="16591fdcef"><code>16591fd</code></a>
Make clippy happy</li>
<li><a
href="d40e785d74"><code>d40e785</code></a>
Merge pull request <a
href="https://redirect.github.com/la10736/rstest/issues/269">#269</a>
from la10736/fix_typos</li>
<li><a
href="9110f0cff7"><code>9110f0c</code></a>
Fix typo</li>
<li><a
href="696eaf63c1"><code>696eaf6</code></a>
Merge pull request <a
href="https://redirect.github.com/la10736/rstest/issues/268">#268</a>
from la10736/arg_destruct</li>
<li><a
href="39490761ca"><code>3949076</code></a>
Fixed warning in beta</li>
<li><a
href="d35ade2521"><code>d35ade2</code></a>
Docs and make clippy happy</li>
<li><a
href="40087a7aa3"><code>40087a7</code></a>
Implementation and integration tests</li>
<li><a
href="fcf732dc34"><code>fcf732d</code></a>
Merge pull request <a
href="https://redirect.github.com/la10736/rstest/issues/267">#267</a>
from marcobacis/ignore_parameter</li>
<li><a
href="cf9dd0bf51"><code>cf9dd0b</code></a>
update docs, simplified unit test</li>
<li>Additional commits viewable in <a
href="https://github.com/la10736/rstest/compare/v0.21.0...v0.22.0">compare
view</a></li>
</ul>
</details>
<br />
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Addresses some confusion about when to implement `WidgetRef` vs `impl
Widget for &W`. Notes the stability rationale and links to an issue that
helps explain the context of where we're at in working this out.
Bumps
[EmbarkStudios/cargo-deny-action](https://github.com/embarkstudios/cargo-deny-action)
from 1 to 2.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/embarkstudios/cargo-deny-action/releases">EmbarkStudios/cargo-deny-action's
releases</a>.</em></p>
<blockquote>
<h2>Release 2.0.1 - cargo-deny 0.16.1</h2>
<h3>Fixed</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/691">PR#691</a>
fixed an issue where workspace dependencies that used the current dir
'.' path component would incorrectly trigger the
<code>unused-workspace-dependency</code> lint.</li>
</ul>
<h2>Release 2.0.0 - cargo-deny 0.16.0</h2>
<h2><code>Action</code></h2>
<h3>Added</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny-action/pull/78">PR#78</a>
added SSH support, thanks <a
href="https://github.com/nagua"><code>@nagua</code></a>!</li>
</ul>
<h3>Changed</h3>
<ul>
<li>This release includes breaking changes in cargo-deny, so this
release begins the <code>v2</code> tag, using <code>v1</code> will be
stable but not follow future <code>cargo-deny</code> releases.</li>
</ul>
<h2><code>cargo-deny</code></h2>
<h3>Removed</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/681">PR#681</a>
finished the deprecation introduced in <a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/611">PR#611</a>,
making the usage of the deprecated fields into errors.</li>
</ul>
<h4><code>[advisories]</code></h4>
<p>The following fields have all been removed in favor of denying all
advisories by default. To ignore an advisory the <a
href="https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html#the-ignore-field-optional"><code>ignore</code></a>
field can be used as before.</p>
<ul>
<li><code>vulnerability</code> - Vulnerability advisories are now
<code>deny</code> by default</li>
<li><code>unmaintained</code> - Unmaintained advisories are now
<code>deny</code> by default</li>
<li><code>unsound</code> - Unsound advisories are now <code>deny</code>
by default</li>
<li><code>notice</code> - Notice advisories are now <code>deny</code> by
default</li>
<li><code>severity-threshold</code> - The severity of vulnerabilities is
now irrelevant</li>
</ul>
<h4><code>[licenses]</code></h4>
<p>The following fields have all been removed in favor of denying all
licenses that are not explicitly allowed via either <a
href="https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html#the-allow-field-optional"><code>allow</code></a>
or <a
href="https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html#the-exceptions-field-optional"><code>exceptions</code></a>.</p>
<ul>
<li><code>unlicensed</code> - Crates whose license(s) cannot be
confidently determined are now always errors. The <a
href="https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html#the-clarify-field-optional"><code>clarify</code></a>
field can be used to help cargo-deny determine the license.</li>
<li><code>allow-osi-fsf-free</code> - The OSI/FSF Free attributes are
now irrelevant, only whether it is explicitly allowed.</li>
<li><code>copyleft</code> - The copyleft attribute is now irrelevant,
only whether it is explicitly allowed.</li>
<li><code>default</code> - The default is now <code>deny</code>.</li>
<li><code>deny</code> - All licenses are now denied by default, this
field added nothing.</li>
</ul>
<h3>Changed</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/685">PR#685</a>
follows up on <a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/673">PR#673</a>,
moving the fields that were added to their own separate <a
href="https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html#the-workspace-dependencies-field-optional"><code>bans.workspace-dependencies</code></a>
section. This is an unannounced breaking change but is fairly minor and
0.15.0 was never released on github actions so the amount of people
affected by this will be (hopefully) small. This also makes the
workspace duplicate detection off by default since the field is
optional, <em>but</em> makes it so that if not specified workspace
duplicates are now <code>deny</code> instead of <code>warn</code>.</li>
</ul>
<h3>Fixed</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/685">PR#685</a>
resolved <a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/issues/682">#682</a>
by adding the <code>include-path-dependencies</code> field, allowing
path dependencies to be ignored if it is <code>false</code>.</li>
</ul>
<h2>Release 1.6.3 - cargo-deny 0.14.21</h2>
<h3>Fixed</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/643">PR#643</a>
resolved <a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/issues/629">#629</a>
by making the hosted git (github, gitlab, bitbucket) org/user name
comparison case-insensitive. Thanks <a
href="https://github.com/pmnlla"><code>@pmnlla</code></a>!</li>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/649">PR#649</a>
fixed an issue where depending on the same crate multiple times by using
different <code>cfg()/triple</code> targets could cause features to be
resolved incorrectly and thus crates to be not pulled into the graph
used for checking.</li>
</ul>
<h2>[0.14.20] - 2024-03-23</h2>
<h3>Fixed</h3>
<ul>
<li><a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/pull/642">PR#642</a>
resolved <a
href="https://redirect.github.com/EmbarkStudios/cargo-deny/issues/641">#641</a>
by pinning <code>gix-transport</code> (and its unique dependencies) to
0.41.2 as a workaround for <code>cargo install</code> not using the
lockfile. See <a
href="https://redirect.github.com/Byron/gitoxide/issues/1328">this
issue</a> for more information.</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="8371184bd1"><code>8371184</code></a>
Bump to 0.16.1</li>
<li><a
href="08954043da"><code>0895404</code></a>
Move to v2 tag</li>
<li><a
href="10d8902cf9"><code>10d8902</code></a>
Bump to 0.16.0</li>
<li><a
href="d425dbf412"><code>d425dbf</code></a>
Update .gitignore</li>
<li><a
href="53bface5b1"><code>53bface</code></a>
Update image base</li>
<li><a
href="3f8dc3eed7"><code>3f8dc3e</code></a>
Add ability to fetch git dependecies in cargo via ssh (<a
href="https://redirect.github.com/embarkstudios/cargo-deny-action/issues/78">#78</a>)</li>
<li>See full diff in <a
href="https://github.com/embarkstudios/cargo-deny-action/compare/v1...v2">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
This example demonstrates how to use Ratatui with widgets that fetch
data asynchronously. It uses the `octocrab` crate to fetch a list of
pull requests from the GitHub API. You will need an environment
variable named `GITHUB_TOKEN` with a valid GitHub personal access
token. The token does not need any special permissions.
Co-authored-by: Dheepak Krishnamurthy <me@kdheepak.com>
Removes the height and width fields from TestBackend, which can get
out of sync with the Buffer, which currently clamps to 255,255.
This changes the `TestBackend` serde representation. It should be
possible to read older data, but data generated after this change
can't be read by older versions.
`axis.labels(vec![])` removes all the labels correctly.
This makes calling axis.labels with an empty Vec the equivalent
of not calling axis.labels. It's likely that this is never used, but it
prevents weird cases by removing the mix-up of `Option::None`
and `Vec::is_empty`, and simplifies the implementation code.
