config

package module
Version: v0.0.0-...-364964f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 28, 2019 License: MIT Imports: 9 Imported by: 239

README

Config wercker status GoDoc

Package config provides convenient access methods to configuration stored as JSON or YAML.

This is a fork of the original version. This version extends the functionality of the original without losing compatibility. Major features added:

Example and more information you can find here.

Documentation

Overview

Package config provides convenient access methods to configuration stored as JSON or YAML.

Let's start with a simple YAML file config.yml:

development:
  database:
    host: localhost
  users:
    - name: calvin
      password: yukon
    - name: hobbes
      password: tuna
production:
  database:
    host: 192.168.1.1

We can parse it using ParseYaml(), which will return a *Config instance on success:

    file, err := ioutil.ReadFile("config.yml")
    if err != nil {
		panic(err)
    }
    yamlString := string(file)

    cfg, err := config.ParseYaml(yamlString)

An equivalent JSON configuration could be built using ParseJson():

cfg, err := config.ParseJson(jsonString)

From now, we can retrieve configuration values using a path in dotted notation:

// "localhost"
host, err := cfg.String("development.database.host")

// or...

// "192.168.1.1"
host, err := cfg.String("production.database.host")

Besides String(), other types can be fetched directly: Bool(), Float64(), Int(), Map() and List(). All these methods will return an error if the path doesn't exist, or the value doesn't match or can't be converted to the requested type.

A nested configuration can be fetched using Get(). Here we get a new *Config instance with a subset of the configuration:

cfg, err := cfg.Get("development")

Then the inner values are fetched relatively to the subset:

// "localhost"
host, err := cfg.String("database.host")

For lists, the dotted path must use an index to refer to a specific value. To retrieve the information from a user stored in the configuration above:

// map[string]interface{}{ ... }
user1, err := cfg.Map("development.users.0")
// map[string]interface{}{ ... }
user2, err := cfg.Map("development.users.1")

// or...

// "calvin"
name1, err := cfg.String("development.users.0.name")
// "hobbes"
name2, err := cfg.String("development.users.1.name")

JSON or YAML strings can be created calling the appropriate Render*() functions. Here's how we render a configuration like the one used in these examples:

cfg := map[string]interface{}{
    "development": map[string]interface{}{
        "database": map[string]interface{}{
            "host": "localhost",
        },
        "users": []interface{}{
            map[string]interface{}{
                "name":     "calvin",
                "password": "yukon",
            },
            map[string]interface{}{
                "name":     "hobbes",
                "password": "tuna",
            },
        },
    },
    "production": map[string]interface{}{
        "database": map[string]interface{}{
            "host": "192.168.1.1",
        },
    },
}

json, err := config.RenderJson(cfg)

// or...

yaml, err := config.RenderYaml(cfg)

This results in a configuration string to be stored in a file or database.

For more more convenience it can parse OS environment variables and command line arguments.

cfg, err := config.ParseYaml(yamlString)
cfg.Env()

// or

cfg.Flag()

We can also specify the order of parsing:

cfg.Env().Flag()

// or

cfg.Flag().Env()

In case of OS environment all existing at the moment of parsing keys will be scanned in OS environment, but in uppercase and the separator will be `_` instead of a `.`. If EnvPrefix() is used the given prefix will be used to lookup the environment variable, e.g PREFIX_FOO_BAR will set foo.bar. In case of flags separator will be `-`. In case of command line arguments possible to use regular dot notation syntax for all keys. For see existing keys we can run application with `-h`.

We can use unsafe method to get value:

// ""
cfg.UString("undefined.key")

// or with default value
unsafeValue := cfg.UString("undefined.key", "default value")

There is unsafe methods, like regular, but wuth prefix `U`.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Get

func Get(cfg interface{}, path string) (interface{}, error)

Get returns a child of the given value according to a dotted path.

func RenderJson

func RenderJson(cfg interface{}) (string, error)

RenderJson renders a JSON configuration.

func RenderYaml

func RenderYaml(cfg interface{}) (string, error)

