{"id":18267721,"url":"https://github.com/eschao/config","last_synced_at":"2025-04-04T22:30:39.954Z","repository":{"id":57500174,"uuid":"113294114","full_name":"eschao/config","owner":"eschao","description":"A golang library for reading configurations from JSON, Yaml files, environment variables and command line ","archived":false,"fork":false,"pushed_at":"2020-03-06T14:54:03.000Z","size":673,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-20T20:14:28.395Z","etag":null,"topics":["cli","command-line","configuration","environment-variables","go","json","yaml"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eschao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-06T09:11:16.000Z","updated_at":"2024-09-25T08:40:00.000Z","dependencies_parsed_at":"2022-08-28T16:10:48.246Z","dependency_job_id":null,"html_url":"https://github.com/eschao/config","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eschao%2Fconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eschao%2Fconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eschao%2Fconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eschao%2Fconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eschao","download_url":"https://codeload.github.com/eschao/config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247260286,"owners_count":20909977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","configuration","environment-variables","go","json","yaml"],"created_at":"2024-11-05T11:28:37.168Z","updated_at":"2025-04-04T22:30:39.568Z","avatar_url":"https://github.com/eschao.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Introduction\n**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.\n\n## Installation\n1. Install [Yaml](https://github.com/go-yaml/yaml) library first:\n```\ngo get gopkg.in/yaml.v2\n```\n\n2. Install **config** library:\n```\ngo get github.com/eschao/config\n```\n\n## Usage\n### I. Define configuration name in structure tags\nLike JSON, Yaml, **config** uses tags to define configurations:\n\n| Tag | Example | Function |\n|-----|---------|------|\n| json | Host string `json:\"host\"` | Maps `Host` to a JSON field: **host** |\n| yaml | Host string `yaml:\"host\"` | Maps `Host` to a Yaml field: **host** |\n| env | Host string `env:\"HOST\"` | Maps `Host` to a Environment variable: **HOST** |\n| cli | Host string `cli:\"host database host\"` | Maps `Host` to a command line argument: **-host** or **--host** |\n| default | Port int `default:\"8080\"` | Defines the port with default value: **8080** |\n| separator | Path string `json:\"path\" separator:\";\"` | Separator is used to split string to a slice |\n\n\n#### 1. Data types\n **config** supports the following golang data types:\n  * bool\n  * string\n  * int8, int16, int, int32, int64\n  * uint8, uint16, uint, uint32, uint64\n  * float32, float64\n  * slice type. e.g: []string, []int ...\n  \n#### 2. Defines **default** values\nUsing **default** keyword in structure tags to define default value:\n```golang\n  type Log struct {\n    Path  string `default:\"/var/logs\"`\n    Level string `default:\"debug\"`\n  }\n```\n\n#### 3. Defines configruation name for JSON\nLike parsing JSON object, using **json** keyword to define configuration name:\n```golang\n  type Database struct {\n    Host     string `json:\"host\"`\n    Port     int    `json:\"port\"`\n    Username string `json:\"username\" default:\"admin\"`\n    Password string `json:\"password\" default:\"admin\"`\n    Log      Log    `json:\"log\"`\n  }\n```\n\nCorresponding JSON file:\n```json\n {\n   \"host\": \"test.db.hostname\",\n   \"port\": 8080,\n   \"username\": \"amdin\",\n   \"password\": \"admin\",\n   \"log\": {\n     \"path\": \"/var/logs/db\",\n     \"level\": \"debug\"\n   }\n }\n ```\n\n#### 4. Defines configuration name for Yaml\nLike parsing Yaml object, using **yaml** keyword to define configuration name\n```golang\n  type Database struct {\n    Host     string `yaml:\"host\"`\n    Port     int    `yaml:\"port\"`\n    Username string `yaml:\"username\" default:\"admin\"`\n    Password string `yaml:\"password\" default:\"admin\"`\n    Log      Log    `yaml:\"log\"`\n  }\n```\nCorresponding Yaml file:\n```yaml\n host: test.db.hostname\n port: 8080\n username: amdin\n password: admin\n log:\n   path: /var/logs/db\n   level: debug\n ```\n \n#### 5. Defines configuration name for Environment variable\nUsing **env** keyword to define configuration name\n```golang\n  type Database struct {\n    Host     string `env:\"DB_HOST\"`\n    Port     int    `env:\"DB_PORT\"`\n    Username string `env:\"DB_USER\" default:\"admin\"`\n    Password string `env:\"DB_PASSWORD\" default:\"admin\"`\n    Log      Log    `env:\"DB_LOG_\"`\n  }\n```\n\nCorresponding Environment variables:\n```shell\n export DB_HOST=test.db.hostname\n export DB_PORT=8080\n export DB_USER=admin\n export DB_PASSWORD=admin\n export DB_LOG_PATH=/var/logs/db\n export DB_LOG_LEVEL=debug\n```\nSince 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```.\n\n#### 6. Defines configuration name for Command line\nUsing **cli** keyword to define configuration name\n```golang\n  type Database struct {\n    Host     string `cli:\"host database host name\"`\n    Port     int    `cli:\"port database port\"`\n    Username string `cli:\"username database username\" default:\"admin\"`\n    Password string `cli:\"password database password\" default:\"admin\"`\n    Log      Log    `cli:\"log database log configurations\"`\n  }\n```\nFor **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\n\nCorresponding command line:\n```shell\n  ./main -host test.db.hostname -port 8080 -username admin -password admin log -path /var/logs/db -level debug\n```\nor\n```shell\n  ./main -host=test.db.hostname -port=8080 -username=admin -password=admin log -path=/var/logs/db -level=debug\n```\n\n#### 7. Defines configuration name as a slice type\nUsing **separator** to split string as a slice:\n```golang\n  type Log struct {\n    Levels []string `env:\"LEVELS\" cli:\"levels log levels\" separator:\";\"`\n  }\n```\n\nIf the separator is not given, its default is **:**, The separator only works on **env** and **cli** tags\n```golang\n  logConfig := Log{}\n  // export LEVELS=debug;error;info\n  config.ParseEnv(\u0026logConfig)\n  // logConfig[0] == debug\n  // logConfig[1] == error\n  // logConfig[2] == info\n```\n\n### II. Parses configurations\n#### 1. Parses default values\nWhen default values are defined in tags, calls ```config.ParseDefault(interface{})``` to assign them to given structure instance **BEFORE** parsing any other configuration types:\n```golang\n  logConfig := Log{}\n  config.ParseDefault(\u0026logConfig)\n```\n\u003eNote: Other parsing functions don't set structure instance with default values whatever if the configuration value is provided or not\n\n#### 2. Parses from Environment variables\n```golang\n  dbConfig := Database{}\n  config.ParseEnv(\u0026dbConfig)\n```\n\n#### 3. Parses from Command line\n```golang\n  dbConfig := Database{}\n  config.ParseCli(\u0026dbConfig)\n```\n\n#### 4. Parses from default configuration files\nCalls **ParseConfigFile(interface{}, string)** to parse given configuration file:\n```golang\n  dbConfig := Database{}\n  config.ParseConfigFile(\u0026dbConfig, \"config.json\")\n```\n\nIf 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.\n\nThe **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.\n```golang\n  dbConfig := Database{}\n  config.ParseConfigFile(\u0026dbConfig, \"\")\n```\n\n#### 4. Parses from configuration file specified by command line\nCalls **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:\n```golang\n  dbConfig := Database{}\n  config.ParseConfig(\u0026dbConfig, \"c\")\n```\nRun application like:\n```shell\n  ./main -c config.json\n```\n**ParseConfig()** will analyze command line arguments and get configure file: **config.json** from argument **-c**\n\n### III. Multi-Configurations \nYou can define all supported configuration tags in a structure and call corresponding functions in your desired order to parse.\n\nExamples:\n```golang\n  type Log struct {\n    Path   string `json:\"path\" yaml:\"path\" env:\"PATH\" cli:\"path log path\" default:\"/var/logs\"`\n    Levels string `json:\"levels\" yaml:\"levels\" env:\"LEVELS\" cli:\"levels log levels\" default:\"debug;error\"`\n  }\n  \n  type Database struct {\n    Host     string `json:\"host\"   yaml:\"host\"   env:\"DB_HOST\"   cli:\"host database host name\"`\n    Port     int    `json:\"port\"   yaml:\"port\"   env:\"DB_PORT\"   cli:\"port database port\"`\n    Username string `json:\"user\"   yaml\" user\"   env:\"DB_USER\"   cli:\"username database username\" default:\"admin\"`\n    Password string `json:\"passwd\" yaml:\"passwd\" env:\"DB_PASSWD\" cli:\"password database password\" default:\"admin\"`\n    Log      Log    `json:\"log\"    yaml:\"log\"    env:\"DB_LOG_\"   cli:\"log database log configurations\"`\n  }\n```\nThen, you can parse as below:\n```golang\n dbConfig := Database{}\n \n // parse default values\n if err := config.ParseDefault(\u0026dbConfig); err != nil {\n   // error handling\n }\n\n // parse configuration file from command line\n err := config.ParseConfig(\u0026dbConfig, \"c\")\n \n // parse default configurations\n if err != nil {\n   err = config.ParseConfigFile(\u0026dbConfig), \"\")\n }\n \n // parse environment variables\n if err != nil {\n   err = config.ParseEnv(\u0026dbConfig)\n }\n \n // parse command line\n if err != nil {\n   err = config.ParseCli(\u0026dbConfig)\n }\n \n // check if all requried configurations are set\n ...\n```\n\nYou don't need to call all of them. Just invokes parsing function that your need.\n\n## License\nThis project is licensed under the Apache License Version 2.0.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feschao%2Fconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feschao%2Fconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feschao%2Fconfig/lists"}