Breaking: add options, bump version to v0.2.0

Author: fuelen

.github/workflows/release.yml

@@ -23,8 +23,8 @@ jobs:
           - { target: x86_64-apple-darwin         , os: macos-13      }
           - { target: x86_64-unknown-linux-gnu    , os: ubuntu-22.04  }
           - { target: x86_64-unknown-linux-musl   , os: ubuntu-22.04 , use-cross: true }
-          - { target: x86_64-pc-windows-gnu       , os: windows-2019  }
-          - { target: x86_64-pc-windows-msvc      , os: windows-2019  }
+          - { target: x86_64-pc-windows-gnu       , os: windows-2025  }
+          - { target: x86_64-pc-windows-msvc      , os: windows-2025  }
 
     steps:
     - name: Checkout source code

README.md

@@ -14,7 +14,7 @@ Add `html2text` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:html2text, "~> 0.1"}
+    {:html2text, "~> 0.2"}
   ]
 end
 ```
@@ -27,28 +27,18 @@ mix deps.get
 
 ## Usage
 
-The library provides a single main function `HTML2Text.convert/2` that takes HTML content and a width parameter.
-
 ```elixir
 # Convert with specific line width
 html = "<h1>Welcome</h1><p>This is a sample paragraph with some content.</p>"
-text = HTML2Text.convert(html, 30)
+text = HTML2Text.convert!(html, width: 30)
 IO.puts(text)
+
 # Output:
 # # Welcome
 #
 # This is a sample paragraph
 # with some content.
 
-
-# Convert with unlimited width
-text = HTML2Text.convert(html, :infinity)
-IO.puts(text)
-# Output:
-# # Welcome
-#
-# This is a sample paragraph with some content.
-
 html = """
 <article>
   <h1>Article Title</h1>
@@ -92,7 +82,7 @@ html = """
 </article>
 """
 
-text = HTML2Text.convert(html, 70)
+text = HTML2Text.convert!(html)
 IO.puts(text)
 
 # Output:
@@ -120,8 +110,8 @@ IO.puts(text)
 #
 # ## Conclusion
 #
-# This article provided an overview of important web technologies and
-# some key statistics.
+# This article provided an overview of important web technologies and some key
+# statistics.
 #
 # [1]: http://example.com
 ```

lib/html2_text.ex

@@ -39,61 +39,64 @@ defmodule HTML2Text do
     version: version,
     force_build: System.get_env("HTML2TEXT_BUILD") in ["1", "true"]
 
-  @doc """
-  Converts HTML content to plain text with configurable line width.
-
-  This function converts HTML content to plain text and optionally wraps lines at the
-  specified width. The width can be either a positive integer representing the maximum
-  number of characters per line, or `:infinity` for unlimited line width.
+  @type opts :: [
+          width: pos_integer() | :infinity,
+          decorate: boolean(),
+          link_footnotes: boolean(),
+          table_borders: boolean(),
+          pad_block_width: boolean(),
+          allow_width_overflow: boolean(),
+          min_wrap_width: pos_integer(),
+          raw: boolean(),
+          wrap_links: boolean(),
+          unicode_strikeout: boolean()
+        ]
 
