tty-config 0.4.0 → 0.5.0

data/lib/tty-config.rb

@@ -1 +1 @@
-require_relative 'tty/config'
+require_relative "tty/config"

data/lib/tty/config.rb

@@ -12,6 +12,9 @@ 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
 
@@ -26,18 +29,30 @@ 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
 
@@ -65,6 +80,10 @@ 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
@@ -72,11 +91,12 @@ module TTY
       @settings = settings
       @location_paths = []
       @validators = {}
-      @filename = 'config'
-      @extname = '.yml'
-      @key_delim = '.'
+      @filename = "config"
+      @extname = ".yml"
+      @key_delim = "."
       @envs = {}
-      @env_prefix = ''
+      @env_prefix = ""
+      @env_separator = "_"
       @autoload_env = false
       @aliases = {}
 
@@ -99,11 +119,20 @@ module TTY
       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
@@ -111,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)
@@ -118,6 +155,8 @@ module TTY
 
     # Check if env variables are auto loaded
     #
+    # @return [Boolean]
+    #
     # @api public
     def autoload_env?
       @autoload_env == true
@@ -130,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)
@@ -156,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
 
@@ -171,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)
@@ -187,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)
@@ -217,14 +297,17 @@ 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)
@@ -235,8 +318,16 @@ module TTY
 
     # 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)
@@ -246,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
@@ -271,7 +383,7 @@ module TTY
     # @example
     #   alias_setting(:foo, to: :bar)
     #
-    # @param [Array[String]] keys
+    # @param [Array<String>] keys
     #   the alias key
     #
     # @api public
@@ -281,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
 
@@ -294,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
@@ -345,7 +457,7 @@ 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
@@ -360,36 +472,44 @@ module TTY
 
     # 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
-
-      if file.nil?
-        dir = @location_paths.empty? ? Dir.pwd : @location_paths.first
-        file = ::File.join(dir, "#{filename}#{@extname}")
-      end
+    def write(file = find_file, create: false, force: false, format: :auto,
+              path: nil)
+      file = fullpath(file, path)
+      check_can_write(file, force)
 
       set_file_metadata(file)
-
       ext = (format == :auto ? extname : ".#{format}")
       content = marshal(@settings, ext: ext)
+      filepath = Pathname.new(file)
 
-      ::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)
@@ -412,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
@@ -432,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)
@@ -446,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
 
@@ -469,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]
 
@@ -489,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)
@@ -507,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)
@@ -519,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)
@@ -533,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|
@@ -546,17 +692,37 @@ 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)
@@ -568,8 +734,77 @@ 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 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
+        filepath.dirname.mkpath
+      end
+    end
+
     # Crate a marshaller instance based on the extension name
     #
+    # @param [String] ext
+    #   the extension name
+    #
     # @return [nil, Marshaller]
     #
     # @api private
@@ -581,6 +816,13 @@ module TTY
       marshaller.new
     end
 
+    # Unmarshal content into a hash object
+    #
+    # @param [String] content
+    #   the content to convert into a hash object
+    #
+    # @return [Hash{String => Object}]
+    #
     # @api private
     def unmarshal(content, ext: nil)
       ext ||= extname
@@ -593,6 +835,9 @@ module TTY
 
     # Marshal hash object into a configuration file content
     #
+    # @param [Hash{String => Object}] object
+    #   the object to convert to string
+    #
     # @return [String]
     #
     # @api private