Define, read and write any Ruby app configurations with a penchant for terminal clients.
TTY::Config provides app configuration component for TTY toolkit.
This is a one-stop shop for all your configuration needs:
- Read and write config files in YAML, JSON, TOML, INI, HCL and Java Properties formats
- Add custom marshallers or override the built-in ones
- Set and read settings for deeply nested keys
- Set defaults for undefined settings
- Read settings with indifferent access
- Merge configuration settings from other hash objects
- Read values from environment variables
Add this line to your application's Gemfile:
gem 'tty-config'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-config
- 1. Usage
- 2. Interface
- 2.1 set
- 2.2 set_if_empty
- 2.3 set_from_env
- 2.4 fetch
- 2.5 merge
- 2.6 coerce
- 2.7 append
- 2.8 remove
- 2.9 delete
- 2.10 alias_setting
- 2.11 validate
- 2.12 env_prefix=
- 2.13 filename=
- 2.14 extname=
- 2.15 append_path
- 2.16 prepend_path
- 2.17 read
- 2.18 write
- 2.19 exist?
- 2.20 autoload_env
- 2.21 register_marshaller
- 2.22 unregister_marshaller
- 3. Examples
Initialize the configuration and provide the name:
config = TTY::Config.new
config.filename = 'investments'
Then configure values for different nested keys with set
and append
:
config.set(:settings, :base, value: 'USD')
config.set(:settings, :color, value: true)
config.set(:coins, value: ['BTC'])
config.append('ETH', 'TRX', 'DASH', to: :coins)
You can get any value by using fetch
:
config.fetch(:settings, :base)
# => 'USD'
config.fetch(:coins)
# => ['BTC', 'ETH', 'TRX', 'DASH']
And call write
to persist the configuration to investments.yml
file:
config.write
# =>
# ---
# settings:
# base: USD
# color: true
# coins:
# - BTC
# - ETH
# - TRX
# - DASH
To read an investments.yml
file, you need to provide the locations to search in:
config.append_path Dir.pwd
config.append_path Dir.home
Finally, call read
to convert configuration file back into an object again:
config.read
An example of an application configuration:
class App
attr_reader :config
def initialize
@config = TTY::Config.new
@config.filename = 'investments'
@config.extname = '.toml'
@config.append_path Dir.pwd
@config.append_path Dir.home
end
def self.config
@config ||= self.class.new.config
end
end
To set configuration setting use set
method. It accepts any number of keys and value by either using :value
keyword argument or passing a block:
config.set(:base, value: 'USD')
config.set(:base) { 'USD' }
The block version of specifying a value will mean that the value is evaluated every time it's being read.
You can also specify deeply nested configuration settings by passing sequence of keys:
config.set :settings, :base, value: 'USD'
Which is equivalent to:
config.set 'settings.base', value: 'USD'
Internally all configuration settings are stored as string keys for ease of working with configuration files and command line application's inputs.
To set a configuration setting only if it hasn't been set before use set_if_empty
:
config.set_if_empty :base, value: 'USD'
Similar to set
it allows you to specify arbitrary sequence of keys followed by a key value or block:
config.set_if_empty :settings, :base, value: 'USD'
To read configuration options from environment variables use set_from_env
. At minimum it requires a single argument which will match the name of ENV
variable. The name of this parameter is case insensitive.
Given the following environment variables:
ENV['HOST'] = '192.168.1.17'
ENV['PORT'] = '7727'
You can make the config aware of the above env variables:
config.set_from_env(:host)
config.set_from_env(:port)
Then you can retrieve values like any other configuration option:
config.fetch(:host)
# => '192.168.1.17'
config.fetch(:port)
# => '7727'
If you want the configuration key name to be different from ENV
variable name use a block:
config.set_from_env(:host) { 'HOSTNAME' }
config.set_from_env(:host) { :hostname }
You can also configure settings for deeply nested keys:
config.set_from_env(:settings, :base) { 'CURRENCY' }
config.set_from_env(:settings, :base) { :currency }
config.set_from_env('settings.base') { 'CURRENCY'}
config.set_from_env('settings.base') { :currency}
And assuming ENV['CURRENCY']=USD
:
config.fetch(:settings, :base)
# => USD
You can also prefix your environment variables. See env_prefix=
It's important to recognise that set_from_env
doesn't record the value for the environment variables. They are read each time from the ENV
when fetch
is called.
To get a configuration setting use fetch
, which can accept default value either with a :default
keyword or a block that will be lazy evaluated:
config.fetch(:base, default: 'USD')
config.fetch(:base) { 'USD' }
Similar to set
operation, fetch
allows you to retrieve deeply nested values:
config.fetch(:settings, :base) # => USD
Which is equivalent to:
config.fetch('settings.base')
fetch
has indifferent access so you can mix string and symbol keys, all the following examples retrieve the value:
config.fetch(:settings, :base)
config.fetch('settings', 'base')
config.fetch(:settings', 'base')
config.fetch('settings', :base)
To merge in other configuration settings as hash use merge
:
config.set(:a, :b, value: 1)
config.set(:a, :c, value: 2)
config.merge({'a' => {'c' => 3, 'd' => 4}})
config.fetch(:a, :c) # => 3
config.fetch(:a, :d) # => 4
Internally all configuration settings are stored as string keys for ease of working with file values and command line applications inputs.
You can initialize configuration based on a hash, with all the keys converted to symbols:
hash = {"settings" => {"base" => "USD", "exchange" => "CCCAGG"}}
config = TTY::Config.coerce(hash)
config.to_h
# =>
# {settings: {base: "USD", exchange: "CCCAGG"}}
To append arbitrary number of values to a value under a given key use append
:
config.set(:coins) { ["BTC"] }
config.append("ETH", "TRX", to: :coins)
# =>
# {coins: ["BTC", "ETH", "TRX"]}
You can also append values to deeply nested keys:
config.set(:settings, :bases, value: ["USD"])
config.append("EUR", "GBP", to: [:settings, :bases])
# =>
# {settings: {bases: ["USD", "EUR", "GBP"]}}
Use remove
to remove a set of values from a key.
config.set(:coins, value: ["BTC", "TRX", "ETH", "DASH"])
config.remove("TRX", "DASH", from: :coins)
# =>
# ["BTC", "ETH"]
If the key is nested the :from
accepts an array:
config.set(:holdings, :coins, value: ["BTC", "TRX", "ETH", "DASH"])
config.remove("TRX", "DASH", from: [:holdings, :coins])
# =>
# ["BTC", "ETH"]
To completely delete a value and corresponding key use delete
:
config.set(:base, value: "USD")
config.delete(:base)
# =>
# "USD"
You can also delete deeply nested keys and their values:
config.set(:settings, :base, value: "USD")
config.delete(:settings, :base)
# =>
# "USD"
In order to alias a configuration setting to another name use alias_setting
.
For example, given an already existing setting:
config.set(:base, value: 'baz')
You can alias it to another name:
config.alias_setting(:base, to: :currency)
And then access like any other configuration setting:
config.fetch(:currency)
# => 'USD'
Deep nested configuration options are also supported:
config.set(:settings, :base, value: 'USD')
And then can be aliased like so:
config.alias_setting(:settings, :base, to: [:settings, :currency])
config.alias_setting('settings.base', to [:settings, :currency])
You can then access the deep nested settings:
config.fetch(:settings, :currency)
# => 'USD'
config.fetch('settings.currency')
# => 'USD'
To ensure consistency of the data, you can validate values being set at arbitrarily deep keys using validate
method, that takes an arbitrarily nested key as its argument and a validation block.
config.validate(:settings, :base) do |key, value|
if value.length != 3
raise TTY::Config::ValidationError, "Currency code needs to be 3 chars long."
end
end
You can assign multiple validations for a given key and each of them will be run in the order they were registered when checking a value.
When setting value all the validations will be run:
config.set(:settings, :base, value: 'PL')
# raises TTY::Config::ValidationError, 'Currency code needs to be 3 chars long.'
If the value is provided as a proc or a block then the validation will be delayed until the value is actually read:
config.set(:settings, :base) { 'PL' }
config.fetch(:settings, :base)
# raises TTY::Config::ValidationError, 'Currency code needs to be 3 chars long.'
Given the following variables:
ENV['MYTOOL_HOST'] = '192.168.1.17'
ENV['MYTOOL_PORT'] = ' 7727'
You can inform configuration about common prefix using env_prefix
:
config.env_prefix = 'mytool'
Then set configuration key name to environment variable name:
config.set_from_env(:host)
config.set_from_env(:port)
And finally retrieve the value:
config.fetch(:host)
#=> '192.168.1.17'
config.fetch(:port)
# => '7727'
By default, TTY::Config searches for config
named configuration file. To change this use filename=
method without the extension name:
config.filename = 'investments'
Then any supported extensions will be searched for such as .yml
, .json
and .toml
.
By default '.yml' extension is used to write configuration out to a file but you can change that with extname=
:
config.extname = '.toml'
You need to tell the TTY::Config where to search for configuration files. To search multiple paths for a configuration file use append_path
or prepend_path
methods.
For example, if you want to search through /etc
directory first, then user home directory and then current directory do:
config.append_path("/etc/") # look in /etc directory
config.append_path(Dir.home) # look in user's home directory
config.append_path(Dir.pwd) # look in current working directory
None of these paths are required, but you should provide at least one path if you wish to read a configuration file.
The prepend_path
allows you to add configuration search paths that should be searched first.
config.append_path(Dir.pwd) # look in current working directory second
config.prepend_path(Dir.home) # look in user's home directory first
There are two ways for reading configuration files and both use the read
method. One attempts to guess extension and format of your data, the other allows you to request specific extension and format.
Currently the supported file formats are:
yaml
for.yaml
,.yml
extensionsjson
for.json
extensiontoml
for.toml
extensionini
for.ini
,.cnf
,.conf
,.cfg
,.cf extensions
hcl
for.hcl
extensionsjprops
for.properties
,.props
,.prop
extensions
Calling read
without any arguments searches through provided locations to find configuration file and reads it. Therefore, you need to specify at least one search path that contains the configuration file together with actual filename. When filename is specified then all known extensions will be tried.
For example, to find file called investments in the current directory do:
config.append_path(Dir.pwd) # look in current working directory
config.filename = 'investments' # file to search for
Find and read the configuration file:
config.read
You can also specify directly the file to read without setting up any search paths or filenames. If you specify a configuration with a known file extension, an appropriate format will be guessed, in this instance TOML
:
config.read('./investments.toml')
In cases where you wish to specify a custom file extension, you will need to also specify the file format to use.
For example, if you have a configuration file formatted using YAML
notation with extension called .config
, to read it do:
config.read('investments.config', format: :yaml)
By default TTY::Config, persists configuration file in the current working directory with a config.yml
name. However, you can change that by specifying the filename and extension type:
config.filename = 'investments'
config.extname = '.toml'
To write current configuration to a file, you can either specified direct location path and filename:
config.write('./investments.toml')
Or, specify location paths to be searched for already existing configuration to overwrite:
config.append_path(Dir.pwd) # search current working directory
config.write
To create configuration file regardless whether it exists or not, use :force
flag:
config.write(force: true) # overwrite any found config file
config.write('./investments.toml', force: true) # overwrite specific config file
To check if a configuration file exists within the configured search paths use exist?
method:
config.exist? # => true
The autoload_env
method allows you to automatically read environment variables. In most cases you would combine it with env_prefix= to only read a subset of variables. When using autoload_env
, anytime the fetch
is called a corresponding environment variable will be checked.
For example, given an environment variable MYTOOL_HOST
set to localhost
:
ENV['MYTOOL_HOST']=localhost
And loading environment variables with a prefix of MYTOOL
:
config.env_prefix = 'mytool'
config.autoload_env
You can retrieve value with:
config.fetch(:host)
# => 'localhost'
There are number of built-in marshallers that handle the process of serializing internal configuration from and back into a desired format, for example, a JSON
string.
Currently supported formats out-of-the-box are: YAML
, JSON
, TOML
, INI
& HCL
.
To create your own marshaller use the TTY::Config::Marshaller
interface. You need to provide the implementation for the following marshalling methods:
marshal
unmarshal
In addition, you will need to specify the extension types this marshaller will handle using the extension
method. The method accepts a list of names preceded by a dot:
extension ".ext1", ".ext2", ".ext3"
Optionally, you can provide a dependency or dependencies that will be lazy loaded if the extension is used. For this use the dependency
method.
You can either specify dependencies as a list of names:
dependency "toml"
dependency "toml", "tomlrb"
Or provide dependencies in a block:
dependency do
require "toml"
require "tomlrb"
end
Putting it all together, you can create your own marshaller like so:
class MyCustomMarshaller
include TTY::Config::Marshaller
dependency "my_dep"
extension ".ext1", ".ext2"
def marshal(object)
MyDep.dump(object)
end
def unmarshal(content)
MyDep.parse(content)
end
end
And then let the configuration know about your marshaller by calling the register_marshaller
:
config.register_marshaller(:my_custom, MyCustomMarshaller)
Bear in mind that you can also override the built-in implementation of a marshaller. For example, if you find a better performing Ruby gem for TOML parsing, register your custom marshaller under the :toml
name like so:
config.register_marshaller(:toml, MyTOMLMarshaller)
By default, the TTY::Config is ready to recognize various extensions. See (2.17 read)[#217-read] section for more details. But, you're free to remove the default marshallers from the internal registry with unregister_marshaller
method.
For example, to remove all the built-in marshallers do:
config.unregister_marshaller :yaml, :json, :toml, :ini, :hcl
TTY::Config fully supports working with environment variables. For example, there are couple of environment variables that your configuration is interested in, which normally would be set in terminal but for the sake of this example we assign them:
ENV['MYTOOL_HOST'] = '192.168.1.17'
ENV['MYTOOL_PORT'] = '7727'
Then in order to make your configuration aware of the above, you would use env_prefix= and set_from_env:
config.env_prefix = 'mytool'
config.set_from_env(:host)
config.set_from_env(:port)
Or automatically load all prefixed environment variables with autoload_env:
config.env_prefix = 'mytool'
config.autoload_env
And then retrieve values with fetch:
config.fetch(:host)
#=> '192.168.1.17'
config.fetch(:port)
# => '7727'
This is an example of combining tty-config
with optparse
stdlib.
Let's assume you want to create a command line tool that among many options accepts --host|-h
and --port|-p
flags. In addition, these flags will take precedence over the options specified in the configuration file.
First, you need to parse the flags and store results away in options hash:
require 'optparse'
options = {}
option_parser = OptionParser.new do |opts|
opts.on("-h", "--host HOSTNAME_OR_IP", "Hostname or IP Adress") do |h|
options[:host] = h
end
opts.on("-p", "--port PORT", "Port of application", Integer) do |p|
options[:port] = p
end
opts.on("-c", "--config FILE",
"Read config values from file (defaults: ./config.yml, ~/.config.yml") do |c|
options[:config_file_path] = c
end
...
end
option_parser.parse!
Then, you create a configuration instance:
config = TTY::Config.new
And setup config filename:
config_filename = options[:config_file_path] || 'config.yml'
As well as add configuration file locations to search in:
config.append_path Dir.pwd
config.append_path Dir.home
Once config is initialized, you can read the configuration from a config file:
begin
config.read(config_filename) # by default the 'config.yml' is read
rescue TTY::Config::ReadError => read_error
STDERR.puts "\nNo configuration file found:"
STDERR.puts read_error
end
Then merge options passed as arguments with those stored in a configuration file:
config.merge(options)
Provide optional validation to ensure both host and port are configured:
if !config.fetch(:host) || !config.fetch(:port)
STDERR.puts "Host and port have to be specified (call with --help for help)."
exit 1
end
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-config. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the TTY::Config project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Copyright (c) 2018 Piotr Murach. See LICENSE for further details.