store

README

Store

Store is a dead simple configuration manager for Go applications.

I didn't like existing configuration management solutions like globalconf, tachyon or viper. First two just don't feel right and viper, imo, a little overcomplicated—definitely offering too much for small things. Store supports either JSON, TOML or YAML out-of-the-box and lets you register practically any other configuration format. It persists all of your configurations in either $XDG_CONFIG_HOME or $HOME on Linux and in %APPDATA% on Windows.

Look, when I say it's dead simple, I actually mean it:

package main

import (
	"log"
	"time"

	"github.com/tucnak/store"
)

func init() {
	// You must init store with some truly unique path first!
	store.Init("cats-n-dogs/project-hotel")
}

type Cat struct {
	Name   string `toml:"naym"`
	Clever bool   `toml:"ayy"`
}

type Hotel struct {
	Name string
	Cats []Cat `toml:"guests"`

	Opens  *time.Time
	Closes *time.Time
}

func main() {
	var hotel Hotel

	if err := store.Load("hotel.toml", &hotel); err != nil {
		log.Println("failed to load the cat hotel:", err)
		return
	}

	// ...

	if err := store.Save("hotel.toml", &hotel); err != nil {
		log.Println("failed to save the cat hotel:", err)
		return
	}
}

Store supports any other formats via the handy registration system: register the format once and you'd be able to Load and Save files in it afterwards:

store.Register("ini", ini.Marshal, ini.Unmarshal)

err := store.Load("configuration.ini", &object)
// ...

Documentation

Overview

Package store is a dead simple configuration manager for Go applications.

Index

• func Init(application string)
• func Load(path string, v any) error
• func LoadWith(path string, v any, um UnmarshalFunc) error
• func Register(extension string, m MarshalFunc, um UnmarshalFunc)
• func Save(path string, v any) error
• func SaveWith(path string, v any, m MarshalFunc) error
• func SetApplicationName(handle string)
• type MarshalFunc
• type UnmarshalFunc

Functions

func Init

func Init(application string)

Init sets up a unique application name that will be used for name of the configuration directory on the file system. By default, Store puts all the config data to to $XDG_CONFIG_HOME or $HOME on Linux systems and to %APPDATA% on Windows.

Beware: Store will panic on any sensitive calls unless you run Init inb4.

func Load

func Load(path string, v any) error

Load reads a configuration from `path` and puts it into `v` pointer. Store supports either JSON, TOML or YAML and will deduce the file format out of the filename (.json/.toml/.yaml). For other formats of custom extensions please you LoadWith.

Path is a full filename, including the file extension, e.g. "foobar.json". If `path` doesn't exist, Load will create one and emptify `v` pointer by replacing it with a newly created object, derived from type of `v`.

Load panics on unknown configuration formats.

func LoadWith

func LoadWith(path string, v any, um UnmarshalFunc) error

LoadWith loads the configuration using any unmarshaler at all.

func Register

func Register(extension string, m MarshalFunc, um UnmarshalFunc)

Register is the way you register configuration formats, by mapping some file name extension to corresponding marshal and unmarshal functions. Once registered, the format given would be compatible with Load and Save.

func Save

func Save(path string, v any) error

Save puts a configuration from `v` pointer into a file `path`. Store supports either JSON, TOML or YAML and will deduce the file format out of the filename (.json/.toml/.yaml). For other formats of custom extensions please you LoadWith.

Path is a full filename, including the file extension, e.g. "foobar.json".

Save panics on unknown configuration formats.

func SaveWith

func SaveWith(path string, v any, m MarshalFunc) error

SaveWith saves the configuration using any marshaler at all.

func SetApplicationName

func SetApplicationName(handle string)

SetApplicationName is DEPRECATED (use Init instead).

Types

type MarshalFunc

type MarshalFunc func(v any) ([]byte, error)

MarshalFunc is any marshaler.

type UnmarshalFunc

type UnmarshalFunc func(data []byte, v any) error

UnmarshalFunc is any unmarshaler.