tty-config 0.3.1 → 0.5.1

data/lib/tty/config.rb

@@ -1,11 +1,25 @@
 # 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
+  # Responsible for managing application configuration
+  #
+  # @api public
   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
@@ -15,80 +29,33 @@ module TTY
     # Error raised when validation assertion fails
     ValidationError = Class.new(StandardError)
 
+    # Coerce a hash object into Config instance
+    #
+    # @return [TTY::Config]
+    #
+    # @api private
     def self.coerce(hash, &block)
       new(normalize_hash(hash), &block)
     end
 
     # Convert string keys via method
     #
+    # @param [Hash] hash
+    #   the hash to normalize keys for
+    # @param [Symbol] method
+    #   the method to use for converting keys
+    #
+    # @return [Hash{Symbol => Object}]
+    #   the converted hash
+    #
     # @api private
     def self.normalize_hash(hash, method = :to_sym)
-      hash.reduce({}) do |acc, (key, val)|
+      hash.each_with_object({}) do |(key, val), acc|
         value = val.is_a?(::Hash) ? normalize_hash(val, method) : val
         acc[key.public_send(method)] = value
-        acc
-      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
@@ -113,22 +80,33 @@ module TTY
     # @api public
     attr_accessor :env_prefix
 
+    # The string used to separate parts in ENV variable name
+    # @api public
+    attr_accessor :env_separator
+
     # 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 = '.'
+      @filename = "config"
+      @extname = ".yml"
+      @key_delim = "."
       @envs = {}
-      @env_prefix = ''
+      @env_prefix = ""
+      @env_separator = "_"
       @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,14 +116,23 @@ 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
     end
 
     # Add path to locations to search in
     #
+    # @example
+    #   append_path(Dir.pwd)
+    #
+    # @param [String] path
+    #   the path to append
+    #
+    # @return [Array<String>]
+    #
     # @api public
     def append_path(path)
       @location_paths << path
@@ -153,6 +140,14 @@ module TTY
 
     # Insert location path at the begining
     #
+    # @example
+    #   prepend_path(Dir.pwd)
+    #
+    # @param [String] path
+    #   the path to prepend
+    #
+    # @return [Array<String>]
+    #
     # @api public
     def prepend_path(path)
       @location_paths.unshift(path)
@@ -160,6 +155,8 @@ module TTY
 
     # Check if env variables are auto loaded
     #
+    # @return [Boolean]
+    #
     # @api public
     def autoload_env?
       @autoload_env == true
@@ -172,9 +169,26 @@ module TTY
       @autoload_env = true
     end
 
-    # Set a value for a composite key and overrides any existing keys.
+    # Set a value for a composite key and overrides any existing keys
     # Keys are case-insensitive
     #
+    # @example
+    #   set(:foo, :bar, :baz, value: 2)
+    #
+    # @example
+    #   set(:foo, :bar, :baz) { 2 }
+    #
+    # @example
+    #   set("foo.bar.baz", value: 2)
+    #
+    # @param [Array<String, Symbol>, String] keys
+    #   the nested key to set value for
+    # @param [Object] value
+    #   the value to set
+    #
+    # @return [Object]
+    #   the set value
+    #
     # @api public
     def set(*keys, value: nil, &block)
       assert_either_value_or_block(value, block)
@@ -198,12 +212,22 @@ module TTY
 
     # Set a value for a composite key if not present already
     #
-    # @param [Array[String|Symbol]] keys
+    # @example
+    #   set_if_empty(:foo, :bar, :baz, value: 2)
+    #
+    # @param [Array<String, Symbol>] keys
     #   the keys to set value for
+    # @param [Object] value
+    #   the value to set
+    #
+    # @return [Object, nil]
+    #   the set value or nil
     #
     # @api public
     def set_if_empty(*keys, value: nil, &block)
-      return unless deep_find(@settings, keys.last.to_s).nil?
+      keys = convert_to_keys(keys)
+      return unless deep_fetch(@settings, *keys).nil?
+
       block ? set(*keys, &block) : set(*keys, value: value)
     end
 
@@ -213,12 +237,11 @@ module TTY
     #   set_from_env(:host)
     #   set_from_env(:foo, :bar) { 'HOST' }
     #
-    # @param [Array[String]] keys
+    # @param [Array<String>] keys
     #   the keys to bind to ENV variables
     #
     # @api public
     def set_from_env(*keys, &block)
-      assert_keys_with_block(convert_to_keys(keys), block)
       key = flatten_keys(keys)
       env_key = block.nil? ? key : block.()
       env_key = to_env_key(env_key)
@@ -229,17 +252,32 @@ module TTY
     #
     # @param [String] key
     #
+    # @return [String]
+    #
     # @api private
     def to_env_key(key)
