Add conditional and mapping pipeline primitives

PipeIf and PipeUnless enable conditional transformations in pipelines.
PipeMap splits a string, transforms each part, and rejoins. Includes
Lines and Words splitters for common use cases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: schigh

README.md

@@ -35,6 +35,27 @@ format("  42  ") // "00000042"
 
 **PipeErr** composes fallible transformers. Short-circuits on the first error.
 
+**PipeIf** applies a transformation only when a predicate is true. Otherwise passes through.
+
+```go
+isLong := func(s string) bool { return len([]rune(s)) > 100 }
+clean := str.Pipe(
+    str.TrimSpace,
+    str.PipeIf(isLong, str.Truncate(100, "...")),
+)
+```
+
+**PipeUnless** is the inverse: applies when the predicate is false.
+
+**PipeMap** splits a string, transforms each part, and rejoins.
+
+```go
+trimLines := str.PipeMap(str.Lines, "\n", str.TrimSpace)
+trimLines("  hello  \n  world  ") // "hello\nworld"
+```
+
+Built-in splitters: `Lines` (split on `\n`) and `Words` (split on whitespace).
+
 ## Transform
 
 **ToSnakeCase** / **ToCamelCase** / **ToPascalCase** / **ToKebabCase** / **ToTitleCase** / **ToScreamingSnake**

example_test.go

@@ -142,6 +142,43 @@ func ExampleSlugifyASCII_pipe() {
 	// Output: hello-world
 }
 