-  ## Parameters
+  @doc """
+  Converts HTML content to plain text.
+
+  ## Options
+  - `:width` — Maximum line width (positive integer or `:infinity`). Defaults to `80`. Setting to `:infinity` disables line wrapping and outputs the entire text on a single line.
+  - `:decorate` — Enables text decorations like bold or italic. Boolean, defaults to `true`. When `false`, output is plain text without styling.
+  - `:link_footnotes` — Adds numbered link footnotes at the end of the text. Boolean, defaults to `true`. When `false`, links are omitted.
+  - `:table_borders` — Shows ASCII borders around table cells. Boolean, defaults to `true`. When `false`, tables render without borders.
+  - `:pad_block_width` — Pads blocks with spaces to align text to full width. Boolean, defaults to `false`. Useful for fixed-width layouts.
+  - `:allow_width_overflow` — Allows lines to exceed the specified width if wrapping is impossible. Boolean, defaults to `false`. Prevents errors when content can't fit.
+  - `:min_wrap_width` — Minimum length of text chunks when wrapping lines. Integer ≥ 1, defaults to `3`. Helps avoid awkwardly narrow wraps.
+  - `:raw` — Enables raw mode with minimal processing and formatting. Boolean, defaults to `false`. Produces plain, raw text output.
+  - `:wrap_links` — Wraps long URLs or links onto multiple lines. Boolean, defaults to `true`. When `false`, links stay on a single line and may overflow.
+  - `:unicode_strikeout` — Uses Unicode characters for strikeout text. Boolean, defaults to `true`. When `false`, strikeout renders in simpler styles.
 
-  - `html` - A binary containing the HTML content to convert
-  - `width` - Either a positive integer for line width or `:infinity` for unlimited width
+  ## Examples
 
-  ## Return Value
+      iex> html = "<h1>Title</h1><p>Some paragraph text.</p>"
+      ...> HTML2Text.convert(html, width: 15)
+      {:ok, "# Title\\n\\nSome paragraph\\ntext.\\n"}
 
-  Returns a string containing the plain text representation of the HTML content.
+      iex> HTML2Text.convert("<b>Important</b>", decorate: false)
+      {:ok, "Important\\n"}
 
-  ## Examples
-
-      # Converting with specific width
-      iex> html = "<h1>Welcome to Our Amazing Website</h1><p>This is a comprehensive guide that covers everything you need to know about our services and products.</p>"
-      iex> HTML2Text.convert(html, 30)
-      "# Welcome to Our Amazing\\n# Website\\n\\nThis is a comprehensive guide\\nthat covers everything you\\nneed to know about our\\nservices and products.\\n"
-
-      # Converting with unlimited width
-      iex> html = "<div><strong>Important:</strong> Please read all the terms and conditions carefully before proceeding with your purchase.</div>"
-      iex> HTML2Text.convert(html, :infinity)
-      "**Important:** Please read all the terms and conditions carefully before proceeding with your purchase.\\n"
-
-      # Converting lists and complex HTML
-      iex> html = "<ul><li>First item with some detailed description</li><li>Second item that also has quite a bit of text</li><li>Third item</li></ul>"
-      iex> HTML2Text.convert(html, 25)
-      "* First item with some\\n  detailed description\\n* Second item that also\\n  has quite a bit of text\\n* Third item\\n"
-
-      # Converting tables and structured content
-      iex> html = "<table><tr><td>Product Name</td><td>Description</td><td>Price</td></tr><tr><td>Widget</td><td>A useful widget for everyday tasks</td><td>$19.99</td></tr></table>"
-      iex> HTML2Text.convert(html, 50)
-      \"""
-      ───────────┬────────────────────────────────┬─────
-      Product    │Description                     │Price
-      Name       │                                │     
-      ───────────┼────────────────────────────────┼─────
-      Widget     │A useful widget for everyday    │$19.9
-                 │tasks                           │9    
-      ───────────┴────────────────────────────────┴─────
-      \"""
+      iex> HTML2Text.convert("<table><tr><td>A</td><td>B</td></tr></table>", [])
+      {:ok, "─┬─\\nA│B\\n─┴─\\n"}
 
   """
-  @spec convert(String.t(), pos_integer() | :infinity) :: String.t()
-  def convert(html, :infinity) when is_binary(html) do
-    do_convert(html, :infinity)
+  @spec convert(html :: String.t(), opts()) :: {:ok, text :: String.t()} | {:error, reason :: String.t()}
+  def convert(html, opts \\ []) do
+    do_convert(html, opts)
   end
 
-  def convert(html, width) when is_binary(html) and is_integer(width) and width > 0 do
-    do_convert(html, width)
+  @doc """
+  Converts HTML content to plain text, raising on failure.
+
+  This function behaves like `convert/2`, but raises an error if conversion fails.
+  """
+  @spec convert!(html :: String.t(), opts :: opts()) :: String.t()
+  def convert!(html, opts \\ []) do
+    case do_convert(html, opts) do
+      {:ok, text} -> text
+      {:error, reason} -> raise "HTML to text conversion failed: #{reason}"
+    end
   end
 
-  defp do_convert(_html, _width), do: :erlang.nif_error(:nif_not_loaded)
+  defp do_convert(_html, _opts), do: :erlang.nif_error(:nif_not_loaded)
 end

mix.exs

@@ -1,6 +1,6 @@
 defmodule HTML2Text.MixProject do
   use Mix.Project
-  @version "0.1.1"
+  @version "0.2.0"
   @source_url "https://github.com/fuelen/html2text"
 
   def project do

native/html2text_nif/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "html2text_nif"
-version = "0.1.1"
+version = "0.2.0"
 authors = []
 edition = "2021"
 

native/html2text_nif/Cargo.toml

@@ -1,28 +1,92 @@
-use rustler::{NifResult, Env, Atom, Term};
-use std::io::Cursor;
-use html2text::from_read;
+use rustler::{Env, NifResult, Term, Atom};
 
 #[rustler::nif(schedule = "DirtyCpu")]
