From bc7636ef4d1421d861d2d874199facc241f88529 Mon Sep 17 00:00:00 2001 From: Chris Emerson Date: Thu, 14 Dec 2023 22:21:38 +0000 Subject: [PATCH 1/3] Changes for release 0.7.0. --- CHANGELOG.md | 13 +++++++++++++ Cargo.toml | 2 +- README.md | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b1fec81..8f11d0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,19 @@ Possible log types: - `[fixed]` for any bug fixes. - `[security]` to invite users to upgrade in case of vulnerabilities. +### 0.7.0 + +- [changed] Remove some noisy stderr output when encoutering control chars + (thanks sftse) +- [added] A builder-based config API. +- [changed] Updated MSRV to 1.60 +- [fixed] Fixed #88: panic when a width of zero passed in (thanks bingen13) +- [fixed] Fixed #90: Fixed a divide-by-zero panic with colspan=0 (thanks mtorromeo) +- [added] Add very basic CSS colour support (under the css feature flag) +- [changed] Overhauled error handling. Internally (and in the lower level + API) errors (mainly "TooNarrow") are passed around with `Result`. Fixed + some panics and infinite loops. (Thanks WIZeaz for fuzzing) + ### 0.6.0 - [changed] Improve layout of tables thanks to sftse: diff --git a/Cargo.toml b/Cargo.toml index a674cc7..b00ff41 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "html2text" -version = "0.6.0" +version = "0.7.0" authors = ["Chris Emerson "] description = "Render HTML as plain text." repository = "https://github.com/jugglerchris/rust-html2text/" diff --git a/README.md b/README.md index 7bea1f8..f90fe9d 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,13 @@ The project aims to do a reasonable job of rendering reasonable HTML in a terminal or other places where HTML needs to be converted to text (for example the text/plain fallback in HTML e-mails). +With features (see below) some CSS/colour support is available. + ## Examples +The simple functions like `from_read()` return formatted text (in various +formats including plain text). + ```rust use html2text::from_read; let html = b" @@ -32,6 +37,29 @@ assert_eq!(from_read(&html[..], 20), "); ``` +A lower level API gives a bit more control. This give the same result (except for +returning errors as Result instead of panicking): + +```rust +use html2text::config; + +let html = b" + "; + +assert_eq!( + config::plain() + .string_from_read(html, 20), + Ok("\ +* Item one +* Item two +* Item three +"); +``` + A couple of simple demonstration programs are included as examples: ### html2text @@ -56,3 +84,7 @@ $ cargo run --example html2term foo.html Note that this example takes the HTML file as a parameter so that it can read keys from stdin. + +## Cargo Features + + From 42fe36420cadd5fe68c48c8b1ec334b774c7cd09 Mon Sep 17 00:00:00 2001 From: Chris Emerson Date: Fri, 15 Dec 2023 07:09:27 +0000 Subject: [PATCH 2/3] Updates ready for release. Remove ansi_colour feature - the function is available all the time now. --- CHANGELOG.md | 1 + Cargo.toml | 1 - README.md | 25 ++++++++++++++++++++++++- examples/html2text.rs | 13 +++---------- src/lib.rs | 2 -- 5 files changed, 28 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f11d0a..386ecc1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Possible log types: - [fixed] Fixed #88: panic when a width of zero passed in (thanks bingen13) - [fixed] Fixed #90: Fixed a divide-by-zero panic with colspan=0 (thanks mtorromeo) - [added] Add very basic CSS colour support (under the css feature flag) +- [changed] Removed ansi\_colours feature (from\_read\_coloured is always available) - [changed] Overhauled error handling. Internally (and in the lower level API) errors (mainly "TooNarrow") are passed around with `Result`. Fixed some panics and infinite loops. (Thanks WIZeaz for fuzzing) diff --git a/Cargo.toml b/Cargo.toml index b00ff41..e07d891 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -26,7 +26,6 @@ lightningcss = { version = "1.0.0-alpha.51", optional=true } html_trace = [] html_trace_bt = ["backtrace"] default = [] -ansi_colours = [] css = ["dep:lightningcss"] [[example]] diff --git a/README.md b/README.md index f90fe9d..7cfab0f 100644 --- a/README.md +++ b/README.md @@ -87,4 +87,27 @@ read keys from stdin. ## Cargo Features - +|Feature| Description| +|-------|------------| +|css | Limited handling of CSS, adding Coloured nodes to the render tree. | +|html\_trace| Add verbose internal logging (not recommended) | +|html\_trace\_bt| Add backtraces to the verbose internal logging | + +### CSS support + +When the `css` feature is enabled, some simple CSS handling is done. + +* The contents of \ elements are parsed and some colour rules are extracted +* Some simplified selector matching is done: currently `` with + CSS rules similar to `.foo { color:#123456; }`. This will add `Coloured(...)` nodes + to the render tree when matching. + +The CSS handling is expected to improve in future (PRs welcome), but not to a full- +blown browser style system, which would be overkill for terminal output. + +There are two ways to make use of the colours: +* Use `from_read_rich()` or one of its variants. One of the annotations you may get + back is `Colour(..)`. +* Use `from_read_coloured()`. This is similar to `from_read()`, but you provide + a function to add terminal colours (or other styling) based on the same + RichAnnotations. See examples/html2text.rs for an example using termion. diff --git a/examples/html2text.rs b/examples/html2text.rs index aa2eb8a..b40ef6e 100644 --- a/examples/html2text.rs +++ b/examples/html2text.rs @@ -4,12 +4,9 @@ use argparse::{ArgumentParser, Store, StoreOption, StoreTrue}; use std::io; use std::io::Write; -#[cfg(feature = "ansi_colours")] use html2text::render::text_renderer::RichAnnotation; -#[cfg(feature = "ansi_colours")] use termion; -#[cfg(feature = "ansi_colours")] fn default_colour_map(annotations: &[RichAnnotation], s: &str) -> String { use termion::color::*; use RichAnnotation::*; @@ -76,15 +73,12 @@ fn default_colour_map(annotations: &[RichAnnotation], s: &str) -> String { result } -fn translate(input: R, width: usize, literal: bool, _use_colour: bool) -> String +fn translate(input: R, width: usize, literal: bool, use_colour: bool) -> String where R: io::Read, { - #[cfg(feature = "ansi_colours")] - { - if _use_colour { - return html2text::from_read_coloured(input, width, default_colour_map).unwrap(); - }; + if use_colour { + return html2text::from_read_coloured(input, width, default_colour_map).unwrap(); } if literal { let decorator = html2text::render::text_renderer::TrivialDecorator::new(); @@ -124,7 +118,6 @@ fn main() { StoreTrue, "Output only literal text (no decorations)", ); - #[cfg(feature = "ansi_colours")] ap.refer(&mut use_colour) .add_option(&["--colour"], StoreTrue, "Use ANSI terminal colours"); ap.parse_args_or_exit(); diff --git a/src/lib.rs b/src/lib.rs index f5c1377..3eeb901 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1850,10 +1850,8 @@ where .expect("Failed to convert to HTML") } -#[cfg(feature = "ansi_colours")] mod ansi_colours; -#[cfg(feature = "ansi_colours")] pub use ansi_colours::from_read_coloured; #[cfg(test)] From 522e6cf0bfeb935540d9f1fbd88335747578522e Mon Sep 17 00:00:00 2001 From: Chris Emerson Date: Fri, 15 Dec 2023 07:46:15 +0000 Subject: [PATCH 3/3] Make html2text's colour support #[cfg(unix)] Termion is not available on Windows. --- examples/html2text.rs | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/examples/html2text.rs b/examples/html2text.rs index b40ef6e..7821b5f 100644 --- a/examples/html2text.rs +++ b/examples/html2text.rs @@ -4,9 +4,12 @@ use argparse::{ArgumentParser, Store, StoreOption, StoreTrue}; use std::io; use std::io::Write; +#[cfg(unix)] use html2text::render::text_renderer::RichAnnotation; +#[cfg(unix)] use termion; +#[cfg(unix)] fn default_colour_map(annotations: &[RichAnnotation], s: &str) -> String { use termion::color::*; use RichAnnotation::*; @@ -73,12 +76,15 @@ fn default_colour_map(annotations: &[RichAnnotation], s: &str) -> String { result } -fn translate(input: R, width: usize, literal: bool, use_colour: bool) -> String +fn translate(input: R, width: usize, literal: bool, _use_colour: bool) -> String where R: io::Read, { - if use_colour { - return html2text::from_read_coloured(input, width, default_colour_map).unwrap(); + #[cfg(unix)] + { + if _use_colour { + return html2text::from_read_coloured(input, width, default_colour_map).unwrap(); + } } if literal { let decorator = html2text::render::text_renderer::TrivialDecorator::new(); @@ -118,6 +124,7 @@ fn main() { StoreTrue, "Output only literal text (no decorations)", ); + #[cfg(unix)] ap.refer(&mut use_colour) .add_option(&["--colour"], StoreTrue, "Use ANSI terminal colours"); ap.parse_args_or_exit();