feat: add a flatten combinator, that will flatten a slice of strings …

…into a single string (#65)

docs/combinators.adoc

@@ -575,6 +575,20 @@ chomp.Opt(chomp.Tag("Hey"))("Hello, World!")
 rem: "Hello, World!"
 ext: ""
 ....
+
+|https://pkg.go.dev/github.com/purpleclay/chomp#Flatten[Flatten]
+|
+[source,go]
+----
+chomp.Flatten(
+    chomp.Many(chomp.Parentheses()),
+)("(H)(el)(lo), World!")
+----
+|
+....
+rem: ", World!"
+ext: "Hello"
+....
 |===
 
 == Ready-made parsers [[ready-made_parsers]]

modifier.go

@@ -1,6 +1,9 @@
 package chomp
 
-import "fmt"
+import (
+	"fmt"
+	"strings"
+)
 
 // MappedCombinator is a function capable of converting the output from a [Combinator]
 // into any given type. Upon success, it will return the unparsed text, along with the
@@ -101,3 +104,20 @@ func Peek[T Result](c Combinator[T]) Combinator[T] {
 		return s, ext, err
 	}
 }
+
+// Flatten the output of a [Combinator] by joining all extracted values
+// into a string.
+//
+//	chomp.Flatten(
+//		chomp.Many(chomp.Parentheses()),
+//	)("(H)(el)(lo), World!")
+//	// (", World!", "Hello", nil)
+func Flatten(c Combinator[[]string]) Combinator[string] {
+	return func(s string) (string, string, error) {
+		rem, ext, err := c(s)
+		if err != nil {
+			return rem, "", ParserError{Err: err, Type: "flatten"}
+		}
+		return rem, strings.Join(ext, ""), nil
+	}
+}

modifier_test.go

@@ -84,3 +84,15 @@ func TestPeekUsingSequence(t *testing.T) {
 	assert.Equal(t, "Hello and Good Morning!", rem)
 	assert.Equal(t, []string{"Hello", "and", "Good"}, ext)
 }
+
+func TestFlatten(t *testing.T) {
+	t.Parallel()
+
+	rem, ext, err := chomp.Flatten(
+		chomp.Many(chomp.Parentheses()),
+	)("(H)(el)(lo) and Good Morning!")
+
+	require.NoError(t, err)
+	assert.Equal(t, " and Good Morning!", rem)
+	assert.Equal(t, "Hello", ext)
+}