config

package
v3.5.6 Latest Latest
Warning

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

Go to latest
Published: Apr 13, 2023 License: Apache-2.0 Imports: 23 Imported by: 2

Documentation

Overview

Package config is a go config management implement. support YAML,TOML,JSON,INI,HCL format.

Source code and other details for the project are available at GitHub:

https://github.com/gookit/config

JSON format content example:

{
	"name": "app",
	"debug": false,
	"baseKey": "value",
	"age": 123,
	"envKey": "${SHELL}",
	"envKey1": "${NotExist|defValue}",
	"map1": {
		"key": "val",
		"key1": "val1",
		"key2": "val2"
	},
	"arr1": [
		"val",
		"val1",
		"val2"
	],
	"lang": {
		"dir": "res/lang",
		"defLang": "en",
		"allowed": {
			"en": "val",
			"zh-CN": "val2"
		}
	}
}

Usage please see example(more example please see examples folder in the lib):

Example
// WithOptions(ParseEnv)

// add Decoder and Encoder
// use yaml github.com/gookit/config/yaml
// AddDriver(Yaml, yaml.Driver)
// use toml github.com/gookit/config/toml
// AddDriver(Toml, toml.Driver)
// use toml github.com/gookit/config/hcl
// AddDriver(Hcl, hcl.Driver)
// Or
// config.DecoderEncoder(config.JSON, yaml.Decoder, yaml.Encoder)

err := LoadFiles("testdata/json_base.json")
if err != nil {
	panic(err)
}

// fmt.Printf("config data: \n %#v\n", Data())

err = LoadFiles("testdata/json_other.json")
// LoadFiles("testdata/json_base.json", "testdata/json_other.json")
if err != nil {
	panic(err)
}

// load from string
err = LoadSources(JSON, []byte(jsonStr))
if err != nil {
	panic(err)
}

// fmt.Printf("config data: \n %#v\n", Data())
fmt.Print("get config example:\n")

name := String("name")
fmt.Printf("- get string\n val: %v\n", name)

arr1 := Strings("arr1")
fmt.Printf("- get array\n val: %#v\n", arr1)

val0 := String("arr1.0")
fmt.Printf("- get sub-value by path 'arr.index'\n val: %#v\n", val0)

map1 := StringMap("map1")
fmt.Printf("- get map\n val: %#v\n", map1)

val0 = String("map1.key")
fmt.Printf("- get sub-value by path 'map.key'\n val: %#v\n", val0)

// can parse env name(ParseEnv: true)
fmt.Printf("get env 'envKey' val: %s\n", String("envKey", ""))
fmt.Printf("get env 'envKey1' val: %s\n", String("envKey1", ""))

// set value
_ = Set("name", "new name")
name = String("name")
fmt.Printf("- set string\n val: %v\n", name)

// if you want export config data
// buf := new(bytes.Buffer)
// _, err = config.DumpTo(buf, config.JSON)
// if err != nil {
// 	panic(err)
// }
// fmt.Printf("export config:\n%s", buf.String())

// Out:
// get config example:
// - get string
//  val: app
// - get array
//  val: []string{"val", "val1", "val2"}
// - get sub-value by path 'arr.index'
//  val: "val"
// - get map
//  val: map[string]string{"key":"val", "key1":"val1", "key2":"val2"}
// - get sub-value by path 'map.key'
//  val: "val"
// get env 'envKey' val: /bin/zsh
// get env 'envKey1' val: defValue
// - set string
//  val: new name
Output:

Example (ExportConfig)
// Notice: before dump please set driver encoder
// SetEncoder(Yaml, yaml.Encoder)

ClearAll()
// load from string
err := LoadStrings(JSON, `{
"name": "app",
"age": 34
}`)
if err != nil {
	panic(err)
}

buf := new(bytes.Buffer)
_, err = DumpTo(buf, JSON)
if err != nil {
	panic(err)
}

fmt.Printf("%s", buf.String())
Output:

{"age":34,"name":"app"}

Index

Examples

Constants

View Source
const (
	Ini  = "ini"
	Hcl  = "hcl"
	Yml  = "yml"
	JSON = "json"
	Yaml = "yaml"
	Toml = "toml"
)

Ini There are supported config format

View Source
const (
	OnSetValue  = "set.value"
	OnSetData   = "set.data"
	OnLoadData  = "load.data"
	OnCleanData = "clean.data"
)

