tty-config 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b7d2891f50d6ec7735ddf4c68e811d2b9726d5f1
-  data.tar.gz: a4c6a91a265b84c849aa7be416eb0062d9253ff7
+SHA256:
+  metadata.gz: 5f98bab385a665c7b78c6d94d82c4ba93c7f37354fcd801a87b7d4ca9f9cd14f
+  data.tar.gz: 62265adbaae3b68b9b73e590a1a06df502577d669c67be39a1425515c1f30482
 SHA512:
-  metadata.gz: 2f735b5c715194df5873b78bee19062392effc855f712659ab3fc07cd6c87737eedcc79fbce15362ecbe473df226090a3d76c00c1438f0f522c265f742141c50
-  data.tar.gz: 282c1817e5c73f18bf1be3c0b2c32d41d142a22a894ab5c528901bdfda0a573cbda9cfe74961b92dfe63ee91e89d89f2e06649cd4c208c7e85db47e226dd2ce5
+  metadata.gz: b6abcbe7ddc76d4856354221e6780ea0e502f28cd02bf79633d4584c05206d4629cf22cfd797a3457ffebc6454a3269a0481b34c5736005406cf6f334d101a2d
+  data.tar.gz: 9f423088aa20776fbe529ed554025887320a71c203c247f97e068a03c8a650ce48fa5d91feb4e9e831f368177305db9b8025c62475eda4959232652c77d9e9a4

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change log
 
+## [v0.3.0] - 2018-10-20
+
+### Added
+* Add #set_from_env for binding keys to environment variables
+* Add #env_prefix for setting environment variables prefix
+* Add #autoload_env for loading all environment variables
+* Add #generate for generating file content from the settings
+* Add #alias_setting for aliasing settings
+* Add ability to read & write INI file types
+
+### Changed
+* Change #fetch to read environment variables before defaults
+* Change #fetch to handle aliased settings
+* Change to remove stdout output when dependency cannot be loaded
+* Change to allow for config files without any extension
+
 ## [v0.2.0] - 2018-05-07
 
 ### Added
@@ -12,5 +28,6 @@
 
 * Initial implementation and release
 
+[v0.3.0]: https://github.com/piotrmurach/tty-config/compare/v0.2.0...v0.3.0
 [v0.2.0]: https://github.com/piotrmurach/tty-config/compare/v0.1.0...v0.2.0
 [v0.1.0]: https://github.com/piotrmurach/tty-config/compare/v0.1.0

data/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+</div>
+
 # TTY::Config [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-config.svg)][gem]
@@ -21,9 +25,11 @@
 
 ## Features
 
-* Read & write configurations in YAML, JSON, TOML formats
-* Simple interface for setting and fetching values for deeply nested keys
-* Merging of configuration options from other hashes
+* Read & write configurations in YAML, JSON, TOML, INI formats
+* Simple interface for adding and reading settings for deeply nested keys
+* Indifferent access for reading settings
+* Merging of configuration settings from other hashes
+* Reading values from environment variables
 
 ## Installation
 
