configure

README

Configure

configure is a golang library that populates a struct from environment variables, command line arguments and YAML files. It works by reading a struct definition with special tags.

Usage

The latest can be seen if you run:

godoc github.com/gravitational/configure

But here's a quickstart: Define a sample structure, for example:

	 type Config struct {
	   StringVar   string              `env:"STRING_VAR" cli:"string-var" yaml:"string_var"`
	   BoolVar     bool                `env:"BOOL_VAR" cli:"bool_var" yaml:"bool_var"`
	   IntVar      int                 `env:"INT_VAR" cli:"int_var" yaml:"int_var"`
	   HexVar      hexType             `env:"HEX_VAR" cli:"hex_var" yaml:"hex_var"`
	   MapVar      map[string]string   `env:"MAP_VAR" cli:"map_var" yaml:"map_var,flow"`
	   SliceMapVar []map[string]string `env:"SLICE_MAP_VAR" cli:"slice_var" yaml:"slice_var,flow"`
	}

Then you can query the environment and populate that structure from environment variables, YAML files or command line arguments.

	import (
	   "os"
	   "github.com/gravitational/configure"
	)

	func main() {
	   var cfg Config
	   // parse environment variables
	   err := configure.ParseEnv(&cfg)
	   // parse YAML
	   err = configure.ParseYAML(&cfg)
	   // parse command line arguments
	   err = configure.ParseCommandLine(&cfg, os.Args[1:])
	}

Documentation

Overview

Copyright 2015 Gravitational, Inc.

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.

Copyright 2015 Gravitational, Inc.

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.

Copyright 2015 Gravitational, Inc.

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.

Package configure generates configuration tools based on a struct definition with tags. It can read a configuration for a struct from YAML, environment variables and command line.

Given the struct definition:

 type Config struct {
   StringVar   string              `env:"TEST_STRING_VAR" cli:"string" yaml:"string"`
   BoolVar     bool                `env:"TEST_BOOL_VAR" cli:"bool" yaml:"bool"`
   IntVar      int                 `env:"TEST_INT_VAR" cli:"int" yaml:"int"`
   HexVar      hexType             `env:"TEST_HEX_VAR" cli:"hex" yaml:"hex"`
   MapVar      map[string]string   `env:"TEST_MAP_VAR" cli:"map" yaml:"map,flow"`
   SliceMapVar []map[string]string `env:"TEST_SLICE_MAP_VAR" cli:"slice" yaml:"slice,flow"`
}

You can start initializing the struct from YAML, command line or environment:

import (
   "os"

   "github.com/gravitational/configure"
)

func main() {
   var cfg Config
   // parse environment variables
   err := configure.ParseEnv(&cfg)
   // parse YAML
   err = configure.ParseYAML(&cfg)
   // parse command line arguments
   err = configure.ParseCommandLine(&cfg, os.Ars[1:])
}

Copyright 2015 Gravitational, Inc.

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.

Copyright 2015 Gravitational, Inc.

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.

Copyright 2015 Gravitational, Inc.

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.

Index

• func IncIP(ip net.IP) net.IP
• func NewCommandLineApp(v interface{}) (*kingpin.Application, error)
• func ParseCommandLine(v interface{}, args []string) error
• func ParseEnv(v interface{}) error
• func ParseYAML(data []byte, cfg interface{}, funcArgs ...ParseOption) error
• type CIDR
  • func CIDRFlag(s kingpin.Settings) *CIDR
  • func ParseCIDR(v string) (*CIDR, error)
  • func (c *CIDR) FirstIP() net.IP
  • func (c *CIDR) RelativeIP(offset int) net.IP
  • func (c *CIDR) Set(v string) error
  • func (c *CIDR) String() string
• type CLISetter
• type EnvSetter
• type KeyVal
  • func KeyValParam(s kingpin.Settings) *KeyVal
  • func (kv *KeyVal) Set(v string) error
  • func (kv *KeyVal) SetEnv(v string) error
  • func (kv *KeyVal) String() string
