Add word wrapping mode (#3597)

* feat: add word wrapping mode for --wrap flag

* Run `cargo fmt` and add CHANGELOG entry

* Add word wrap tests, update manpage and shell completions

- Add integration tests for word wrapping: basic word boundary breaking,
  fallback to character wrapping for long words, line numbers, and
  short lines that fit without wrapping
- Update manpage to document the new 'word' wrapping mode
- Update bash, fish, zsh, and PowerShell completions with 'word' option
- Avoid unnecessary clone of `line_buf` when word wrap is disabled

* make clippy and cargo fmt happy

---------

Co-authored-by: Keith Hall <keith-hall@users.noreply.github.com>

src/printer.rs

@@ -781,11 +781,21 @@ impl Printer for InteractivePrinter<'_> {
                             // Displayed width of line_buf
                             let mut current_width = 0;
 
+                            let word_wrap = matches!(self.config.wrapping_mode, WrappingMode::Word);
+
+                            // For word wrapping, track last whitespace position.
+                            let mut last_ws_idx: Option<usize> = None;
+
                             for c in text.chars() {
                                 // calculate the displayed width for next character
                                 let cw = c.width().unwrap_or(0);
                                 current_width += cw;
 
+                                // Track whitespace positions for word wrapping.
+                                if word_wrap && c.is_whitespace() {
+                                    last_ws_idx = Some(line_buf.len());
+                                }
+
                                 // if next character cannot be printed on this line,
                                 // flush the buffer.
                                 if current_width > max_width {
@@ -807,13 +817,37 @@ impl Printer for InteractivePrinter<'_> {
                                         }
                                     }
 
+                                    // Determine the break point and remainder
+                                    // for word wrapping.
+                                    let (emit_end, rest_start) = if word_wrap {
+                                        if let Some(ws_idx) = last_ws_idx {
+                                            // Skip the whitespace character itself
+                                            // and carry the rest to the next line.
+                                            let rs = ws_idx
+                                                + line_buf[ws_idx..]
+                                                    .chars()
+                                                    .next()
+                                                    .map(|ch| ch.len_utf8())
+                                                    .unwrap_or(0);
+                                            (ws_idx, Some(rs))
+                                        } else {
+                                            (line_buf.len(), None)
+                                        }
+                                    } else {
+                                        (line_buf.len(), None)
+                                    };
+
                                     // It wraps.
                                     write!(
                                         handle,
                                         "{}{}\n{}",
                                         as_terminal_escaped(
                                             style,
-                                            &format!("{}{line_buf}", self.ansi_style),
+                                            &format!(
+                                                "{}{}",
+                                                self.ansi_style,
+                                                &line_buf[..emit_end]
+                                            ),
                                             self.config.true_color,
                                             self.config.colored_output,
                                             self.config.use_italic_text,
@@ -826,8 +860,21 @@ impl Printer for InteractivePrinter<'_> {
                                     cursor = 0;
                                     max_width = cursor_max;
 
-                                    line_buf.clear();
-                                    current_width = cw;
+                                    if let Some(rs) = rest_start {
+                                        // Word wrap: carry remainder to next line.
+                                        let remainder = line_buf[rs..].to_string();
+                                        let rem_width: usize = remainder
+                                            .chars()
+                                            .map(|ch| ch.width().unwrap_or(0))
+                                            .sum();
+                                        line_buf.clear();
+                                        line_buf.push_str(&remainder);
+                                        current_width = rem_width + cw;
+                                    } else {
+                                        line_buf.clear();
+                                        current_width = cw;
+                                    }
+                                    last_ws_idx = None;
                                 }
 
                                 line_buf.push(c);