Skip to content

Commit

Permalink
tabled/ work on documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@zhiburt
zhiburt committed Nov 21, 2024
1 parent 2bb1175 commit 9b058c1
Show file tree
Hide file tree
Showing 11 changed files with 411 additions and 353 deletions.
282 changes: 127 additions & 155 deletions README.md
View file

Large diffs are not rendered by default.

73 changes: 31 additions & 42 deletions tabled/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,73 +20,62 @@ Most of a table configuration can be found in [`tabled::settings`](https://docs.

```rust
use tabled::{Table, Tabled};
use testing_table::assert_table;

#[derive(Tabled)]
struct Language {
name: String,
designed_by: String,
struct Language<'a> {
name: &'a str,
designed_by: &'a str,
invented_year: usize,
}

impl Language {
fn new(name: &str, designed_by: &str, invented_year: usize) -> Self {
Self {
name: name.to_string(),
designed_by: designed_by.to_string(),
invented_year,
}
}
}

let languages = vec![
Language::new("C", "Dennis Ritchie", 1972),
Language::new("Go", "Rob Pike", 2009),
Language::new("Rust", "Graydon Hoare", 2010),
Language::new("Hare", "Drew DeVault", 2022),
Language { name: "C", designed_by: "Dennis Ritchie", invented_year: 1972 },
Language { name: "Go", designed_by: "Rob Pike", invented_year: 2009 },
Language { name: "Rust", designed_by: "Graydon Hoare", invented_year: 2010 },
Language { name: "Hare", designed_by: "Drew DeVault", invented_year: 2022 },
];

let table = Table::new(languages).to_string();
let table = Table::new(languages);

assert_eq!(
assert_table!(
table,
"+------+----------------+---------------+\n\
| name | designed_by | invented_year |\n\
+------+----------------+---------------+\n\
| C | Dennis Ritchie | 1972 |\n\
+------+----------------+---------------+\n\
| Go | Rob Pike | 2009 |\n\
+------+----------------+---------------+\n\
| Rust | Graydon Hoare | 2010 |\n\
+------+----------------+---------------+\n\
| Hare | Drew DeVault | 2022 |\n\
+------+----------------+---------------+"
"+------+----------------+---------------+"
"| name | designed_by | invented_year |"
"+------+----------------+---------------+"
"| C | Dennis Ritchie | 1972 |"
"+------+----------------+---------------+"
"| Go | Rob Pike | 2009 |"
"+------+----------------+---------------+"
"| Rust | Graydon Hoare | 2010 |"
"+------+----------------+---------------+"
"| Hare | Drew DeVault | 2022 |"
"+------+----------------+---------------+"
);
```

The same example but we are building a table step by step.

```rust
use tabled::{builder::Builder, settings::Style};
use testing_table::assert_table;

let mut builder = Builder::new();
builder.push_record(["C", "Dennis Ritchie", "1972"]);
builder.push_record(["Go", "Rob Pike", "2009"]);
builder.push_record(["Rust", "Graydon Hoare", "2010"]);
builder.push_record(["Hare", "Drew DeVault", "2022"]);

let table = builder.build()
.with(Style::ascii_rounded())
.to_string();
let mut table = builder.build();
table.with(Style::ascii_rounded());

assert_eq!(
assert_table!(
table,
concat!(
".------------------------------.\n",
"| C | Dennis Ritchie | 1972 |\n",
"| Go | Rob Pike | 2009 |\n",
"| Rust | Graydon Hoare | 2010 |\n",
"| Hare | Drew DeVault | 2022 |\n",
"'------------------------------'"
)
".------------------------------."
"| C | Dennis Ritchie | 1972 |"
"| Go | Rob Pike | 2009 |"
"| Rust | Graydon Hoare | 2010 |"
"| Hare | Drew DeVault | 2022 |"
"'------------------------------'"
);
```
2 changes: 1 addition & 1 deletion tabled/examples/border_text.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ fn main() {
.with(theme)
.with(LineText::new("Numbers", Rows::first()).offset(1))
.with(LineText::new("More numbers", Rows::single(1)).offset(1))
.with(LineText::new("end", Rows::last()).offset(1))
.with(LineText::new("end", Rows::last() + 1).offset(1))
.to_string();

println!("{table}");
Expand Down
18 changes: 3 additions & 15 deletions tabled/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,9 @@
//! }
//!
//! let languages = vec![
//! Language{
//! name: "C",
//! designed_by: "Dennis Ritchie",
//! invented_year: 1972
//! },
//! Language{
//! name: "Rust",
//! designed_by: "Graydon Hoare",
//! invented_year: 2010
//! },
//! Language{
//! name: "Go",
//! designed_by: "Rob Pike",
//! invented_year: 2009
//! },
//! Language{ name: "C", designed_by: "Dennis Ritchie", invented_year: 1972 },
//! Language{ name: "Rust", designed_by: "Graydon Hoare", invented_year: 2010 },
//! Language{ name: "Go", designed_by: "Rob Pike", invented_year: 2009 },
//! ];
//!
//! let table = Table::new(languages).to_string();
Expand Down
2 changes: 1 addition & 1 deletion tabled/src/settings/peaker/mod.rs
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! The module contains [`Priority`] and [`Peaker`] trait,
//! its implementations to be used in [`Height`] and [`Width`].
//!
//!
//! [`Width`]: crate::settings::width::Width
//! [`Height`]: crate::settings::height::Height
Expand Down
130 changes: 65 additions & 65 deletions tabled/src/tables/compact.rs
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,4 @@
//! This module contains a [`CompactTable`] table.
//!
//! In contrast to [`Table`] [`CompactTable`] does no allocations but it consumes an iterator.
//! It's useful when you don't want to re/allocate a buffer for your data.
//!
//! # Example
//!
//! It works smoothly with arrays.
//!
#![cfg_attr(feature = "std", doc = "```")]
#![cfg_attr(not(feature = "std"), doc = "```ignore")]
//!use tabled::{settings::Style, tables::CompactTable};
//!
//! let data = [
//! ["FreeBSD", "1993", "William and Lynne Jolitz", "?"],
//! ["OpenBSD", "1995", "Theo de Raadt", ""],
//! ["HardenedBSD", "2014", "Oliver Pinter and Shawn Webb", ""],
//! ];
//!
//! let table = CompactTable::from(data)
//! .with(Style::psql())
//! .to_string();
//!
//! assert_eq!(
//! table,
//! concat!(
//! " FreeBSD | 1993 | William and Lynne Jolitz | ? \n",
//! " OpenBSD | 1995 | Theo de Raadt | \n",
//! " HardenedBSD | 2014 | Oliver Pinter and Shawn Webb | ",
//! )
//! );
//! ```
//!
//! But it's default creation requires to be given an estimated cell width, and the amount of columns.
//!
#![cfg_attr(feature = "std", doc = "```")]
#![cfg_attr(not(feature = "std"), doc = "```ignore")]
//!use tabled::{settings::Style, tables::CompactTable};
//!
//! let data = [
//! ["FreeBSD", "1993", "William and Lynne Jolitz", "?"],
//! ["OpenBSD", "1995", "Theo de Raadt", ""],
//! ["HardenedBSD", "2014", "Oliver Pinter and Shawn Webb", ""],
//! ];
//!
//! // See what will happen if the given width is too narrow
//!
//! let table = CompactTable::new(&data)
//! .columns(4)
//! .width(5)
//! .with(Style::ascii())
//! .to_string();
//!
//! assert_eq!(
//! table,
//! "+-----+-----+-----+-----+\n\
//! | FreeBSD | 1993 | William and Lynne Jolitz | ? |\n\
//! |-----+-----+-----+-----|\n\
//! | OpenBSD | 1995 | Theo de Raadt | |\n\
//! |-----+-----+-----+-----|\n\
//! | HardenedBSD | 2014 | Oliver Pinter and Shawn Webb | |\n\
//! +-----+-----+-----+-----+"
//! );
//! ```
//!
//! [`Table`]: crate::Table
use core::cmp::max;
use core::fmt;
Expand All @@ -84,6 +19,71 @@ use crate::{

/// A table which consumes an [`IntoRecords`] iterator.
/// It assumes that the content has only single line.
///
/// In contrast to [`Table`] [`CompactTable`] does no allocations but it consumes an iterator.
/// It's useful when you don't want to re/allocate a buffer for your data.
///
/// # Example
///
/// It works smoothly with arrays.
///
#[cfg_attr(feature = "std", doc = "```")]
#[cfg_attr(not(feature = "std"), doc = "```ignore")]
/// use tabled::{settings::Style, tables::CompactTable};
///
/// let data = [
/// ["FreeBSD", "1993", "William and Lynne Jolitz", "?"],
/// ["OpenBSD", "1995", "Theo de Raadt", ""],
/// ["HardenedBSD", "2014", "Oliver Pinter and Shawn Webb", ""],
/// ];
///
/// let table = CompactTable::from(data)
/// .with(Style::psql())
/// .to_string();
///
/// assert_eq!(
/// table,
/// concat!(
/// " FreeBSD | 1993 | William and Lynne Jolitz | ? \n",
/// " OpenBSD | 1995 | Theo de Raadt | \n",
/// " HardenedBSD | 2014 | Oliver Pinter and Shawn Webb | ",
/// )
/// );
/// ```
///
/// But it's default creation requires to be given an estimated cell width, and the amount of columns.
///
#[cfg_attr(feature = "std", doc = "```")]
#[cfg_attr(not(feature = "std"), doc = "```ignore")]
/// use tabled::{settings::Style, tables::CompactTable};
///
/// let data = [
/// ["FreeBSD", "1993", "William and Lynne Jolitz", "?"],
/// ["OpenBSD", "1995", "Theo de Raadt", ""],
/// ["HardenedBSD", "2014", "Oliver Pinter and Shawn Webb", ""],
/// ];
///
/// // See what will happen if the given width is too narrow
///
/// let table = CompactTable::new(&data)
/// .columns(4)
/// .width(5)
/// .with(Style::ascii())
/// .to_string();
///
/// assert_eq!(
/// table,
/// "+-----+-----+-----+-----+\n\
/// | FreeBSD | 1993 | William and Lynne Jolitz | ? |\n\
/// |-----+-----+-----+-----|\n\
/// | OpenBSD | 1995 | Theo de Raadt | |\n\
/// |-----+-----+-----+-----|\n\
/// | HardenedBSD | 2014 | Oliver Pinter and Shawn Webb | |\n\
/// +-----+-----+-----+-----+"
/// );
/// ```
///
/// [`Table`]: crate::Table
#[derive(Debug, Clone)]
pub struct CompactTable<I, D> {
records: I,
Expand Down
91 changes: 31 additions & 60 deletions tabled/src/tables/extended.rs
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,5 @@
//! This module contains an [`ExtendedTable`] structure which is useful in cases where
//! a structure has a lot of fields.
//!
#![cfg_attr(feature = "derive", doc = "```")]
#![cfg_attr(not(feature = "derive"), doc = "```ignore")]
//! use tabled::{Tabled, tables::ExtendedTable};
//!
//! #[derive(Tabled)]
//! struct Language {
//! name: &'static str,
//! designed_by: &'static str,
//! invented_year: usize,
//! }
//!
//! let languages = vec![
//! Language{
//! name: "C",
//! designed_by: "Dennis Ritchie",
//! invented_year: 1972
//! },
//! Language{
//! name: "Rust",
//! designed_by: "Graydon Hoare",
//! invented_year: 2010
//! },
//! Language{
//! name: "Go",
//! designed_by: "Rob Pike",
//! invented_year: 2009
//! },
//! ];
//!
//! let table = ExtendedTable::new(languages).to_string();
//!
//! let expected = "-[ RECORD 0 ]-+---------------\n\
//! name | C\n\
//! designed_by | Dennis Ritchie\n\
//! invented_year | 1972\n\
//! -[ RECORD 1 ]-+---------------\n\
//! name | Rust\n\
//! designed_by | Graydon Hoare\n\
//! invented_year | 2010\n\
//! -[ RECORD 2 ]-+---------------\n\
//! name | Go\n\
//! designed_by | Rob Pike\n\
//! invented_year | 2009";
//!
//! assert_eq!(table, expected);
//! ```
use crate::grid::util::string::get_line_width;
use crate::Tabled;
Expand All @@ -62,21 +15,39 @@ use std::rc::Rc;
/// It escapes strings to resolve a multi-line ones.
/// Because of that ANSI sequences will be not be rendered too so colores will not be showed.
///
/// ```
/// use tabled::tables::ExtendedTable;
#[cfg_attr(feature = "derive", doc = "```")]
#[cfg_attr(not(feature = "derive"), doc = "```ignore")]
/// use tabled::{Tabled, tables::ExtendedTable};
///
/// #[derive(Tabled)]
/// struct Language {
/// name: &'static str,
/// designed_by: &'static str,
/// invented_year: usize,
/// }
///
/// let languages = vec![
/// Language{ name: "C", designed_by: "Dennis Ritchie", invented_year: 1972 },
/// Language{ name: "Rust", designed_by: "Graydon Hoare", invented_year: 2010 },
/// Language{ name: "Go", designed_by: "Rob Pike", invented_year: 2009 },
/// ];
///
/// let table = ExtendedTable::new(languages).to_string();
///
/// let data = vec!["Hello", "2021"];
/// let table = ExtendedTable::new(&data).to_string();
/// let expected = "-[ RECORD 0 ]-+---------------\n\
/// name | C\n\
/// designed_by | Dennis Ritchie\n\
/// invented_year | 1972\n\
/// -[ RECORD 1 ]-+---------------\n\
/// name | Rust\n\
/// designed_by | Graydon Hoare\n\
/// invented_year | 2010\n\
/// -[ RECORD 2 ]-+---------------\n\
/// name | Go\n\
/// designed_by | Rob Pike\n\
/// invented_year | 2009";
///
/// assert_eq!(
/// table,
/// concat!(
/// "-[ RECORD 0 ]-\n",
/// "&str | Hello\n",
/// "-[ RECORD 1 ]-\n",
/// "&str | 2021",
/// )
/// );
/// assert_eq!(table, expected);
/// ```
#[derive(Clone)]
pub struct ExtendedTable {
Expand Down
Loading

0 comments on commit 9b058c1

Please sign in to comment.