Add streaming pretty printer utilities

It is inspired by the paper _Lazy v. Yield: Incremental, Linear
Pretty-printing_ by Oleg Kiselyov, Simon Peyton-Jones, and Amr Sabry.
It adds indentation and alignment features to be useful in the context
of streaming tree structure pretty printing (XML, JSON, ...).

Any type that has an instance of `Renderable` can be printed.

The printer guarantees that the data is printed as early as possible
and the it is correct up to the first malformed tree structure.

build.sbt

@@ -123,6 +123,9 @@ lazy val text = crossProject(JVMPlatform, JSPlatform, NativePlatform)
   .settings(
     name := "fs2-data-text",
     description := "Utilities for textual data format",
+    libraryDependencies ++= List(
+      "org.typelevel" %%% "cats-collections-core" % "0.9.8"
+    ),
     mimaBinaryIssueFilters ++= List(
       // private class
       ProblemFilters.exclude[IncompatibleResultTypeProblem]("fs2.data.text.CharLikeCharChunks.create"),

text/shared/src/main/scala/fs2/data/text/render/DocEvent.scala

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2024 fs2-data Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package fs2.data.text.render
+
+sealed trait DocEvent
+
+object DocEvent {
+
+  /** Renders the text _as is_. */
+  case class Text(text: String) extends DocEvent
+
+  /** Adds a new line and indent, or a space if undone by a group */
+  case object Line extends DocEvent
+
+  /** Adds a new line and indent, or a empty if undone by a group */
+  case object LineBreak extends DocEvent
+
+  /** Begins a new group */
+  case object GroupBegin extends DocEvent
+
+  /** Ends a group */
+  case object GroupEnd extends DocEvent
+
+  /** Begins a new indent, incrementing the current indentation level */
+  case object IndentBegin extends DocEvent
+
+  /** Ends an indent , decrementing the current indentation level */
+  case object IndentEnd extends DocEvent
+
+  /** Begins a new alignment, setting the current indentation level to the current column */
+  case object AlignBegin extends DocEvent
+
+  /** Ends an alignment, setting the current indentation level back to what it was before this alignment */
+  case object AlignEnd extends DocEvent
+}

text/shared/src/main/scala/fs2/data/text/render/RenderException.scala

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2024 fs2-data Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package fs2.data.text.render
+
+final case class RenderException(msg: String) extends Exception(msg)

text/shared/src/main/scala/fs2/data/text/render/Renderable.scala

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024 fs2-data Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package fs2.data.text.render
+
+/** Typeclass indicating how to render a given event type. */
+trait Renderable[Event] {
+
+  /** Creates a new instance of a renderer.
+    * This allows for renderer with mutable state.
+    * If the renderer has no state, it can return the same instance every time.
+    */
+  def newRenderer(): Renderer[Event]
+
+}

text/shared/src/main/scala/fs2/data/text/render/Renderer.scala

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024 fs2-data Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package fs2.data.text.render
+
+import fs2.{Stream, Pure}
+
+trait Renderer[Event] {
+
+  /** Transforms the event into a stream of document events.
+    * The stream may be partial (e.g. opening a group when the event describes a new tree node).
+    */
+  def doc(evt: Event): Stream[Pure, DocEvent]
+
+}

text/shared/src/main/scala/fs2/data/text/render/internal/Annotated.scala

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2024 fs2-data Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package fs2.data.text.render.internal
+
+private sealed trait Annotated
+private object Annotated {
+  case class Text(text: String, hp: Int) extends Annotated
+  case class Line(hp: Int) extends Annotated
+  case class LineBreak(hp: Int) extends Annotated
+  case class GroupBegin(hpl: Position) extends Annotated
+  case class GroupEnd(hp: Int) extends Annotated
+  case class IndentBegin(hp: Int) extends Annotated
+  case class IndentEnd(hp: Int) extends Annotated
+  case class AlignBegin(hp: Int) extends Annotated
+  case class AlignEnd(hp: Int) extends Annotated
+}

text/shared/src/main/scala/fs2/data/text/render/internal/Position.scala

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2024 fs2-data Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package fs2.data.text.render.internal
+
+private sealed trait Position
+private object Position {
+  case object TooFar extends Position
+  case class Small(pos: Int) extends Position
+}