Skip to content

Commit 0979c97

Browse files
tertsdiepraamtertsdiepraam
committed
update and format README.md
1 parent fe0a129 commit 0979c97

File tree

1 file changed

+48
-30
lines changed

1 file changed

+48
-30
lines changed

‎README.md

+48-30
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,22 @@
44

55
# uutils-term-grid
66

7-
This library arranges textual data in a grid format suitable for fixed-width fonts, using an algorithm to minimise the amount of space needed.
7+
This library arranges textual data in a grid format suitable for fixed-width
8+
fonts, using an algorithm to minimise the amount of space needed.
89

910
---
1011

11-
This library is forked from the [`rust-term-grid`](https://github.com/ogham/rust-term-grid) library.
12+
This library is forked from the unmaintained
13+
[`rust-term-grid`](https://github.com/ogham/rust-term-grid) library. The core
14+
functionality has remained the same, with some additional bugfixes, performance
15+
improvements and a new API.
1216

1317
---
1418

1519
# Installation
1620

17-
This crate works with `cargo`. Add the following to your `Cargo.toml` dependencies section:
21+
This crate works with `cargo`. Add the following to your `Cargo.toml`
22+
dependencies section:
1823

1924
```toml
2025
[dependencies]
@@ -23,18 +28,26 @@ uutils_term_grid = "0.3"
2328

2429
The Minimum Supported Rust Version is 1.70.
2530

26-
This library arranges textual data in a grid format suitable for
27-
fixed-width fonts, using an algorithm to minimise the amount of space
28-
needed. For example:
31+
This library arranges textual data in a grid format suitable for fixed-width
32+
fonts, using an algorithm to minimise the amount of space needed. For example:
2933

3034
```rust
3135
use term_grid::{Grid, GridOptions, Direction, Filling};
3236

37+
// Create a `Vec` of text to put in the grid
3338
let cells = vec![
3439
"one", "two", "three", "four", "five", "six",
3540
"seven", "eight", "nine", "ten", "eleven", "twelve"
3641
];
3742

43+
// Then create a `Grid` with those cells.
44+
// The grid requires several options:
45+
// - The filling determines the string used as separator
46+
// between the columns.
47+
// - The direction specifies whether the layout should
48+
// be done row-wise or column-wise.
49+
// - The width is the maximum width that the grid might
50+
// have.
3851
let grid = Grid::new(
3952
cells,
4053
GridOptions {
@@ -44,6 +57,7 @@ let grid = Grid::new(
4457
}
4558
);
4659

60+
// A `Grid` implements `Display` and can be printed directly.
4761
println!("{grid}");
4862
```
4963

@@ -57,35 +71,39 @@ nine ten eleven twelve
5771

5872
## Creating a grid
5973

60-
To add data to a grid, first create a new [`Grid`] value with a list of strings and a set of options.
74+
To add data to a grid, first create a new [`Grid`] value with a list of strings
75+
and a set of options.
6176

62-
There are three options that must be specified in the [`GridOptions`] value
63-
that dictate how the grid is formatted:
77+
There are three options that must be specified in the [`GridOptions`] value that
78+
dictate how the grid is formatted:
6479

65-
- [`filling`](struct.GridOptions.html#structfield.direction): what to put in between two columns — either a number of
80+
- [`filling`][filling]: what to put in between two columns — either a number of
6681
spaces, or a text string;
67-
- [`direction`](struct.GridOptions.html#structfield.direction): specifies whether the cells should go along
68-
rows, or columns:
69-
- `Direction::LeftToRight` starts them in the top left and
70-
moves _rightwards_, going to the start of a new row after reaching the
71-
final column;
72-
- `Direction::TopToBottom` starts them in the top left and moves
73-
_downwards_, going to the top of a new column after reaching the final
82+
- [`direction`][direction]: specifies whether the cells should go along rows, or
83+
columns:
84+
- [`Direction::LeftToRight`][LeftToRight] starts them in the top left and
85+
moves _rightwards_, going to the start of a new row after reaching the final
86+
column;
87+
- [`Direction::TopToBottom`][TopToBottom] starts them in the top left and
88+
moves _downwards_, going to the top of a new column after reaching the final
7489
row.
75-
- [`width`](struct.GridOptions.html#structfield.direction): the width to fill the grid into. Usually, this should be the width
76-
of the terminal.
90+
- [`width`][width]: the width to fill the grid into. Usually, this should be the
91+
width of the terminal.
7792

78-
## Cells and data
93+
[filling]: struct.GridOptions.html#structfield.filling
94+
[direction]: struct.GridOptions.html#structfield.direction
95+
[width]: struct.GridOptions.html#structfield.width
96+
[LeftToRight]: enum.Direction.html#variant.LeftToRight
97+
[TopToBottom]: enum.Direction.html#variant.TopToBottom
7998

80-
Grids to not take [`String`]s or `&str`s — they take [`Cell`] values.
99+
## Width of grid cells
81100

82-
A [`Cell`] is a struct containing an individual cell’s contents, as a string,
83-
and its pre-computed length, which gets used when calculating a grid’s final
84-
dimensions. Usually, you want the _Unicode width_ of the string to be used for
85-
this, so you can turn a [`String`] into a [`Cell`] with the `.into()` function.
101+
This library calculates the width of strings as displayed in the terminal using
102+
the [`textwrap`][textwrap] library (with the [`display_width`][display_width] function).
103+
This takes into account the width of characters and ignores ANSI codes.
86104

87-
However, you may also want to supply your own width: when you already know the
88-
width in advance, or when you want to change the measurement, such as skipping
89-
over terminal control characters. For cases like these, the fields on the
90-
[`Cell`] values are public, meaning you can construct your own instances as
91-
necessary.
105+
The width calculation is currently not configurable. If you have a use-case for
106+
which this calculation is wrong, please open an issue.
107+
108+
[textwrap]: https://docs.rs/textwrap/latest/textwrap/index.html
109+
[display_width]: https://docs.rs/textwrap/latest/textwrap/core/fn.display_width.html

0 commit comments

Comments
 (0)