config

= config

Typed YAML and JSON configuration files for Go, with reusable commands and
flags available separately for `urfave/cli/v3` applications.

Configuration types implement `Validate() error`. Values are validated after
loading and before writing. Writes are atomic and use private permissions. The
library currently supports Linux.

== Install

[source,shell]
----
go get github.com/vekio/config
----

== Usage

[source,go]
----
type Config struct {
    Address string `yaml:"address"`
}

func (c Config) Validate() error {
    if c.Address == "" {
        return fmt.Errorf("address is required")
    }
    return nil
}

file, err := config.NewYAMLConfigFile[Config]("myapp", "config.yml")
if err != nil {
    return err
}

cfg, err := file.LoadOrCreate(Config{Address: "127.0.0.1:8080"})
----

Files use `<user-config-dir>/<app-name>/<file-name>`. YAML and JSON formats are
available:

[source,go]
----
config.NewYAMLConfigFile[Config]("myapp", "config.yml")
config.NewJSONConfigFile[Config]("myapp", "config.json")
----

`DefaultDataDir("myapp")` returns the conventional application data directory.

Applications can select another path explicitly with
`file.SetPath("./config.dev.yml")` before loading or writing the configuration.

== CLI

Reusable commands and a global configuration path flag are provided for
`urfave/cli/v3` in a separate module:

[source,shell]
----
go get github.com/vekio/config/urfave
----

[source,go]
----
import "github.com/vekio/config/urfave"

app := &cli.Command{
    Name:     "myapp",
    Flags:    []cli.Flag{urfave.NewConfigFlag(file)},
    Commands: []*cli.Command{urfave.NewConfigCommand(file, defaults)},
}
----

The `config` command provides `show`, `path`, `validate`, and `init`.
`config init --force` replaces an existing file.

The global `--config` flag takes precedence over `<APPNAME>_CONFIG_FILE`.
Hyphens and dots in the application name become underscores, so `my-app` uses
`MY_APP_CONFIG_FILE`.

See link:example/load_or_create/main.go[LoadOrCreate example] and
link:urfave/example/main.go[CLI example].