OnSetValue there are some event names for config data changed.

Variables

View Source
var (
	// JSONAllowComments support write comments on json file.
	JSONAllowComments = true

	// JSONMarshalIndent if not empty, will use json.MarshalIndent for encode data.
	JSONMarshalIndent string
)

JSONAllowComments ...

View Source
var JSONDriver = &jsonDriver{
	StdDriver: StdDriver{
		name:    JSON,
		decoder: JSONDecoder,
		encoder: JSONEncoder,
	},
}

JSONDriver instance fot json

Functions

func AddDriver

func AddDriver(driver Driver)

AddDriver set a decoder and encoder driver for a format.

func BindStruct

func BindStruct(key string, dst any) error

BindStruct alias method of the 'Structure'

func Bool

func Bool(key string, defVal ...bool) bool

Bool get a bool value, if not found return default value

func ClearAll

func ClearAll()

ClearAll data and caches

func Data

func Data() map[string]any

Data return all config data

func Delimiter

func Delimiter(sep byte) func(*Options)

Delimiter set delimiter char

func DumpTo

func DumpTo(out io.Writer, format string) (int64, error)

DumpTo a writer and use format

func EnableCache

func EnableCache(opts *Options)

EnableCache set readonly

func Exists

func Exists(key string, findByPath ...bool) bool

Exists key exists check

func Float

func Float(key string, defVal ...float64) float64

Float get a float64 value, if not found return default value

func Get

func Get(key string, findByPath ...bool) any

Get config value by key string, support get sub-value by key path(eg. 'map.key'), ok is true, find value from config ok is false, not found or error

func GetEnv

func GetEnv(name string, defVal ...string) (val string)

GetEnv get os ENV value by name

func GetValue

func GetValue(key string, findByPath ...bool) (any, bool)

GetValue get value by given key string.

func Getenv

func Getenv(name string, defVal ...string) (val string)

Getenv get os ENV value by name. like os.Getenv, but support default value Notice: - Key is not case-sensitive when getting

func Int

func Int(key string, defVal ...int) int

Int get a int by key

func Int64

func Int64(key string, defVal ...int64) int64

Int64 get a int value, if not found return default value

func IntMap

func IntMap(key string) map[string]int

IntMap get config data as a map[string]int

func Ints

func Ints(key string) []int

Ints get config data as a int slice/array

func LoadData

func LoadData(dataSource ...any) error

LoadData load one or multi data

func LoadDir

func LoadDir(dir, suffix string) error

LoadDir ...

func LoadExists

func LoadExists(sourceFiles ...string) error

LoadExists load one or multi files, will ignore not exist

func LoadExistsByFormat

func LoadExistsByFormat(format string, sourceFiles ...string) error

LoadExistsByFormat load one or multi files by give format

func LoadFiles

func LoadFiles(sourceFiles ...string) error

LoadFiles load one or multi files

func LoadFilesByFormat

func LoadFilesByFormat(format string, sourceFiles ...string) error

LoadFilesByFormat load one or multi files by give format

func LoadFlags

func LoadFlags(keys []string) error

LoadFlags load data from cli flags

func LoadOSEnv

func LoadOSEnv(keys []string, keyToLower bool)

LoadOSEnv load data from OS ENV

func LoadRemote

func LoadRemote(format, url string) error

LoadRemote load config data from remote URL.

func LoadSources

func LoadSources(format string, src []byte, more ...[]byte) error

LoadSources load one or multi byte data

func LoadStrings

func LoadStrings(format string, str string, more ...string) error

LoadStrings load one or multi string

func MapOnExists

func MapOnExists(key string, dst any) error

MapOnExists mapping data to the dst structure only on key exists.

func MapStruct

func MapStruct(key string, dst any) error

MapStruct alias method of the 'Structure'

Usage:

dbInfo := &Db{}
config.MapStruct("db", dbInfo)

func OnConfigChange

func OnConfigChange(run func(in fsnotify.Event))

OnConfigChange ...

func ParseEnv

func ParseEnv(opts *Options)

ParseEnv set parse env

func ParseEnvVarStringHookFunc

func ParseEnvVarStringHookFunc() mapstructure.DecodeHookFunc

ParseEnvVarStringHookFunc returns a DecodeHookFunc that parse ENV var

func Readonly

func Readonly(opts *Options)

Readonly set readonly

