config

package module
v0.2.6 Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2021 License: MIT Imports: 5 Imported by: 20

README

Config

release github build status pipeline status Test Coverage Maintainability

A Go package to deal with configuration.
Github https://github.com/usvc/go-config
Gitlab https://gitlab.com/usvc/modules/go/config

Usage

Importing
import "github.com/usvc/go-config"
Defining configuration

Following example can also be found at ./cmd/config/config.go

var conf = config.Map{
	// with env : BOOL=true
	// with flag: --bool | -b
	"bool": &config.Bool{
		Default:   false,
		Shorthand: "b",
		Usage:     "specifies a boolean value",
	},
	// with env : FLOAT=-123
	// with flag: --float -123 | -f -123
	"float": &config.Float{
		Default:   1.6180339887498948482045868343,
		Shorthand: "f",
		Usage:     "specifies a floating point value",
	},
	// with env : INT=-123
	// with flag: --int -123 | -i -123
	"int": &config.Int{
		Default:   -1,
		Shorthand: "i",
		Usage:     "specifies a signed integer value",
	},
	// with env : INTS="-123 -456"
	// with flag: --int-slice -123,-456 | -I -123,-456
	"int slice": &config.IntSlice{
		Default:   []int{-2, -3},
		Shorthand: "I",
		Usage:     "specifies a slice of signed integers value",
	},
	// with env : STRING=value
	// with flag: --string value | -s value
	"string": &config.String{
		Default:   "default",
		Shorthand: "s",
		Usage:     "specifies a string value",
	},
	// with env : STRING_SLICE="value1 value2"
	// with flag: --string-slice value1,value2 | -S value1,value2
	"string slice": &config.StringSlice{
		Default:   []string{"hello", "world"},
		Shorthand: "S",
		Usage:     "specifies a slice of strings value",
	},
	// with env : UINT=123
	// with flag: --uint 123 | -u 123
	"uint": &config.Uint{
		Default:   1,
		Shorthand: "u",
		Usage:     "specifies an unsigned integer value",
	},
	// with env : UINT_SLICE="123 456"
	// with flag: --uint-slice 123,456 | -U 123,456
	"uint slice": &config.UintSlice{
		Default:   []uint{2, 3},
		Shorthand: "U",
		Usage:     "specifies a slice of unsigned integers value",
	},
}
Consuming from environment

Following example assumes the above conf variable was defined.

conf.LoadFromEnvironment()
Applying to Cobra (github.com/spf13/cobra package)

Following example assumes the above conf variable was defined.

cmd := cobra.Command { /* ... config ... */ }
conf.ApplyToCobra(cmd)
Deciding environment/flag precedence

Following example assumes the above conf variable was defined.

To give priority to environment variables first, call LoadFromEnvironment() outside of the cobra.Command's runtime functions (eg. PreRun/Run)

func main() {
  cmd := cobra.Command{ /* ... config ... */ }
  conf.ApplyToCobra(cmd)
  conf.LoadFromEnvironment()
  cmd.Execute()
}

To give priority to values from flags first, call LoadFromEnvironment() inside one of cobra.Command's runtime functions:

func main() {
  cmd := cobra.Command{
    // ... other config ...
    PreRun: func(c *cobra.Command, args []string) {
      conf.LoadFromEnvironment()
    },
    // ... other config ...
  }
  conf.ApplyToCobra(cmd)
  cmd.Execute()
}
Retrieving values frrom the configuration

Following example assumes the above conf variable was defined.

fmt.Println("bool     : %v", conf.GetValue())
fmt.Println("float    : %v", conf.GetValue())
fmt.Println("int      : %v", conf.GetValue())
fmt.Println("[]int    : %v", conf.GetValue())
fmt.Println("string   : %s", conf.GetValue())
fmt.Println("[]string : %v", conf.GetValue())
fmt.Println("uint     : %v", conf.GetValue())
fmt.Println("[]uint   : %v", conf.GetValue())
Note on *Slice types

For the slice types (IntSlice, StringSlice, UintSlice), when running in flag mode, the delimiter is a comma (,), but in environment variable mode, the delimiter is a space ( ). This is because of how the underlying package (github.com/spf13/viper) does the string splitting.

Note on configuration names

The config.Map is used to define a dictionary of your configuration values using a map[string]config.Config data structure. The string becomes the name of the configuration and this string is manipulated before being passed to the downstream library.

