config/README.md

## Introduction
**config** is a simple golang library and designed to read configurations from JSON, Yaml files, environment variables and command line. **config** depends on [go-yaml](https://github.com/go-yaml/yaml) to anlayze Yaml file and uses built-in golang library to handle JSON file.

## Installation
1. Install [Yaml](https://github.com/go-yaml/yaml) library first:
```
go get gopkg.in/yaml.v2
```

2. Install **config** library:
```
go get github.com/eschao/config
```

## Usage
### I. Define configuration name in structure tags
Like JSON, Yaml, **config** uses tags to define configurations:

| Tag | Example | Function |
|-----|---------|------|
| json | Host string `json:"host"` | Maps `Host` to a JSON field: **host** |
| yaml | Host string `yaml:"host"` | Maps `Host` to a Yaml field: **host** |
| env | Host string `env:"HOST"` | Maps `Host` to a Environment variable: **HOST** |
| cli | Host string `cli:"host database host"` | Maps `Host` to a command line argument: **-host** or **--host** |
| default | Port int `default:"8080"` | Defines the port with default value: **8080** |
| separator | Path string `json:"path" separator:";"` | Separator is used to split string to a slice |


#### 1. Data types
 **config** supports the following golang data types:
  * bool
  * string
  * int8, int16, int, int32, int64
  * uint8, uint16, uint, uint32, uint64
  * float32, float64
  * slice type. e.g: []string, []int ...
  
#### 2. Defines **default** values
Using **default** keyword in structure tags to define default value:
```golang
  type Log struct {
    Path  string `default:"/var/logs"`
    Level string `default:"debug"`
  }
```

#### 3. Defines configruation name for JSON
Like parsing JSON object, using **json** keyword to define configuration name:
```golang
  type Database struct {
    Host     string `json:"host"`
    Port     int    `json:"port"`
    Username string `json:"username" default:"admin"`
    Password string `json:"password" default:"admin"`
    Log      Log    `json:"log"`
  }
```

Corresponding JSON file:
```json
 {
   "host": "test.db.hostname",
   "port": 8080,
   "username": "amdin",
   "password": "admin",
   "log": {
     "path": "/var/logs/db",
     "level": "debug"
   }
 }
 ```

#### 4. Defines configuration name for Yaml
Like parsing Yaml object, using **yaml** keyword to define configuration name
```golang
  type Database struct {
    Host     string `yaml:"host"`
    Port     int    `yaml:"port"`
    Username string `yaml:"username" default:"admin"`
    Password string `yaml:"password" default:"admin"`
    Log      Log    `yaml:"log"`
  }
```
Corresponding Yaml file:
```yaml
 host: test.db.hostname
 port: 8080
 username: amdin
 password: admin
 log:
   path: /var/logs/db
   level: debug
 ```
 
#### 5. Defines configuration name for Environment variable
Using **env** keyword to define configuration name
```golang
  type Database struct {
    Host     string `env:"DB_HOST"`
    Port     int    `env:"DB_PORT"`
    Username string `env:"DB_USER" default:"admin"`
    Password string `env:"DB_PASSWORD" default:"admin"`
    Log      Log    `env:"DB_LOG_"`
  }
```

Corresponding Environment variables:
```shell
 export DB_HOST=test.db.hostname
 export DB_PORT=8080
 export DB_USER=admin
 export DB_PASSWORD=admin
 export DB_LOG_PATH=/var/logs/db
 export DB_LOG_LEVEL=debug
```
Since the ```Log``` is a structure and nested in ```Database``` structure, the tag of ```Log``` and tags of its structure members will be combined to be an unique environment variable, for example: ```Path``` will be mapped to environment var: ```DB_LOG_PATH```. But if the ```Log``` has no tag definition, only tags of its structure members will be used, that means the ```Path``` will be mapped to ```PATH```.

#### 6. Defines configuration name for Command line
Using **cli** keyword to define configuration name
```golang
  type Database struct {
    Host     string `cli:"host database host name"`
    Port     int    `cli:"port database port"`
    Username string `cli:"username database username" default:"admin"`
    Password string `cli:"password database password" default:"admin"`
    Log      Log    `cli:"log database log configurations"`
  }
```
For **cli** definition, the string before the first space is command line argument, the rest string are the command line usage and will be oupputed when printing usage

Corresponding command line:
```shell
  ./main -host test.db.hostname -port 8080 -username admin -password admin log -path /var/logs/db -level debug
```
or
```shell
  ./main -host=test.db.hostname -port=8080 -username=admin -password=admin log -path=/var/logs/db -level=debug
```

#### 7. Defines configuration name as a slice type
Using **separator** to split string as a slice:
```golang
  type Log struct {
    Levels []string `env:"LEVELS" cli:"levels log levels" separator:";"`
  }
```

If the separator is not given, its default is **:**, The separator only works on **env** and **cli** tags
```golang
  logConfig := Log{}
  // export LEVELS=debug;error;info
  config.ParseEnv(&logConfig)
  // logConfig[0] == debug
  // logConfig[1] == error
  // logConfig[2] == info
```

### II. Parses configurations
#### 1. Parses default values
When default values are defined in tags, calls ```config.ParseDefault(interface{})``` to assign them to given structure instance **BEFORE** parsing any other configuration types:
```golang
  logConfig := Log{}
  config.ParseDefault(&logConfig)
```
>Note: Other parsing functions don't set structure instance with default values whatever if the configuration value is provided or not

#### 2. Parses from Environment variables
```golang
  dbConfig := Database{}
  config.ParseEnv(&dbConfig)
```

#### 3. Parses from Command line
```golang
  dbConfig := Database{}
  config.ParseCli(&dbConfig)
```

#### 4. Parses from default configuration files
Calls **ParseConfigFile(interface{}, string)** to parse given configuration file:
```golang
  dbConfig := Database{}
  config.ParseConfigFile(&dbConfig, "config.json")
```

If the configuration file is not given, the default configuration files: **config.json** and **config.yaml** will be located under the same folder with fixed searching order.

The **config.json** will always be located first, if it doesn't exist, then checks **config.yaml**. If all of them are not found, parsing will fail.
```golang
  dbConfig := Database{}
  config.ParseConfigFile(&dbConfig, "")
```

#### 4. Parses from configuration file specified by command line
Calls **ParseConfig(interface{}, string)** to parse the configuration file given by command line. The second parameter is a command line argument which is used to specifiy config file:
```golang
  dbConfig := Database{}
  config.ParseConfig(&dbConfig, "c")
```
Run application like:
```shell
  ./main -c config.json
```
**ParseConfig()** will analyze command line arguments and get configure file: **config.json** from argument **-c**

### III. Multi-Configurations 
You can define all supported configuration tags in a structure and call corresponding functions in your desired order to parse.

Examples:
```golang
  type Log struct {
    Path   string `json:"path" yaml:"path" env:"PATH" cli:"path log path" default:"/var/logs"`
    Levels string `json:"levels" yaml:"levels" env:"LEVELS" cli:"levels log levels" default:"debug;error"`
  }
  
  type Database struct {
    Host     string `json:"host"   yaml:"host"   env:"DB_HOST"   cli:"host database host name"`
    Port     int    `json:"port"   yaml:"port"   env:"DB_PORT"   cli:"port database port"`
    Username string `json:"user"   yaml" user"   env:"DB_USER"   cli:"username database username" default:"admin"`
    Password string `json:"passwd" yaml:"passwd" env:"DB_PASSWD" cli:"password database password" default:"admin"`
    Log      Log    `json:"log"    yaml:"log"    env:"DB_LOG_"   cli:"log database log configurations"`
  }
```
Then, you can parse as below:
```golang
 dbConfig := Database{}
 
 // parse default values
 if err := config.ParseDefault(&dbConfig); err != nil {
   // error handling
 }

 // parse configuration file from command line
 err := config.ParseConfig(&dbConfig, "c")
 
 // parse default configurations
 if err != nil {
   err = config.ParseConfigFile(&dbConfig), "")
 }
 
 // parse environment variables
 if err != nil {
   err = config.ParseEnv(&dbConfig)
 }
 
 // parse command line
 if err != nil {
   err = config.ParseCli(&dbConfig)
 }
 
 // check if all requried configurations are set
 ...
```

You don't need to call all of them. Just invokes parsing function that your need.

## License
This project is licensed under the Apache License Version 2.0.