diff --git a/CHANGELOG.md b/CHANGELOG.md index b1fec81..386ecc1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,20 @@ 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] 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) + ### 0.6.0 - [changed] Improve layout of tables thanks to sftse: diff --git a/Cargo.toml b/Cargo.toml index a674cc7..e07d891 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/" @@ -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 7bea1f8..7cfab0f 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,30 @@ $ 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 + +|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..7821b5f 100644 --- a/examples/html2text.rs +++ b/examples/html2text.rs @@ -4,12 +4,12 @@ use argparse::{ArgumentParser, Store, StoreOption, StoreTrue}; use std::io; use std::io::Write; -#[cfg(feature = "ansi_colours")] +#[cfg(unix)] use html2text::render::text_renderer::RichAnnotation; -#[cfg(feature = "ansi_colours")] +#[cfg(unix)] use termion; -#[cfg(feature = "ansi_colours")] +#[cfg(unix)] fn default_colour_map(annotations: &[RichAnnotation], s: &str) -> String { use termion::color::*; use RichAnnotation::*; @@ -80,11 +80,11 @@ fn translate(input: R, width: usize, literal: bool, _use_colour: bool) -> Str where R: io::Read, { - #[cfg(feature = "ansi_colours")] + #[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(); @@ -124,7 +124,7 @@ fn main() { StoreTrue, "Output only literal text (no decorations)", ); - #[cfg(feature = "ansi_colours")] + #[cfg(unix)] 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)]