| Current Path : /opt/puppetlabs/puppet/lib/ruby/vendor_gems/gems/hocon-1.3.1/ |
| Current File : //opt/puppetlabs/puppet/lib/ruby/vendor_gems/gems/hocon-1.3.1/README.md |
ruby-hocon
==========
[](https://badge.fury.io/rb/hocon) [](https://travis-ci.org/puppetlabs/ruby-hocon)
This is a port of the [Typesafe Config](https://github.com/typesafehub/config) library to Ruby.
The library provides Ruby support for the [HOCON](https://github.com/typesafehub/config/blob/master/HOCON.md) 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](#basic-usage)). 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](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.
Basic Usage
===========
```sh
gem install hocon
```
To use the simple API, for reading config values:
```rb
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:
```rb
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:
```rb
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
=======
```sh
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
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)