{"id":13561043,"url":"https://github.com/puppetlabs/ruby-hocon","last_synced_at":"2025-05-15T21:07:04.120Z","repository":{"id":14609737,"uuid":"17326988","full_name":"puppetlabs/ruby-hocon","owner":"puppetlabs","description":"A Ruby port of the Typesafe Config library.","archived":false,"fork":false,"pushed_at":"2025-02-04T16:45:16.000Z","size":675,"stargazers_count":35,"open_issues_count":10,"forks_count":30,"subscribers_count":153,"default_branch":"main","last_synced_at":"2025-05-08T11:15:51.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-01T23:44:17.000Z","updated_at":"2025-01-07T08:06:40.000Z","dependencies_parsed_at":"2024-01-16T18:59:48.643Z","dependency_job_id":"516ce835-007b-4a92-8818-7f991ca7923d","html_url":"https://github.com/puppetlabs/ruby-hocon","commit_stats":{"total_commits":272,"total_committers":29,"mean_commits":9.379310344827585,"dds":0.7316176470588236,"last_synced_commit":"58161b8cc9fa6ea755efc298335f750f152252d4"},"previous_names":["cprice404/ruby-typesafe-config"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fruby-hocon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fruby-hocon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fruby-hocon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fruby-hocon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/ruby-hocon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254422761,"owners_count":22068678,"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":[],"created_at":"2024-08-01T13:00:51.912Z","updated_at":"2025-05-15T21:07:04.102Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":["HOCON"],"sub_categories":[],"readme":"ruby-hocon\n==========\n[![Gem Version](https://badge.fury.io/rb/hocon.svg)](https://badge.fury.io/rb/hocon) [![Build Status](https://travis-ci.org/puppetlabs/ruby-hocon.png?branch=master)](https://travis-ci.org/puppetlabs/ruby-hocon)\n\nThis is a port of the [Typesafe Config](https://github.com/typesafehub/config) library to Ruby.\n\nThe library provides Ruby support for the [HOCON](https://github.com/typesafehub/config/blob/master/HOCON.md) configuration file format.\n\n\nAt present, it supports parsing and modification of existing HOCON/JSON files via the `ConfigFactory`\nclass and the `ConfigValueFactory` class, and rendering parsed config objects back to a String\n([see examples below](#basic-usage)). It also supports the parsing and modification of HOCON/JSON files via\n`ConfigDocumentFactory`.\n\n**Note:** While the project is production ready, since not all features in the Typesafe library are supported,\nyou may still run into some issues. If you find a problem, feel free to open a github issue.\n\nThe implementation is intended to be as close to a line-for-line port as the two languages allow,\nin hopes of making it fairly easy to port over new changesets from the Java code base over time.\n\nSupport\n=======\n\nFor best results, if you find an issue with this library, please open an issue on our [Jira issue tracker](https://tickets.puppetlabs.com/browse/HC).  Issues filed there tend to be more visible to the current maintainers than issues on the Github issue tracker.\n\n\nBasic Usage\n===========\n\n```sh\ngem install hocon\n```\n\nTo use the simple API, for reading config values:\n\n```rb\nrequire 'hocon'\n\nconf = Hocon.load(\"myapp.conf\")\nputs \"Here's a setting: #{conf[\"foo\"][\"bar\"][\"baz\"]}\"\n```\n\nBy default, the simple API will determine the configuration file syntax/format\nbased on the filename extension of the file; `.conf` will be interpreted as HOCON,\n`.json` will be interpreted as strict JSON, and any other extension will cause an\nerror to be raised since the syntax is unknown.  If you'd like to use a different\nfile extension, you manually specify the syntax, like this:\n\n```rb\nrequire 'hocon'\nrequire 'hocon/config_syntax'\n\nconf = Hocon.load(\"myapp.blah\", {:syntax =\u003e Hocon::ConfigSyntax::HOCON})\n```\n\nSupported values for `:syntax` are: JSON, CONF, and HOCON.  (CONF and HOCON are\naliases, and both map to the underlying HOCON syntax.)\n\nTo use the ConfigDocument API, if you need both read/write capability for\nmodifying settings in a config file, or if you want to retain access to\nthings like comments and line numbers:\n\n```rb\nrequire 'hocon/parser/config_document_factory'\nrequire 'hocon/config_value_factory'\n\n# The below 4 variables will all be ConfigDocument instances\ndoc = Hocon::Parser::ConfigDocumentFactory.parse_file(\"myapp.conf\")\ndoc2 = doc.set_value(\"a.b\", \"[1, 2, 3, 4, 5]\")\ndoc3 = doc.remove_value(\"a\")\ndoc4 = doc.set_config_value(\"a.b\", Hocon::ConfigValueFactory.from_any_ref([1, 2, 3, 4, 5]))\n\ndoc_has_value = doc.has_value?(\"a\") # returns boolean\norig_doc_text = doc.render # returns string\n```\n\nNote that a `ConfigDocument` is used primarily for simple configuration manipulation while preserving\nwhitespace and comments. As such, it is not powerful as the regular `Config` API, and will not resolve\nsubstitutions.\n\nCLI Tool\n========\nThe `hocon` gem comes bundles with a `hocon` command line tool which can be used to get and set values from hocon files\n\n```\nUsage: hocon [options] {get,set,unset} PATH [VALUE]\n\nExample usages:\n  hocon -i settings.conf -o new_settings.conf set some.nested.value 42\n  hocon -f settings.conf set some.nested.value 42\n  cat settings.conf | hocon get some.nested.value\n\nSubcommands:\n  get PATH - Returns the value at the given path\n  set PATH VALUE - Sets or adds the given value at the given path\n  unset PATH - Removes the value at the given path\n\nOptions:\n    -i, --in-file HOCON_FILE         HOCON file to read/modify. If omitted, STDIN assumed\n    -o, --out-file HOCON_FILE        File to be written to. If omitted, STDOUT assumed\n    -f, --file HOCON_FILE            File to read/write to. Equivalent to setting -i/-o to the same file\n    -j, --json                       Output values from the 'get' subcommand in json format\n    -h, --help                       Show this message\n    -v, --version                    Show version\n```\n\nCLI Examples\n--------\n### Basic Usage\n```\n$ cat settings.conf\n{\n  foo: bar\n}\n\n$ hocon -i settings.conf get foo\nbar\n\n$ hocon -i settings.conf set foo baz\n\n$ cat settings.conf\n{\n  foo: baz\n}\n\n# Write to a different file\n$ hocon -i settings.conf -o new_settings.conf set some.nested.value 42\n$ cat new_settings.conf\n{\n  foo: bar\n  some: {\n    nested: {\n      value: 42\n\n    }\n  }\n}\n\n# Write back to the same file\n$ hocon -f settings.conf set some.nested.value 42\n$ cat settings.conf\n{\n  foo: bar\n  some: {\n    nested: {\n      value: 42\n\n    }\n  }\n}\n```\n\n### Complex Values\nIf you give `set` a properly formatted hocon dictionary or array, it will try to accept it\n\n```\n$ hocon -i settings.conf set foo \"{one: [1, 2, 3], two: {hello: world}}\"\n{\n  foo: {one: [1, 2, 3], two: {hello: world}}\n}\n```\n\n### Chaining\nIf `--in-file` or `--out-file` aren't specified, STDIN and STDOUT are used for the missing options. Therefore it's possible to chain `hocon` calls\n\n```\n$ cat settings.conf\n{\n  foo: bar\n}\n\n$ cat settings.conf | hocon set foo 42 | hocon set one.two three\n{\n  foo: 42\n  one: {\n    two: three\n  }\n}\n```\n\n### JSON Output\nCalls to the `get` subcommand will return the data in HOCON format by default, but setting the `-j/--json` flag will cause it to return a valid JSON object\n\n```\n$ cat settings.conf\nfoo: {\n  bar: {\n    baz: 42\n  }\n}\n\n$ hocon -i settings.conf get foo --json\n{\n    \"bar\": {\n        \"baz\": 42\n    }\n}\n```\n\nTesting\n=======\n\n```sh\nbundle install --path .bundle\nbundle exec rspec spec\n```\n\nUnsupported Features\n====================\n\nThis supports many of the same things as the Java library, but there are some notable exceptions.\nUnsupported features include:\n\n* Non file includes\n* Loading resources from the class path or URLs\n* Properties files\n* Parsing anything other than files and strings\n* Duration and size settings\n* Java system properties\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fruby-hocon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fruby-hocon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fruby-hocon/lists"}