func Set

func Set(key string, val any, setByPath ...bool) error

Set val by key

func SetData

func SetData(data map[string]any)

SetData for override the Config.Data

func SetDecoder deprecated

func SetDecoder(format string, decoder Decoder)

SetDecoder add/set a format decoder

Deprecated: please use driver instead

func SetEncoder deprecated

func SetEncoder(format string, encoder Encoder)

SetEncoder set a encoder for the format

Deprecated: please use driver instead

func String

func String(key string, defVal ...string) string

String get a string by key

func StringMap

func StringMap(key string) map[string]string

StringMap get config data as a map[string]string

func Strings

func Strings(key string) []string

Strings get strings by key

func Uint

func Uint(key string, defVal ...uint) uint

Uint get a uint value, if not found return default value

func WatchConfig

func WatchConfig(suffix string)

WatchConfig ...

func WithHookFunc

func WithHookFunc(fn HookFunc) func(*Options)

WithHookFunc set hook func

func WithOptions

func WithOptions(opts ...func(*Options))

WithOptions with options

func WriteTo

func WriteTo(out io.Writer) (int64, error)

WriteTo a writer

Types

type Config

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

Config structure definition

func Default

func Default() *Config

Default get the default instance

func New

func New(name string) *Config

New config instance

func NewEmpty

func NewEmpty(name string) *Config

NewEmpty config instance

func NewWith

func NewWith(name string, fn func(c *Config)) *Config

NewWith create config instance, and you can call some init func

func NewWithOptions

func NewWithOptions(name string, opts ...func(*Options)) *Config

NewWithOptions config instance

func (*Config) AddDriver

func (c *Config) AddDriver(driver Driver)

AddDriver set a decoder and encoder driver for a format.

func (*Config) BindStruct

func (c *Config) BindStruct(key string, dst any) error

BindStruct alias method of the 'Structure'

func (*Config) Bool

func (c *Config) Bool(key string, defVal ...bool) (value bool)

Bool looks up a value for a key in this section and attempts to parse that value as a boolean, along with a boolean result similar to a map lookup. of following(case insensitive):

  • true
  • yes
  • false
  • no
  • 1
  • 0

The `ok` boolean will be false in the event that the value could not be parsed as a bool

func (*Config) ClearAll

func (c *Config) ClearAll()

ClearAll data and caches

func (*Config) ClearCaches

func (c *Config) ClearCaches()

ClearCaches clear caches

func (*Config) ClearData

func (c *Config) ClearData()

ClearData clear data

func (*Config) ConfigDir

func (c *Config) ConfigDir() []string

ConfigDir ...

func (*Config) Data

func (c *Config) Data() map[string]any

Data get all config data

func (*Config) DelDriver

func (c *Config) DelDriver(format string)

DelDriver delete driver of the format

func (*Config) DriverNames

func (c *Config) DriverNames() []string

DriverNames get loaded driver names

func (*Config) DumpTo

func (c *Config) DumpTo(out io.Writer, format string) (n int64, err error)

DumpTo use the format(json,yaml,toml) dump config data to a writer

func (*Config) Error

func (c *Config) Error() error

Error get last error, will clear after read.

func (*Config) Exists

func (c *Config) Exists(key string, findByPath ...bool) (ok bool)

Exists key exists check

func (*Config) Float

func (c *Config) Float(key string, defVal ...float64) (value float64)

Float get a float64 by key

func (*Config) Get

func (c *Config) Get(key string, findByPath ...bool) any

Get config value by key

func (*Config) GetValue

func (c *Config) GetValue(key string, findByPath ...bool) (value any, ok bool)

GetValue get value by given key string.

func (*Config) HasDecoder

func (c *Config) HasDecoder(format string) bool

HasDecoder has decoder

func (*Config) HasEncoder

func (c *Config) HasEncoder(format string) bool

HasEncoder has encoder

func (*Config) Int

func (c *Config) Int(key string, defVal ...int) (value int)

Int get a int value, if not found return default value

func (*Config) Int64

func (c *Config) Int64(key string, defVal ...int64) (value int64)

Int64 get a int value, if not found return default value

func (*Config) IntMap

func (c *Config) IntMap(key string) (mp map[string]int)

IntMap get config data as a map[string]int

func (*Config) Ints

func (c *Config) Ints(key string) (arr []int)

Ints get config data as a int slice/array

