ConfigKit/example_test.go

package configkit_test

import (
	"errors"
	"fmt"
	"os"
	"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 ExampleLoad_sequenceDeclaration() {
	type Item struct {
		ID string `yaml:"id"`
	}
	type Config struct {
		Items []Item `yaml:"items"`
	}
	result, err := configkit.Load[Config](configkit.Bytes("catalog.yml", []byte(`configkit:
  sequences:
    - destination: [items]
      key: id
items:
  - id: prompt
`)))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(result.Config.Items[0].ID)
	// Output: prompt
}

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 ExampleDiff() {
	type Config struct {
		Workers int `yaml:"workers"`
	}
	before, err := configkit.Load[Config](configkit.Mapping("before", map[string]any{"workers": 2}))
	if err != nil {
		fmt.Println(err)
		return
	}
	after, err := configkit.Load[Config](configkit.Mapping("after", map[string]any{"workers": 4}))
	if err != nil {
		fmt.Println(err)
		return
	}
	differences, err := configkit.Diff(before, after)
	if err != nil {
		fmt.Println(err)
		return
	}
	for _, difference := range differences {
		fmt.Printf("%s: %s -> %s\n", difference.Path.String(),
			strings.TrimSpace(difference.Left.YAML), strings.TrimSpace(difference.Right.YAML))
	}
	// Output: /workers: 2 -> 4
}

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>
}

func ExampleSecretEnv() {
	const name = "CONFIGKIT_EXAMPLE_API_KEY"
	previous, present := os.LookupEnv(name)
	_ = os.Setenv(name, "disposable-example-value")
	defer func() {
		if present {
			_ = os.Setenv(name, previous)
		} else {
			_ = os.Unsetenv(name)
		}
	}()

	type Config struct {
		APIKey configkit.Secret `yaml:"api_key"`
	}
	result, err := configkit.Load[Config](configkit.Bytes("secret.yml", []byte("api_key: "+name+"\n")))
	fmt.Println(result.Config.APIKey.EnvName(), result.Config.APIKey.IsResolved(), err)
	// Output: CONFIGKIT_EXAMPLE_API_KEY true <nil>
}

func ExampleOverride() {
	type Config struct {
		Workers int `yaml:"workers"`
	}
	workers, workersWasSet := 0, true // Supplied by the application's CLI parser.
	var overrides []configkit.Override
	if workersWasSet {
		overrides = append(overrides, configkit.Override{
			Path: configkit.Keys("workers"), Value: workers, Flag: "--workers",
		})
	}
	result, err := configkit.Load(configkit.NoSource(), configkit.Options[Config]{
		Definition: configkit.Definition[Config]{Defaults: func() Config { return Config{Workers: 4} }},
		Overrides:  overrides,
	})
	fmt.Println(result.Config.Workers, result.Sources()[0].Label, err)
	// Output: 0 --workers <nil>
}

func ExampleResult_Explain() {
	type Config struct {
		Workers int `yaml:"workers"`
	}
	result, err := configkit.Load(configkit.Bytes("config.yml", []byte("workers: 8\n")), configkit.Options[Config]{
		Definition: configkit.Definition[Config]{Defaults: func() Config { return Config{Workers: 4} }},
	})
	explanation, ok := result.Explain(configkit.Keys("workers"))
	fmt.Printf("%s -> %s known=%t error=%v\n",
		strings.TrimSpace(explanation.History[0].After.YAML),
		strings.TrimSpace(explanation.Effective.YAML), ok, err)
	// Output: 4 -> 8 known=true error=<nil>
}