• Stars
    star
    56
  • Rank 530,013 (Top 11 %)
  • Language
    Go
  • License
    MIT License
  • Created over 9 years ago
  • Updated over 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

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

More Repositories

1

messenger

Package messenger is used for making bots for use with Facebook messenger
Go
274
star
2

zrlify

Zach Latta-ify your web browsing experience!
JavaScript
17
star
3

down

A Markdown engine in Go!
Go
3
star
4

dotfiles

my dotfiles
Vim Script
3
star
5

pipe-ist

A back to basics build tool for JavaScript, TypeScript and pretty much everything else
TypeScript
3
star
6

stm32-vscode-simple

a project template for assembly level hacking with the stm32l476vg with vscode.
Assembly
3
star
7

loaf

Loaf is a toy programming language.
C++
2
star
8

lang

Lang is a small programming language, which does very little
Go
1
star
9

ponzies-the-game

A video game adaption of the ponz.ies startup we all know and love!
Haxe
1
star
10

gerrycode

Review projects.
Go
1
star
11

annoy

i'm sorry chicago hacks attendees :(
Ruby
1
star
12

go-fibonacci

fibonacci number generator for school science project
Go
1
star
13

becomethethey.today

JavaScript
1
star
14

qoe

HTML
1
star
15

restrict

Package restrict is an unidiomatic Go library for working with JWTs
Go
1
star
16

esoteric-adventures

#LD48 Esoteric adventures is a game where you battle against the corporations in order to save your forest and furthermore the world from being put under the power of the right wing.
JavaScript
1
star
17

night

A PHASER PLATFORMER. I WILL PROBABLY KEEP WORKING ON THIS. IT IS AN EXAMPLE
JavaScript
1
star
18

distance-matrix

A small wrapper around the google distance matrix API.
Python
1
star
19

opengl-a-day

I'm going to learn OpenGL. One day at a time... Hopefully... (Future Harrison, I sure hope you followed through one this) edit: i did, just not in this repo lol
C++
1
star
20

go-ircclient

A simple IRC client made in go
Go
1
star
21

lornock

a game made with Handmade-ish C++ and OpenGL, a bit of a mess
C++
1
star
22

nutrimon

nutrimon
Go
1
star