globalconf

README

globalconf

Effortlessly persist/retrieve flags of your Golang programs. If you need global configuration instead of requiring user always to set command line flags, you are looking at the right package.

Usage

import "github.com/rakyll/globalconf"

Loading a config file

By default, globalconf provides you a config file under ~/.config/<yourappname>/config.ini. If you don't prefer the default location you can load from a specified path as well.

globalconf.New("appname") // loads from ~/.config/<appname>/config.ini
globalconf.NewWithFilename("/path/to/config/file")

Parsing flag values

globalconf populates flags with data in the config file if they are not already set.

var (
	flagName    = flag.String("name", "", "Name of the person.")
	flagAddress = flag.String("addr", "", "Address of the person.")
)

Assume the configuration file to be loaded contains the following lines.

name = Burcu
addr = Brandschenkestrasse 110, 8002

And your program is being started, $ myapp -name=Jane

conf, err := globalconf.New("myapp")
conf.ParseAll()

*flagName is going to be equal to Jane, whereas *flagAddress is Brandschenkestrasse 110, 8002, what is provided in the configuration file.

Custom flag sets

Custom flagsets are supported, but required registration before parse is done. Command line flags are automatically registered.

globalconf.Register("termopts", termOptsFlagSet)
conf.ParseAll() // parses command line and all registered flag sets

Custom flag set values should be provided in their own segment. Getting back to the sample ini config file, termopts values will have their own segment.

name = Burcu
addr = Brandschenkestrasse 110, 8002

[termopts]
color = true
background = ff0000

Environment variables

If globalconf.EnvPrefix is not an empty string, environment variables will take precedence over values in the configuration file. Command line flags, however, will override the environment variables.

// If global.EnvPrefix is not "", variables will be read from the environment.

globalconf.EnvPrefix = "MYAPP_"
conf, err := globalconf.NewWithFilename("/path/to/config", "APPCONF_")
conf.ParseAll()

With environment variables: APPCONF_NAME = Burcu

and configuration: name = Jane addr = Brandschenkestrasse 110, 8002

name will be set to "burcu" and addr will be set to "Brandschenkestrasse 110, 8002".

Modifying stored flags

Modifications are persisted as long as you set a new flag.

f := &flag.Flag{Name: "name", Value: val}
conf.Set("", f) // if you are modifying a command line flag
	
f := &flag.Flag{Name: "color", Value: val}
conf.Set("termopts", color) // if you are modifying a custom flag set flag

Deleting stored flags

Deletions are persisted as long as you delete a flag's value.

conf.Delete("", "name") // removes command line flag "name"s value from config
conf.Delete("termopts", "color") // removes "color"s value from the custom flag set

License

Copyright 2014 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Index

• Variables
• func Register(flagSetName string, set *flag.FlagSet)
• type GlobalConf
  • func New(appName string) (g *GlobalConf, err error)
  • func NewWithFilename(filename string) (*GlobalConf, error)
  • func NewWithOptions(opts Options) (g *GlobalConf, err error)
  • func (g *GlobalConf) Delete(flagSetName, flagName string) error
  • func (g *GlobalConf) Parse()
  • func (g *GlobalConf) ParseAll()
  • func (g *GlobalConf) ParseSet(flagSetName string, set *flag.FlagSet)
  • func (g *GlobalConf) Set(flagSetName string, f *flag.Flag) error
• type Options

Variables

var EnvPrefix string = ""

If not empty, environment variables will override the config. Example:

globalconf.EnvPrefix = "MYAPP_"

MYAPP_VAR=val will override var = otherval in config file.

Functions

func Register

func Register(flagSetName string, set *flag.FlagSet)

Registers a flag set to be parsed. Register all flag sets before calling this function. flag.CommandLine is automatically registered.

Types

type GlobalConf

type GlobalConf struct {
	Filename string
	// contains filtered or unexported fields
}

Represents a GlobalConf context.

func New

func New(appName string) (g *GlobalConf, err error)

Opens/creates a config file for the specified appName. The path to config file is ~/.config/appName/config.ini.

func NewWithFilename

func NewWithFilename(filename string) (*GlobalConf, error)

Opens and loads contents of a config file whose filename is provided as the first argument.

func NewWithOptions

func NewWithOptions(opts Options) (g *GlobalConf, err error)

NewWithOptions creates a GlobalConf from the provided Options. The caller is responsible for creating any referenced config files.

func (*GlobalConf) Delete

func (g *GlobalConf) Delete(flagSetName, flagName string) error

Deletes a flag from config file and persists the changes to the disk.

func (*GlobalConf) Parse

func (g *GlobalConf) Parse()

Parses all the registered flag sets, including the command line set and sets values from the config file if they are not already set.

func (*GlobalConf) ParseAll

func (g *GlobalConf) ParseAll()

Parses command line flags and then, all of the registered flag sets with the values provided in the config file.

func (*GlobalConf) ParseSet

func (g *GlobalConf) ParseSet(flagSetName string, set *flag.FlagSet)

Parses the config file for the provided flag set. If the flags are already set, values are overwritten by the values in the config file. Defaults are not set if the flag is not in the file.

func (*GlobalConf) Set

func (g *GlobalConf) Set(flagSetName string, f *flag.Flag) error

Sets a flag's value and persists the changes to the disk.

type Options

type Options struct {
	ConfigFile string
	EnvPrefix  string
}