{"id":13411235,"url":"https://github.com/romshark/yamagiconf","last_synced_at":"2025-04-21T02:32:09.300Z","repository":{"id":239029095,"uuid":"798286045","full_name":"romshark/yamagiconf","owner":"romshark","description":"The magic YAML configuration framework for Go","archived":false,"fork":false,"pushed_at":"2024-10-16T00:22:44.000Z","size":322,"stargazers_count":16,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-17T11:52:41.101Z","etag":null,"topics":["config","configuration","go","golang","parser","yaml","yaml-configuration"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/romshark.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-09T13:25:53.000Z","updated_at":"2024-10-16T00:19:22.000Z","dependencies_parsed_at":"2024-10-17T07:13:12.699Z","dependency_job_id":"ddf4b6c1-a84c-4325-aa89-10c5c3e08b22","html_url":"https://github.com/romshark/yamagiconf","commit_stats":null,"previous_names":["romshark/yamagiconf"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romshark%2Fyamagiconf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romshark%2Fyamagiconf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romshark%2Fyamagiconf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romshark%2Fyamagiconf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/romshark","download_url":"https://codeload.github.com/romshark/yamagiconf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223846176,"owners_count":17213132,"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":["config","configuration","go","golang","parser","yaml","yaml-configuration"],"created_at":"2024-07-30T20:01:12.351Z","updated_at":"2024-11-09T15:32:22.204Z","avatar_url":"https://github.com/romshark.png","language":"Go","funding_links":[],"categories":["配置","Configuration"],"sub_categories":["标准CLI","Standard CLI"],"readme":"![yamagiconf](https://github.com/romshark/yamagiconf/assets/9574743/9d4f5b77-a461-47b2-8f6f-65194755b4f1)\n\n\u003ca href=\"https://pkg.go.dev/github.com/romshark/yamagiconf\"\u003e\n    \u003cimg src=\"https://godoc.org/github.com/romshark/yamagiconf?status.svg\" alt=\"GoDoc\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://goreportcard.com/report/github.com/romshark/yamagiconf\"\u003e\n    \u003cimg src=\"https://goreportcard.com/badge/github.com/romshark/yamagiconf\" alt=\"GoReportCard\"\u003e\n\u003c/a\u003e\n\u003ca href='https://coveralls.io/github/romshark/yamagiconf?branch=main'\u003e\n    \u003cimg src='https://coveralls.io/repos/github/romshark/yamagiconf/badge.svg?branch=main' alt='Coverage Status' /\u003e\n\u003c/a\u003e\n\n# yamagiconf\n\nThe heavily opinionated **YA**ML **Magi**c **Conf**iguration framework for Go\nkeeps your configs simple and consistent\nby being *more restrictive than your regular YAML parser* 🚷 allowing only a subset of YAML\nand enforcing some restrictions to the target Go type.\n\nIf you hate [YAML](https://yaml.org/), and you're afraid of\n[YAML documents from hell](https://ruudvanasseldonk.com/2023/01/11/the-yaml-document-from-hell),\nand you can't stand complex, unexplorable and unintuitive configurations then yamagiconf is for you!\n\n🪄 It's magic because it uses [reflect](https://pkg.go.dev/reflect) to find recursively all\nvalues of types that implement `interface { Validate() error }` and calls them reporting\nan error annotated with line and column in the YAML file if necessary.\n\n## (anti-)Features\n\n- Go restrictions:\n\t- 🚫 Forbids recursive Go types.\n\t- 🚫 Forbids the use of `any`, `int` \u0026 `uint` (unspecified width), and other types.\n\tOnly maps, slices, arrays and deterministic primitives are allowed.\n\t- ❗️ Requires `yaml` struct tags on all exported fields.\n\t- ❗️ Requires `env` struct tags to be POSIX-style.\n\t- 🚫 Forbids the use of `env` struct tag on non-primitive fields.\n\tAllows only floats, ints, strings, bool and types that implement the\n\t[`encoding.TextUnmarshaler`](https://pkg.go.dev/encoding#TextUnmarshaler) interface.\n\t- 🚫 Forbids the use of `env` on primitive fields implementing\n\tthe [`yaml.Unmarshaler`](https://pkg.go.dev/gopkg.in/yaml.v3#Unmarshaler) interface.\n\t- 🚫 Forbids the use of `yaml` and `env` struct tags within implementations of\n\t[`encoding.TextUnmarshaler`](https://pkg.go.dev/encoding#TextUnmarshaler) and/or\n\t[`yaml.Unmarshaler`](https://pkg.go.dev/gopkg.in/yaml.v3#Unmarshaler).\n\t- 🚫 Forbids the use of YAML struct tag option `\"inline\"` for non-embedded structs and\n\trequires embedded structs to use option `\"inline\"`.\n- YAML restrictions:\n\t- 🚫 Forbids the use of `no`, `yes`, `on` and `off` for `bool`,\n\tallows only `true` and `false`.\n\t- 🚫 Forbids the use of `~`, `Null` and other variations, allows only `null` for nilables.\n\t- 🚫 Forbids assigning `null` to non-nilables (which normally would assign zero value).\n\t- 🚫 Forbids fields in the YAML file that aren't specified by the Go type.\n\t- 🚫 Forbids the use of [YAML tags](https://yaml.org/spec/1.2.2/#3212-tags).\n\t- 🚫 Forbids redeclaration of anchors.\n\t- 🚫 Forbids unused anchors.\n\t- 🚫 Forbids anchors with implicit `null` value (no value) like `foo: \u0026bar`.\n\t- ❗️ Requires fields specified in the configuration type to be present in the YAML file.\n\t- 🚫 Forbids assigning non-string values to Go types that implement\n\tthe [`encoding.TextUnmarshaler`](https://pkg.go.dev/encoding#TextUnmarshaler) interface.\n\t- 🚫 Forbids empty array items ([see rationale](#why-are-empty-array-items-forbidden)).\n\t- 🚫 Forbids multi-document files.\n\t- 🚫 Forbids [YAML merge keys](https://yaml.org/type/merge.html).\n- Features:\n\t- 🪄 If any type within your configuration struct implements the `Validate` interface,\n\tthen its validation method will be called using reflection\n\t(doesn't apply to unexported fields which are invisible to `reflect`).\n\tIf it returns an error - the error will be reported.\n\tKeeps your validation logic close to your configuration type definitions.\n\t- Reports errors by `line:column` when possible.\n\t- Supports [github.com/go-playground/validator](https://github.com/go-playground/validator)\n\tvalidation struct tags.\n\t- Implements `env` struct tags to overwrite fields from env vars if provided.\n\t- Supports [`encoding.TextUnmarshaler`](https://pkg.go.dev/encoding#TextUnmarshaler)\n\tand [`yaml.Unmarshaler`](https://pkg.go.dev/gopkg.in/yaml.v3#Unmarshaler)\n\t(except for the root struct type).\n\t- Supports `time.Duration`.\n\n## Example\n\nhttps://go.dev/play/p/PjV0aG7uIUH\n\n```yaml\nlist:\n  - foo: valid\n    bar: valid\n  - foo: valid\n    bar: valid\nmap:\n  valid: valid\nsecret: 'this will be overwritten from env var SECRET'\nrequired: 'this must not be empty'\n```\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/romshark/yamagiconf\"\n)\n\ntype Config struct {\n\tList []Struct                            `yaml:\"list\"`\n\tMap  map[ValidatedString]ValidatedString `yaml:\"map\"`\n\n\t// Secret will be overwritten if env var SECRET is set.\n\tSecret string `yaml:\"secret\" env:\"SECRET\"`\n\n\t// See https://github.com/go-playground/validator\n\t// for all available validation tags\n\tRequired string `yaml:\"required\" validate:\"required\"`\n}\n\ntype Struct struct {\n\tFoo string          `yaml:\"foo\"`\n\tBar ValidatedString `yaml:\"bar\"`\n}\n\n// Validate will automatically be called by yamagiconf\nfunc (v *Struct) Validate() error {\n\tif v.Foo == \"invalid\" {\n\t\treturn fmt.Errorf(\"invalid foo\")\n\t}\n\tif v.Bar == \"invalid\" {\n\t\treturn fmt.Errorf(\"invalid bar\")\n\t}\n\treturn nil\n}\n\ntype ValidatedString string\n\n// Validate will automatically be called by yamagiconf\nfunc (v ValidatedString) Validate() error {\n\tif v == \"invalid\" {\n\t\treturn fmt.Errorf(\"string is invalid\")\n\t}\n\treturn nil\n}\n\nfunc main() {\n\tvar c Config\n\tif err := yamagiconf.LoadFile(\"./config.yaml\", \u0026c); err != nil {\n\t\tfmt.Println(\"Whoops, something is wrong with your config!\", err)\n\t}\n\tfmt.Printf(\"%#v\\n\", c)\n}\n```\n\n## FAQ\n\n### \n\n### Why are empty array items forbidden?\n\nConsider the following YAML array:\n\n```yaml\narray:\n  - \n  - ''\n  - \"\"\n  - x\n```\n\nEven though this YAML array works as expect with a Go array:\n`[4]string{\"\", \"\", \"\", \"x\"}`, parsing the same YAML into a Go slice will result in\nthe empty item being ommited: `[]string{\"\", \"\", \"x\"}` which is counterintuitive.\nTherefore, yamagiconf forbids empty array items in general to keep behavior\nconsistent and intuitive independent of the Go target type.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromshark%2Fyamagiconf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromshark%2Fyamagiconf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromshark%2Fyamagiconf/lists"}