add doc.zero_width_string function

* add doc.zero_width_string function

* add doc.zero_width_string example test

* update changelog

Author: marcobacis

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Remove the `doc.to_string_builder` method.
+- The `doc` module gains the `zero_width_string` function
 
 ## v1.3.0 - 2023-01-03
 

birdie_snapshots/zero_width_string_1.accepted

@@ -0,0 +1,5 @@
+---
+version: 1.0.4
+title: zero width string 1
+---
+doc with zero width

birdie_snapshots/zero_width_string_2.accepted

@@ -0,0 +1,5 @@
+---
+version: 1.0.4
+title: zero width string 2
+---
+I'm a red, bold text

src/glam/doc.gleam

@@ -236,6 +236,33 @@ pub fn from_string(string: String) -> Document {
   Text(string, string.length(string))
 }
 
+/// Turns a string into a document whose length is not taken into account when
+/// formatting it.
+///
+/// This kind of string can be used to render non-visible characters like ansi
+/// color codes.
+///
+/// ## Examples
+///
+/// ```gleam
+/// // Should break in two lines, but doesn't because of the zero_width_string
+/// // does not contribute to the total line length.
+/// [
+///   zero_width_string("\u{001b}[1;31m"),
+///   from_string("I'm a red"),
+///   break(", ", ","),
+///   from_string("bold text"),
+/// ]
+/// |> concat
+/// |> group
+/// |> to_string(20)
+/// // -> "\u{001b}[1;31mI'm a red, bold text"
+/// ```
+///
+pub fn zero_width_string(string: String) -> Document {
+  Text(string, 0)
+}
+
 /// Allows the pretty printer to break the `break` documents inside the given
 /// group.
 ///

test/glam/doc_test.gleam

@@ -2,6 +2,7 @@ import gleam/list
 import gleam/string
 import gleeunit/should
 import glam/doc
+import birdie
 
 pub fn append_test() {
   doc.from_string("foo")
@@ -200,3 +201,30 @@ pub fn flex_break_with_group_and_nesting_test() {
   doc.to_string(list, 1)
   |> should.equal("[\n  1,\n  2,\n  3,\n  4,\n  5,\n]")
 }
+
+pub fn zero_width_string_test() {
+  [
+    doc.from_string("doc"),
+    doc.break(" ", ""),
+    doc.from_string("with"),
+    doc.break(" ", ""),
+    doc.zero_width_string("zero width"),
+  ]
+  |> doc.concat
+  |> doc.group
+  |> doc.to_string(10)
+  |> birdie.snap(title: "zero width string 1")
+}
+
+pub fn zero_width_string_example_test() {
+  [
+    doc.zero_width_string("\u{001b}[1;31m"),
+    doc.from_string("I'm a red"),
+    doc.break(", ", ","),
+    doc.from_string("bold text"),
+  ]
+  |> doc.concat
+  |> doc.group
+  |> doc.to_string(20)
+  |> birdie.snap(title: "zero width string 2")
+}