• type KeyValSlice
  • func (kv *KeyValSlice) Set(v string) error
  • func (kv *KeyValSlice) SetEnv(v string) error
  • func (kv *KeyValSlice) String() string
• type ParseOption
  • func EnableTemplating() ParseOption
• type StringSetter

Functions

func IncIP

func IncIP(ip net.IP) net.IP

func NewCommandLineApp

func NewCommandLineApp(v interface{}) (*kingpin.Application, error)

NewCommandLineApp generates a command line parsing tool based on the struct that was passed in as a parameter

func ParseCommandLine

func ParseCommandLine(v interface{}, args []string) error

ParseCommandLine takes a pointer to a function and attempts to initialize it from environment variables.

func ParseEnv

func ParseEnv(v interface{}) error

ParseEnv takes a pointer to a struct and attempts to initialize it from environment variables.

func ParseYAML

func ParseYAML(data []byte, cfg interface{}, funcArgs ...ParseOption) error

ParseYAML parses yaml-encoded byte string into the struct passed to the function. EnableTemplating() argument allows to treat configuration file as a template for example, it will support {{env "VAR"}} - that will substitute environment variable "VAR" and pass it to YAML file parser

Types

type CIDR

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

CIDR adds several helper methods over subnet range

func CIDRFlag

func CIDRFlag(s kingpin.Settings) *CIDR

CIDRFlag returns CIDR range flag

func ParseCIDR

func ParseCIDR(v string) (*CIDR, error)

ParseCIDR parses value of the CIDR from string

func (*CIDR) FirstIP

func (c *CIDR) FirstIP() net.IP

FirstIP returns the first IP in this subnet that is not .0

func (*CIDR) RelativeIP

func (c *CIDR) RelativeIP(offset int) net.IP

RelativeIP returns an IP given an offset from the first IP in the range. offset starts at 0, i.e. c.RelativeIP(0) == c.FirstIP()

func (*CIDR) Set

func (c *CIDR) Set(v string) error

func (*CIDR) String

func (c *CIDR) String() string

type CLISetter

type CLISetter interface {
	SetCLI(string) error
}

CLISetter is an interface for setting any value from command line flag

type EnvSetter

type EnvSetter interface {
	SetEnv(string) error
}

Setter is an interface that properties of struct can implement to initialize the value of any struct from string

type KeyVal

type KeyVal map[string]string

KeyVal is map that can parse itself from string, represented as a comma-separated list of keys and values "key:val,key:val"

func KeyValParam

func KeyValParam(s kingpin.Settings) *KeyVal

KeyValParam accepts a kingpin setting parameter and returns kingpin-compatible value

func (*KeyVal) Set

func (kv *KeyVal) Set(v string) error

Set accepts string with arguments in the form "key:val,key2:val2"

func (*KeyVal) SetEnv

func (kv *KeyVal) SetEnv(v string) error

SetEnv sets the value from environment variable using json encoding

func (*KeyVal) String

func (kv *KeyVal) String() string

String returns a string with comma separated key-values: "key:val,key2:val2"

type KeyValSlice

type KeyValSlice []map[string]string

KeyValSlice is a list of key value strings

func (*KeyValSlice) Set

func (kv *KeyValSlice) Set(v string) error

Set accepts string with arguments in the form "key:val,key2:val2"

func (*KeyValSlice) SetEnv

func (kv *KeyValSlice) SetEnv(v string) error

SetEnv sets the value from environment variable using json encoding

func (*KeyValSlice) String

func (kv *KeyValSlice) String() string

String returns a string with comma separated key-values: "key:val,key2:val2"

type ParseOption

type ParseOption func(p *parseOptions)

ParseOption is a functional argument type

func EnableTemplating

func EnableTemplating() ParseOption

EnableTemplating allows to treat configuration file as a template for example, it will support {{env "VAR"}} - that will substitute environment variable "VAR" and pass it to YAML file parser

type StringSetter

type StringSetter interface {
	Set(string) error
}

StringSetter is an interface that allows to set variable from any string