RenderYaml renders a YAML configuration.

func Set

func Set(cfg interface{}, path string, value interface{}) error

Set returns an error, in case when it is not possible to establish the value obtained in accordance with given dotted path.

Types

type Config

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

Config represents a configuration with convenient access methods.

func Must

func Must(cfg *Config, err error) *Config

Must is a wrapper for parsing functions to be used during initialization. It panics on failure.

func ParseJson

func ParseJson(cfg string) (*Config, error)

ParseJson reads a JSON configuration from the given string.

func ParseJsonFile

func ParseJsonFile(filename string) (*Config, error)

ParseJsonFile reads a JSON configuration from the given filename.

func ParseYaml

func ParseYaml(cfg string) (*Config, error)

ParseYaml reads a YAML configuration from the given string.

func ParseYamlBytes

func ParseYamlBytes(cfg []byte) (*Config, error)

ParseYamlBytes reads a YAML configuration from the given []byte.

func ParseYamlFile

func ParseYamlFile(filename string) (*Config, error)

ParseYamlFile reads a YAML configuration from the given filename.

func (*Config) Args

func (cfg *Config) Args(args ...string) *Config

Args command line arguments, based on existing config keys.

func (*Config) Bool

func (cfg *Config) Bool(path string) (bool, error)

Bool returns a bool according to a dotted path.

func (*Config) Copy

func (c *Config) Copy(dottedPath ...string) (*Config, error)

Copy returns a deep copy with given path or without.

func (*Config) Env

func (cfg *Config) Env() *Config

Fetch data from system env, based on existing config keys.

func (*Config) EnvPrefix

func (cfg *Config) EnvPrefix(prefix string) *Config

Fetch data from system env using prefix, based on existing config keys.

func (*Config) Error

func (c *Config) Error() error

Error return last error

func (*Config) Extend

func (c *Config) Extend(cfg *Config) (*Config, error)

Extend returns extended copy of current config with applied values from the given config instance. Note that if you extend with different structure you will get an error. See: `.Set()` method for details.

func (*Config) Flag

func (cfg *Config) Flag() *Config

Parse command line arguments, based on existing config keys.

func (*Config) Float64

func (cfg *Config) Float64(path string) (float64, error)

Float64 returns a float64 according to a dotted path.

func (*Config) Get

func (cfg *Config) Get(path string) (*Config, error)

Get returns a nested config according to a dotted path.

func (*Config) Int

func (cfg *Config) Int(path string) (int, error)

Int returns an int according to a dotted path.

func (*Config) List

func (cfg *Config) List(path string) ([]interface{}, error)

List returns a []interface{} according to a dotted path.

func (*Config) Map

func (cfg *Config) Map(path string) (map[string]interface{}, error)

Map returns a map[string]interface{} according to a dotted path.

func (*Config) Set

func (cfg *Config) Set(path string, val interface{}) error

Set a nested config according to a dotted path.

func (*Config) String

func (cfg *Config) String(path string) (string, error)

String returns a string according to a dotted path.

func (*Config) UBool

func (c *Config) UBool(path string, defaults ...bool) bool

UBool returns a bool according to a dotted path or default value or false.

func (*Config) UFloat64

func (c *Config) UFloat64(path string, defaults ...float64) float64

UFloat64 returns a float64 according to a dotted path or default value or 0.

func (*Config) UInt

func (c *Config) UInt(path string, defaults ...int) int

UInt returns an int according to a dotted path or default value or 0.

func (*Config) UList

func (c *Config) UList(path string, defaults ...[]interface{}) []interface{}

UList returns a []interface{} according to a dotted path or defaults or []interface{}.

func (*Config) UMap

func (c *Config) UMap(path string, defaults ...map[string]interface{}) map[string]interface{}

UMap returns a map[string]interface{} according to a dotted path or default or map[string]interface{}.

func (*Config) UString

func (c *Config) UString(path string, defaults ...string) string

UString returns a string according to a dotted path or default or "".

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL