ErrUsage: do not print usage information, rename it to WriteError

When an error happened the usage output is often not needed. The error string
should be sufficient to understand the issue.

- do not print the usage output in ErrUsage()
- print the additional information that can "--help" can be checked for more
  information, include the path that was used to run the binary,
- rename ErrUsage to WriteError

README.md

@@ -30,7 +30,7 @@ func main() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -66,7 +66,7 @@ func main() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -132,7 +132,7 @@ func main() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -176,7 +176,7 @@ func main() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -207,7 +207,7 @@ func main() {
 	parsed, err := proteus.MustParse(&params,
 		proteus.WithAutoUsage(os.Stderr, "Demo App", func() { os.Exit(0) }))
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

dynamic_test.go

@@ -57,7 +57,7 @@ func TestDynamic(t *testing.T) {
 		proteus.WithProviders(provider))
 	if err != nil {
 		buffer := bytes.Buffer{}
-		parsed.ErrUsage(&buffer, err)
+		parsed.WriteError(&buffer, err)
 		t.Error(buffer.String())
 	}
 

example_errusage_test.go

@@ -6,7 +6,7 @@ import (
 	"github.com/simplesurance/proteus"
 )
 
-func ExampleParsed_ErrUsage() {
+func ExampleParsed_WriteError() {
 	params := struct {
 		Latitude  float64
 		Longitude float64
@@ -15,7 +15,7 @@ func ExampleParsed_ErrUsage() {
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
 		// "parsed" is never nil; it can be used to parse the error
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

example_mustparse_test.go

@@ -17,7 +17,7 @@ func ExampleMustParse() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -36,7 +36,7 @@ func ExampleMustParse_withTags() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -58,7 +58,7 @@ func ExampleMustParse_providers() {
 			cfgenv.New("CONFIG"), // change env var prefix to CONFIG
 			cfgflags.New()))      // flags are used, but priority is to env vars
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 
@@ -78,7 +78,7 @@ func ExampleMustParse_trimSpaces() {
 			TrimSpace: true,
 		}))
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

example_paramset_test.go

@@ -15,7 +15,7 @@ func Example_paramSet() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

example_tags_defaults_test.go

@@ -19,7 +19,7 @@ func Example_tagsAndDefaults() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

example_test.go

@@ -17,7 +17,7 @@ func Example() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

example_xtype_test.go

@@ -24,7 +24,7 @@ func Example_xtypes() {
 
 	parsed, err := proteus.MustParse(&params)
 	if err != nil {
-		parsed.ErrUsage(os.Stderr, err)
+		parsed.WriteError(os.Stderr, err)
 		os.Exit(1)
 	}
 

parsed.go

@@ -26,14 +26,15 @@ type Parsed struct {
 	}
 }
 
-// ErrUsage is a specialized version of Usage(), that is intended
-// to be used when configuration parsing failed. Additionally to the
-// usage text, it also outputs the validation errors with the supplied
-// parameters. It does not terminate the application.
-func (p *Parsed) ErrUsage(w io.Writer, err error) {
+// WriteError writes the strings representation of err to w.
+// The line is prefixed with "ERROR: " .
+func (p *Parsed) WriteError(w io.Writer, err error) {
 	// TODO: the output here can be a lot more insightful
-	fmt.Fprintf(w, "%s: %s\n", binaryName(), err.Error())
-	p.usage(w)
+	fmt.Fprintf(w, "config error: %s\n", err.Error())
+	// the full path to the binary is used instead of only the name, to
+	// ensure that the quoted '%s --help' part can be copy&pasted and
+	// contains a valid path to run the binary
+	fmt.Fprintf(w, "\nRun '%s --help' for more information.\n", os.Args[0])
 }
 
 // Usage prints usage and detailed help output to the provided writer.

parser_test.go

@@ -74,7 +74,7 @@ func TestDefaultValueAllTypes(t *testing.T) {
 		proteus.WithLogger(plog.TestLogger(t)))
 	if err != nil {
 		t.Logf("Unexpected error parsing configuration: %+v", err)
-		parsed.ErrUsage(testWriter, err)
+		parsed.WriteError(testWriter, err)
 		t.FailNow()
 	}
 
@@ -134,7 +134,7 @@ func TestEmbeddingParameters(t *testing.T) {
 		proteus.WithLogger(plog.TestLogger(t)))
 	if err != nil {
 		t.Logf("Unexpected error parsing configuration: %+v", err)
-		parsed.ErrUsage(testWriter, err)
+		parsed.WriteError(testWriter, err)
 		t.FailNow()
 	}
 
@@ -186,7 +186,7 @@ func TestEmbeddingParamSet(t *testing.T) {
 		proteus.WithLogger(plog.TestLogger(t)))
 	if err != nil {
 		t.Logf("Unexpected error parsing configuration: %+v", err)
-		parsed.ErrUsage(testWriter, err)
+		parsed.WriteError(testWriter, err)
 		t.FailNow()
 	}
 
@@ -231,7 +231,7 @@ func TestParseWithTrim(t *testing.T) {
 		}))
 	if err != nil {
 		t.Logf("Unexpected error parsing configuration: %+v", err)
-		parsed.ErrUsage(testWriter, err)
+		parsed.WriteError(testWriter, err)
 		t.FailNow()
 	}