Add ParseAll

Author: DrJosh9000

go.mod

@@ -2,8 +2,6 @@ module github.com/buildkite/go-pipeline
 
 go 1.23.0
 
-toolchain go1.24.1
-
 retract (
 	v1.0.1 // Solely to publish the retraction of v1.0.0. We'll skip straight to v1.0.2 when we're ready to publish
 	v1.0.0 // Published accidentally.

parser.go

@@ -3,6 +3,7 @@ package pipeline
 import (
 	"errors"
 	"io"
+	"iter"
 	"strings"
 
 	"github.com/buildkite/go-pipeline/ordered"
@@ -13,6 +14,9 @@ import (
 type Options func(*Pipeline)
 
 // Parse parses a pipeline. It does not apply interpolation.
+// Note that it only parses the first YAML document in the input.
+// To parse all YAML documents in the input reader as pipelines, use ParseAll.
+//
 // Warnings are passed through the err return:
 //
 //	p, err := Parse(src)
@@ -42,6 +46,46 @@ func Parse(src io.Reader) (*Pipeline, error) {
 	return p, ordered.Unmarshal(n, p)
 }
 
+// ParseAll parses all YAML documents in the input stream as pipelines.
+// It does not stop yielding on decoding or unmarshaling errors.
+// It does not apply interpolation.
+//
+// Warnings are passed through the err return:
+//
+//	for p, err := range ParseAll(src) {
+//		if w := warning.As(err); w != nil {
+//			// Here are some warnings that should be shown
+//			log.Printf("*Warning* - pipeline is not fully parsed:\n%v", w)
+//		} else if err != nil {
+//			// Parse could not understand src at all
+//			return err
+//		}
+//		// Use p
+//	}
+func ParseAll(src io.Reader) iter.Seq2[*Pipeline, error] {
+	dec := yaml.NewDecoder(src)
+	return func(yield func(*Pipeline, error) bool) {
+		for {
+			// The loop body here is essentially similar to Parse (above).
+			n := new(yaml.Node)
+			if err := dec.Decode(n); err != nil {
+				if err == io.EOF {
+					return // end of stream
+				}
+				if !yield(nil, formatYAMLError(err)) {
+					return
+				}
+				continue
+			}
+
+			p := new(Pipeline)
+			if !yield(p, ordered.Unmarshal(n, p)) {
+				return
+			}
+		}
+	}
+}
+
 func formatYAMLError(err error) error {
 	return errors.New(strings.TrimPrefix(err.Error(), "yaml: "))
 }

parser_test.go

@@ -70,6 +70,61 @@ func TestParserParsesYAML(t *testing.T) {
 	}
 }
 
+func TestParseAll_ParsesMultipleDocuments(t *testing.T) {
+	input := strings.NewReader(`---
+steps:
+  - command: "hallo"
+---
+steps:
+  - command: "tschüss"
+---
+steps:
+  - command: "bis später"
+`)
+
+	want := []*Pipeline{
+		{Steps: Steps{&CommandStep{Command: "hallo"}}},
+		{Steps: Steps{&CommandStep{Command: "tschüss"}}},
+		{Steps: Steps{&CommandStep{Command: "bis später"}}},
+	}
+
+	var got []*Pipeline
+
+	for gotPipeline, err := range ParseAll(input) {
+		if err != nil {
+			t.Fatalf("Parse(input) error = %v", err)
+		}
+
+		got = append(got, gotPipeline)
+	}
+
+	if diff := cmp.Diff(got, want, cmp.Comparer(ordered.EqualSS), cmp.Comparer(ordered.EqualSA)); diff != "" {
+		t.Errorf("parsed pipelines diff (-got, +want):\n%s", diff)
+	}
+
+	// Multiple objects can be encoded as separate documents with yaml.Encoder.
+	var gotYAML strings.Builder
+	enc := yaml.NewEncoder(&gotYAML)
+	for i, p := range got {
+		if err := enc.Encode(p); err != nil {
+			t.Errorf("yaml.Marshal(got[%d]) error = %v", i, err)
+		}
+	}
+
+	wantYAML := `steps:
+    - command: hallo
+---
+steps:
+    - command: tschüss
+---
+steps:
+    - command: bis später
+`
+	if diff := cmp.Diff(gotYAML.String(), wantYAML); diff != "" {
+		t.Errorf("marshalled YAML diff (-got +want):\n%s", diff)
+	}
+}
+
 func TestParserParsesYAMLWithInterpolation(t *testing.T) {
 	tests := []struct {
 		desc             string