-      env_key = key.to_s.upcase
-      @env_prefix == '' ? env_key : "#{@env_prefix.to_s.upcase}_#{env_key}"
+      env_key = key.to_s.gsub(key_delim, env_separator).upcase
+      if @env_prefix == ""
+        env_key
+      else
+        "#{@env_prefix.to_s.upcase}#{env_separator}#{env_key}"
+      end
     end
 
     # Fetch value under a composite key
     #
-    # @param [Array[String|Symbol]] keys
+    # @example
+    #   fetch(:foo, :bar, :baz)
+    #
+    # @example
+    #   fetch("foo.bar.baz")
+    #
+    # @param [Array<String, Symbol>, String] keys
     #   the keys to get value at
     # @param [Object] default
+    #   the default value
+    #
+    # @return [Object]
     #
     # @api public
     def fetch(*keys, default: nil, &block)
@@ -259,24 +297,37 @@ module TTY
       value = block || default if value.nil?
 
       while callable_without_params?(value)
-        value = value.call
+        value = value.()
       end
       value
     end
 
     # Merge in other configuration settings
     #
-    # @param [Hash[Object]] other_settings
+    # @param [Hash{Symbol => Object]] other_settings
+    #
+    # @return [Hash, nil]
+    #   the combined settings or nil
     #
     # @api public
     def merge(other_settings)
+      return unless other_settings.respond_to?(:to_hash)
+
       @settings = deep_merge(@settings, other_settings)
     end
 
     # Append values to an already existing nested key
     #
-    # @param [Array[String|Symbol]] values
+    # @example
+    #   append(1, 2, to: %i[foo bar])
+    #
+    # @param [Array<Object>] values
     #   the values to append
+    # @param [Array<String, Symbol] to
+    #   the nested key to append to
+    #
+    # @return [Array<Object>]
+    #   the values for a nested key
     #
     # @api public
     def append(*values, to: nil)
@@ -286,24 +337,45 @@ module TTY
 
     # Remove a set of values from a nested key
     #
-    # @param [Array[String|Symbol]] keys
-    #   the keys for a value removal
+    # @example
+    #   remove(1, 2, from: :foo)
+    #
+    # @example
+    #   remove(1, 2, from: %i[foo bar])
+    #
+    # @param [Array<Object>] values
+    #   the values to remove from a nested key
+    # @param [Array<String, Symbol>, String] from
+    #   the nested key to remove values from
     #
     # @api public
     def remove(*values, from: nil)
       keys = Array(from)
+      raise ArgumentError, "Need to set key to remove from" if keys.empty?
+
       set(*keys, value: Array(fetch(*keys)) - values)
     end
 
     # Delete a value from a nested key
     #
-    # @param [Array[String|Symbol]] keys
+    # @example
+    #   delete(:foo, :bar, :baz)
+    #
+    # @example
+    #   delete(:unknown) { |key| "#{key} isn't set" }
+    #
+    # @param [Array<String, Symbol>] keys
     #   the keys for a value deletion
     #
+    # @yield [key] Invoke the block with a missing key
+    #
+    # @return [Object]
+    #   the deleted value(s)
+    #
     # @api public
-    def delete(*keys)
+    def delete(*keys, &default)
       keys = convert_to_keys(keys)
-      deep_delete(*keys, @settings)
+      deep_delete(*keys, @settings, &default)
     end
 
     # Define an alias to a nested key
@@ -311,7 +383,7 @@ module TTY
     # @example
     #   alias_setting(:foo, to: :bar)
     #
-    # @param [Array[String]] keys
+    # @param [Array<String>] keys
     #   the alias key
     #
     # @api public
@@ -321,11 +393,11 @@ module TTY
       alias_key = flatten_keys(alias_keys)
 
       if alias_key == flat_setting
-        raise ArgumentError, 'Alias matches setting key'
+        raise ArgumentError, "Alias matches setting key"
       end
 
       if fetch(alias_key)
-        raise ArgumentError, 'Setting already exists with an alias ' \
+        raise ArgumentError, "Setting already exists with an alias " \
                              "'#{alias_keys.map(&:inspect).join(', ')}'"
       end
 
@@ -334,7 +406,7 @@ module TTY
 
     # Register a validation rule for a nested key
     #
-    # @param [Array[String]] keys
+    # @param [Array<String>] keys
     #   a deep nested keys
     # @param [Proc] validator
     #   the logic to use to validate given nested key
@@ -385,37 +457,64 @@ module TTY
     # @api public
     def read(file = find_file, format: :auto)
       if file.nil?
-        raise ReadError, 'No file found to read configuration from!'
+        raise ReadError, "No file found to read configuration from!"
       elsif !::File.exist?(file)
         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.
     #
+    # @example
+    #   write(force: true, create: true)
+    #
     # @param [String] file