func (*Config) IsEmpty

func (c *Config) IsEmpty() bool

IsEmpty of the config

func (*Config) LoadData

func (c *Config) LoadData(dataSources ...any) (err error)

LoadData load data from map OR struct

The dataSources can be:

  • map[string]any

func (*Config) LoadDir

func (c *Config) LoadDir(dir, suffix string) (err error)

LoadDir loadDir

func (*Config) LoadExists

func (c *Config) LoadExists(sourceFiles ...string) (err error)

LoadExists load and parse config files, but will ignore not exists file.

func (*Config) LoadExistsByFormat

func (c *Config) LoadExistsByFormat(format string, sourceFiles ...string) (err error)

LoadExistsByFormat load one or multi files by give format

func (*Config) LoadFiles

func (c *Config) LoadFiles(sourceFiles ...string) (err error)

LoadFiles load and parse config files

func (*Config) LoadFilesByFormat

func (c *Config) LoadFilesByFormat(format string, sourceFiles ...string) (err error)

LoadFilesByFormat load one or multi files by give format

func (*Config) LoadFlags

func (c *Config) LoadFlags(keys []string) (err error)

LoadFlags parse command line arguments, based on provide keys. Usage:

// debug flag is bool type
c.LoadFlags([]string{"env", "debug:bool"})

func (*Config) LoadOSEnv

func (c *Config) LoadOSEnv(keys []string, keyToLower bool)

LoadOSEnv load data from os ENV

func (*Config) LoadRemote

func (c *Config) LoadRemote(format, url string) (err error)

LoadRemote load config data from remote URL.

Usage:

c.LoadRemote(config.JSON, "http://abc.com/api-config.json")

func (*Config) LoadSources

func (c *Config) LoadSources(format string, src []byte, more ...[]byte) (err error)

LoadSources load data from byte content.

Usage:

config.LoadSources(config.Yml, []byte(`
name: blog
arr:
	key: val

`))

func (*Config) LoadStrings

func (c *Config) LoadStrings(format string, str string, more ...string) (err error)

LoadStrings load data from source string content.

func (*Config) LoadedFiles

func (c *Config) LoadedFiles() []string

LoadedFiles get loaded files name

func (*Config) MapOnExists

func (c *Config) MapOnExists(key string, dst any) error

MapOnExists mapping data to the dst structure only on key exists.

func (*Config) MapStruct

func (c *Config) MapStruct(key string, dst any) error

MapStruct alias method of the 'Structure'

func (*Config) Name

func (c *Config) Name() string

Name get config name

func (*Config) OnConfigChange

func (c *Config) OnConfigChange(run func(in fsnotify.Event))

OnConfigChange ...

func (*Config) Options

func (c *Config) Options() *Options

Options get

func (*Config) Readonly

func (c *Config) Readonly()

Readonly disable set data to config.

Usage:

config.LoadFiles(a, b, c)
config.Readonly()

func (*Config) Set

func (c *Config) Set(key string, val any, setByPath ...bool) (err error)

Set a value by key string.

func (*Config) SetData

func (c *Config) SetData(data map[string]any)

SetData for override the Config.Data

func (*Config) SetDecoder deprecated

func (c *Config) SetDecoder(format string, decoder Decoder)

SetDecoder set decoder

Deprecated: please use driver instead

func (*Config) SetDecoders deprecated

func (c *Config) SetDecoders(decoders map[string]Decoder)

SetDecoders set decoders

Deprecated: please use driver instead

func (*Config) SetEncoder deprecated

func (c *Config) SetEncoder(format string, encoder Encoder)

SetEncoder set a encoder for the format

Deprecated: please use driver instead

func (*Config) SetEncoders deprecated

func (c *Config) SetEncoders(encoders map[string]Encoder)

SetEncoders set encoders

Deprecated: please use driver instead

func (*Config) String

func (c *Config) String(key string, defVal ...string) string

String get a string by key, if not found return default value

func (*Config) StringMap

func (c *Config) StringMap(key string) (mp map[string]string)

StringMap get config data as a map[string]string

func (*Config) Strings

func (c *Config) Strings(key string) (arr []string)

Strings get config data as a string slice/array

func (*Config) Structure

func (c *Config) Structure(key string, dst any) error

Structure get config data and binding to the dst structure.

Usage:

dbInfo := Db{}
config.Structure("db", &dbInfo)

