README
¶
= config
Typed YAML and JSON configuration files for Go, with reusable commands and
flags 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.NewDefaultConfigFile[Config]("myapp")
if err != nil {
return err
}
cfg, err := file.LoadOrCreate(Config{Address: "127.0.0.1:8080"})
----
The default file is `<user-config-dir>/myapp/config.yml`. Explicit YAML and
JSON constructors are also available:
[source,go]
----
config.NewYAMLConfigFile[Config]("/etc", "myapp", "config.yml")
config.NewJSONConfigFile[Config]("/etc", "myapp", "config.json")
----
`DefaultDataDir("myapp")` returns the conventional application data directory.
== CLI
Reusable commands and a global configuration path flag are provided for
`urfave/cli/v3`:
[source,go]
----
app := &cli.Command{
Name: "myapp",
Flags: []cli.Flag{config.NewConfigFlag(file)},
Commands: []*cli.Command{config.NewConfigCommand(file, defaults)},
}
----
The `config` command provides `show`, `path`, `validate`, and `init`.
`config init --force` replaces an existing file.
The global `--config` flag overrides the file path. It can also be set through
`<APPNAME>_CONFIG_FILE`; for example, `MYAPP_CONFIG_FILE`.
See link:example/load_or_create/main.go[LoadOrCreate example] and
link:example/cli/main.go[CLI example].
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultDataDir ¶ added in v0.2.0
DefaultDataDir returns the application's conventional data directory. XDG_DATA_HOME takes precedence when set and must contain an absolute path.
func NewConfigCommand ¶ added in v0.2.0
func NewConfigCommand[T Validatable](file *ConfigFile[T], defaultData T) *urfavecli.Command
NewConfigCommand creates a reusable config command with show, path, validate, and init subcommands. Invoking config without a subcommand displays help.
func NewConfigFlag ¶ added in v0.2.0
func NewConfigFlag[T Validatable](file *ConfigFile[T]) *urfavecli.StringFlag
NewConfigFlag creates a global --config flag that overrides file's path when explicitly set by the client application.
Types ¶
type ConfigFile ¶
type ConfigFile[T Validatable] struct { // contains filtered or unexported fields }
ConfigFile wraps the metadata and helpers required to manage one application-specific configuration file.
func NewDefaultConfigFile ¶
func NewDefaultConfigFile[T Validatable](appName string) (*ConfigFile[T], error)
NewDefaultConfigFile creates a typed YAML configuration file inside the user's configuration directory.
func NewJSONConfigFile ¶
func NewJSONConfigFile[T Validatable](baseDir, appName, fileName string) (*ConfigFile[T], error)
NewJSONConfigFile creates a typed JSON configuration file.
func NewYAMLConfigFile ¶
func NewYAMLConfigFile[T Validatable](baseDir, appName, fileName string) (*ConfigFile[T], error)
NewYAMLConfigFile creates a typed YAML configuration file.
func (*ConfigFile[T]) Content ¶
func (c *ConfigFile[T]) Content() ([]byte, error)
Content reads and returns the content of the configuration file. It returns an error if the file cannot be read.
func (*ConfigFile[T]) Create ¶ added in v0.2.0
func (c *ConfigFile[T]) Create(data T) error
Create validates and writes a new configuration file. It returns an error wrapping os.ErrExist when the file already exists.
func (*ConfigFile[T]) Load ¶ added in v0.2.0
func (c *ConfigFile[T]) Load() (T, error)
Load reads and validates the configuration from disk.
func (*ConfigFile[T]) LoadOrCreate ¶ added in v0.2.0
func (c *ConfigFile[T]) LoadOrCreate(defaultData T) (T, error)
LoadOrCreate loads an existing configuration or saves and returns defaultData when the file does not exist.
func (*ConfigFile[T]) Path ¶
func (c *ConfigFile[T]) Path() string
Path constructs and returns the full path to the configuration file. It combines the base directory, application name, and file name.
func (*ConfigFile[T]) Save ¶ added in v0.2.0
func (c *ConfigFile[T]) Save(data T) error
Save validates and writes the configuration to disk, replacing an existing file atomically.
type Validatable ¶
type Validatable interface {
Validate() error
}
Validatable is implemented by configuration types that can perform their own validation after being loaded from disk.
Source Files
Directories