tty-config 0.2.0 → 0.5.0

data/lib/tty-config.rb

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

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,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
 
@@ -50,14 +76,36 @@ module TTY
     # @api public
     attr_reader :validators
 
+    # The prefix used for searching ENV variables
+    # @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 = {})
-      @location_paths = []
       @settings = settings
+      @location_paths = []
       @validators = {}
-      @filename = 'config'
-      @extname = '.yml'
-      @extensions = ['.yaml', '.yml', '.json', '.toml']
-      @key_delim = '.'
+      @filename = "config"
+      @extname = ".yml"
+      @key_delim = "."
+      @envs = {}
+      @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
@@ -68,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
@@ -83,14 +140,55 @@ 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)
     end
 
-    # Set a value for a composite key and overrides any existing keys.
+    # Check if env variables are auto loaded
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def autoload_env?
+      @autoload_env == true
+    end
+
+    # Auto load env variables
+    #
+    # @api public
+    def autoload_env
+      @autoload_env = true
+    end
+
+    # 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)
@@ -114,45 +212,122 @@ 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
 
+    # Bind a key to ENV variable
+    #
+    # @example
+    #   set_from_env(:host)
+    #   set_from_env(:foo, :bar) { 'HOST' }
+    #
+    # @param [Array<String>] keys
+    #   the keys to bind to ENV variables
+    #
+    # @api public
+    def set_from_env(*keys, &block)
+      key = flatten_keys(keys)
+      env_key = block.nil? ? key : block.()
+      env_key = to_env_key(env_key)
+      @envs[key.to_s.downcase] = env_key
+    end
+
+    # Convert config key to standard ENV var name
+    #
+    # @param [String] key
+    #
+    # @return [String]
+    #
+    # @api private
+    def to_env_key(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)
+      # check alias
+      real_key = @aliases[flatten_keys(keys)]
+      keys = real_key.split(key_delim) if real_key
+
       keys = convert_to_keys(keys)
+      env_key = autoload_env? ? to_env_key(keys[0]) : @envs[flatten_keys(keys)]
+      # first try settings
       value = deep_fetch(@settings, *keys)
+      # then try ENV var
+      if value.nil? && env_key
+        value = ENV[env_key]
+      end
+      # then try default
       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)
@@ -162,27 +337,79 @@ 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
+    #
+    # @example
+    #   alias_setting(:foo, to: :bar)
+    #
+    # @param [Array<String>] keys
+    #   the alias key
+    #
+    # @api public
+    def alias_setting(*keys, to: nil)
+      flat_setting = flatten_keys(keys)
+      alias_keys = Array(to)
+      alias_key = flatten_keys(alias_keys)
+
+      if alias_key == flat_setting
+        raise ArgumentError, "Alias matches setting key"
+      end
+
+      if fetch(alias_key)
+        raise ArgumentError, "Setting already exists with an alias " \
+                             "'#{alias_keys.map(&:inspect).join(', ')}'"
+      end
+
+      @aliases[alias_key] = flat_setting
     end
 
-    # Register validation for a nested key
+    # Register a validation rule for a nested key
+    #
+    # @param [Array<String>] keys
+    #   a deep nested keys
+    # @param [Proc] validator
+    #   the logic to use to validate given nested key
     #
     # @api public
     def validate(*keys, &validator)
@@ -192,26 +419,8 @@ module TTY
       validators[key] = values
     end
 
-    # Check if key passes all registered validations
-    #
-    # @api private
-    def assert_valid(key, value)
-      validators[key].each do |validator|
-        validator.call(key, value)
-      end
-    end
-
-    # Delay key validation
+    # Find configuration file matching filename and extension
     #
-    # @api private
-    def delay_validation(key, callback)
-      -> do
-        val = callback.()
-        assert_valid(key, val)
-        val
-      end
-    end
-
     # @api private
     def find_file
       @location_paths.each do |location_path|
@@ -227,9 +436,10 @@ module TTY
     # @return [Boolean]
     #
     # @api public
