Configure is a Go package that gives you easy configuration of your project through redundancy

Overview

Configure

GoDoc

Configure is a Go package that gives you easy configuration of your project through redundancy. It has an API inspired by negroni and the flag package.

What is it?

Configure aims to be the github.com/codegangsta/negroni of configuration. It is a Checker manager, in the same way negroni manages net/http middleware. A Checker is a way of retrieving configuration values from a source: these can be easily made by completing the Checker interface. The idea is that you as a developer provide Configure with a selection of Checkers, either built in or not and it will iterate over them attempting to find values defined by the developer. If a Checker is successful in its retrieval, then Configure will stop the iteration for that value. If it is not then Configure will attempt the next Checker in chronological order.

Getting Started

After you have installed Go (and have made sure to correctly setup your GOPATH) create a new .go file, maybe hello.go.

package main

import (
  "fmt"
  
  "github.com/paked/configure"
)

var (
  conf = configure.New()
  name = conf.String("name", "Harrison", "The name you want to greet")
)

func init() {
  conf.Use(configure.NewEnvironment())
  conf.Use(configure.NewFlag())
}

func main() {
  conf.Parse()
  fmt.Printf("Hello, %v", *name)
}

If you run this code with

go run hello.go

Hello, Harrison will be printed to your terminal, not that interesting right... read on!

Stage One : Declaration

var (
  conf = configure.New()
  name = conf.String("name", "Harrison", "The name you want to greet")
)

The declaration stage is important because it defines exactly what you CAN configure! First, conf is created which is your key to adding Checkers and retrieving variables. After that you begin properly declaring your variables, in this example only a string is declared but in practice you can use any number of Strings, Ints or Bools. The variables returned by these methods are pointers to their respective types.

Stage Two : Configuration

func init() {
  conf.Use(configure.NewEnvironment())
  conf.Use(configure.NewFlag())
}

The configuration stage is where you configure configure by adding Checkers to the stack. Checkers are objects which will attempt to retrieve your variables from their respective data sources. When a Checker fails the next one in the stack is called, the stack is in the same order that the Checker's were added in. You can configure configure anytime before you call the conf.Parse() function, but the init() function provides a reliable place to do so.

note: When using the Environment Checker, all keys will be translated to uppercase and have dashes replaced with underscores (ie. hello-world to HELLO_WORLD).

Stage Three : Usage

func main() {
  conf.Parse()
  fmt.Printf("Hello, %v", *name)
}

The final stage is where you can actually use the variables you have declared. After using conf.Parse() your variables should then be populated and accesible by dereferencing it (name).

Execution

If you were to run this code in its current state it would print Hello, Harrison because Harrison is the default value provided in the declaration stage. But if you provide --name=Johny when you execute the command it will print Hello, Johny. At this point configure is behaving like the default flag package through the Flag Checker. Now, run export NAME=Jarvis in your command line and execute the program again and ommit the entire --name=command line flag. You will see a Hello, Jarvis, as configure has fallen back upon the Environment Checker. Note that, if you provide both means of input the environment variable will be used, as it has higher priority as it was added before the Flag Checker in the configuration stage. This works with any number of Checkers from any source, as long as the fulfil the Checker interface.

Further Reading

More package documentation can be found on godoc.

A more complicated example can be found in the example folder, it uses all three variable types (Int, Bool and String) and all three of the default Checker's (JSON, Environment and Flag).

Contributing

If you notice something that you feel is broken or missing in configure feel free to open up an issue so that we can discuss it more. While small changes could be immediately put into a PR, I believe it saves everyones time to discuss major changes before implementing them. Contributions are welcome and appreciated.

Checkers

Name Location Initialiser Description
Environment [builtin] http://github.com/paked/configure NewEnvironment() Environment checks the os environment variables for values
JSON [builtin] http://github.com/paked/configure NewJSON(io.Reader) Retrieves values from an io.Reader containing JSON
Flag [builtin] http://github.com/paked/configure NewFlag() Retrieve flagged values from os.Args in a --x=y format
HCL [builtin] http://github.com/paked/configure NewHCL(io.Reader) Retrieve values from an io.Reader containing HCL

If you write your own Checker I would LOVE to see it, create a PR with a new entry in the table!

Note

As you may have noticed, I am not particularly great at English. If you notice a way to de-garble a few of my sentences be sure to let me know... Not only I, but future readers will be grateful too :)

designed and implemented by Harrison Shoebridge
Comments
  • Suggestion

    Suggestion

    Thanks for the library. Enjoyed using it. One thing would might be nice is to note Environment variables must be ALL capital letters in order for the config lib to pick them up. It took me a bit to debug why I couldn't get those configuration values to show up until I realized that they needed to be capital. So some note in documentation would be great. It's especially hard when you mix other config types. Another option is to ignore case and allow the environment variables to be lower case.

    I appreciate the lib, thanks again.

    opened by JC1738 2
  • support hashicopr configuration language

    support hashicopr configuration language

    hey,

    i love your configure package and we are using it in several applications but some of the guys here want to use hcl instead of json. So why not supporting hcl in this package.

    opened by patdhlk 2
  • No support for durations

    No support for durations

    The checker interface doesn't allow storing and retrieving durations, which are often very useful especially for webapplications. Of course one could use an int to store durations, but if things like "m","h","days",... are interpreted it is way easier for the user to configure durations.

    opened by Backfighter 1
  • add support for hcl

    add support for hcl

    add support for the hashicorp configuration language, #2 (https://github.com/hashicorp/hcl) because this configuration language supports hcl and json. Samples are oriented on the JSON echo sample but based on a hcl config file.

    the implementation is based on the json implementation, but not really tested yet

    opened by patdhlk 0
  • + added MongoDb checker

    + added MongoDb checker

    Hello, I created a checker to get configuration from a mongodb collection. I added minimal documentation and test, if it proves useful to you i might work more onto adding a docker container with the test data and / or merging it to this fork to make it embedded directly.

    Tell me if anything is not in order

    opened by LouAdrien 3
  • auto usage message

    auto usage message

    Hi, I'm very new to GO and I think this is the most complete library for the configuration in go.

    I would suggest to make a smarter default usage message, maybe taken from the variables needed and with a message like "you can set variables using environment or a json config file (config.json)". The message could be based on the settings provided in the code.

    What do you think about?

    opened by greenkey 4
