conf

README

What?

Conf stores a struct in a TOML file, and provides functions to read it back again.

Why this package?

I didn't need anything fancy, but kept rewriting the same kind of read and write functions in various projects - so finally I have decided to make a small package that I can import.

Default locations

The 'LoadConfig' function tries to read from (in order):

1. Current dir
2. User config dir, in a subdirectory named after your app
3. System config dir, in a subdirectory named after your app

If you want a custom path, use 'ReadConfig' to read and 'WriteConfig' to write. To always target one specific location, use the 'LoadFrom...' and 'SaveTo...' functions.

The user config dir is whatever os.UserConfigDir reports, and the system config dir is:

Platform	System config dir
Linux and other unix-like	/etc
Windows	%ProgramData%
macOS	/Library/Application Support
plan9	not supported

Documentation

https://pkg.go.dev/github.com/uidbz/conf

Bugs, feature requests, etc.

https://github.com/uidbz/conf/issues

Import

import (
	"github.com/uidbz/conf"
)

Usage

package main

import (
	"fmt"

	"github.com/uidbz/conf"
)

type MyConfig struct {
	Field1 string
	Field2 string
}

func main() {
	err := conf.SaveToUserConfigDir("MyApp", "config.toml", MyConfig{"Hey", "hey"})
	if err != nil {
		panic(err)
	}

	config := MyConfig{}
	loadPath, err := conf.LoadConfig("MyApp", "config.toml", &config)
	if err != nil {
		panic(err)
	}

	fmt.Println("Loaded config from:", loadPath)
	fmt.Println("Config data:", config)
}

Documentation

Overview

Package conf stores a struct in a TOML config file and reads it back again.

Encoding and decoding is done by github.com/pelletier/go-toml/v2, so the usual `toml:"..."` struct tags apply. Every load function takes a pointer to a struct; every save function takes the struct or a pointer to it.

To load a config file, use one of:

LoadConfig              // search current dir, then user config dir, then system config dir
ReadConfig              // read one specific path
LoadFromCurrentDir      // read from the current working dir
LoadFromUserConfigDir   // read from appName in the user config dir
LoadFromSystemConfigDir // read from appName in the system config dir

To save a struct, use one of:

WriteConfig            // write to one specific path, creating parent dirs
SaveToCurrentDir       // write to the current working dir
SaveToUserConfigDir    // write to appName in the user config dir
SaveToSystemConfigDir  // write to appName in the system config dir

To resolve the standard paths without touching the file system, use:

PathCurrentDir
PathUserConfigDir
PathSystemConfigDir

A short example:

type MyConfig struct {
	Field1 string
	Field2 string
}

func main() {
	if err := conf.SaveToUserConfigDir("MyApp", "config.toml", MyConfig{"Hey", "hey"}); err != nil {
		panic(err)
	}

	config := MyConfig{}
	loadPath, err := conf.LoadConfig("MyApp", "config.toml", &config)
	if err != nil {
		panic(err)
	}

	fmt.Println("Loaded config from:", loadPath)
	fmt.Println("Config data:", config)
}

Index

• func LoadConfig(appName, configFile string, v any) (configPath string, err error)
• func LoadFromCurrentDir(configFile string, v any) (configPath string, err error)
• func LoadFromSystemConfigDir(appName, configFile string, v any) (configPath string, err error)
• func LoadFromUserConfigDir(appName, configFile string, v any) (configPath string, err error)
• func PathCurrentDir(configFile string) (configPath string)
• func PathSystemConfigDir(appName, configFile string) (configPath string, err error)
• func PathUserConfigDir(appName, configFile string) (configPath string, err error)
• func ReadConfig(configPath string, v any) error
• func SaveToCurrentDir(configFile string, v any) error
• func SaveToSystemConfigDir(appName, configFile string, v any) error
• func SaveToUserConfigDir(appName, configFile string, v any) error
• func WriteConfig(configPath string, v any) error

Functions

func LoadConfig

func LoadConfig(appName, configFile string, v any) (configPath string, err error)

LoadConfig reads a TOML config file into v, which must be a pointer to a struct. It searches the following locations and reads the first file that exists:

1. the current working directory
2. appName inside the user config dir
3. appName inside the system config dir

The path that was used is returned even when err is non-nil, so callers can report which file failed.

func LoadFromCurrentDir

func LoadFromCurrentDir(configFile string, v any) (configPath string, err error)

LoadFromCurrentDir reads configFile from the current working directory into v, which must be a pointer to a struct. The path that was used is returned even when err is non-nil.

func LoadFromSystemConfigDir

func LoadFromSystemConfigDir(appName, configFile string, v any) (configPath string, err error)

LoadFromSystemConfigDir reads configFile from the appName subdirectory of the system config dir into v, which must be a pointer to a struct. The path that was used is returned even when err is non-nil.

func LoadFromUserConfigDir

func LoadFromUserConfigDir(appName, configFile string, v any) (configPath string, err error)

LoadFromUserConfigDir reads configFile from the appName subdirectory of the user config dir into v, which must be a pointer to a struct. The path that was used is returned even when err is non-nil.

func PathCurrentDir

func PathCurrentDir(configFile string) (configPath string)

PathCurrentDir returns the absolute path to configFile in the current working directory. If the working directory cannot be determined, configFile is returned unchanged.

func PathSystemConfigDir

func PathSystemConfigDir(appName, configFile string) (configPath string, err error)

PathSystemConfigDir returns the path to configFile in the appName subdirectory of the system-wide config dir, which is /etc on Linux and other unix-like systems, %ProgramData% on Windows and /Library/Application Support on macOS. It returns an error on plan9, and on Windows when %ProgramData% is not set.

func PathUserConfigDir

func PathUserConfigDir(appName, configFile string) (configPath string, err error)

PathUserConfigDir returns the path to configFile in the appName subdirectory of the user config dir, as reported by os.UserConfigDir.

func ReadConfig

func ReadConfig(configPath string, v any) error

ReadConfig reads the TOML file at configPath into v, which must be a pointer to a struct. Use it when the config file lives somewhere the Load functions do not look.

func SaveToCurrentDir

func SaveToCurrentDir(configFile string, v any) error

SaveToCurrentDir marshals v to TOML and writes it to configFile in the current working directory.

func SaveToSystemConfigDir

func SaveToSystemConfigDir(appName, configFile string, v any) error

SaveToSystemConfigDir marshals v to TOML and writes it to configFile in the appName subdirectory of the system config dir. Writing there usually requires elevated privileges.

func SaveToUserConfigDir

func SaveToUserConfigDir(appName, configFile string, v any) error

SaveToUserConfigDir marshals v to TOML and writes it to configFile in the appName subdirectory of the user config dir.

func WriteConfig

func WriteConfig(configPath string, v any) error

WriteConfig marshals v to TOML and writes it to configPath, creating any missing parent directories. Use it when the config file should go somewhere the Save functions do not write. The file is created with mode 0644.