Complete single-source semantic validation

example_test.go

@@ -0,0 +1,96 @@
+package configkit_test
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func ExampleLoad() {
+	type Config struct {
+		Enabled bool `yaml:"enabled"`
+		Workers int  `yaml:"workers"`
+	}
+	result, err := configkit.Load[Config](configkit.Bytes("example.yml", []byte("enabled: true\nworkers: 3\n")))
+	fmt.Println(result.Config, err)
+	// Output: {true 3} <nil>
+}
+
+func ExampleNoSource() {
+	type Config struct {
+		Workers int `yaml:"workers"`
+	}
+	result, err := configkit.Load(configkit.NoSource(), configkit.Options[Config]{
+		Definition: configkit.Definition[Config]{Defaults: func() Config { return Config{Workers: 4} }},
+	})
+	fmt.Println(result.Config.Workers, len(result.Sources()), err)
+	// Output: 4 0 <nil>
+}
+
+func ExampleValidation_Error() {
+	type Config struct {
+		First  string `yaml:"first"`
+		Second string `yaml:"second"`
+	}
+	_, err := configkit.Load(configkit.Bytes("duplicates.yml", []byte("first: same\nsecond: same\n")), configkit.Options[Config]{
+		Definition: configkit.Definition[Config]{Validate: func(configuration *Config, validation *configkit.Validation) {
+			if configuration.First == configuration.Second {
+				validation.Error(configkit.Keys("second"), "must differ from first", configkit.Keys("first"))
+			}
+		}},
+	})
+	var loadError *configkit.LoadError
+	errors.As(err, &loadError)
+	diagnostic := loadError.Diagnostics()[0]
+	fmt.Println(diagnostic.Code, diagnostic.Path, len(diagnostic.Related))
+	// Output: validate.error /second 1
+}
+
+func ExampleVersionRule() {
+	type Config struct {
+		Version string `yaml:"version"`
+	}
+	_, err := configkit.Load(configkit.Bytes("version.yml", []byte("version: old\n")), configkit.Options[Config]{
+		Definition: configkit.Definition[Config]{Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(version configkit.Version, validation *configkit.Validation) error {
+				if version.Text != "v1" {
+					validation.Error(configkit.Keys("version"), "unsupported version; migrate using the application guide")
+				}
+				return nil
+			},
+		}},
+	})
+	var loadError *configkit.LoadError
+	errors.As(err, &loadError)
+	fmt.Println(loadError.Diagnostics()[0].Message)
+	// Output: unsupported version; migrate using the application guide
+}
+
+func ExampleResolution() {
+	type Config struct {
+		Input   int `yaml:"input"`
+		Derived int `yaml:"derived"`
+	}
+	var order []string
+	result, err := configkit.Load(configkit.Bytes("resolved.yml", []byte("input: 3\n")), configkit.Options[Config]{
+		Definition: configkit.Definition[Config]{
+			Resolve: func(configuration *Config, resolution *configkit.Resolution) error {
+				order = append(order, "resolve")
+				configkit.Default(resolution, configkit.Keys("derived"), &configuration.Derived,
+					configuration.Input*2, "derived from input", configkit.Keys("input"))
+				return nil
+			},
+			Validate: func(configuration *Config, validation *configkit.Validation) {
+				order = append(order, "validate")
+				if configuration.Derived < configuration.Input {
+					validation.Error(configkit.Keys("derived"), "must not be less than input")
+				}
+			},
+		},
+	})
+	fmt.Println(strings.Join(order, " then "), result.Config.Derived, err)
+	// Output: resolve then validate 6 <nil>
+}