{"id":47607438,"url":"https://github.com/o3co/go.hocon","last_synced_at":"2026-06-14T04:01:03.851Z","repository":{"id":345244913,"uuid":"1184973948","full_name":"o3co/go.hocon","owner":"o3co","description":"Full Lightbend HOCON spec-compliant parser and config library for Go","archived":false,"fork":false,"pushed_at":"2026-06-14T02:15:21.000Z","size":639,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-06-14T02:23:42.244Z","etag":null,"topics":["config","configuration","go","golang","hocon","lightbend","parser"],"latest_commit_sha":null,"homepage":null,"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/o3co.png","metadata":{"files":{"readme":"README.ja.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T05:35:00.000Z","updated_at":"2026-06-14T02:06:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/o3co/go.hocon","commit_stats":null,"previous_names":["o3co/go.hocon"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/o3co/go.hocon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3co%2Fgo.hocon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3co%2Fgo.hocon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3co%2Fgo.hocon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3co%2Fgo.hocon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/o3co","download_url":"https://codeload.github.com/o3co/go.hocon/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3co%2Fgo.hocon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34308622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","hocon","lightbend","parser"],"created_at":"2026-04-01T19:36:19.963Z","updated_at":"2026-06-14T04:01:03.841Z","avatar_url":"https://github.com/o3co.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go.hocon — Go 向け HOCON パーサー\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/o3co/go.hocon.svg)](https://pkg.go.dev/github.com/o3co/go.hocon)\n[![Go Report Card](https://goreportcard.com/badge/github.com/o3co/go.hocon)](https://goreportcard.com/report/github.com/o3co/go.hocon)\n[![CI](https://github.com/o3co/go.hocon/actions/workflows/test.yml/badge.svg)](https://github.com/o3co/go.hocon/actions/workflows/test.yml)\n[![Lint](https://github.com/o3co/go.hocon/actions/workflows/lint.yml/badge.svg)](https://github.com/o3co/go.hocon/actions/workflows/lint.yml)\n[![codecov](https://codecov.io/gh/o3co/go.hocon/branch/develop/graph/badge.svg)](https://codecov.io/gh/o3co/go.hocon)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n[Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) 仕様の Go パーサー。現在の準拠率は [仕様準拠](#仕様準拠) を参照。\n\n\u003e **[Claude](https://claude.ai/)（Anthropic）による実装** — 設計・実装のすべてを Claude Code が担当。\n\u003e [GitHub Copilot](https://github.com/features/copilot) および [OpenAI Codex](https://openai.com/index/openai-codex/) によるレビュー。\n\n[English](README.md)\n\n---\n\n## クイックスタート\n\n### 1. インストール\n\n```bash\ngo get github.com/o3co/go.hocon\n```\n\nGo 1.21 以上が必要。\n\n### 2. 使い方\n\n```go\nimport \"github.com/o3co/go.hocon\"\n\ncfg, err := hocon.ParseString(`\n  server {\n    host = \"localhost\"\n    port = 8080\n  }\n`)\nif err != nil {\n    log.Fatal(err)\n}\n\nhost := cfg.GetString(\"server.host\")  // \"localhost\"\nport := cfg.GetInt(\"server.port\")     // 8080\n```\n\n## なぜ HOCON？\n\n| | `.env` | JSON | YAML | HOCON |\n|---|---|---|---|---|\n| Comments | No | No | Yes | Yes |\n| Nesting | No | Yes | Yes | Yes |\n| References / Substitution | No | No | No | Yes (`${var}`) |\n| File inclusion | No | No | No | Yes (`include`) |\n| Object merging | No | No | Anchors (fragile) | Yes (deep merge) |\n| Optional values | No | No | No | Yes (`${?var}`) |\n| Trailing commas | N/A | No | N/A | Yes |\n| Unquoted strings | Yes | No | Yes | Yes |\n\nHOCON は単なるシリアライズ形式ではなく、**プログラムに注入するための設定言語** です。JSON / YAML / TOML はデータ構造の表現に徹しており、ファイルの重ね合わせ・環境変数・参照解決はアプリ側（Pydantic、Serde、Zod 等）の責務になります。HOCON はそれらを仕様そのものに内包しているため、プログラムが設定を受け取る時点で、フォールバックは合成済み・`${VAR}` 参照は解決済みの「1 枚の設定」になっています。「このレイヤーに値があるか？」に由来する条件分岐は、コードではなくフォーマット境界で消えます。\n\n加えて HOCON は YAML の可読性と JSON の構造性を兼ね備えるため、フラットなキーバリュー設定を超えるユースケースには強い選択肢になります。\n\n## 特徴\n\n- HOCON の全構文をサポート：オブジェクト、配列、スカラー、代入（`${path}`、`${?path}`）\n- 自己参照代入（`path = ${path} [\"/extra\"]`）\n- 重複キーのディープマージ（後勝ちセマンティクス）\n- `+=` 追記演算子\n- `include \"file.conf\"` および `include file(\"file.conf\")` ディレクティブ\n- トリプルクォート文字列（`\"\"\"...\"\"\"`）\n- Duration パース（`10ms`、`2s`、`1h`、`1d`）\n- バイトサイズパース（`1KB`、`1KiB`、`1MB`、...）\n- 安全な省略値アクセスのためのジェネリック `Option[T]`\n- `hocon` 構造体タグによる Unmarshal\n- 外部依存ゼロ — 標準ライブラリのみ\n\n## API\n\n### パース\n\n```go\nhocon.ParseString(input string) (*Config, error)\nhocon.ParseFile(path string)    (*Config, error)\n```\n\n### スカラーゲッター\n\n| メソッド | 戻り値 | パニック条件 |\n|---------|-------|------------|\n| `GetString(path)` | `string` | missing・null・型違い |\n| `GetInt(path)` | `int` | missing・null・型違い |\n| `GetInt64(path)` | `int64` | missing・null・型違い |\n| `GetFloat64(path)` | `float64` | missing・null・型違い |\n| `GetFloat32(path)` | `float32` | missing・null・型違い |\n| `GetBool(path)` | `bool` | missing・null・型違い |\n| `GetDuration(path)` | `time.Duration` | missing・null・不正フォーマット |\n| `GetBytes(path)` | `int64` | missing・null・不正フォーマット |\n\nそれぞれに `GetXxxOption(path) Option[T]` 版があり、パニックの代わりに `None` を返す。\n\n### スライスゲッター\n\n```go\ncfg.GetStringSlice(path)   []string\ncfg.GetInt64Slice(path)    []int64\ncfg.GetIntSlice(path)      []int\ncfg.GetConfigSlice(path)   []*Config\n```\n\nそれぞれに `GetXxxSliceOption` 版あり。\n\n### オブジェクトアクセス\n\n```go\nsub := cfg.GetConfig(\"server\")        // \"server\" スコープの *Config\nopt := cfg.GetConfigOption(\"server\")  // Option[*Config]\n```\n\n### 検査\n\n```go\ncfg.Has(\"server.host\")  // null 値でも true\ncfg.Keys()              // 直接の子キー一覧（宣言順）\n```\n\n### フォールバックマージ\n\n```go\nmerged := overrides.WithFallback(defaults)\n// overrides が優先。defaults は不足キーを補完する\n```\n\n### Option[T]\n\n```go\nopt := cfg.GetStringOption(\"key\")\nif opt.IsSome() {\n    v, _ := opt.Get()\n}\nv := opt.OrElse(\"default\")\n```\n\n### Unmarshal\n\n```go\ntype ServerConfig struct {\n    Host    string        `hocon:\"host\"`\n    Port    int           `hocon:\"port\"`\n    Timeout time.Duration `hocon:\"timeout,omitempty\"`\n    Tags    []string      `hocon:\"tags\"`\n}\n\nvar s ServerConfig\nerr := cfg.Unmarshal(\u0026s)\n\n// map[string]any も対応\nm := make(map[string]any)\nerr = cfg.Unmarshal(\u0026m)\n```\n\n`hocon` タグがないフィールドはフィールド名を小文字化したキーで検索する。`omitempty` はキーが存在しないとき、フィールドの既存値を保持する。\n\n### エラー型\n\n```go\nvar pe *hocon.ParseError   // 字句解析・構文解析エラー — Line, Col, FilePath を持つ\nvar re *hocon.ResolveError // 代入・include 解決エラー — Path を持つ\nvar ce *hocon.ConfigError  // GetXxx パニックのペイロード — Path を持つ\n```\n\n## HOCON の例\n\n```hocon\n# コメントは # または //\ndatabase {\n  host = \"db.example.com\"\n  port = 5432\n  url  = \"jdbc:\"${database.host}\":\"${database.port}  // 代入 + 文字列連結\n}\n\n# 重複キーはディープマージ（スカラーは後勝ち）\nserver { host = localhost }\nserver { port = 8080 }      // 結果: { host: localhost, port: 8080 }\n\n# 自己参照追記\npath = [\"/usr/bin\"]\npath = ${path} [\"/usr/local/bin\"]  // [\"/usr/bin\", \"/usr/local/bin\"]\n\n# += 演算子（値を 1 要素として追記: a += b ≡ a = ${?a} [b]）\nitems = [1]\nitems += 2        // [1, 2]\nitems += [3, 4]   // [1, 2, [3, 4]]  （配列を渡すと 1 つのネスト要素として追記）\n\n# インクルード\ninclude \"defaults.conf\"\ninclude file(\"overrides.conf\")\n\n# Duration・バイトサイズ\ntimeout   = \"30s\"\ncache-ttl = \"5m\"\nmax-size  = \"512MiB\"\n```\n\n## 仕様準拠\n\n[Lightbend HOCON 仕様](https://github.com/lightbend/config/blob/main/HOCON.md) への準拠状況は [`docs/spec-compliance.md`](docs/spec-compliance.md) に項目単位で記載しています。以下の表は 2026-05-13 時点のスナップショットです — 最新値は [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) を参照してください。\n\n| 指標 | 状況 |\n| --- | --- |\n| 仕様全体（out-of-scope を含む） | **71.8%** |\n| In-scope のみ | **80.2%** |\n| Lightbend `equiv01`–`equiv05` + `test01`–`test13` | 13/13 合格 |\n| [hocon2](https://github.com/o3co/hocon2) 準拠テスト（JSON/YAML/TOML/Properties 出力） | 77/77 合格 |\n\n## 関連プロジェクト\n\n| プロジェクト | 言語 | レジストリ | 説明 |\n|---------|----------|----------|-------------|\n| [ts.hocon](https://github.com/o3co/ts.hocon) | TypeScript | [npm](https://www.npmjs.com/package/@o3co/ts.hocon) | TypeScript/Node.js 向け HOCON パーサー |\n| [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/o3co-hocon) | Rust 向け HOCON パーサー |\n| [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties 変換 CLI |\n\n3 つのパーサー実装（[ts.hocon](https://github.com/o3co/ts.hocon)、[rs.hocon](https://github.com/o3co/rs.hocon)、[go.hocon](https://github.com/o3co/go.hocon)）はすべて同じ Lightbend HOCON 仕様で追跡されています — 実装ごとの準拠率は [横断ロールアップ](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) を参照してください。\n\n## ベストプラクティス\n\n### 設定構成\n\n- **ドメインごとに分割**: 設定を論理的な単位に分けましょう（`database.conf`、`server.conf`、`logging.conf`）\n- **`include` で合成**: ドメイン別ファイルからフル設定を組み立てましょう\n- **設定にロジックを入れない**: HOCON は宣言的なデータのためのもので、条件分岐や計算には向きません\n\n### 環境変数\n\n- **`${ENV}` の使用を最小限に**: 設定ファイル自体にデフォルト値を定義し、`${?ENV}`（オプショナル）を使いましょう\n- **ローカル開発で環境変数を必須にしない**: デフォルトだけで動くようにしましょう\n- **必須の環境変数を文書化**: プロジェクトの README や `.env.example` にリストしましょう\n\n### 開発 / 本番の分離\n\n```text\nconfig/\n├── application.conf    # 共有デフォルト\n├── dev.conf            # include \"application.conf\" + 開発用オーバーライド\n└── prod.conf           # include \"application.conf\" + 本番用オーバーライド\n```\n\n### バリデーション\n\n- 設定のバリデーションは常にアプリケーション起動時に行い、使用時ではなく早期に検出しましょう\n- スキーマバリデーション（TypeScript は Zod、Go は struct Unmarshal、Rust は Serde）を使って早期にエラーをキャッチしましょう\n\n```go\nconf, err := hocon.ParseString(`\nserver {\n  host = \"localhost\"\n  port = 8080\n}\ndebug = true\n`)\nif err != nil {\n    log.Fatal(err)\n}\n\nvar app struct {\n    Server struct { Host string; Port int } `hocon:\"server\"`\n    Debug  bool                             `hocon:\"debug\"`\n}\nif err := conf.Unmarshal(\u0026app); err != nil {\n    log.Fatal(err) // 起動時に即座に失敗\n}\n```\n\n## ライセンス\n\nApache License 2.0 — [LICENSE](LICENSE) を参照。\n\nCopyright 2026 1o1 Co. Ltd.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo3co%2Fgo.hocon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fo3co%2Fgo.hocon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo3co%2Fgo.hocon/lists"}