Releases(6.2.2)
Owner
Harrison Shoebridge
hacker and human
Harrison Shoebridge
Wg-configurator - This project makes it easier to configure a fleet of servers interconnected via the WireGuard point-to-point virtual private network.

WireGuard Configurator This project makes it easier to configure a fleet of servers interconnected via the WireGuard point-to-point virtual private ne

Caleb L. Power 1 Mar 29, 2022
shops is a simple command-line tool written in Go that helps you simplify the way you manage configuration across a set of machines.

shops is a simple command-line tool written in Go that helps you simplify the way you manage configuration across a set of machines. shops is your configuration management tool of choice when Chef, Puppet, Ansible are all too complicated and all you really want to do is run a bunch of regular shell against a set of hosts.

James Mills 16 Jul 5, 2021
Go configuration made easy!

gofigure Go configuration made easy! Just define a struct and call Gofigure Supports strings, ints/uints/floats, slices and nested structs Supports en

Ian Kent 65 Sep 26, 2022
A golang package for parsing ini-style configuration files

Mini Mini is a simple ini configuration file parser. The ini syntax supported includes: The standard name=value Comments on new lines starting with #

Stephen Asbury 31 Jul 7, 2022
Flags-first package for configuration

ff stands for flags-first, and provides an opinionated way to populate a flag.FlagSet with configuration data from the environment.

Peter Bourgon 1.1k Sep 18, 2022
Environment variables configuration package for Go microservices.

gocfg Environment variables configuration package for Go microservices. It helps validate environment variable values and set default values if needed

Sergey Prokhorov 0 Dec 30, 2021
Small library to read your configuration from environment variables

envconfig envconfig is a library which allows you to parse your configuration from environment variables and fill an arbitrary struct. See the example

Vincent Rischmann 226 Sep 16, 2022
It syncronizes the configuration described in a YAML file against your GitHub Organization

It syncronizes the configuration described in a YAML file against your GitHub Organization. Combined with a CI system, it can be used to implement GitOps for GitHub.

Carlos Tadeu Panato Junior 6 Jul 19, 2021
Cfginterpolator is an interpolate library in golang allowing to include data from external sources in your configuration

cfginterpolator cfginterpolator is an interpolate library in golang allowing to include data from external sources in your configuration cfginterpolat

Benoit Bayszczak 0 Dec 14, 2021
Genv is a library for Go (golang) that makes it easy to read and use environment variables in your projects. It also allows environment variables to be loaded from the .env file.

genv Genv is a library for Go (golang) that makes it easy to read and use environment variables in your projects. It also allows environment variables

Şakir Şensoy 29 Sep 26, 2022
Project my config into your prebuild

Projector A simple key value store per path. Building From Source git clone [email protected]:ThePrimeagen/projector.git cd projector # Install it where

ThePrimeagen 10 Jun 23, 2022
✨Clean and minimalistic environment configuration reader for Golang

Clean Env Minimalistic configuration reader Overview This is a simple configuration reading tool. It just does the following: reads and parses configu

Ilya Kaznacheev 732 Sep 21, 2022
12 factor configuration as a typesafe struct in as little as two function calls

Config Manage your application config as a typesafe struct in as little as two function calls. type MyConfig struct { DatabaseUrl string `config:"DAT

Jeremy Loy 317 Sep 2, 2022
JSON or YAML configuration wrapper with convenient access methods.

Config Package config provides convenient access methods to configuration stored as JSON or YAML. This is a fork of the original version. This version

Oleg Lebedev 254 Sep 26, 2022
An opinionated configuration loading framework for Containerized and Cloud-Native applications.

Opinionated configuration loading framework for Containerized and 12-Factor compliant applications. Read configurations from Environment Variables, an

Sherif Abdel-Naby 81 Sep 25, 2022
Load configuration in cascade from multiple backends into a struct

Confita is a library that loads configuration from multiple backends and stores it in a struct. Supported backends Environment variables JSON files Ya

Heetch 455 Sep 15, 2022
A minimalist Go configuration library

fig fig is a tiny library for loading an application's config file and its environment into a Go struct. Individual fields can have default values def

null 232 Sep 21, 2022
go-up! A simple configuration library with recursive placeholders resolution and no magic.

go-up! A simple configuration library with placeholders resolution and no magic. go-up provides a simple way to configure an application from multiple

Francesco 37 Mar 23, 2022
goconfig uses a struct as input and populates the fields of this struct with parameters from command line, environment variables and configuration file.

goconfig goconfig uses a struct as input and populates the fields of this struct with parameters from command line, environment variables and configur

Go Sidekick 0 May 30, 2022