tty-config 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15acd31b643bbf86fbacabac790174050f401eb46fdb943365f7f05180d5487a
-  data.tar.gz: 51d27ba31c438bd5dacfcfa2ee255bfc29ac2879cd9fa51512226a073da91a85
+  metadata.gz: 0f0321ad959e00b63f653d7f27a89964cdc24b103aab2052615e0ed3fdf284ce
+  data.tar.gz: 12df44d97821e84cb19620fadec565841d0de28abc1a4ba1cd8a05d9d1d6ec24
 SHA512:
-  metadata.gz: d5fd67029f81ef16988f1892178c30e84ead7376f7ae863fc66acfe8f97dedc7a158a7cc7cbef282356ae42d9b7182338f54fcb27595a9474fa7d7cbec0e4211
-  data.tar.gz: a0f36d8133ae66dd2bb94f051e2cf90299ae63ec10d4af4d0204564d055c51c4136ebc8fcadf1c4505cbc9b0ab26485009f1b9a6544c9d7338a7b1d1a7f8d992
+  metadata.gz: ebe68702be360238664adf912b42342df8e3e3be266d7e52d2be515d8f48373db53850688517f7c569f2b9674a88371a3205bad707d48a209c01d147af27c07f
+  data.tar.gz: af1c4f4586a6be640f65ebe01e0dcb88340860b4ae1645ba611135e618ca1b772c75eab2ab9744e0409dddac316154f2358d403e0950af20c25c1755ee7f16cc

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change log
 
+## [v0.4.0] - 2020-01-25
+
+### Added
+* Add DependencyLoader for a generic interface for loading marshalling dependencies
+* Add Marshaller as a generic interface for building marshalling plugins
+* Add MarshallerRegistry for storing all marshallers
+* Add Marshallers to allow configuration of marshallers via #register_marshaller
+  & #unregister_marshaller
+
+### Changed
+* Change #initialize to accept hash as settings
+* Change #marshal & #unmarshal to use marshalling plugins
+* Change gemspec to add metadata and remove test artefacts
+
 ## [v0.3.2] - 2019-06-18
 
 ### Changed
@@ -41,6 +55,7 @@
 
 * Initial implementation and release
 
+[v0.4.0]: https://github.com/piotrmurach/tty-config/compare/v0.3.2...v0.4.0
 [v0.3.2]: https://github.com/piotrmurach/tty-config/compare/v0.3.1...v0.3.2
 [v0.3.1]: https://github.com/piotrmurach/tty-config/compare/v0.3.0...v0.3.1
 [v0.3.0]: https://github.com/piotrmurach/tty-config/compare/v0.2.0...v0.3.0

data/README.md

@@ -25,11 +25,15 @@
 
 ## Features
 
-* 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
+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
 
 ## Installation
 
