v0.2.1.

Author: mzattahri

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2.1
+
+- Improved examples and documentation.
+
 ## v0.2.0
 
 ### Added

example_test.go

@@ -7,6 +7,7 @@ import (
 	"mz.attahri.com/code/lines"
 )
 
+// ExampleHead demonstrates iterating over the first n lines of a reader.
 func ExampleHead() {
 	r := strings.NewReader("one\ntwo\nthree\nfour\nfive")
 	for line, err := range lines.Head(r, 3) {
@@ -21,6 +22,7 @@ func ExampleHead() {
 	// three
 }
 
+// ExampleTail demonstrates iterating over the last n lines of a reader in reverse order.
 func ExampleTail() {
 	r := strings.NewReader("one\ntwo\nthree\nfour\nfive")
 	for line, err := range lines.Tail(r, 2) {
@@ -34,6 +36,7 @@ func ExampleTail() {
 	// four
 }
 
+// ExampleFilter demonstrates filtering lines that exactly match a given value.
 func ExampleFilter() {
 	r := strings.NewReader("apple\nbanana\napricot\ncherry")
 	for line, err := range lines.Filter(lines.All(r), "banana") {
@@ -46,6 +49,7 @@ func ExampleFilter() {
 	// Line 2: banana
 }
 
+// ExampleFilterFunc demonstrates filtering lines using a custom predicate function.
 func ExampleFilterFunc() {
 	r := strings.NewReader("apple\nbanana\napricot\ncherry")
 	for line, err := range lines.FilterFunc[string](lines.All(r), func(s string) bool {
@@ -61,6 +65,7 @@ func ExampleFilterFunc() {
 	// apricot
 }
 
+// ExampleTake demonstrates limiting a scanner to the first n lines.
 func ExampleTake() {
 	r := strings.NewReader("one\ntwo\nthree\nfour\nfive")
 	for line, err := range lines.Take(lines.All(r), 2) {
@@ -74,6 +79,7 @@ func ExampleTake() {
 	// two
 }
 
+// ExampleSkip demonstrates skipping the first n lines of a scanner.
 func ExampleSkip() {
 	r := strings.NewReader("one\ntwo\nthree\nfour\nfive")
 	for line, err := range lines.Skip(lines.All(r), 3) {
@@ -87,6 +93,7 @@ func ExampleSkip() {
 	// five
 }
 
+// ExampleRange demonstrates extracting a range of lines by line number.
 func ExampleRange() {
 	r := strings.NewReader("one\ntwo\nthree\nfour\nfive")
 	for line, err := range lines.Range(lines.All(r), 2, 4) {
@@ -101,6 +108,7 @@ func ExampleRange() {
 	// four
 }
 
+// ExampleTakeWhile demonstrates yielding lines while a predicate holds true.
 func ExampleTakeWhile() {
 	r := strings.NewReader("# comment 1\n# comment 2\ncode\n# not a header")
 	for line, err := range lines.TakeWhile[string](lines.All(r), func(s string) bool {
@@ -116,6 +124,7 @@ func ExampleTakeWhile() {
 	// # comment 2
 }
 
+// ExampleSkipWhile demonstrates skipping lines while a predicate holds true.
 func ExampleSkipWhile() {
 	r := strings.NewReader("# comment 1\n# comment 2\ncode\nmore code")
 	for line, err := range lines.SkipWhile[string](lines.All(r), func(s string) bool {
@@ -131,6 +140,7 @@ func ExampleSkipWhile() {
 	// more code
 }
 
+// ExampleMap demonstrates transforming each line's content.
 func ExampleMap() {
 	r := strings.NewReader("hello\nworld")
 	for upper, err := range lines.Map[string](lines.All(r), func(l *lines.Line) string {
@@ -146,6 +156,7 @@ func ExampleMap() {
 	// WORLD
 }
 
+// ExampleCollect demonstrates materializing a scanner into a slice.
 func ExampleCollect() {
 	r := strings.NewReader("one\ntwo\nthree")
 	all, err := lines.Collect(lines.All(r))
@@ -159,6 +170,7 @@ func ExampleCollect() {
 	// two
 }
 
+// ExampleGet demonstrates retrieving a specific line by number.
 func ExampleGet() {
 	r := strings.NewReader("one\ntwo\nthree")
 	line, err := lines.Get(lines.All(r), 2)
@@ -170,6 +182,7 @@ func ExampleGet() {
 	// two
 }
 
+// ExampleContains demonstrates checking if a line exists in a scanner.
 func ExampleContains() {
 	r := strings.NewReader("apple\nbanana\ncherry")
 	found, err := lines.Contains(lines.All(r), "banana")
@@ -181,6 +194,7 @@ func ExampleContains() {
 	// true
 }
 
+// ExampleIndex demonstrates finding the line number of the first matching line.
 func ExampleIndex() {
 	r := strings.NewReader("apple\nbanana\ncherry")
 	lineno, err := lines.Index(lines.All(r), "banana")
@@ -192,6 +206,7 @@ func ExampleIndex() {
 	// 2
 }
 
+// ExampleLastIndex demonstrates finding the line number of the last matching line.
 func ExampleLastIndex() {
 	r := strings.NewReader("apple\nbanana\napple\ncherry")
 	lineno, err := lines.LastIndex(lines.All(r), "apple")
@@ -203,6 +218,7 @@ func ExampleLastIndex() {
 	// 3
 }
 
+// ExampleFindAll demonstrates finding all line numbers matching a predicate.
 func ExampleFindAll() {
 	r := strings.NewReader("TODO: first\ndone\nTODO: second\ndone")
 	matches, err := lines.FindAll[string](lines.All(r), func(s string) bool {
@@ -216,6 +232,7 @@ func ExampleFindAll() {
 	// [1 3]
 }
 
+// ExampleCount demonstrates counting lines equal to a given value.
 func ExampleCount() {
 	r := strings.NewReader("apple\nbanana\napple\ncherry")
 	n, err := lines.Count(lines.All(r), "apple")
@@ -227,6 +244,7 @@ func ExampleCount() {
 	// 2
 }
 
+// ExampleCountFunc demonstrates counting lines matching a predicate.
 func ExampleCountFunc() {
 	r := strings.NewReader("short\na]very long line here\nmedium")
 	n, err := lines.CountFunc(lines.All(r), func(s string) bool {

lines.go

@@ -1,6 +1,12 @@
 // Package lines provides iterator-based tools to read, search, and modify
 // lines in text files and streams.
 //
+// # Generic Text Support
+//
+// Many functions in this package are generic over the [Text] constraint,
+// accepting both string and []byte. This allows working with line content
+// in whichever form is most convenient for your use case.
+//
 // # Line Numbers
 //
 // All line numbers in this package are 1-based to match editor conventions.
@@ -10,7 +16,8 @@
 //
 // The core abstraction is [Scanner], a type alias for iter.Seq2[*Line, error].
 // Create scanners with [All] (forward) or [Backward] (reverse), then compose
-// them with [Filter], [Take], [Head], and [Tail].
+// them with [Filter], [Take], [Skip], and [Range]. Use [Head] and [Tail] for
+// convenient access to the first or last n lines from a reader.
 //
 // # Searching
 //

rewrite.go

@@ -68,6 +68,7 @@ func (lw *lineWriter) Write(p []byte) (n int, err error) {
 }
 
 // Transform applies fn to each line from src and writes results to dst.
+// Return [ErrDrop] from fn to skip a line.
 // Lines are processed in a streaming fashion without buffering the entire
 // file, making it suitable for large files. The caller is responsible for
 // positioning src (e.g., seek to start if needed) before calling.

rewrite_test.go

@@ -94,7 +94,9 @@ func ExampleRewrite() {
 	}
 
 	if err := lines.Rewrite(f, fn); err != nil {
-		f.Close() //nolint:errcheck // best effort cleanup before exit
+		if err := f.Close(); err != nil {
+			log.Fatal(err)
+		}
 		log.Fatal(err)
 	}
 	if err := f.Close(); err != nil {

scan_test.go

@@ -12,6 +12,7 @@ import (
 	"mz.attahri.com/code/lines"
 )
 
+// ExampleAll demonstrates iterating over all lines from a reader.
 func ExampleAll() {
 	const txt = "First line\nSecond line\nThird line"
 
@@ -27,6 +28,7 @@ func ExampleAll() {
 	// 3: Third line
 }
 
+// ExampleBackward demonstrates iterating over lines in reverse order.
 func ExampleBackward() {
 	const txt = "First line\nSecond line\nThird line"
 
@@ -86,7 +88,11 @@ func TestBackward(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer f.Close() //nolint:errcheck // test cleanup
+	defer func() {
+		if err := f.Close(); err != nil {
+			t.Fatal(err)
+		}
+	}()
 
 	// Collect lines in reverse
 	var reverse []string