Utilities for constructing diagnostics

Wrangling diagnostics is a common concern in the parsers and evaluator,
and these helper functions are intended to make that code more concise.

zcl/diagnostic.go

@@ -37,7 +37,7 @@ type Diagnostic struct {
 }
 
 // Diagnostics is a list of Diagnostic instances.
-type Diagnostics []Diagnostic
+type Diagnostics []*Diagnostic
 
 // error implementation, so that diagnostics can be returned via APIs
 // that normally deal in vanilla Go errors.
@@ -61,3 +61,26 @@ func (d Diagnostics) Error() string {
 		return fmt.Sprintf("%s, and %d other diagnostic(s)", d[0].Error(), count-1)
 	}
 }
+
+// Append appends a new error to a Diagnostics and return the whole Diagnostics.
+//
+// This is provided as a convenience for returning from a function that
+// collects and then returns a set of diagnostics:
+//
+//     return nil, diags.Append(&zcl.Diagnostic{ ... })
+//
+// Note that this modifies the array underlying the diagnostics slice, so
+// must be used carefully within a single codepath. It is incorrect (and rude)
+// to extend a diagnostics created by a different subsystem.
+func (d Diagnostics) Append(diag *Diagnostic) Diagnostics {
+	return append(d, diag)
+}
+
+// Extend concatenates the given Diagnostics with the receiver and returns
+// the whole new Diagnostics.
+//
+// This is similar to Append but accepts multiple diagnostics to add. It has
+// all the same caveats and constraints.
+func (d Diagnostics) Extend(diags Diagnostics) Diagnostics {
+	return append(d, diags...)
+}

zcl/pos.go

@@ -66,6 +66,14 @@ func (r *Range) ContainsOffset(offset int) bool {
 	return offset >= r.Start.Byte && offset < r.End.Byte
 }
 
+// Ptr returns a pointer to a copy of the receiver. This is a convenience when
+// ranges in places where pointers are required, such as in Diagnostic, but
+// the range in question is returned from a method. Go would otherwise not
+// allow one to take the address of a function call.
+func (r Range) Ptr() *Range {
+	return &r
+}
+
 // String returns a compact string representation of the receiver.
 // Callers should generally prefer to present a range more visually,
 // e.g. via markers directly on the relevant portion of source code.