Merge pull request #96 from jugglerchris/update_release_0.7.0

Update for release 0.7.0

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:

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "html2text"
-version = "0.6.0"
+version = "0.7.0"
 authors = ["Chris Emerson <[email protected]>"]
 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]]

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"
+       <ul>
+         <li>Item one</li>
+         <li>Item two</li>
+         <li>Item three</li>
+       </ul>";
+
+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 \<style\> elements are parsed and some colour rules are extracted
+* Some simplified selector matching is done: currently `<span class="foo">` 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.

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<R>(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();

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)]