+func ExamplePipeIf() {
+	isLong := func(s string) bool { return len([]rune(s)) > 10 }
+	shorten := str.Pipe(
+		str.TrimSpace,
+		str.PipeIf(isLong, str.Truncate(10, "...")),
+	)
+	fmt.Println(shorten("  hello  "))
+	fmt.Println(shorten("  this is a long string  "))
+	// Output:
+	// hello
+	// this is...
+}
+
+func ExamplePipeUnless() {
+	isEmpty := func(s string) bool { return s == "" }
+	fn := str.PipeUnless(isEmpty, str.SlugifyASCII)
+	fmt.Println(fn("Hello World"))
+	fmt.Println(fn(""))
+	// Output:
+	// hello-world
+	//
+}
+
+func ExamplePipeMap() {
+	trimLines := str.PipeMap(str.Lines, "\n", str.TrimSpace)
+	fmt.Println(trimLines("  hello  \n  world  "))
+	// Output:
+	// hello
+	// world
+}
+
+func ExamplePipeMap_words() {
+	shoutWords := str.PipeMap(str.Words, " ", str.ToScreamingSnake)
+	fmt.Println(shoutWords("hello world"))
+	// Output: HELLO WORLD
+}
+
 func ExampleLevenshtein() {
 	fmt.Println(str.Levenshtein("kitten", "sitting"))
 	// Output: 3

mappers.go

@@ -0,0 +1,34 @@
+package str
+
+import "strings"
+
+// PipeMap returns a transformer that splits the input using split, applies fn
+// to each part, and rejoins with the join string. Nil split or nil fn returns
+// the input unchanged.
+func PipeMap(split func(string) []string, join string, fn func(string) string) func(string) string {
+	return func(s string) string {
+		if split == nil || fn == nil {
+			return s
+		}
+		parts := split(s)
+		if len(parts) == 0 {
+			return ""
+		}
+		for i, p := range parts {
+			parts[i] = fn(p)
+		}
+		return strings.Join(parts, join)
+	}
+}
+
+// Lines splits a string on newlines. Empty string returns []string{""}.
+// Splits on "\n" only; "\r" is preserved if present.
+func Lines(s string) []string {
+	return strings.Split(s, "\n")
+}
+
+// Words splits a string on whitespace, matching strings.Fields behavior.
+// Empty string returns nil.
+func Words(s string) []string {
+	return strings.Fields(s)
+}

mappers_test.go

@@ -0,0 +1,130 @@
+package str
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestPipeMap(t *testing.T) {
+	t.Run("trim every line", func(t *testing.T) {
+		fn := PipeMap(Lines, "\n", TrimSpace)
+		got := fn("  hello  \n  world  ")
+		if got != "hello\nworld" {
+			t.Errorf("got %q, want %q", got, "hello\nworld")
+		}
+	})
+
+	t.Run("uppercase every word", func(t *testing.T) {
+		fn := PipeMap(Words, " ", strings.ToUpper)
+		got := fn("hello world")
+		if got != "HELLO WORLD" {
+			t.Errorf("got %q, want %q", got, "HELLO WORLD")
+		}
+	})
+
+	t.Run("nil split is passthrough", func(t *testing.T) {
+		fn := PipeMap(nil, "\n", strings.ToUpper)
+		if got := fn("hello"); got != "hello" {
+			t.Errorf("got %q, want %q", got, "hello")
+		}
+	})
+
+	t.Run("nil fn is passthrough", func(t *testing.T) {
+		fn := PipeMap(Lines, "\n", nil)
+		if got := fn("hello"); got != "hello" {
+			t.Errorf("got %q, want %q", got, "hello")
+		}
+	})
+
+	t.Run("empty string", func(t *testing.T) {
+		fn := PipeMap(Lines, "\n", TrimSpace)
+		if got := fn(""); got != "" {
+			t.Errorf("got %q, want empty", got)
+		}
+	})
+
+	t.Run("single element", func(t *testing.T) {
+		fn := PipeMap(Lines, "\n", strings.ToUpper)
+		if got := fn("hello"); got != "HELLO" {
+			t.Errorf("got %q, want %q", got, "HELLO")
+		}
+	})
+
+	t.Run("composes in Pipe", func(t *testing.T) {
+		fn := Pipe(
+			TrimSpace,
+			PipeMap(Lines, "\n", TrimSpace),
+		)
+		got := fn("  hello  \n  world  ")
+		if got != "hello\nworld" {
+			t.Errorf("got %q, want %q", got, "hello\nworld")
+		}
+	})
+}
+
+func TestLines(t *testing.T) {
+	t.Run("normal", func(t *testing.T) {
+		got := Lines("a\nb\nc")
+		if len(got) != 3 || got[0] != "a" || got[1] != "b" || got[2] != "c" {
+			t.Errorf("got %v", got)
+		}
+	})
+
+	t.Run("empty string", func(t *testing.T) {
+		got := Lines("")
+		if len(got) != 1 || got[0] != "" {
+			t.Errorf("got %v, want [\"\"]", got)
+		}
+	})
+
+	t.Run("no newlines", func(t *testing.T) {
+		got := Lines("hello")
+		if len(got) != 1 || got[0] != "hello" {
+			t.Errorf("got %v", got)
+		}
+	})
+
+	t.Run("trailing newline", func(t *testing.T) {
+		got := Lines("a\nb\n")
+		if len(got) != 3 || got[2] != "" {
+			t.Errorf("got %v, want [a, b, \"\"]", got)
+		}
+	})
+
+	t.Run("cr preserved", func(t *testing.T) {
+		got := Lines("a\r\nb")
+		if len(got) != 2 || got[0] != "a\r" {
+			t.Errorf("got %v, want [\"a\\r\", \"b\"]", got)
+		}
+	})
+}
+
+func TestWords(t *testing.T) {
+	t.Run("normal", func(t *testing.T) {
+		got := Words("hello world")
+		if len(got) != 2 || got[0] != "hello" || got[1] != "world" {
+			t.Errorf("got %v", got)
+		}
+	})
+
+	t.Run("empty string", func(t *testing.T) {
+		got := Words("")
+		if len(got) != 0 {
+			t.Errorf("got %v, want empty", got)
+		}
+	})
+
+	t.Run("multiple spaces", func(t *testing.T) {
+		got := Words("hello   world")
+		if len(got) != 2 {
+			t.Errorf("got %v, want 2 elements", got)
+		}
+	})
+
+	t.Run("single word", func(t *testing.T) {
+		got := Words("hello")
+		if len(got) != 1 || got[0] != "hello" {
+			t.Errorf("got %v", got)
+		}
+	})
+}

pipe.go

@@ -12,6 +12,36 @@ func Pipe(fns ...func(string) string) func(string) string {
 	}
 }
 