-    #   the path to a file
+    #   the file to write to
+    # @param [Boolean] create
+    #   whether or not to create missing path directories, false by default
+    # @param [Boolean] force
+    #   whether or not to overwrite existing configuration file, false by default
+    # @param [String] format
+    #   the format name for the configuration file, :auto by defualt
+    # @param [String] path
+    #   the custom path to use to write a file to
+    #
+    # @raise [TTY::Config::WriteError]
     #
     # @api public
-    def write(file = find_file, force: false, format: :auto)
-      if file && ::File.exist?(file)
-        if !force
-          raise WriteError, "File `#{file}` already exists. " \
-                            'Use :force option to overwrite.'
-        elsif !::File.writable?(file)
-          raise WriteError, "Cannot write to #{file}."
-        end
-      end
+    def write(file = find_file, create: false, force: false, format: :auto,
+              path: nil)
+      file = fullpath(file, path)
+      check_can_write(file, force)
 
-      if file.nil?
-        dir = @location_paths.empty? ? Dir.pwd : @location_paths.first
-        file = ::File.join(dir, "#{filename}#{@extname}")
-      end
+      set_file_metadata(file)
+      ext = (format == :auto ? extname : ".#{format}")
+      content = marshal(@settings, ext: ext)
+      filepath = Pathname.new(file)
 
-      content = marshal(file, @settings, format: format)
-      ::File.write(file, content)
+      create_missing_dirs(filepath, create)
+      ::File.write(filepath, content)
+    end
+
+    # Set file name and extension
+    #
+    # @example
+    #   set_file_metadata("config.yml")
+    #
+    # @param [File] file
+    #   the file to set metadata for
+    #
+    # @api public
+    def set_file_metadata(file)
+      self.extname  = ::File.extname(file)
+      self.filename = ::File.basename(file, extname)
     end
 
     # Current configuration
@@ -433,7 +532,7 @@ module TTY
     # @api private
     def assert_either_value_or_block(value, block)
       if value.nil? && block.nil?
-        raise ArgumentError, 'Need to set either value or block'
+        raise ArgumentError, "Need to set either value or block"
       elsif !(value.nil? || block.nil?)
         raise ArgumentError, "Can't set both value and block"
       end
@@ -453,7 +552,11 @@ module TTY
     # that will be performed at point when a new proc is invoked.
     #
     # @param [String] key
+    #   the key to set validation for
     # @param [Proc] callback
+    #   the callback to wrap
+    #
+    # @return [Proc]
     #
     # @api private
     def delay_validation(key, callback)
@@ -467,18 +570,14 @@ module TTY
     # Check if key passes all registered validations for a key
     #
     # @param [String] key
+    #   the key to validate a value for
     # @param [Object] value
+    #   the value to check
     #
     # @api private
     def assert_valid(key, value)
       validators[key].each do |validator|
-        validator.call(key, value)
-      end
-    end
-
-    def assert_keys_with_block(keys, block)
-      if keys.size > 1 && block.nil?
-        raise ArgumentError, 'Need to set env var in block'
+        validator.(key, value)
       end
     end
 
@@ -490,12 +589,16 @@ module TTY
     #
     # @param [Hash] settings
     #
-    # @param [Array[Object]]
+    # @param [Array<Object>] keys
     #   the keys to nest
     #
+    # @return [Hash]
+    #   the nested setting
+    #
     # @api private
     def deep_set(settings, *keys)
       return settings if keys.empty?
+
       key, *rest = *keys
       value = settings[key]
 
@@ -510,15 +613,13 @@ module TTY
       end
     end
 
-    def deep_find(settings, key, found = nil)
-      if settings.respond_to?(:key?) && settings.key?(key)
-        settings[key]
-      elsif settings.is_a?(Enumerable)
-        settings.each { |obj| found = deep_find(obj, key) }
-        found
-      end
-    end
-
+    # Convert key to an array of key elements
+    #
+    # @param [String, Array<String, Symbol>] keys
+    #
+    # @return [Array<String>]
+    #
+    # @api private
     def convert_to_keys(keys)
       first_key = keys[0]
       if first_key.to_s.include?(key_delim)
@@ -528,6 +629,18 @@ module TTY
       end
     end
 
+    # Convert nested key from an array to a string
+    #
+    # @example
+    #   flatten_keys(%i[foo bar baz]) # => "foo.bar.baz"
+    #
+    # @param [Array<String, Symbol>] keys
+    #   the nested key to convert
+    #
+    # @return [String]
+    #   the delimited nested key
+    #
+    # @api private
     def flatten_keys(keys)
       first_key = keys[0]
       if first_key.to_s.include?(key_delim)
@@ -540,8 +653,12 @@ module TTY
     # Fetch value under deeply nested keys with indiffernt key access
     #
     # @param [Hash] settings