func (*Config) ToJSON

func (c *Config) ToJSON() string

ToJSON string

func (*Config) Uint

func (c *Config) Uint(key string, defVal ...uint) (value uint)

Uint get a int value, if not found return default value

func (*Config) WatchConfig

func (c *Config) WatchConfig(suffix string)

WatchConfig loadDir

func (*Config) With

func (c *Config) With(fn func(c *Config)) *Config

With apply some options

func (*Config) WithOptions

func (c *Config) WithOptions(opts ...func(*Options)) *Config

WithOptions apply some options

func (*Config) WriteTo

func (c *Config) WriteTo(out io.Writer) (n int64, err error)

WriteTo Write out config data representing the current state to a writer.

type Decoder

type Decoder func(blob []byte, v any) (err error)

Decoder for decode yml,json,toml format content

var JSONDecoder Decoder = func(data []byte, v any) (err error) {
	if JSONAllowComments {
		str := jsonutil.StripComments(string(data))
		return json.Unmarshal([]byte(str), v)
	}

	return json.Unmarshal(data, v)
}

JSONDecoder for json decode

type Driver

type Driver interface {
	Name() string
	GetDecoder() Decoder
	GetEncoder() Encoder
}

Driver interface. TODO refactor: rename GetDecoder() to Decode(), rename GetEncoder() to Encode()

type Encoder

type Encoder func(v any) (out []byte, err error)

Encoder for decode yml,json,toml format content

var JSONEncoder Encoder = func(v any) (out []byte, err error) {
	if len(JSONMarshalIndent) > 0 {
		return json.MarshalIndent(v, "", JSONMarshalIndent)
	}
	return json.Marshal(v)
}

JSONEncoder for json encode

type HookFunc

type HookFunc func(event string, c *Config)

HookFunc on config data changed.

type Options

type Options struct {
	// parse env value. like: "${EnvName}" "${EnvName|default}"
	ParseEnv bool
	// config is readonly
	Readonly bool
	// enable config data cache
	EnableCache bool
	// parse key, allow find value by key path. eg: 'key.sub' will find `map[key]sub`
	ParseKey bool
	// tag name for binding data to struct
	// Deprecated: please set tag name by DecoderConfig
	TagName string
	// the delimiter char for split key path, if `FindByPath=true`. default is '.'
	Delimiter byte
	// default write format
	DumpFormat string
	// default input format
	ReadFormat string
	// DecoderConfig setting for binding data to struct
	DecoderConfig *mapstructure.DecoderConfig
	// HookFunc on data changed.
	HookFunc HookFunc
}

Options config options

func GetOptions

func GetOptions() *Options

GetOptions get options

type StdDriver

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

StdDriver struct

func NewDriver

func NewDriver(name string, dec Decoder, enc Encoder) *StdDriver

NewDriver new std driver instance.

func (*StdDriver) Decode

func (d *StdDriver) Decode(blob []byte, v any) (err error)

Decode of driver

func (*StdDriver) Encode

func (d *StdDriver) Encode(v any) ([]byte, error)

Encode of driver

func (*StdDriver) GetDecoder

func (d *StdDriver) GetDecoder() Decoder

GetDecoder of driver

func (*StdDriver) GetEncoder

func (d *StdDriver) GetEncoder() Encoder

GetEncoder of driver

func (*StdDriver) Name

func (d *StdDriver) Name() string

Name of driver

Directories

Path Synopsis
Package dotnev provide load .env data to os ENV
Package dotnev provide load .env data to os ENV
Package hcl is driver use HCL format content as config source
Package hcl is driver use HCL format content as config source
Package hclv2 is driver use HCL format content as config source
Package hclv2 is driver use HCL format content as config source
Package ini is driver use INI format content as config source
Package ini is driver use INI format content as config source
Package json use the https://github.com/json-iterator/go for parse json
Package json use the https://github.com/json-iterator/go for parse json
Package json5 use the https://github.com/yosuke-furukawa/json5 for parse json5
Package json5 use the https://github.com/yosuke-furukawa/json5 for parse json5
Package other is an example of a custom driver
Package other is an example of a custom driver
Package toml is driver use TOML format content as config source
Package toml is driver use TOML format content as config source
Package yaml is a driver use YAML format content as config source
Package yaml is a driver use YAML format content as config source

Jump to

Keyboard shortcuts

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