+// PipeIf returns a transformer that applies fn only when the predicate returns true.
+// If the predicate returns false, the input passes through unchanged.
+// Nil predicate is treated as always-false (no-op). Nil fn is a no-op.
+func PipeIf(predicate func(string) bool, fn func(string) string) func(string) string {
+	return func(s string) string {
+		if predicate == nil || fn == nil {
+			return s
+		}
+		if predicate(s) {
+			return fn(s)
+		}
+		return s
+	}
+}
+
+// PipeUnless returns a transformer that applies fn only when the predicate returns false.
+// If the predicate returns true, the input passes through unchanged.
+// Nil predicate is treated as always-false, so fn always applies. Nil fn is a no-op.
+func PipeUnless(predicate func(string) bool, fn func(string) string) func(string) string {
+	return func(s string) string {
+		if fn == nil {
+			return s
+		}
+		if predicate == nil || !predicate(s) {
+			return fn(s)
+		}
+		return s
+	}
+}
+
 // PipeErr composes multiple fallible string transformers into a single function.
 // Functions are applied left to right. Short-circuits on the first non-nil error;
 // the error is returned unwrapped from the failing function. With zero functions,

pipe_test.go

@@ -36,6 +36,90 @@ func TestPipe(t *testing.T) {
 	})
 }
 
+func TestPipeIf(t *testing.T) {
+	isLong := func(s string) bool { return len(s) > 5 }
+
+	t.Run("predicate true applies fn", func(t *testing.T) {
+		fn := PipeIf(isLong, strings.ToUpper)
+		if got := fn("hello world"); got != "HELLO WORLD" {
+			t.Errorf("got %q, want %q", got, "HELLO WORLD")
+		}
+	})
+
+	t.Run("predicate false passes through", func(t *testing.T) {
+		fn := PipeIf(isLong, strings.ToUpper)
+		if got := fn("hi"); got != "hi" {
+			t.Errorf("got %q, want %q", got, "hi")
+		}
+	})
+
+	t.Run("nil predicate is no-op", func(t *testing.T) {
+		fn := PipeIf(nil, strings.ToUpper)
+		if got := fn("hello"); got != "hello" {
+			t.Errorf("got %q, want %q", got, "hello")
+		}
+	})
+
+	t.Run("nil fn is no-op", func(t *testing.T) {
+		fn := PipeIf(isLong, nil)
+		if got := fn("hello world"); got != "hello world" {
+			t.Errorf("got %q, want %q", got, "hello world")
+		}
+	})
+
+	t.Run("composes in Pipe", func(t *testing.T) {
+		fn := Pipe(
+			TrimSpace,
+			PipeIf(isLong, strings.ToUpper),
+		)
+		if got := fn("  hello world  "); got != "HELLO WORLD" {
+			t.Errorf("got %q, want %q", got, "HELLO WORLD")
+		}
+		if got := fn("  hi  "); got != "hi" {
+			t.Errorf("got %q, want %q", got, "hi")
+		}
+	})
+
+	t.Run("empty string", func(t *testing.T) {
+		fn := PipeIf(isLong, strings.ToUpper)
+		if got := fn(""); got != "" {
+			t.Errorf("got %q, want empty", got)
+		}
+	})
+}
+
+func TestPipeUnless(t *testing.T) {
+	isShort := func(s string) bool { return len(s) <= 5 }
+
+	t.Run("predicate false applies fn", func(t *testing.T) {
+		fn := PipeUnless(isShort, strings.ToUpper)
+		if got := fn("hello world"); got != "HELLO WORLD" {
+			t.Errorf("got %q, want %q", got, "HELLO WORLD")
+		}
+	})
+
+	t.Run("predicate true passes through", func(t *testing.T) {
+		fn := PipeUnless(isShort, strings.ToUpper)
+		if got := fn("hi"); got != "hi" {
+			t.Errorf("got %q, want %q", got, "hi")
+		}
+	})
+
+	t.Run("nil predicate always applies fn", func(t *testing.T) {
+		fn := PipeUnless(nil, strings.ToUpper)
+		if got := fn("hello"); got != "HELLO" {
+			t.Errorf("got %q, want %q", got, "HELLO")
+		}
+	})
+
+	t.Run("nil fn is no-op", func(t *testing.T) {
+		fn := PipeUnless(isShort, nil)
+		if got := fn("hello world"); got != "hello world" {
+			t.Errorf("got %q, want %q", got, "hello world")
+		}
+	})
+}
+
 func TestPipeErr(t *testing.T) {
 	good := func(s string) (string, error) { return strings.ToUpper(s), nil }
 	bad := func(s string) (string, error) { return "", errors.New("fail") }