@@ -72,6 +76,8 @@ Or install it yourself as:
   * [2.18 write](#218-write)
   * [2.19 exist?](#219-exist)
   * [2.20 autoload_env](#220-autoload_env)
+  * [2.21 register_marshaller](#221-register_marshaller)
+  * [2.22 unregister_marshaller](#222-register_marshaller)
 * [3. Examples](#3-examples)
   * [3.1 Working with env vars](#31-working-with-env-vars)
   * [3.2 Working with optparse](#32-working-with-optparse)
@@ -85,7 +91,7 @@ config = TTY::Config.new
 config.filename = 'investments'
 ```
 
-then configure values for different nested keys with `set` and `append`:
+Then configure values for different nested keys with `set` and `append`:
 
 ```ruby
 config.set(:settings, :base, value: 'USD')
@@ -95,7 +101,7 @@ config.set(:coins, value: ['BTC'])
 config.append('ETH', 'TRX', 'DASH', to: :coins)
 ```
 
-get any value by using `fetch`:
+You can get any value by using `fetch`:
 
 ```ruby
 config.fetch(:settings, :base)
@@ -105,7 +111,7 @@ config.fetch(:coins)
 # => ['BTC', 'ETH', 'TRX', 'DASH']
 ```
 
-and `write` configration out to `investments.yml`:
+And call `write` to persist the configuration to `investments.yml` file:
 
 ```ruby
 config.write
@@ -121,14 +127,14 @@ config.write
 #  - DASH
 ```
 
-and then to read an `investments.yml` file, you need to provide the locations to search in:
+To read an `investments.yml` file, you need to provide the locations to search in:
 
 ```ruby
 config.append_path Dir.pwd
 config.append_path Dir.home
 ```
 
-Finally, read in configuration back again:
+Finally, call `read` to convert configuration file back into an object again:
 
 ```ruby
 config.read
@@ -175,7 +181,7 @@ You can also specify deeply nested configuration settings by passing sequence of
 config.set :settings, :base, value: 'USD'
 ```
 
-is equivalent to:
+Which is equivalent to:
 
 ```ruby
 config.set 'settings.base', value: 'USD'
@@ -240,7 +246,7 @@ config.set_from_env('settings.base') { 'CURRENCY'}
 config.set_from_env('settings.base') { :currency}
 ```
 
-And asssuming `ENV['CURRENCY']=USD`:
+And assuming `ENV['CURRENCY']=USD`:
 
 ```ruby
 config.fetch(:settings, :base)
@@ -266,7 +272,7 @@ Similar to `set` operation, `fetch` allows you to retrieve deeply nested values:
 config.fetch(:settings, :base) # => USD
 ```
 
-is equivalent to:
+Which is equivalent to:
 
 ```ruby
 config.fetch('settings.base')
@@ -432,7 +438,7 @@ 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 validaitons will be run:
+When setting value all the validations will be run:
 
 ```ruby
 config.set(:settings, :base, value: 'PL')
@@ -529,8 +535,10 @@ Currently the supported file formats are:
 * `json` for `.json` extension
 * `toml` for `.toml` extension
 * `ini`  for `.ini`, `.cnf`, `.conf`, `.cfg`, `.cf extensions`
+* `hcl`  for `.hcl` extensions
+* `jprops` 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 specifed then all known extensions will be tried.
+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:
 
@@ -599,9 +607,9 @@ 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.
+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 environment variable will be checked.
 
-For example, given an evironment variable `MYTOOL_HOST` set to `localhost`:
+For example, given an environment variable `MYTOOL_HOST` set to `localhost`:
 
 ```ruby
 ENV['MYTOOL_HOST']=localhost
@@ -621,6 +629,83 @@ config.fetch(:host)
 # => 'localhost'
 ```
 
+### 2.21 register_marshaller
+
+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:
+
+```ruby
+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:
+
+```ruby
+dependency "toml"
+dependency "toml", "tomlrb"
+```
+
+Or provide dependencies in a block:
+
+```ruby
+dependency do
+  require "toml"
+  require "tomlrb"
+end
+```
+
+Putting it all together, you can create your own marshaller like so:
+
+```ruby
+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`:
+
+```ruby
+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:
+
+```ruby
+config.register_marshaller(:toml, MyTOMLMarshaller)
+```
+
+### 2.22 unregister_marshaller
+
+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:
+
+```ruby
+config.unregister_marshaller :yaml, :json, :toml, :ini, :hcl
+```
+
 ## 3. Examples
 
 ### 3.1 Working with env vars
@@ -640,7 +725,7 @@ config.set_from_env(:host)
 config.set_from_env(:port)
 ```
 
-or automatically load all prefixed environment variables with [autoload_env](#220-autoload-env):
+Or automatically load all prefixed environment variables with [autoload_env](#220-autoload-env):
 
 ```ruby
 config.env_prefix = 'mytool'

data/lib/tty/config.rb

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
-require 'pathname'
+require "pathname"
 
-require_relative 'config/version'
+require_relative "config/version"
+require_relative "config/marshallers"
+require_relative "config/marshallers/ini_marshaller"
+require_relative "config/marshallers/json_marshaller"
+require_relative "config/marshallers/yaml_marshaller"
+require_relative "config/marshallers/toml_marshaller"
+require_relative "config/marshallers/hcl_marshaller"
+require_relative "config/marshallers/java_props_marshaller"
 
 module TTY
   class Config
+    include Marshallers
+
+    # Error raised when failed to load a dependency
+    DependencyLoadError = Class.new(StandardError)
     # Error raised when key fails validation
     ReadError = Class.new(StandardError)
     # Error raised when issues writing configuration to a file
@@ -30,65 +41,6 @@ module TTY
       end
     end
 
-    # Generate file content based on the data hash
-    #
-    # @param [Hash] data
-    #
-    # @return [String]
-    #   the file content
-    #
-    # @api public
-    def self.generate(data, separator: '=')
-      content  = []
-      values   = {}
-      sections = {}
-
-      data.keys.sort.each do |key|
-        val = data[key]
-        if val.is_a?(NilClass)
-          next
-        elsif val.is_a?(Hash) ||
-              (val.is_a?(Array) && val.first.is_a?(Hash))
-          sections[key] = val
-        elsif val.is_a?(Array)
-          values[key] = val.join(',')
-        else
-          values[key] = val
-        end
-      end
-
-      # values
-      values.each do |key, val|
-        content << "#{key} #{separator} #{val}"
-      end
-      content << '' unless values.empty?
-
-      # sections
-      sections.each do |section, object|
-        next if object.empty? # only add section if values present
-
-        content << "[#{section}]"
-        if object.is_a?(Array)
-          object = object.reduce({}, :merge!)
-        end
-        object.each do |key, val|
-          val = val.join(',') if val.is_a?(Array)
-          content << "#{key} #{separator} #{val}" if val
-        end
-        content << ''
-      end
-      content.join("\n")
-    end
-
-    # Storage for suppported format & extensions pairs
-    # @api public
-    EXTENSIONS = {
-      yaml: %w(.yaml .yml),
-      json: %w(.json),
-      toml: %w(.toml),
-      ini:  %w(.ini .cnf .conf .cfg .cf)
-    }.freeze
-
     # A collection of config paths
     # @api public
     attr_reader :location_paths
@@ -116,19 +68,25 @@ module TTY
     # Create a configuration instance
     #
     # @api public
-    def initialize(**settings)
+    def initialize(settings = {})
       @settings = settings
       @location_paths = []
       @validators = {}
       @filename = 'config'
       @extname = '.yml'
-      @extensions = EXTENSIONS.values.flatten << ''
       @key_delim = '.'
       @envs = {}
       @env_prefix = ''
       @autoload_env = false
       @aliases = {}
 
+      register_marshaller :yaml, Marshallers::YAMLMarshaller
+      register_marshaller :json, Marshallers::JSONMarshaller
+      register_marshaller :toml, Marshallers::TOMLMarshaller
+      register_marshaller :ini, Marshallers::INIMarshaller
+      register_marshaller :hcl, Marshallers::HCLMarshaller
+      register_marshaller :jprops, Marshallers::JavaPropsMarshaller
+
       yield(self) if block_given?
     end
 
@@ -138,7 +96,7 @@ module TTY
     #
     # api public
     def extname=(name)
-      unless @extensions.include?(name)
+      unless extensions.include?(name)
         raise UnsupportedExtError, "Config file format `#{name}` is not supported."
       end
       @extname = name
@@ -392,7 +350,12 @@ module TTY
         raise ReadError, "Configuration file `#{file}` does not exist!"
       end
 
-      merge(unmarshal(file, format: format))
+      set_file_metadata(file)
+
+      ext = (format == :auto ? extname : ".#{format}")
+      content = ::File.read(file)
+
+      merge(unmarshal(content, ext: ext))
     end
 
     # Write current configuration to a file.
@@ -416,10 +379,24 @@ module TTY
         file = ::File.join(dir, "#{filename}#{@extname}")
       end
 
-      content = marshal(file, @settings, format: format)
+      set_file_metadata(file)
+
+      ext = (format == :auto ? extname : ".#{format}")
+      content = marshal(@settings, ext: ext)
+
       ::File.write(file, content)
     end
 
+    # Set file name and extension
+    #
+    # @param [File] file
+    #
+    # @api public
+    def set_file_metadata(file)
+      self.extname  = ::File.extname(file)
+      self.filename = ::File.basename(file, extname)
+    end
+
     # Current configuration
     #
     # @api public
@@ -583,7 +560,7 @@ module TTY
     # @api private
     def search_in_path(path)
       path = Pathname.new(path)
-      @extensions.each do |ext|
+      extensions.each do |ext|
         if ::File.exist?(path.join("#{filename}#{ext}").to_s)
           return path.join("#{filename}#{ext}").to_s
         end
@@ -591,81 +568,41 @@ module TTY
       nil
     end
 
+    # Crate a marshaller instance based on the extension name
+    #
+    # @return [nil, Marshaller]
+    #
     # @api private
-    def unmarshal(file, format: :auto)
-      file_ext = ::File.extname(file)
-      ext = (format == :auto ? file_ext : ".#{format}")
-      self.extname  = file_ext
-      self.filename = ::File.basename(file, file_ext)
-
-      case ext
-      when *EXTENSIONS[:yaml]
-        load_read_dep('yaml', ext)
-        if YAML.respond_to?(:safe_load)
-          YAML.safe_load(::File.read(file))
-        else
-          YAML.load(::File.read(file))
-        end
-      when *EXTENSIONS[:json]
-        load_read_dep('json', ext)
-        JSON.parse(::File.read(file))
-      when *EXTENSIONS[:toml]
-        load_read_dep('toml', ext)
-        TOML.load(::File.read(file))
-      when *EXTENSIONS[:ini]
-        load_read_dep('inifile', ext)
-        ini = IniFile.load(file).to_h
-        global = ini.delete('global')
-        ini.merge!(global)
-      else
-        raise ReadError, "Config file format `#{ext}` is not supported."
-      end
+    def create_marshaller(ext)
+      marshaller = marshallers.find { |marsh| marsh.ext.include?(ext) }
+
+      return nil if marshaller.nil?
+
+      marshaller.new
     end
 
-    # Try loading read dependency
     # @api private
-    def load_read_dep(gem_name, format)
-      require gem_name
-    rescue LoadError
-      raise ReadError, "Gem `#{gem_name}` is missing. Please install it " \
-                       "to read #{format} configuration format."
+    def unmarshal(content, ext: nil)
+      ext ||= extname
+      if marshaller = create_marshaller(ext)
+        marshaller.unmarshal(content)
+      else
+        raise ReadError, "Config file format `#{ext}` is not supported."
+      end
     end
 
-    # Marshal data hash into a configuration file content
+    # Marshal hash object into a configuration file content
     #
     # @return [String]
     #
     # @api private
-    def marshal(file, data, format: :auto)
-      file_ext = ::File.extname(file)
-      ext = (format == :auto ? file_ext : ".#{format}")
-      self.extname  = file_ext
-      self.filename = ::File.basename(file, file_ext)
-
-      case ext
-      when *EXTENSIONS[:yaml]
-        load_write_dep('yaml', ext)
-        YAML.dump(self.class.normalize_hash(data, :to_s))
-      when *EXTENSIONS[:json]
-        load_write_dep('json', ext)
-        JSON.pretty_generate(data)
-      when *EXTENSIONS[:toml]
-        load_write_dep('toml', ext)
-        TOML::Generator.new(data).body
-      when *EXTENSIONS[:ini]
-        Config.generate(data)
+    def marshal(object, ext: nil)
+      ext ||= extname
+      if marshaller = create_marshaller(ext)
+        marshaller.marshal(object)
       else
         raise WriteError, "Config file format `#{ext}` is not supported."
       end
     end
-
-    # Try loading write depedency
-    # @api private
-    def load_write_dep(gem_name, format)
-      require gem_name
-    rescue LoadError
-      raise WriteError, "Gem `#{gem_name}` is missing. Please install it " \
-                       "to read #{format} configuration format."
-    end
   end # Config
 end # TTY