For environment variables, all non-alphanumeric characters will be converted to an underscore (_), and all alphabetic characters will be converted to UPPERCASE_IN_SNAKE_CASE.

For flags, all non-alphanumeric characters will be converted to a hypen (-), and all alphabetic characters will be converted to lowercase-in-kebab-case.

Example CLI Application

The example CLI application can be found in the ./cmd/config directory and includes the configuration as found above. To test it out you can run the following:

# bool
go run ./cmd/config --bool
BOOL=1 go run ./cmd/config

# float
go run ./cmd/config --float 3.142
FLOAT=3.142 go run ./cmd/config

# int
go run ./cmd/config --int -12345
INT=-12345 go run ./cmd/config

# []int
go run ./cmd/config --int-slice -12345 --int-slice -67890
INT_SLICE="-12345 -67890" go run ./cmd/config

# string
go run ./cmd/config --string "hello world"
STRING="hello world" go run ./cmd/config

# []string
go run ./cmd/config --string-slice "hello" --string-slice "world"
STRING_SLICE="hello world" go run ./cmd/config

# uint
go run ./cmd/config --uint 12345
UINT=12345 go run ./cmd/config

# []uint
go run ./cmd/config --uint-slice 12345 --uint-slice 67890
UINT_SLICE="12345 67890" go run ./cmd/config

Development Runbook

Getting Started
  1. Clone this repository
  2. Run make deps to pull in external dependencies
  3. Write some awesome stuff
  4. Run make test to ensure unit tests are passing
  5. Push
Continuous Integration (CI) Pipeline
On Github

Github is used to deploy binaries/libraries because of it's ease of access by other developers.

Releasing

Releasing of the binaries can be done via Travis CI.

  1. On Github, navigate to the tokens settings page (by clicking on your profile picture, selecting Settings, selecting Developer settings on the left navigation menu, then Personal Access Tokens again on the left navigation menu)
  2. Click on Generate new token, give the token an appropriate name and check the checkbox on public_repo within the repo header
  3. Copy the generated token
  4. Navigate to travis-ci.org and access the cooresponding repository there. Click on the More options button on the top right of the repository page and select Settings
  5. Scroll down to the section on Environment Variables and enter in a new NAME with RELEASE_TOKEN and the VALUE field cooresponding to the generated personal access token, and hit Add
On Gitlab

Gitlab is used to run tests and ensure that builds run correctly.

Version Bumping
  1. Run make .ssh
  2. Copy the contents of the file generated at ./.ssh/id_rsa.base64 into an environment variable named DEPLOY_KEY in Settings > CI/CD > Variables
  3. Navigate to the Deploy Keys section of the Settings > Repository > Deploy Keys and paste in the contents of the file generated at ./.ssh/id_rsa.pub with the Write access allowed checkbox enabled
  • DEPLOY_KEY: generate this by running make .ssh and copying the contents of the file generated at ./.ssh/id_rsa.base64
DockerHub Publishing
  1. Login to https://hub.docker.com, or if you're using your own private one, log into yours
  2. Navigate to your security settings at the /settings/security endpoint
  3. Click on Create Access Token, type in a name for the new token, and click on Create
  4. Copy the generated token that will be displayed on the screen
  5. Enter the following varialbes into the CI/CD Variables page at Settings > CI/CD > Variables in your Gitlab repository:
  • DOCKER_REGISTRY_URL: The hostname of the Docker registry (defaults to docker.io if not specified)
  • DOCKER_REGISTRY_USERNAME: The username you used to login to the Docker registry
  • DOCKER_REGISTRY_PASSWORD: The generated access token

Licensing

Code in this package is licensed under the MIT license (click to see full text))

Documentation

Overview

github.com/usvc/go-config is a package to manage configuration values in libraries/applications.

Defining a configuration map: 

var conf = config.Map{
	"bool_key": &config.Bool{},
	"float_key": &config.Float{},
	"int_key": &config.Int{},
	"int_slice_key": &config.IntSlice{},
	"string_key": &config.String{},
	"uint_key": &config.Uint{},
	"uint_slice_key": &config.UintSlice{},
}

Loading environment variables (assuming conf is defined): 

conf.LoadFromEnvironment()

Applying to an instance of cobra.Command: 

command := cobra.Command{ ... }
conf.ApplyToCobra(&command)

Applying to an instance of cobra.Command persistently: 

command := cobra.Command{ ... }
conf.ApplyToCobraPersistent(&command)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bool 

