Flags persisted in an ini-like config file.

[![Godoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/schachmat/ingo)
[![Go Report Card](https://goreportcard.com/badge/schachmat/ingo)](https://goreportcard.com/report/schachmat/ingo)
[![Coverage](https://gocover.io/_badge/github.com/schachmat/ingo)](https://gocover.io/github.com/schachmat/ingo)

**ingo** is a simple Go library helping you to persist flags in a ini-like config
file.

## Features and limitations

* Requires Go 1.5 or later
* automatically creates config file, if it does not exist yet
* option value priorities (from high to low):
  0. flags given on the commandline
  0. flags read from the config file
  0. defaults given when flags are initialized
* write defaults to config file, if they are not set there already
* every flag in the config file has the flag usage prepended as a comment
* shorthand flags pointing to the same variable as another flag will not be
  written to the config file to reduce noise. Both short and long version will
  still show up in the `-h` output.
* only rewrite the config file, when it would change
* old flags, which are not used anymore are not removed
* when old flags are found, a warning is printed to stderr (see example below)
* flags must not contain the runes `:` and `=` and not start with `#` as these
  runes are used as separators and comment prefix in the config file
* no sections, namespaces or FlagSets other than the default one

## Installation

```shell
go get -u github.com/schachmat/ingo
```

## Usage example

Just setup your flags with defaults like you are used to do. Instead of
`flag.Parse()` you have to call `ingo.Parse(APPLICATION_NAME)` and check if an
error is returned. Thats all.

```go
package main

import (
	"flag"
	"fmt"
	"log"
	"github.com/schachmat/ingo"
)

func main() {
	num := flag.Int("num", 3, "`NUMBER` of times to\n    \tdo a barrel roll")
	location := flag.String("location", "space", "`WHERE` to do the barrel roll")
	flag.StringVar(location, "l", "space", "`WHERE` to do the barrel roll (shorthand)")
	if err := ingo.Parse("keep_rollin"); err != nil {
		log.Fatal(err)
	}
	fmt.Println(*num, *location)
}
```

The (one newline, four spaces, one tab) separator will ensure that multi-line
usage strings will be laid out correctly in the config file *and* in the `-h`
help message. The code will create the following config file `.keep_rollinrc`
(or any other location if specified in the environment variable
`KEEP_ROLLINRC`):

```shell
# WHERE to do the barrel roll
location=space

# NUMBER of times to
# do a barrel roll
num=3
```

If you change num to 5 in the config file, it will be persistent on all future
runs:

```shell
# WHERE to do the barrel roll
location=space

# NUMBER of times to
# do a barrel roll
num=5
```

If you add a new flag `style` to your programm, it will be added to the config
file on the first run using the default value from the flag:

```shell
# WHERE to do the barrel roll
location=space

# NUMBER of times to
# do a barrel roll
num=5

# HOW to do the barrel roll
style=epic
```

If you remove both location flags from your programm, the config entry will be
rewritten to this:

```shell
# NUMBER of times to
# do a barrel roll
num=5

# HOW to do the barrel roll
style=epic


# The following options are probably deprecated and not used currently!
location=space
```

Also when such old flags are found, a warning like the following is printed to
stderr when running `ingo.Parse`:

```shell
!!!!!!!!!!
! WARNING: keep_rollin was probably updated,
! Check and update .keep_rollinrc as necessary
! and remove the last "deprecated" paragraph to disable this message!
!!!!!!!!!!
```

All config files will have a header like the following explaining the syntax:

```shell
# keep_rollin configuration
#
# This config has https://github.com/schachmat/ingo syntax.
# Empty lines or lines starting with # will be ignored.
# All other lines must look like "KEY=VALUE" (without the quotes).
# The VALUE must not be enclosed in quotes as well!
```

## License - ISC

Copyright (c) 2016-2017,  <teichm@in.tum.de>

Permission to use, copy, modify, and/or distribute this software for any purpose
with or without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.


ingo

Provides configuration through multiple sources, including JSON, flags and environment variables.

# Configure
[![GoDoc](https://godoc.org/github.com/paked/configure?status.svg)](https://godoc.org/github.com/paked/configure)

Configure is a Go package that gives you easy configuration of your project through redundancy. It has an API inspired by [negroni](http://godoc.org/github.com/codegangsta/negroni) and the [flag](http://godoc.org/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](http://godoc.org/github.com/paked/configure#Checker). The idea is that you as a developer provide Configure with a selection of `Checker`s, 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](http://golang.org/doc/code.html#GOPATH)) create a new `.go` file, maybe `hello.go`.
```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
```go
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 `String`s, `Int`s or `Bool`s. The variables returned by these methods are pointers to their respective types.

### Stage Two : Configuration
```go
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
```go
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](http://godoc.org/github.com/paked/configure#Checker).

## Further Reading
[More package documentation can be found on godoc](http://godoc.org/pkg/github.com/paked/configure).

A more complicated example can be found in the [example folder](http://github.com/paked/configure/blob/master/example/), 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](http://github.com/paked)*


configure

gofigure  [![GoDoc](https://godoc.org/github.com/ian-kent/gofigure?status.svg)](https://godoc.org/github.com/ian-kent/gofigure) [![Build Status](https://travis-ci.org/ian-kent/gofigure.svg?branch=master)](https://travis-ci.org/ian-kent/gofigure) [![Coverage Status](https://coveralls.io/repos/ian-kent/gofigure/badge.png?branch=master)](https://coveralls.io/r/ian-kent/gofigure?branch=master)
========

Go configuration made easy!

- Just define a struct and call Gofigure
- Supports strings, ints/uints/floats, slices and nested structs
- Supports environment variables and command line flags

Requires Go 1.2+ because of differences in Go's flag package.

### Example

`go get github.com/ian-kent/gofigure`

```go
package main

import "github.com/ian-kent/gofigure"

type config struct {
  gofigure interface{} `envPrefix:"BAR" order:"flag,env"`
  RemoteAddr string `env:"REMOTE_ADDR" flag:"remote-addr" flagDesc:"Remote address"`
  LocalAddr  string `env:"LOCAL_ADDR" flag:"local-addr" flagDesc:"Local address"`
  NumCPU int `env:"NUM_CPU" flag:"num-cpu" flagDesc:"Number of CPUs"`
  Sources []string `env:"SOURCES" flag:"source" flagDesc:"Source URL (can be provided multiple times)"`
  Numbers []int `env:"NUMBERS" flag:"number" flagDesc:"Number (can be provided multiple times)"`
  Advanced struct{
      MaxBytes int64 `env:"MAX_BYTES" flag:"max-bytes" flagDesc:"Max bytes"`
      MaxErrors int64  `env:"MAX_ERRORS" flag:"max-errors" flagDesc:"Max errors"`
  }
}

func main() {
  var cfg config
  err := gofigure.Gofigure(&cfg)
  if err != nil {
    log.Fatal(err)
  }
  // use cfg
}
```

### gofigure field

The gofigure field is used to configure Gofigure.

The `order` tag is used to set configuration source order, e.g.
environment variables first then command line options second.

Any field matching `camelCase` format will be parsed into `camel`
and `case`, and passed to the source matching `camel`.

For example, the `envPrefix` field is split into `env` and `prefix`,
and the tag value is passed to the environment variable source as
the `prefix` parameter.

### Arrays and environment variables

Array support for environment variables is currently experimental.

To enable it, set `GOFIGURE_ENV_ARRAY=1`.

When enabled, the environment variable is split on commas, e.g.

```
struct {
    EnvArray []string `env:"MY_ENV_VAR"`
}

MY_ENV_VAR=a,b,c

EnvArray = []string{"a", "b", "c"}
```

### Licence

Copyright ©‎ 2014, Ian Kent (http://www.iankent.eu).

Released under MIT license, see [LICENSE](LICENSE.md) for details.


gofigure

Small configuration library for Go that parses environment variables, JSON files, and reloads automatically on SIGHUP.

# config

[![Build Status](https://travis-ci.org/joshbetz/config.svg?branch=master)](https://travis-ci.org/joshbetz/config) [![Go Report Card](https://goreportcard.com/badge/github.com/joshbetz/config)](https://goreportcard.com/report/github.com/joshbetz/config) [![](https://godoc.org/github.com/joshbetz/config?status.svg)](http://godoc.org/github.com/joshbetz/config)


A small configuration library for Go that parses environment variables, JSON
files, and reloads automatically on `SIGHUP`.

## Example

```go
func main() {
	c := config.New("config.json")

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		var value string
		c.Get("value", &value)
		fmt.Fprintf(w, "Value: %s", value)
	})

	http.ListenAndServe(":3000", nil)
}
```

![Reload config on SIGHUP](http://i.imgur.com/6H8b6zy.gif)

## API

```go
func New(file string) *Config
```

Constructor that initializes a Config object and sets up the SIGHUP watcher.

```go
func (config *Config) Get(key string, v interface{}) error
```

Takes the path to a JSON file, the name of the configuration option, and a
pointer to the variable where the config value will be stored. `v` can be a
pointer to a string, bool, or float64.

```go
func (config *Config) Reload()
```

Reloads the config. Happens automatically on `SIGHUP`.


joshbetz/config

Golang package for parsing ini-style configuration files.

Mini
================

[![Build Status](https://travis-ci.org/sasbury/mini.svg?branch=master)](https://travis-ci.org/sasbury/mini) [![GoDoc](https://godoc.org/github.com/sasbury/mini?status.svg)](https://godoc.org/github.com/sasbury/mini)

Mini is a simple [ini configuration file](http://en.wikipedia.org/wiki/INI_file) parser.

The ini syntax supported includes:

* The standard name=value
* Comments on new lines starting with # or ;
* Blank lines
* Sections labelled with [sectionname]
* Split sections, using the same section in more than one place
* Encoded strings, strings containing \n, \t, etc...
* Array values using repeated keys named in the form key[]=value
* Global key/value pairs that appear before the first section

Repeated keys, that aren't array keys, replace their previous value.

To use simply:

    % go get github.com/sasbury/mini


mini

Lightweight configuration manager for Go.

# Store
>Store is a dead simple configuration manager for Go applications.

[![GoDoc](https://godoc.org/github.com/tucnak/store?status.svg)](https://godoc.org/github.com/tucnak/store)

I didn't like existing configuration management solutions like [globalconf](https://github.com/rakyll/globalconf), [tachyon](https://github.com/vektra/tachyon) or [viper](https://github.com/spf13/viper). First two just don't feel right and viper, imo, a little overcomplicated—definitely offering too much for small things. Store supports either JSON, TOML or YAML out-of-the-box and lets you register practically any other configuration format. It persists all of your configurations in either $XDG_CONFIG_HOME or $HOME on Linux and in %APPDATA%
on Windows.

Look, when I say it's dead simple, I actually mean it:
```go
package main

import (
	"log"
	"time"

	"github.com/tucnak/store"
)

func init() {
	// You must init store with some truly unique path first!
	store.Init("cats-n-dogs/project-hotel")
}

type Cat struct {
	Name   string `toml:"naym"`
	Clever bool   `toml:"ayy"`
}

type Hotel struct {
	Name string
	Cats []Cat `toml:"guests"`

	Opens  *time.Time
	Closes *time.Time
}

func main() {
	var hotel Hotel

	if err := store.Load("hotel.toml", &hotel); err != nil {
		log.Println("failed to load the cat hotel:", err)
		return
	}

	// ...

	if err := store.Save("hotel.toml", &hotel); err != nil {
		log.Println("failed to save the cat hotel:", err)
		return
	}
}
```

Store supports any other formats via the handy registration system: register the format once and you'd be able to Load and Save files in it afterwards:
```go
store.Register("ini", ini.Marshal, ini.Unmarshal)

err := store.Load("configuration.ini", &object)
// ...
```


store

Cross platform package that follows the [XDG Standard](https://specifications.freedesktop.org/basedir-spec/latest/).

# XDG [![Build status](https://ci.appveyor.com/api/projects/status/9eoupq9jgsu2p0jv?svg=true)](https://ci.appveyor.com/project/dixonwille/xdg) [![Build Status](https://travis-ci.org/OpenPeeDeeP/xdg.svg?branch=master)](https://travis-ci.org/OpenPeeDeeP/xdg) [![Go Report Card](https://goreportcard.com/badge/github.com/OpenPeeDeeP/xdg)](https://goreportcard.com/report/github.com/OpenPeeDeeP/xdg) [![GoDoc](https://godoc.org/github.com/OpenPeeDeeP/xdg?status.svg)](https://godoc.org/github.com/OpenPeeDeeP/xdg) [![codecov](https://codecov.io/gh/OpenPeeDeeP/xdg/branch/master/graph/badge.svg)](https://codecov.io/gh/OpenPeeDeeP/xdg)

A cross platform package that tries to follow [XDG Standard](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) when possible. Since XDG is linux specific, I am only able to follow standards to the T on linux. But for the other operating systems I am finding similar best practice locations for the files.

## Locations Per OS

The following table shows what is used if the envrionment variable is not set. If the variable is set then this package uses that. Linux follows the default standards. Mac does when it comes to the home directory but for system wide it uses the standard `/Library/Application Support`. As for Windows, the variable defaults are just other environment variables set up by the operation system.

> When creating `XDG` application the `Vendor` and `Application` names are appeneded to the end of the path to keep projects unique.

|  | Linux(and BSD) | Mac | Windows |
| ---: | :---: | :---: | :---: |
| `XDG_DATA_DIRS` | [`/usr/local/share`, `/usr/share`] | [`/Library/Application Support`] | `%PROGRAMDATA%` |
| `XDG_DATA_HOME` | `~/.local/share` | `~/Library/Application Support` | `%APPDATA%` |
| `XDG_CONFIG_DIRS` | [`/etc/xdg`] | [`/Library/Application Support`] | `%PROGRAMDATA%` |
| `XDG_CONFIG_HOME` | `~/.config` | `~/Library/Application Support` | `%APPDATA%` |
| `XDG_CACHE_HOME` | `~/.cache` | `~/Library/Caches` | `%LOCALAPPDATA%` |

## Notes

- This package does not merge files if they exist across different directories.
- The `Query` methods search through the system variables, `DIRS`, first (when using environment variables first in the variable has presidence). It then checks home variables, `HOME`.
- This package will not create any directories for you. In the standard, it states the following:

> If, when attempting to write a file, the destination directory is non-existant an attempt should be made to create it with permission `0700`. If the destination directory exists already the permissions should not be changed. The application should be prepared to handle the case where the file could not be written, either because the directory was non-existant and could not be created, or for any other reason. In such case it may chose to present an error message to the user.
