README

Build Status GoDoc reference Support me on Patreon Buy me a Coffee Support me on LiberaPay

Snuffler

Snuffler will snuffle through all of the paths and globs you provide to look for config files (YAML, TOML, and JSON, for the moment), and use those to populate the config object you provide. It will clobber existing keys, but that's often what you want when generating user specific config which has the ability to override global config. Simply provide the paths/glob where config might live and it will root through them in order for config files.

For example:

package main
import (
	"path/filepath"

	homedir "github.com/mitchellh/go-homedir"
	"github.com/makyo/snuffler"
)

func main() {
	// Get the user's home directory.
	home, err := homedir.Dir()
	if err != nil {
		panic(err)
	}

	// Somewhere else, you've created a YAML/TOML/JSON ready config struct...
	var cfg myConfig

	// Build a new snuffler with a pointer to your config object.
	s := snuffler.New(&cfg)

	// You can add a file by its absolute path. If it does not exist, you'll
	// get an error. Probably a sign that your app wasn't installed
	// correctly or the user can't read the file.
	if err := s.AddFile("/etc/myApp/master.yaml"); err != nil {
		panic(err)
	}

	// You can add a glob for a directory or series of files. It will just
	// grab all files, so be specific with your glob! An error will occur
	// only if your glob is malformed.
	if err := s.AddGlob("/etc/myApp/conf.d/*.yaml"); err != nil {
		panic(err)
	}
	if err := s.AddGlob(filepath.Join(home, ".config", "myApp", "*.[ty][oa]ml"); err != nil {
		panic(err)
	}

	// If a file might not exist, you can easily add it without worrying
	// about an error (and make it obvious to the readers of the code that
	// you're okay with that) by using MaybeAddFile.
	s.MaybeAddFile(filepath.Join(home, ".myApprc")

	// Snuffle will read in all of the files in the order specified above
	// and unmarshal them into the cfg object provided above.
	s.Snuffle()

	// If you need to snuffle config into a new object other than the one
	// you provided during construction, you can use Snorfle.
	var secondCfg myConfig
	s.Snorfle(&secondConfig)
}

Documentation

Overview

    Package snuffler builds config objects from scattered config files.

    Snuffler will snuffle through all of the paths and globs you provide to look for config files (YAML, TOML, and JSON for the moment), and use those to populate the config object you provide. It will clobber existing keys, but that's often what you want when generating user specific config which has the ability to override global config. Simply provide the paths/glob where config might live and it will root through them in order for config files.

    For example:

    package main
    
    import (
    	"path/filepath"
    
    	homedir "github.com/mitchellh/go-homedir"
    	"github.com/makyo/snuffler"
    )
    
    func main() {
    	// Get the user's home directory.
    	home, err := homedir.Dir()
    	if err != nil {
    		panic(err)
    	}
    
    	// Somewhere else, you've created a YAML/TOML ready config struct...
    	var cfg myConfig
    
    	// Build a new snuffler with a pointer to your config object.
    	s := snuffler.New(&cfg)
    
    	// You can add a file by its absolute path. If it does not exist, you'll
    	// get an error. Probably a sign that your app wasn't installed
    	// correctly or the user can't read the file.
    	if err := s.AddFile("/etc/myApp/master.yaml"); err != nil {
    		panic(err)
    	}
    
    	// You can add a glob for a directory or series of files. It will just
    	// grab all files, so be specific with your glob! An error will occur
    	// only if your glob is malformed.
    	if err := s.AddGlob("/etc/myApp/conf.d/*.yaml"); err != nil {
    		panic(err)
    	}
    	if err := s.AddGlob(filepath.Join(home, ".config", "myApp", "*.[ty][oa]ml"); err != nil {
    		panic(err)
    	}
    
    	// If a file might not exist, you can easily add it without worrying
    	// about an error (and make it obvious to the readers of the code that
    	// you're okay with that) by using MaybeAddFile.
    	s.MaybeAddFile(filepath.Join(home, ".myApprc")
    
    	// Snuffle will read in all of the files in the order specified above
    	// and unmarshal them into the cfg object provided above.
    	s.Snuffle()
    
    	// If you need to snuffle config into a new object other than the one
    	// you provided during construction, you can use Snorfle.
    	var secondCfg myConfig
    	s.Snorfle(&secondConfig)
    }
    

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Snuffler

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

      Snuffler is the primary object holding all of the bits required to snuffle through config files.

      func New

      func New(c interface{}) *Snuffler

        New creates a new snuffler object with the given interface. You can then add files to the resulting snuffler and, when run, it will load the config from each of them into the interface.

        func (*Snuffler) AddFile

        func (s *Snuffler) AddFile(p string) error

          AddFile accepts a string containing a filename and adds it to the list of files that the snuffler should load. This file must exist. If you want to add a file that may or may not exist, use MaybeAddFile.

          func (*Snuffler) AddGlob

          func (s *Snuffler) AddGlob(g string)

            AddGlob accepts a string containing a Glob[0] to search for config files.

            [0]: https://golang.org/pkg/path/filepath/#Glob

            func (*Snuffler) GetFileMatchList

            func (s *Snuffler) GetFileMatchList() []string

              GetFileMatchList returns the list of file names matched by the list of patterns the snuffler knows about.

              func (*Snuffler) MaybeAddFile

              func (s *Snuffler) MaybeAddFile(p string)

                MaybeAddFile accepts a string containing a filename and adds it to the list of files that the snuffler should load. This file need not exist. If you want to add a file that must exist, use AddFile.

                func (*Snuffler) Snorfle

                func (s *Snuffler) Snorfle(conf interface{}) error

                  Snorfle performs all the same tasks as Snuffle, but does not use the stored config object reference, instead populating the one that is provided as an argument.

                  func (*Snuffler) Snuffle

                  func (s *Snuffler) Snuffle() error

                    Snuffle performs the noble task of snuffling through all of the specified config files and paths to populate the provided config object. Files are loaded in the order they were received, and values are overwritten if subsequent files specify them.