+    #   the settings to search
+    # @param [Array<Object>] keys
+    #   the nested key to look up
     #
-    # @param [Array[Object]] keys
+    # @return [Object, nil]
+    #   the value or nil
     #
     # @api private
     def deep_fetch(settings, *keys)
@@ -554,6 +671,14 @@ module TTY
       end
     end
 
+    # Merge two deeply nested hash objects
+    #
+    # @param [Hash] this_hash
+    # @param [Hash] other_hash
+    #
+    # @return [Hash]
+    #   the merged hash object
+    #
     # @api private
     def deep_merge(this_hash, other_hash,  &block)
       this_hash.merge(other_hash) do |key, this_val, other_val|
@@ -567,21 +692,41 @@ module TTY
       end
     end
 
+    # Delete a deeply nested key
+    #
+    # @param [Array<String>] keys
+    #   the nested key to delete
+    # @param [Hash{String => Object}]
+    #   the settings to delete key from
+    #
+    # @return [Object]
+    #   the deleted object(s)
+    #
     # @api private
-    def deep_delete(*keys, settings)
+    def deep_delete(*keys, settings, &default)
       key, *rest = keys
       value = settings[key]
-      if !value.nil? && value.is_a?(::Hash)
-        deep_delete(*rest, value)
+      if !rest.empty? && value.is_a?(::Hash)
+        deep_delete(*rest, value, &default)
       elsif !value.nil?
         settings.delete(key)
+      elsif default
+        default.(key)
       end
     end
 
+    # Search for a configuration file in a path
+    #
+    # @param [String] path
+    #   the path to search
+    #
+    # @return [String, nil]
+    #   the configuration file path or nil
+    #
     # @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
@@ -589,81 +734,120 @@ module TTY
       nil
     end
 
+    # Create a full path to a configuration file
+    #
+    # @param [String] file
+    #   the configuration file
+    # @param [String] path
+    #   the path to configuration file
+    #
+    # @return [String]
+    #   the full path to a file
+    #
+    # @api private
+    def fullpath(file, path)
+      if file.nil?
+        dir = path || @location_paths.first || Dir.pwd
+        ::File.join(dir, "#{filename}#{@extname}")
+      elsif file && path
+        ::File.join(path, ::File.basename(file))
+      else
+        file
+      end
+    end
+
+    # Check if a file can be written to
+    #
+    # @param [String] file
+    #   the configuration file
+    # @param [Boolean] force
+    #   whether or not to force writing
+    #
+    # @raise [TTY::Config::WriteError]
+    #
+    # @return [nil]
+    #
     # @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)
+    def check_can_write(file, force)
+      return unless file && ::File.exist?(file)
+
+      if !force
+        raise WriteError, "File `#{file}` already exists. " \
+                          "Use :force option to overwrite."
+      elsif !::File.writable?(file)
+        raise WriteError, "Cannot write to #{file}."
+      end
+    end
+
+    # Create any missing directories
+    #
+    # @param [Pathname] filepath
+    #   the file path
+    # @param [Boolean] create
+    #   whether or not to create missing directories
+    #
+    # @raise [TTY::Config::WriteError]
+    #
+    # @return [nil]
+    #
+    # @api private
+    def create_missing_dirs(filepath, create)
+      if !filepath.dirname.exist? && !create
+        raise WriteError, "Directory `#{filepath.dirname}` doesn't exist. " \
+                          "Use :create option to create missing directories."
       else
-        raise ReadError, "Config file format `#{ext}` is not supported."
+        filepath.dirname.mkpath
       end
     end
 
-    # Try loading read dependency
+    # Crate a marshaller instance based on the extension name
+    #
+    # @param [String] ext
+    #   the extension name
+    #
+    # @return [nil, Marshaller]
+    #
     # @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 create_marshaller(ext)
+      marshaller = marshallers.find { |marsh| marsh.ext.include?(ext) }
+
+      return nil if marshaller.nil?
+
+      marshaller.new
     end
 
-    # Marshal data hash into a configuration file content
+    # Unmarshal content into a hash object
     #
-    # @return [String]
+    # @param [String] content
+    #   the content to convert into a hash object
+    #
+    # @return [Hash{String => Object}]
     #
     # @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 unmarshal(content, ext: nil)
+      ext ||= extname
+      if marshaller = create_marshaller(ext)
+        marshaller.unmarshal(content)
       else
-        raise WriteError, "Config file format `#{ext}` is not supported."
+        raise ReadError, "Config file format `#{ext}` is not supported."
       end
     end
 
-    # Try loading write depedency
+    # Marshal hash object into a configuration file content
+    #
+    # @param [Hash{String => Object}] object
+    #   the object to convert to string
+    #
+    # @return [String]
+    #
     # @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."
+    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
   end # Config
 end # TTY