userconfig

README

User config handler

This package manages user configuration files in yaml format in os specific standard locations.

Variables

var ErrConfigNotStructPtr = errors.New("config must be a non-nil pointer to a struct")

ErrConfigNotStructPtr is returned when config is nil or not a pointer to a struct.

var ErrIncludesVolumeName = errors.New("path includes a volume or share, file path must be relative to the user configuration directory")

ErrIncludesVolumeName is returned when fileName includes a volume name or UNC share (e.g. "C:" or "\host\share" on Windows).

var ErrInvalidExtension = errors.New("filename does not have .yml or .yaml extension")

ErrInvalidExtension is returned when fileName does not end in ".yml" or ".yaml".

var ErrNoPath = errors.New("no filename provided")

ErrNoPath is returned when fileName is empty or contains only whitespace.

var ErrPathAbsolute = errors.New("path is absolute, file path must be relative to the user configuration directory")

ErrPathAbsolute is returned when fileName is an absolute path instead of one relative to the user configuration directory.

var ErrPathTraversal = errors.New("path tries to exit user configuration directory")

ErrPathTraversal is returned when fileName resolves to a path outside the user configuration directory.

Functions

Load

func Load[T any](fileName string, config *T) (err error)

Load prepends the user configuration directory to the given filename, reads the configuration file, and unmarshals its data into config, which must be a pointer to a valid struct. If the file does not exist, Load creates it by calling Save with the given config (leaving config unchanged) instead of returning an error. fileName should contain the path under the user configuration directory, not the full path.

Save

func Save[T any](fileName string, config *T) (err error)

Save prepends the user configuration directory to the given filename, creates directories as needed, marshals config into YAML, and writes it to the file. fileName should contain the path under the user configuration directory, not the full path.

FilePath

func FilePath(fileName string) (filePath string, err error)

FilePath returns the full path of the configuration file with the given filename or path. This function is called from the Save and Load functions.

Examples

See the example folder

Config file locations

If a file path of example/config.yml is provided the following locations will be used

Linux / Unix

$XDG_CONFIG_HOME/example/config.yml or if $XDG_CONFIG_HOME is not defined $HOME/.config/example/config.yml both of which usually resolves to /home/<USERNAME>/.config/example/config.yml

If neither $XDG_CONFIG_HOME or $HOME is defined, an error is returned.

Windows

User config is placed in %AppData%\example\config.yml which usually resolves to C:\Users\<USERNAME>\AppData\Roaming\example\config.yml

If %AppData% is undefined an error is returned.

Mac / Darwin

$HOME/Library/Application Support/example/config.yml which usually resolves to /Users/<USERNAME>/Library/Application Support/example/config.yml. If $HOME is undefined an error is returned.

License and Code of Conduct

This package is released under the MIT License.

Please follow the code of conduct when you interact with the project contributors.

Documentation

Index

• Variables
• func FilePath(fileName string) (p string, err error)
• func Load[T any](fileName string, config *T) (err error)
• func Save[T any](fileName string, config *T) (err error)

Variables

var ErrConfigNotStructPtr = errors.New("config must be a non-nil pointer to a struct")

ErrConfigNotStructPtr is returned when config is nil or not a pointer to a struct.

var ErrIncludesVolumeName = errors.New("path includes a volume or share, file path must be relative to the user configuration directory")

ErrIncludesVolumeName is returned when fileName includes a volume name or UNC share (e.g. "C:" or "\\host\share" on Windows).

var ErrInvalidExtension = errors.New("filename does not have .yml or .yaml extension")

ErrInvalidExtension is returned when fileName does not end in ".yml" or ".yaml".

var ErrNoPath = errors.New("no filename provided")

ErrNoPath is returned when fileName is empty or contains only whitespace.

var ErrPathAbsolute = errors.New("path is absolute, file path must be relative to the user configuration directory")

ErrPathAbsolute is returned when fileName is an absolute path instead of one relative to the user configuration directory.

var ErrPathTraversal = errors.New("path tries to exit user configuration directory")

ErrPathTraversal is returned when fileName resolves to a path outside the user configuration directory.

Functions

func FilePath

func FilePath(fileName string) (p string, err error)

FilePath returns the full path of the configuration file with the given filename or path. This function is called from the Save and Load functions.

func Load

func Load[T any](fileName string, config *T) (err error)

Load prepends the user configuration directory to the given filename, reads the configuration file, and unmarshals its data into config, which must be a pointer to a valid struct. If the file does not exist, Load creates it by calling Save with the given config (leaving config unchanged) instead of returning an error. fileName should contain the path under the user configuration directory, not the full path.

func Save

func Save[T any](fileName string, config *T) (err error)

Save prepends the user configuration directory to the given filename, creates directories as needed, marshals config into YAML, and writes it to the file. fileName should contain the path under the user configuration directory, not the full path.