README
¶
Configuration Package
This package provides a configuration set and settings to form a composite configuration tree.
Examples
Examples are provided in the documentation, more will be added in the future.
Stability
1.0.0 will be contain a stable API.
Documentation
¶
Index ¶
- Variables
- func Dump(w io.Writer) error
- func NewContext(ctx context.Context, set *Set) context.Context
- func Range(fn func(string, *Setting) bool)
- func Update(name, value string) (bool, error)
- type Equality
- type Marshaler
- type Notifier
- type NotifyFunc
- type NotifyHandle
- type Set
- func (s *Set) Bind(value interface{}) *Set
- func (s *Set) Dump(w io.Writer) error
- func (s *Set) Get(name string) *Setting
- func (s *Set) Name() string
- func (s *Set) Notify(n Notifier) *NotifyHandle
- func (s *Set) Parent() *Set
- func (s *Set) Path() string
- func (s *Set) Range(fn func(string, *Setting) bool)
- func (s *Set) Root() *Set
- func (s *Set) Setting(name string, value Value, description string) *Setting
- func (s *Set) Subset(name string) *Set
- func (s *Set) Update(name, value string) (bool, error)
- type Setting
- func (s *Setting) Equals(v string) bool
- func (s *Setting) Flag(arg string, fs *flag.FlagSet)
- func (s *Setting) IsBoolFlag() bool
- func (s *Setting) IsDefault() bool
- func (s *Setting) Notify(n Notifier) *NotifyHandle
- func (s *Setting) Set(v string) error
- func (s *Setting) String() string
- func (s *Setting) Type() string
- type Unmarshaler
- type Value
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Default = &Set{}
Default configuration Set
Functions ¶
func NewContext ¶
NewContext creates a child context of the supplied context embedding the *config.Set. This *config.Set can be retrieved with the FromContext
Types ¶
type Equality ¶
Equality is the interface implemented by type to validate equality of the supplied string to themselves.
type Marshaler ¶
type Marshaler interface {
MarshalSetting() string
}
Marshaler is the interface implemented by types that can marshal themselves into a setting string.
type Notifier ¶
type Notifier interface {
// Notify defines a function that is called when s.Set is called with a different value other than the current
Notify(s *Setting)
}
Notifier for configuration Setting changes
type NotifyFunc ¶
type NotifyFunc func(s *Setting)
NotifyFunc defines a function that is called when s.Set is called with a different value other than the current
type NotifyHandle ¶
type NotifyHandle struct {
// contains filtered or unexported fields
}
NotifyHandle is used to stop notifications of Setting changes
func Notify ¶
func Notify(n Notifier) *NotifyHandle
Notify when any of the settings in this set, or any child set is added or changed
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set defines a composite collection of configuration
func Bind ¶
func Bind(value interface{}) *Set
Bind the Pointer to a Struct. This will take all of the fields and attempt to create settings from them. Any child structs will be set in a subset of the parent struct by name. All fields will be passed into the Set.Setting() function as pointers so that the Set.Set() function can write to the underlying value.
Fields names can be overwritten with the `setting` field tag.
Descriptions on settings can be set with teh `description` field tag.
You can mask the Stringer of the setting (set it to output *****) by setting the field tag `mask:"true"`. This is really important to do to passwords/tokens/etc... to make sure they don't end up in logs.
If a `flag` field tag exists, the `setting.Flag()` function will be called with the value and `flag.CommandLine“
Example ¶
package main
import (
"flag"
"os"
"github.com/portcullis/config"
)
func main() {
// create just a simple struct with some descriptive flags for the configuration
myConfig := struct {
Name string `description:"This is a name" flag:"name"`
Password string `description:"Super secret password" mask:"true"`
HTTP struct {
Addr string `name:"Address" description:"Address to listen" flag:"address"`
Port int16 `description:"What port to listen" flag:"port"`
}
Enabled bool `description:"Enable something"`
}{
Name: "Default User",
}
// set values like normal
myConfig.HTTP.Addr = "0.0.0.0"
myConfig.HTTP.Port = 8080
// bind the configuration under MyApplication to the pointer of the config
config.Subset("MyApplication").Bind(&myConfig)
// parsing the flags, would normally be replaced with os.Args[1:]
flag.CommandLine.Parse([]string{"-name=flagged", "-address=127.0.0.1", "-port=8090"})
// manually update a setting by full path (the value being set can come from os.GetEnv())
config.Update("MyApplication.Enabled", "true")
// dump the output
config.Dump(os.Stdout)
}
Output: Path Type Value Default Value Description MyApplication.Enabled *bool "true" "false" Enable something MyApplication.HTTP.Addr *string "127.0.0.1" "0.0.0.0" Address to listen MyApplication.HTTP.Port *int16 "8090" "8080" What port to listen MyApplication.Name *string "flagged" "Default User" This is a name MyApplication.Password *string "*****" "*****" Super secret password
func FromContext ¶
FromContext extracts the config.Set instance if it exists from the provided context or config.Default if not present
func (*Set) Bind ¶
Bind the Pointer to a Struct. This will take all of the fields and attempt to create settings from them. Any child structs will be set in a subset of the parent struct by name. All fields will be passed into the Set.Setting() function as pointers so that the Set.Set() function can write to the underlying value.
Fields names can be overwritten with the `setting` field tag.
Descriptions on settings can be set with the `description` field tag.
You can mask the Stringer of the setting (set it to output *****) by setting the field tag `mask:"true"`. This is really important to do to passwords/tokens/etc... to make sure they don't end up in logs.
func (*Set) Notify ¶
func (s *Set) Notify(n Notifier) *NotifyHandle
Notify when any of the settings in this set, or any child set is added or changed
func (*Set) Setting ¶
Setting will create a new setting with the specified name, value, and description in the current Set. Name can not be empty, value can not be nil
type Setting ¶
type Setting struct {
// Mask will overwrite the String function to return ***** to protect from logging
Mask bool
// Name of the value
Name string
// Description of this setting, useful for help text
Description string
// DefaultValue of the Setting as a string
DefaultValue string
// Path of the value, this is a dot separated path internally (i.e. Debug.Enabled)
Path string
// Value of the setting
Value Value
// contains filtered or unexported fields
}
Setting within the configuration containing a Value
func New ¶
New will create a new setting with the specified name, value, and description in the Default Set. Name can not be empty, value can not be nil
func (*Setting) Equals ¶
Equals will validate that the input string is the same as the current value using the internal parsing
func (*Setting) Flag ¶
Flag will register the current Setting as a command line flag in the supplied flag.FlagSet. When the supplied fs is nill, the flag.CommandLine is used
func (*Setting) IsBoolFlag ¶
IsBoolFlag is provided to help support boolean flags in the flag package (i.e. -debug rather than -debug=true)
func (*Setting) IsDefault ¶
IsDefault will return if the value matches the default value specified in Setting.DefaultValue
func (*Setting) Notify ¶
func (s *Setting) Notify(n Notifier) *NotifyHandle
Notify provides a callback interface to when a setting has changed via Setting.Set
type Unmarshaler ¶
Unmarshaler is the interface implemented by types that can unmarshal a string setting of themselves.
Source Files