config

README

Simple configuration for Go desktop apps

This package provides a simple configuration wrapper that marshals and unmarshals YAML to the user's config directory (e.g. ~/.config/appname on Linux or %AppData\appname on Windows).

Features:

• Only one dependency - gopkg.in/yaml.v2 for yaml marshalling
• Stores files in the correct config directory by default, across OSes
• Sensible defaults let you get on with more important things

Example

package main

import "github.com/csmith/config"

type MyAppConfig struct {
	Name         string
	LikesMarmite bool
}

func main() {
	conf := &MyAppConfig{}
	
	// config.Load() can take options to customise the directory, filename, etc.
	// If you don't want to immediately load the config, you can use config.New(),
	// then call .Load on the config struct at a later time.
	c, err := config.Load(conf)
	if err != nil {
		panic(err)
	}

	if conf.Name == "" {
		// Prompt the user for missing settings, or use default values.
		// More advanced apps might want to populate a version field and
		// apply migrations/data entry in a more structured way.
		conf.Name = "Bob"
		conf.LikesMarmite = false
	}

	defer func() {
		// config.Save will write out the config to disk, creating directories if necessary.
		if err := c.Save(conf); err != nil {
			panic(err)
		}
	}()
}

Options

A small set of options can be passed to config.New():

config.DirectoryName(string)

Sets the name of the directory to use. This is always rooted below the user's configuration directory. For example, setting the directory name to "myapp" would store a config file at ~/.config/myapp/config.yml on Linux.

If not specified, defaults to argv[0], i.e. the name of the binary being executed.

config.FileName(string)

Sets the name of the file used. If not specified, defaults to config.yml. This can be useful if you need to load multiple configuration files for one application.

config.Permissions(os.FileMode, os.FileMode)

Changes the permissions that will be used for newly created directories and files, respectively. Existing directories and files will not have their permissions changed.

If not specified, defaults to 0700 for directories and 0600 for files (i.e., read/write for the owner only).

Contributes

Feedback, questions, pull requests and bug reports are welcome! Please raise an issue on GitHub.

Documentation

Index

• type Config
  • func Load(target interface{}, o ...Option) (*Config, error)
  • func New(o ...Option) (*Config, error)
  • func (c *Config) Directory() string
  • func (c *Config) Load(target interface{}) error
  • func (c *Config) Save(i interface{}) error
• type Option
  • func DirectoryName(n string) Option
  • func FileName(n string) Option
  • func Permissions(directoryMode os.FileMode, fileMode os.FileMode) Option

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config provides an easy way to read and write configuration files for desktop applications.

Config files are stored in the appropriate location (per os.UserConfigDir()), and automatically marshalled to and from YAML.

func Load

func Load(target interface{}, o ...Option) (*Config, error)

Load is a convenience method that creates a new Config with the given options, and then immediately loads the config into the target struct.

func New

func New(o ...Option) (*Config, error)

New creates a new Config that can be used to load and save configuration information. Options can be passed to customise behaviour, but the defaults are designed to be usable out of the box.

func (*Config) Directory

func (c *Config) Directory() string

Directory returns the directory where the config file is stored.

func (*Config) Load

func (c *Config) Load(target interface{}) error

Load reads the config file from disk, if it exists, and unmarshals it into the target struct. If the file does not exist on disk, no changes will be made to the target but no error will be returned.

func (*Config) Save

func (c *Config) Save(i interface{}) error

Save marshals and writes the config file to disk. If the config directory does not exist it will be created.

type Option

type Option func(*options)

An Option alters the default configuration of the config provider.

func DirectoryName

func DirectoryName(n string) Option

DirectoryName changes the name of the directory that the config file should be stored in.

This is usually the application's name, and if not specified will default to os.Args[0].

func FileName

func FileName(n string) Option

FileName changes the name of the file that the config is stored in.

If not specified, defaults to "config.yml".

func Permissions

func Permissions(directoryMode os.FileMode, fileMode os.FileMode) Option

Permissions sets the filesystem permissions that will be set on newly created directories and files. Existing permissions will not be modified.

If not specified, defaults to 0700 for directories and 0600 for files.