@@ -48,20 +54,27 @@ Or install it yourself as:
 * [2. Interface](#2-interface)
   * [2.1 set](#21-set)
   * [2.2 set_if_empty](#22-set_if_empty)
-  * [2.3 fetch](#23-fetch)
-  * [2.4 merge](#24-merge)
-  * [2.5 coerce](#25-coerce)
-  * [2.6 append](#26-append)
-  * [2.7 remove](#27-remove)
-  * [2.8 delete](#28-delete)
-  * [2.9 validate](#29-validate)
-  * [2.10 filename=](#210-filename)
-  * [2.11 extname=](#211-extname)
-  * [2.12 append_path](#212-append_path)
-  * [2.13 prepend_path](#213-prepend_path)
-  * [2.14 read](#214-read)
-  * [2.15 write](#215-write)
-  * [2.16 persisted?](#216-persisted)
+  * [2.3 set_from_env](#23-set_from_env)
+  * [2.4 fetch](#24-fetch)
+  * [2.5 merge](#25-merge)
+  * [2.6 coerce](#26-coerce)
+  * [2.7 append](#27-append)
+  * [2.8 remove](#28-remove)
+  * [2.9 delete](#29-delete)
+  * [2.10 alias_setting](#210-alias_setting)
+  * [2.11 validate](#211-validate)
+  * [2.12 env_prefix=](#212-env_prefix)
+  * [2.13 filename=](#213-filename)
+  * [2.14 extname=](#214-extname)
+  * [2.15 append_path](#215-append_path)
+  * [2.16 prepend_path](#216-prepend_path)
+  * [2.17 read](#217-read)
+  * [2.18 write](#218-write)
+  * [2.19 exist?](#219-exist)
+  * [2.20 autoload_env](#220-autoload_env)
+* [3. Examples](#3-examples)
+  * [3.1 Working with env vars](#31-working-with-env-vars)
+  * [3.2 Working with optparse](#32-working-with-optparse)
 
 ## 1. Usage
 
@@ -184,7 +197,61 @@ Similar to `set` it allows you to specify arbitrary sequence of keys followed by
 config.set_if_empty :settings, :base, value: 'USD'
 ```
 
-### 2.3 fetch
+### 2.3 set_from_env
+
+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:
+
+```ruby
+ENV['HOST'] = '192.168.1.17'
+ENV['PORT'] = '7727'
+```
+
+You can make the config aware of the above env variables:
+
+```ruby
+config.set_from_env(:host)
+config.set_from_env(:port)
+```
+
+Then you can retrieve values like any other configuration option:
+
+```ruby
+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:
+
+```ruby
+config.set_from_env(:host) { 'HOSTNAME' }
+config.set_from_env(:host) { :hostname }
+```
+
+You can also configure settings for deeply nested keys:
+
+```ruby
+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 asssuming `ENV['CURRENCY']=USD`:
+
+```ruby
+config.fetch(:settings, :base)
+# => USD
+```
+
+You can also prefix your environment variables. See [env_prefix=](#212-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.
+
+### 2.4 fetch
 
 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:
 
@@ -214,7 +281,7 @@ config.fetch(:settings', 'base')
 config.fetch('settings', :base)
 ```
 
-### 2.4 merge
+### 2.5 merge
 
 To merge in other configuration settings as hash use `merge`:
 
@@ -230,7 +297,7 @@ 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.
 
-### 2.5 coerce
+### 2.6 coerce
 
 You can initialize configuration based on a hash, with all the keys converted to symbols:
 
@@ -242,7 +309,7 @@ config.to_h
 # {settings: {base: "USD", exchange: "CCCAGG"}}
 ```
 
-### 2.6 append
+### 2.7 append
 
 To append arbitrary number of values to a value under a given key use `append`:
 
@@ -264,7 +331,7 @@ config.append("EUR", "GBP", to: [:settings, :bases])
 # {settings: {bases: ["USD", "EUR", "GBP"]}}
 ```
 
-### 2.7 remove
+### 2.8 remove
 
 Use `remove` to remove a set of values from a key.
 
@@ -286,12 +353,12 @@ config.remove("TRX", "DASH", from: [:holdings, :coins])
 # ["BTC", "ETH"]
 ```
 
-### 2.8 delete
+### 2.9 delete
 
 To completely delete a value and corresponding key use `delete`:
 
 ```ruby
-config.set(:base, "USD")
+config.set(:base, value: "USD")
 config.delete(:base)
 # =>
 # "USD"
@@ -300,13 +367,58 @@ config.delete(:base)
 You can also delete deeply nested keys and their values:
 
 ```ruby
-config.set(:settings, :base, "USD")
+config.set(:settings, :base, value: "USD")
 config.delete(:settings, :base)
 # =>
 # "USD"
 ```
 
-### 2.9 validate
+### 2.10 alias_setting
+
+In order to alias a configuration setting to another name use `alias_setting`.
+
+For example, given an already existing setting:
+
+```ruby
+config.set(:base, value: 'baz')
+```
+
+You can alias it to another name:
+
+```ruby
+config.alias_setting(:base, to: :currency)
+```
+
+And then access like any other configuration setting:
+
+```ruby
+config.fetch(:currency)
+# => 'USD'
+```
+
+Deep nested configuration options are also supported:
+
+```ruby
+config.set(:settings, :base, value: 'USD')
+```
+
+And then can be aliased like so:
+
+```ruby
+config.alias_setting(:settings, :base, to: [:settings, :currency])
+config.alias_setting('settings.base', to [:settings, :currency])
+```
+
+You can then access the deep nested settings:
+
+```ruby
+config.fetch(:settings, :currency)
+# => 'USD'
+config.fetch('settings.currency')
+# => 'USD'
+```
+
+### 2.11 validate
 
 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.
 
@@ -335,7 +447,38 @@ config.fetch(:settings, :base)
 # raises TTY::Config::ValidationError, 'Currency code needs to be 3 chars long.'
 ```
 
-### 2.10 filename=
+### 2.12 env_prefix=
+
+Given the following variables:
+
+```ruby
+ENV['MYTOOL_HOST'] = '192.168.1.17'
+ENV['MYTOOL_PORT'] = ' 7727'
+```
+
+You can inform configuration about common prefix using `env_prefix`:
+
+```ruby
+config.env_prefix = 'mytool'
+```
+
+Then set configuration key name to environment variable name:
+
+```ruby
+config.set_from_env(:host)
+config.set_from_env(:port)
+```
+
+And finally retrieve the value:
+
+```ruby
+config.fetch(:host) 
+#=> '192.168.1.17'
+config.fetch(:port)
+# => '7727'
+```
+
+### 2.13 filename=
 
 By default, **TTY::Config** searches for `config` named configuration file. To change this use `filename=` method without the extension name:
 
@@ -345,7 +488,7 @@ config.filename = 'investments'
 
 Then any supported extensions will be search for such as `.yml`, `.json` and `.toml`.
 
-### 2.11 extname=
+### 2.14 extname=
 
 By default '.yml' extension is used to write configuration out to a file but you can change that with `extname=`:
 
@@ -353,7 +496,7 @@ By default '.yml' extension is used to write configuration out to a file but you
 config.extname = '.toml'
 ```
 
-### 2.12 append_path
+### 2.15 append_path
 
 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.
 
@@ -367,7 +510,7 @@ 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 configuration file.
 
-### 2.13 prepend_path
+### 2.16 prepend_path
 
 The `prepend_path` allows you to add configuration search paths that should be searched first.
 
@@ -376,11 +519,20 @@ config.append_path(Dir.pwd)   # look in current working directory second
 config.prepend_path(Dir.home) # look in user's home directory first
 ```
 
-### 2.14 read
+### 2.17 read
+
+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` extensions
+* `json` for `.json` extension
+* `toml` for `.toml` extension
+* `ini`  for `.ini`, `.cnf`, `.conf`, `.cfg`, `.cf extensions`
 
-There are two ways for reading configuration files and both use the `read` method.
+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 specifed then all known extensions will be tried.
 
-First one, searches through provided locations to find configuration file and read it. Therefore, you need to specify at least one search path that contains the configuration file.
+For example, to find file called investments in the current directory do:
 
 ```ruby
 config.append_path(Dir.pwd)       # look in current working directory
@@ -393,13 +545,21 @@ Find and read the configuration file:
 config.read
 ```
 
-However, you can also specify directly the file to read without setting up any search paths or filenames:
+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`:
 
 ```ruby
 config.read('./investments.toml')
 ```
 
-### 2.15 write
+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:
+
+```ruby
+config.read('investments.config', format: :yaml)
+```
+
+### 2.18 write
 
 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:
 
@@ -429,12 +589,146 @@ config.write(force: true)                        # overwrite any found config fi
 config.write('./investments.toml', force: true)  # overwrite specific config file
 ```
 
-### 2.16 persisted?
+### 2.19 exist?
+
+To check if a configuration file exists within the configured search paths use `exist?` method:
+
+```ruby
+config.exist? # => true
+```
+
+### 2.20 autoload_env
+
+The `autload_env` allows you to automatically read environment variables. In most cases you would combine it with [env_prefix=](#212-env_prefix) to only read a subset of variables. When using `autload_env`, anytime the `fetch` is called a corresponding enviornment variable will be checked.
+
+For example, given an evironment variable `MYTOOL_HOST` set to `localhost`:
+
+```ruby
+ENV['MYTOOL_HOST']=localhost
+```
+
+And loading environment variables with a prefix of `MYTOOL`:
+
+```ruby
+config.env_prefix = 'mytool'
+config.autoload_env
+```
+
+You can retrieve value with:
+
+```ruby
+config.fetch(:host)
+# => 'localhost'
+```
+
+## 3. Examples
+
+### 3.1 Working with env vars
+
+*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:
+
+```ruby
+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=](#212-env_prefix) and [set_from_env](#23-set_from_env):
+
+```ruby
+config.env_prefix = 'mytool'
+config.set_from_env(:host)
+config.set_from_env(:port)
+```
+
+or automatically load all prefixed environment variables with [autoload_env](#220-autoload-env):
+
+```ruby
+config.env_prefix = 'mytool'
+config.autoload_env
+```
+
+And then retrieve values with [fetch](#24-fetch):
+
+```ruby
+config.fetch(:host)
+#=> '192.168.1.17'
+config.fetch(:port)
+# => '7727'
+```
+
+### 3.2 Working with optparse
+
+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:
+
+```ruby
+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 craete a configuration instance:
+
+```ruby
+config = TTY::Config.new
+```
+
+And setup config filename:
+
+```ruby
+config_filename = options[:config_file_path] || 'config.yml'
+```
+
+As well as add configuration file locations to search in:
+
+```ruby
+config.append_path Dir.pwd
+config.append_path Dir.home
+```
+
+Once config is initialized, you can read the configuration from a config file:
+
+```ruby
+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:
 
-To check if a configuration file exists within the configured search paths use `persisted?` method:
+```ruby
+config.merge(options)
+```
+
+Provide optional validation to ensure both host and port are configured:
 
 ```ruby
-config.persisted? # => true
+if !config.fetch(:host) || !config.fetch(:port)
+  STDERR.puts "Host and port have to be specified (call with --help for help)."
+  exit 1
+end
 ```
 
 ## Development