type Bool struct {
	Shorthand string
	Usage     string
	Default   bool
	Value     bool
}

Bool represents a configuration which should be interpreted as a boolean-typed value

func (*Bool) ApplyToFlagSet 

func (s *Bool) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*Bool) GetDefault 

func (s *Bool) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*Bool) GetShorthand 

func (s *Bool) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*Bool) GetUsage 

func (s *Bool) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*Bool) GetValue 

func (s *Bool) GetValue() interface{}

GetValue returns the value of this configuration

func (*Bool) GetValuePointer 

func (s *Bool) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*Bool) SetValue 

func (s *Bool) SetValue(value interface{})

SetValue sets the value of this configuration

type Config 

type Config interface {
	ApplyToFlagSet(name string, flagset *pflag.FlagSet)
	GetDefault() interface{}
	GetShorthand() string
	GetUsage() string
	GetValue() interface{}
	GetValuePointer() interface{}
	SetValue(value interface{})
}

Config defines an interface that all configuration keys should implement

type Float 

type Float struct {
	Shorthand string
	Usage     string
	Default   float64
	Value     float64
}

Float stores the configuration details for a floating point value

func (*Float) ApplyToFlagSet 

func (s *Float) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*Float) GetDefault 

func (s *Float) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*Float) GetShorthand 

func (s *Float) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*Float) GetUsage 

func (s *Float) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*Float) GetValue 

func (s *Float) GetValue() interface{}

GetValue returns the value of this configuration

func (*Float) GetValuePointer 

func (s *Float) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*Float) SetValue 

func (s *Float) SetValue(value interface{})

SetValue sets the value of this configuration

type Int 

type Int struct {
	Shorthand string
	Usage     string
	Default   int
	Value     int
}

Int represents a configuration which should be interpreted as a signed integer

func (*Int) ApplyToFlagSet 

func (s *Int) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*Int) GetDefault 

func (s *Int) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*Int) GetShorthand 

func (s *Int) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*Int) GetUsage 

func (s *Int) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*Int) GetValue 

func (s *Int) GetValue() interface{}

GetValue returns the value of this configuration

func (*Int) GetValuePointer 

func (s *Int) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*Int) SetValue 

func (s *Int) SetValue(value interface{})

SetValue sets the value of this configuration

type IntSlice 

type IntSlice struct {
	Shorthand string
	Usage     string
	Default   []int
	Value     []int
}

IntSlice represents a configuration which should be interpreted as a slice of signed integers

func (*IntSlice) ApplyToFlagSet 

func (s *IntSlice) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*IntSlice) GetDefault 

func (s *IntSlice) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*IntSlice) GetShorthand 

func (s *IntSlice) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*IntSlice) GetUsage 

func (s *IntSlice) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*IntSlice) GetValue 

func (s *IntSlice) GetValue() interface{}

GetValue returns the value of this configuration

func (*IntSlice) GetValuePointer 

func (s *IntSlice) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*IntSlice) SetValue 

func (s *IntSlice) SetValue(value interface{})

SetValue sets the value of this configuration

type Map 

type Map map[string]Config

Map stores a map of configurations identifed by a string key

func (*Map) ApplyToCobra 

func (m *Map) ApplyToCobra(command *cobra.Command)

ApplyToCobra applies the configuration stored in the instance of Map to a cobra.Command instance as flags (cannot be accessed by child commands)

func (*Map) ApplyToCobraPersistent added in v0.1.20 

func (m *Map) ApplyToCobraPersistent(command *cobra.Command)

ApplyToCobraPersistent applies the configuration stored in the instance of Map to a cobra.Command instance as persistent flags (can be accessed by child commands)

func (*Map) ApplyToFlagSet added in v0.1.20 

