Awesome
ruby-hocon
This is a port of the Typesafe Config library to Ruby.
The library provides Ruby support for the HOCON configuration file format.
At present, it supports parsing and modification of existing HOCON/JSON files via the ConfigFactory
class and the ConfigValueFactory
class, and rendering parsed config objects back to a String
(see examples below). It also supports the parsing and modification of HOCON/JSON files via
ConfigDocumentFactory
.
Note: While the project is production ready, since not all features in the Typesafe library are supported, you may still run into some issues. If you find a problem, feel free to open a github issue.
The implementation is intended to be as close to a line-for-line port as the two languages allow, in hopes of making it fairly easy to port over new changesets from the Java code base over time.
Support
For best results, if you find an issue with this library, please open an issue on our Jira issue tracker. Issues filed there tend to be more visible to the current maintainers than issues on the Github issue tracker.
Basic Usage
gem install hocon
To use the simple API, for reading config values:
require 'hocon'
conf = Hocon.load("myapp.conf")
puts "Here's a setting: #{conf["foo"]["bar"]["baz"]}"
By default, the simple API will determine the configuration file syntax/format
based on the filename extension of the file; .conf
will be interpreted as HOCON,
.json
will be interpreted as strict JSON, and any other extension will cause an
error to be raised since the syntax is unknown. If you'd like to use a different
file extension, you manually specify the syntax, like this:
require 'hocon'
require 'hocon/config_syntax'
conf = Hocon.load("myapp.blah", {:syntax => Hocon::ConfigSyntax::HOCON})
Supported values for :syntax
are: JSON, CONF, and HOCON. (CONF and HOCON are
aliases, and both map to the underlying HOCON syntax.)
To use the ConfigDocument API, if you need both read/write capability for modifying settings in a config file, or if you want to retain access to things like comments and line numbers:
require 'hocon/parser/config_document_factory'
require 'hocon/config_value_factory'
# The below 4 variables will all be ConfigDocument instances
doc = Hocon::Parser::ConfigDocumentFactory.parse_file("myapp.conf")
doc2 = doc.set_value("a.b", "[1, 2, 3, 4, 5]")
doc3 = doc.remove_value("a")
doc4 = doc.set_config_value("a.b", Hocon::ConfigValueFactory.from_any_ref([1, 2, 3, 4, 5]))
doc_has_value = doc.has_value?("a") # returns boolean
orig_doc_text = doc.render # returns string
Note that a ConfigDocument
is used primarily for simple configuration manipulation while preserving
whitespace and comments. As such, it is not powerful as the regular Config
API, and will not resolve
substitutions.
CLI Tool
The hocon
gem comes bundles with a hocon
command line tool which can be used to get and set values from hocon files
Usage: hocon [options] {get,set,unset} PATH [VALUE]
Example usages:
hocon -i settings.conf -o new_settings.conf set some.nested.value 42
hocon -f settings.conf set some.nested.value 42
cat settings.conf | hocon get some.nested.value
Subcommands:
get PATH - Returns the value at the given path
set PATH VALUE - Sets or adds the given value at the given path
unset PATH - Removes the value at the given path
Options:
-i, --in-file HOCON_FILE HOCON file to read/modify. If omitted, STDIN assumed
-o, --out-file HOCON_FILE File to be written to. If omitted, STDOUT assumed
-f, --file HOCON_FILE File to read/write to. Equivalent to setting -i/-o to the same file
-j, --json Output values from the 'get' subcommand in json format
-h, --help Show this message
-v, --version Show version
CLI Examples
Basic Usage
$ cat settings.conf
{
foo: bar
}
$ hocon -i settings.conf get foo
bar
$ hocon -i settings.conf set foo baz
$ cat settings.conf
{
foo: baz
}
# Write to a different file
$ hocon -i settings.conf -o new_settings.conf set some.nested.value 42
$ cat new_settings.conf
{
foo: bar
some: {
nested: {
value: 42
}
}
}
# Write back to the same file
$ hocon -f settings.conf set some.nested.value 42
$ cat settings.conf
{
foo: bar
some: {
nested: {
value: 42
}
}
}
Complex Values
If you give set
a properly formatted hocon dictionary or array, it will try to accept it
$ hocon -i settings.conf set foo "{one: [1, 2, 3], two: {hello: world}}"
{
foo: {one: [1, 2, 3], two: {hello: world}}
}
Chaining
If --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
$ cat settings.conf
{
foo: bar
}
$ cat settings.conf | hocon set foo 42 | hocon set one.two three
{
foo: 42
one: {
two: three
}
}
JSON Output
Calls 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
$ cat settings.conf
foo: {
bar: {
baz: 42
}
}
$ hocon -i settings.conf get foo --json
{
"bar": {
"baz": 42
}
}
Testing
bundle install --path .bundle
bundle exec rspec spec
Unsupported Features
This supports many of the same things as the Java library, but there are some notable exceptions. Unsupported features include:
- Non file includes
- Loading resources from the class path or URLs
- Properties files
- Parsing anything other than files and strings
- Duration and size settings
- Java system properties