README
¶
= 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.
They can also set `<APPNAME>_CONFIG_FILE`, which is read when the `ConfigFile`
is created. Non-alphanumeric characters in the application name become
underscores, and empty values are ignored.
== 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`.
See link:example/load_or_create/main.go[LoadOrCreate example] and
link:urfave/example/main.go[CLI example].
Documentation
¶
Overview ¶
Package config manages typed YAML and JSON configuration files.
Configuration values implement Validatable and are validated after being loaded and before being written. Writes are atomic and use private file permissions.
New configuration files use the user's configuration directory. A path may be selected through APPNAME_CONFIG_FILE, whose prefix is derived from the application name, or explicitly with ConfigFile.SetPath. An explicit SetPath call takes precedence over the environment value captured when the ConfigFile is created. Empty environment values are ignored.
File operations currently support Linux.
Index ¶
- func DefaultDataDir(appName string) (string, error)
- type ConfigFile
- func (c *ConfigFile[T]) AppName() string
- func (c *ConfigFile[T]) Content() ([]byte, error)
- func (c *ConfigFile[T]) Create(data T) error
- func (c *ConfigFile[T]) Load() (T, error)
- func (c *ConfigFile[T]) LoadOrCreate(defaultData T) (T, error)
- func (c *ConfigFile[T]) Path() string
- func (c *ConfigFile[T]) PathEnvVar() string
- func (c *ConfigFile[T]) Save(data T) error
- func (c *ConfigFile[T]) SetPath(path string) error
- type Validatable
Examples ¶
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.
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. It may be used concurrently after its path has been configured.
func NewJSONConfigFile ¶
func NewJSONConfigFile[T Validatable](appName, fileName string) (*ConfigFile[T], error)
NewJSONConfigFile creates a typed JSON configuration file inside the user's configuration directory.
func NewYAMLConfigFile ¶
func NewYAMLConfigFile[T Validatable](appName, fileName string) (*ConfigFile[T], error)
NewYAMLConfigFile creates a typed YAML configuration file inside the user's configuration directory.
Example ¶
package main
import (
"fmt"
"github.com/vekio/config"
)
type exampleConfig struct {
Address string `yaml:"address"`
}
func (c exampleConfig) Validate() error {
if c.Address == "" {
return fmt.Errorf("address is required")
}
return nil
}
func main() {
file, err := config.NewYAMLConfigFile[exampleConfig]("example", "config.yml")
if err != nil {
panic(err)
}
if err := file.SetPath("./config.dev.yml"); err != nil {
panic(err)
}
fmt.Println(file.Path())
}
Output: config.dev.yml
func (*ConfigFile[T]) AppName ¶ added in v0.3.0
func (c *ConfigFile[T]) AppName() string
AppName returns the application name associated with the configuration.
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]) PathEnvVar ¶ added in v0.5.0
func (c *ConfigFile[T]) PathEnvVar() string
PathEnvVar returns the environment variable used to override Path.
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.
func (*ConfigFile[T]) SetPath ¶ added in v0.3.0
func (c *ConfigFile[T]) SetPath(path string) error
SetPath overrides the conventional configuration file path. It must not be called concurrently with any other ConfigFile method.
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