func (m *Map) ApplyToFlagSet(flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration stored in the instance of Map to a provided set of flags

func (Map) Get 

func (m Map) Get(id string) interface{}

Get retrieves the value of the configuration identified by the key :id as an `interface{}` type

func (Map) GetBool 

func (m Map) GetBool(id string) bool

GetBool retrieves the value of the configuration identified by the key :id as a boolean type

func (Map) GetFloat 

func (m Map) GetFloat(id string) float64

GetFloat retrieves the value of the configuration identified by the key :id as a floating point type

func (Map) GetInt 

func (m Map) GetInt(id string) int

GetInt retrieves the value of the configuration identified by the key :id as an integer type

func (Map) GetIntSlice 

func (m Map) GetIntSlice(id string) []int

GetIntSlice retrieves the value of the configuration identified by the key :id as an integer slice type

func (Map) GetString 

func (m Map) GetString(id string) string

GetString retrieves the value of the configuration identified by the key :id as a string type

func (Map) GetStringSlice 

func (m Map) GetStringSlice(id string) []string

GetStringSlice retrieves the value of the configuration identified by the key :id as a string slice type

func (Map) GetUint 

func (m Map) GetUint(id string) uint

GetUint retrieves the value of the configuration identified by the key :id as an unsigned integer type

func (Map) GetUintSlice 

func (m Map) GetUintSlice(id string) []uint

GetUintSlice retrieves the value of the configuration identified by the key :id as an unsigned intger slice type

func (*Map) LoadFromEnvironment 

func (m *Map) LoadFromEnvironment()

LoadFromEnvironment loads the configuration from pre-defined environment variables

func (Map) Reset added in v0.2.6 

func (m Map) Reset() error

type String 

type String struct {
	Shorthand string
	Usage     string
	Default   string
	Value     string
}

String represents a configuration which should be interpreted as a string-typed value

func (*String) ApplyToFlagSet 

func (s *String) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*String) GetDefault 

func (s *String) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*String) GetShorthand 

func (s *String) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*String) GetUsage 

func (s *String) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*String) GetValue 

func (s *String) GetValue() interface{}

GetValue returns the value of this configuration

func (*String) GetValuePointer 

func (s *String) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*String) SetValue 

func (s *String) SetValue(value interface{})

SetValue sets the value of this configuration

type StringSlice 

type StringSlice struct {
	Shorthand string
	Usage     string
	Default   []string
	Value     []string
}

StringSlice represents a configuration which should be represented as a slice of strings

func (*StringSlice) ApplyToFlagSet 

func (s *StringSlice) ApplyToFlagSet(name string, flags *pflag.FlagSet)

// ApplyToFlagSet applies the configuration to a provided flag set

func (*StringSlice) GetDefault 

func (s *StringSlice) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*StringSlice) GetShorthand 

func (s *StringSlice) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*StringSlice) GetUsage 

func (s *StringSlice) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*StringSlice) GetValue 

func (s *StringSlice) GetValue() interface{}

GetValue returns the value of this configuration

func (*StringSlice) GetValuePointer 

func (s *StringSlice) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*StringSlice) SetValue 

func (s *StringSlice) SetValue(value interface{})

SetValue sets the value of this configuration

type Uint 

type Uint struct {
	Shorthand string
	Usage     string
	Default   uint
	Value     uint
}

Uint represents a configuration which should be interpreted as an unsigned integer

func (*Uint) ApplyToFlagSet 

func (s *Uint) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*Uint) GetDefault 

func (s *Uint) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*Uint) GetShorthand 

func (s *Uint) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*Uint) GetUsage 

func (s *Uint) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*Uint) GetValue 

func (s *Uint) GetValue() interface{}

GetValue returns the value of this configuration

func (*Uint) GetValuePointer 

func (s *Uint) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*Uint) SetValue 

func (s *Uint) SetValue(value interface{})

SetValue sets the value of this configuration

type UintSlice 

type UintSlice struct {
	Shorthand string
	Usage     string
	Default   []uint
	Value     []uint
}

UintSlice represents a configuration which should be interpreted as a slice of unsigned integers

func (*UintSlice) ApplyToFlagSet 

func (s *UintSlice) ApplyToFlagSet(name string, flags *pflag.FlagSet)

ApplyToFlagSet applies the configuration to a provided flag set

func (*UintSlice) GetDefault 

func (s *UintSlice) GetDefault() interface{}

GetDefault retrieves the default value of this configuration

func (*UintSlice) GetShorthand 

func (s *UintSlice) GetShorthand() string

GetShorthand retrieves the short form of the flag if available

func (*UintSlice) GetUsage 

func (s *UintSlice) GetUsage() string

GetUsage retrieves the usage string for this configuration

func (*UintSlice) GetValue 

func (s *UintSlice) GetValue() interface{}

GetValue returns the value of this configuration

func (*UintSlice) GetValuePointer 

func (s *UintSlice) GetValuePointer() interface{}

GetValuePointer returns a pointer that points to the instance of the configured value

func (*UintSlice) SetValue 

func (s *UintSlice) SetValue(value interface{})

SetValue sets the value of this configuration

Source Files

View all Source files

Directories

Path Synopsis
cmd
config command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.