-    def persisted?
+    def exist?
       !find_file.nil?
     end
+    alias persisted? exist?
 
     # Find and read a configuration file.
     #
@@ -239,41 +449,72 @@ module TTY
     # @param [String] file
     #   the path to the configuration file to be read
     #
+    # @param [String] format
+    #   the format to read configuration in
+    #
     # @raise [TTY::Config::ReadError]
     #
     # @api public
-    def read(file = find_file)
+    def read(file = find_file, format: :auto)
       if file.nil?
         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))
+      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)
-      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)
 
-      marshal(file, @settings)
+      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
@@ -286,11 +527,9 @@ module TTY
 
     private
 
-    def callable_without_params?(object)
-      object.respond_to?(:call) &&
-        (!object.respond_to?(:arity) || object.arity.zero?)
-    end
-
+    # Ensure that value is set either through parameter or block
+    #
+    # @api private
     def assert_either_value_or_block(value, block)
       if value.nil? && block.nil?
         raise ArgumentError, "Need to set either value or block"
@@ -299,6 +538,49 @@ module TTY
       end
     end
 
+    # Check if object is a proc with no arguments
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def callable_without_params?(object)
+      object.respond_to?(:call) &&
+        (!object.respond_to?(:arity) || object.arity.zero?)
+    end
+
+    # Wrap callback in a proc object that includes validation
+    # 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)
+      -> do
+        val = callback.()
+        assert_valid(key, val)
+        val
+      end
+    end
+
+    # 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.(key, value)
+      end
+    end
+
     # Set value under deeply nested keys
     #
     # The scan starts with the top level key and follows
@@ -307,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]
 
@@ -327,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)
@@ -345,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)
@@ -357,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)
@@ -371,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|
@@ -384,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
@@ -406,62 +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 unmarshal(file)
-      ext = ::File.extname(file)
-      self.extname = ext
-      self.filename = ::File.basename(file, ext)
-      gem_name = nil
-
-      case ext
-      when '.yaml', '.yml'
-        require 'yaml'
-        if YAML.respond_to?(:safe_load)
-          YAML.safe_load(File.read(file))
-        else
-          YAML.load(File.read(file))
-        end
-      when '.json'
-        require 'json'
-        JSON.parse(File.read(file))
-      when '.toml'
-        gem_name = 'toml'
-        require 'toml'
-        TOML.load(::File.read(file))
+    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
+    def create_marshaller(ext)
+      marshaller = marshallers.find { |marsh| marsh.ext.include?(ext) }
+
+      return nil if marshaller.nil?
+
+      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
+      if marshaller = create_marshaller(ext)
+        marshaller.unmarshal(content)
       else
         raise ReadError, "Config file format `#{ext}` is not supported."
       end
-    rescue LoadError
-      puts "Please install `#{gem_name}`"
-      raise ReadError, "Gem `#{gem_name}` is missing. Please install it " \
-                       "to read #{ext} configuration format."
     end
 
+    # Marshal hash object into a configuration file content
+    #
+    # @param [Hash{String => Object}] object
+    #   the object to convert to string
+    #
+    # @return [String]
+    #
     # @api private
-    def marshal(file, data)
-      ext = ::File.extname(file)
-      self.extname = ext
-      self.filename = ::File.basename(file, ext)
-      gem_name = nil
-
-      case ext
-      when '.yaml', '.yml'
-        require 'yaml'
-        ::File.write(file, YAML.dump(self.class.normalize_hash(data, :to_s)))
-      when '.json'
-        require 'json'
-        ::File.write(file, JSON.pretty_generate(data))
-      when '.toml'
-        gem_name = 'toml'
-        require 'toml'
-        ::File.write(file, TOML::Generator.new(data).body)
+    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
-    rescue LoadError
-      puts "Please install `#{gem_name}`"
-      raise ReadError, "Gem `#{gem_name}` is missing. Please install it " \
-                       "to read #{ext} configuration format."
     end
   end # Config
 end # TTY