-fn do_convert(env: Env, html: String, width_term: Term) -> NifResult<String> {
-    let cursor = Cursor::new(html.as_bytes());
-
-    // Determine width - parameters are already validated by Elixir guard
-    let actual_width = if let Ok(atom) = width_term.decode::<Atom>() {
-        let infinity_atom = Atom::from_str(env, "infinity")?;
-        if atom == infinity_atom {
-            usize::MAX
-        } else {
-            unreachable!() // guard should filter this out
+fn do_convert(env: Env, html: String, config_term: Term) -> NifResult<(Atom, String)> {
+    let kv_vec: Vec<(Atom, Term)> = config_term.decode()?;
+
+    let mut width = 80usize;
+    let mut decorate = true;
+    let mut link_footnotes = true;
+    let mut table_borders = true;
+    let mut pad_block_width = false;
+    let mut allow_width_overflow = false;
+    let mut min_wrap_width = 3usize;
+    let mut raw = false;
+    let mut wrap_links = true;
+    let mut unicode_strikeout = true;
+
+    let key_width = Atom::from_str(env, "width")?;
+    let key_decorate = Atom::from_str(env, "decorate")?;
+    let key_link_footnotes = Atom::from_str(env, "link_footnotes")?;
+    let key_table_borders = Atom::from_str(env, "table_borders")?;
+    let key_pad_block_width = Atom::from_str(env, "pad_block_width")?;
+    let key_allow_width_overflow = Atom::from_str(env, "allow_width_overflow")?;
+    let key_min_wrap_width = Atom::from_str(env, "min_wrap_width")?;
+    let key_raw = Atom::from_str(env, "raw")?;
+    let key_wrap_links = Atom::from_str(env, "wrap_links")?;
+    let key_unicode_strikeout = Atom::from_str(env, "unicode_strikeout")?;
+
+    let infinity_atom = Atom::from_str(env, "infinity")?;
+
+    for (key, val) in kv_vec {
+        if key == key_width {
+            if let Ok(atom) = val.decode::<Atom>() {
+                if atom == infinity_atom {
+                    width = usize::MAX;
+                }
+            } else if let Ok(w) = val.decode::<usize>() {
+                width = w;
+            }
+        } else if key == key_decorate {
+            decorate = val.decode::<bool>().unwrap_or(false);
+        } else if key == key_link_footnotes {
+            link_footnotes = val.decode::<bool>().unwrap_or(false);
+        } else if key == key_table_borders {
+            table_borders = val.decode::<bool>().unwrap_or(true);
+        } else if key == key_pad_block_width {
+            pad_block_width = val.decode::<bool>().unwrap_or(false);
+        } else if key == key_allow_width_overflow {
+            allow_width_overflow = val.decode::<bool>().unwrap_or(false);
+        } else if key == key_min_wrap_width {
+            min_wrap_width = val.decode::<usize>().unwrap_or(3);
+        } else if key == key_raw {
+            raw = val.decode::<bool>().unwrap_or(false);
+        } else if key == key_wrap_links {
+            wrap_links = val.decode::<bool>().unwrap_or(true);
+        } else if key == key_unicode_strikeout {
+            unicode_strikeout = val.decode::<bool>().unwrap_or(true);
         }
-    } else if let Ok(width) = width_term.decode::<usize>() {
-        width
-    } else {
-        unreachable!() // guard should filter this out
-    };
-
-    match from_read(cursor, actual_width) {
-        Ok(text) => Ok(text),
-        Err(e) => Err(rustler::Error::Term(Box::new(e.to_string()))),
+    }
+
+    let mut config = html2text::config::plain_no_decorate().max_wrap_width(width);
+
+    if decorate {
+        config = config.do_decorate();
+    }
+    config = config.link_footnotes(link_footnotes);
+
+    if !table_borders {
+        config = config.no_table_borders();
+    }
+    if pad_block_width {
+        config = config.pad_block_width();
+    }
+    if allow_width_overflow {
+        config = config.allow_width_overflow();
+    }
+    config = config.min_wrap_width(min_wrap_width);
+
+    if raw {
+        config = config.raw_mode(true);
+    }
+    if !wrap_links {
+        config = config.no_link_wrapping();
+    }
+    config = config.unicode_strikeout(unicode_strikeout);
+
+    match config.string_from_read(html.as_bytes(), width) {
+        Ok(text) => Ok((Atom::from_str(env, "ok")?, text)),
+        Err(e) => Ok((Atom::from_str(env, "error")?, e.to_string())),
     }
 }