anyway_config 2.1.0 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae67246988f82692f84ae07b01642fbca38c9f1593b0e4292b335e08654bbf7e
-  data.tar.gz: 045f36927093f3e7929889918dff12d63c61ef58ffcb5fc5793f017dd2da1c5e
+  metadata.gz: 0e4b1e98155e34f0220746d9230e433072143638e838f8975023c79cf75a9fe1
+  data.tar.gz: e5d8b4f78fe7f32fc2dd3068f90897a28f57a292596346f5bb368a36094cea36
 SHA512:
-  metadata.gz: de0f8281daad0d2da4ad557f7099602a46d7fa4476f0a3adfb5b7f14c3abcd44fd020a89fd661a4c9ebeb9b5e70550d37f1b16d01bf68d535ab63877b9ae1661
-  data.tar.gz: 04de1b39c49b4dc39faa12ee199143ca64b3722cbc547e8c41b41bc3e7e365848bae2f06dfc9f99db5693782df4239cd5bbdca99cf2e58e50f38147b2b5dc95e
+  metadata.gz: 849c9c7fb4bc1101444dfec952a84ac3b1f605f3415d65d31ea727f176d9281cddc90e8b56ff73a3b25431126d61640931cfbc2621dc607493014e9a97d4ee3a
+  data.tar.gz: 840073b4420e4c1a792db2571b29eb7605cbc7066833bc4afe91defd94ba08153a4f32036a6cd09c6cf8f1da718f7f11d41bb46c8b9ea1ab0a0bfd2a81ab0a20

data/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## master
 
+## 2.2.3 (2022-01-21)
+
+- Fix Ruby 3.1 compatibility. ([@palkan][])
+
+- Add ability to set default key for environmental YAML files. ([@skryukov])
+
+Define a key for environmental yaml files to read default values from with `config.anyway_config.default_environmental_key = "default"`.
+This way Anyway Config will try to read settings under the `"default"` key and then merge environmental settings into them.
+
+## 2.2.2 (2020-10-26)
+
+- Fixed regression introduced by the `#deep_merge!` refinement.
+
+## 2.2.1 (2020-09-28)
+
+- Minor fixes to the prev release.
+
+## 2.2.0 ⛓ (2020-09-28)
+
+- Add RBS signatures and generator. ([@palkan][])
+
+Anyway Config now ships with the basic RBS support. To use config types with Steep, add `library "anyway_config"` to your Steepfile.
+
+We also provide an API to generate a signature for you config class: `MyConfig.to_rbs`. You can use this method to generate a scaffold for your config class.
+
+- Add type coercion support. ([@palkan][])
+
+Example:
+
+```ruby
+class CoolConfig < Anyway::Config
+  attr_config :port, :user
+
+  coerce_types port: :string, user: {dob: :date}
+end
+
+ENV["COOL_USER__DOB"] = "1989-07-01"
+
+config = CoolConfig.new({port: 8080})
+config.port == "8080" #=> true
+config.user["dob"] == Date.new(1989, 7, 1) #=> true
+```
+
+You can also add `.disable_auto_cast!` to your config class to disable automatic conversion.
+
+**Warning** Now values from all sources are coerced (e.g., YAML files). That could lead to a different behaviour.
+
+- Do not dup modules/classes passed as configuration values. ([@palkan][])
+
+- Handle loading empty YAML config files. ([@micahlee][])
+
 ## 2.1.0 (2020-12-29)
 
 - Drop deprecated `attr_config` instance variables support.
@@ -397,3 +448,4 @@ No we're dependency-free!
 [@jastkand]: https://github.com/jastkand
 [@envek]: https://github.com/Envek
 [@progapandist]: https://github.com/progapandist
+[@skryukov]: https://github.com/skryukov

data/README.md

@@ -42,12 +42,14 @@ For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_con
   - [Generators](#generators)
 - [Using with Ruby applications](#using-with-ruby)
 - [Environment variables](#environment-variables)
+- [Type coercion](#type-coercion)
 - [Local configuration](#local-files)
 - [Data loaders](#data-loaders)
 - [Source tracing](#tracing)
 - [Pattern matching](#pattern-matching)
 - [Test helpers](#test-helpers)
 - [OptionParser integration](#optionparser-integration)
+- [RBS support](#rbs-support)
 
 ## Main concepts
 
@@ -94,7 +96,7 @@ Or adding to your project:
 
 ```ruby
 # Gemfile
-gem "anyway_config", "~> 2.0.0"
+gem "anyway_config", "~> 2.0"
 ```
 
 ### Supported Ruby versions
@@ -269,6 +271,7 @@ This feature is similar to `Rails.application.config_for` but more powerful:
 | Load data from environment | ❌ | ✅ |
 | Load data from [custom sources](#data-loaders) | ❌ | ✅ |
 | Local config files | ❌ | ✅ |
+| Type coercion | ❌ | ✅ |
 | [Source tracing](#tracing) | ❌ | ✅ |
 | Return Hash with indifferent access | ❌ | ✅ |
 | Support ERB\* within `config/app.yml` | ✅ | ✅ |
@@ -331,7 +334,7 @@ Your config is filled up with values from the following sources (ordered by prio
 
 1) **YAML configuration files**: `RAILS_ROOT/config/my_cool_gem.yml`.
 
-Recognizes Rails environment, supports `ERB`:
+Rails environment is used as the namespace (required); supports `ERB`:
 
 ```yml
 test:
@@ -370,6 +373,26 @@ staging:
 port: 3002 # This value will not be loaded at all
 ```
 
+To provide default values you can use YAML anchors, but they do not deep-merge settings, so Anyway Config provides a way to define a special top-level key for default values like this:
+
+```ruby
+config.anyway_config.default_environmental_key = "default"
+```
+
+After that, Anyway Config will start reading settings under the `"default"` key and then merge environmental settings into them.
+
+```yml
+default:
+  server: # This values will be loaded in all environments by default
+    host: localhost
+    port: 3002
+
+staging:
+  server:
+    host: staging.example.com # This value will override the defaults when Rails.env.staging? is true
+    # port will be set to the value from the defaults — 3002
+```
+
 You can specify the lookup path for YAML files in one of the following ways:
 
 - By setting `config.anyway_config.default_config_path` to a target directory path:
@@ -451,6 +474,22 @@ config.anyway_config.autoload_static_config_path = "path/to/configs"
 **NOTE:** Configs loaded from the `autoload_static_config_path` are **not reloaded in development**. We call them _static_. So, it makes sense to keep only configs necessary for initialization in this folder. Other configs, _dynamic_, could be stored in `app/configs`.
 Or you can store everything in `app/configs` by setting `config.anyway_config.autoload_static_config_path = "app/configs"`.
 
+**NOTE 2**: Since _static_ configs are loaded before initializers, it's not possible to use custom inflection Rules (usually defined in `config/initializers/inflections.rb`) to resolve constant names from files. If you rely on custom inflection rules (see, for example, [#81](https://github.com/palkan/anyway_config/issues/81)), we recommend configuration Rails inflector before initialization as well:
+
+```ruby
+# config/application.rb
+
+# ...
+
+require_relative "initializers/inflections"
+
+module SomeApp
+  class Application < Rails::Application
+    # ...
+  end
+end
+```
+
 ### Generators
 
 Anyway Config provides Rails generators to create new config classes:
@@ -525,13 +564,15 @@ Environmental variables for your config should start with your config name, uppe
 
 For example, if your config name is "mycoolgem", then the env var "MYCOOLGEM_PASSWORD" is used as `config.password`.
 
-Environment variables are automatically type cast:
+By default, environment variables are automatically type cast\*:
 
 - `"True"`, `"t"` and `"yes"` to `true`;
 - `"False"`, `"f"` and `"no"` to `false`;
 - `"nil"` and `"null"` to `nil` (do you really need it?);
 - `"123"` to 123 and `"3.14"` to 3.14.
 
+\* See below for coercion customization.
+
 *Anyway Config* supports nested (_hashed_) env variables—just separate keys with double-underscore.
 
 For example, "MYCOOLGEM_OPTIONS__VERBOSE" is parsed as `config.options["verbose"]`.
@@ -549,6 +590,94 @@ If you want to provide a text-like env variable which contains commas then wrap
 MYCOOLGEM = "Nif-Nif, Naf-Naf and Nouf-Nouf"
 ```
 
+## Type coercion
+
+> 🆕 v2.2.0
+
+You can define custom type coercion rules to convert string data to config values. To do that, use `.coerce_types` method:
+
+```ruby
+class CoolConfig < Anyway::Config
+  config_name :cool
+  attr_config port: 8080,
+    host: "localhost",
+    user: {name: "admin", password: "admin"}
+
+  coerce_types port: :string, user: {dob: :date}
+end
+
+ENV["COOL_USER__DOB"] = "1989-07-01"
+
+config = CoolConfig.new
+config.port == "8080" # Even though we defined the default value as int, it's converted into a string
+config.user["dob"] == Date.new(1989, 7, 1) #=> true
+```
+
+Type coercion is especially useful to deal with array values:
+
+```ruby
+# To define an array type, provide a hash with two keys:
+#  - type — elements type
+#  - array: true — mark the parameter as array
+coerce_types list: {type: :string, array: true}
+```
+
+You can use `type: nil` in case you don't want to coerce values, just convert a value into an array:
+
+```ruby
+# From AnyCable config (sentinels could be represented via strings or hashes)
+coerce_types redis_sentinels: {type: nil, array: true}
+```
+
+It's also could be useful to explicitly define non-array types (to avoid confusion):
+
+```ruby
+coerce_types non_list: :string
+```
+
+Finally, it's possible to disable auto-casting for a particular config completely:
+
+```ruby
+class CoolConfig < Anyway::Config
+  attr_config port: 8080,
+    host: "localhost",
+    user: {name: "admin", password: "admin"}
+
+  disable_auto_cast!
+end
+
+ENV["COOL_PORT"] = "443"
+
+CoolConfig.new.port == "443" #=> true
+```
+
+**IMPORTANT**: Values provided explicitly (via attribute writers) are not coerced. Coercion is only happening during the load phase.
+
+The following types are supported out-of-the-box: `:string`, `:integer`, `:float`, `:date`, `:datetime`, `:uri`, `:boolean`.
+
+You can use custom deserializers by passing a callable object instead of a type name:
+
+```ruby
+COLOR_TO_HEX = lambda do |raw|
+  case raw
+  when "red"
+    "#ff0000"
+  when "green"
+    "#00ff00"
+  when "blue"
+    "#0000ff"
+  end
+end
+
+class CoolConfig < Anyway::Config
+  attr_config :color
+
+  coerce_types color: COLOR_TO_HEX
+end
+
+CoolConfig.new({color: "red"}).color #=> "#ff0000"
+```
+
 ## Local files
 
 It's useful to have a personal, user-specific configuration in development, which extends the project-wide one.
@@ -610,7 +739,7 @@ In order to support [source tracing](#tracing), you need to wrap the resulting H
 
 ```ruby
 def call(name:, **_opts)
-  trace!(source: :chamber) do
+  trace!(:chamber) do
     Chamber.env.to_h[name] || {}
   end
 end
@@ -790,6 +919,62 @@ describe_options(
 )
 ```
 
+## RBS support
+
+Anyway Config comes with Ruby type signatures (RBS).
+
+To use them with Steep, add `library "anyway_config"` to your Steepfile.
+
+We also provide an API to generate a type signature for your config class:
+
+```ruby
+class MyGem::Config < Anyway::Config
+  attr_config :host, port: 8080, tags: [], debug: false
+
+  coerce_types host: :string, port: :integer,
+    tags: {type: :string, array: true}
+
+  required :host
+end
+```
+
+Then calling `MyGem::Config.to_rbs` will return the following signature:
+
+```rbs
+module MyGem
+  interface _Config
+    def host: () -> String
+    def host=: (String) -> void
+    def port: () -> String?
+    def port=: (String) -> void
+    def tags: () -> Array[String]?
+    def tags=: (Array[String]) -> void
+    def debug: () -> bool
+    def debug?: () -> bool
+    def debug=: (bool) -> void
+  end
+
+  class Config < Anyway::Config
+    include _Config
+  end
+end
+```
+
+### Handling `on_load`
+
+When we use `on_load` callback with a block, we switch the context (via `instance_eval`), and we need to provide type hints for the type checker. Here is an example:
+
+```ruby
+class MyConfig < Anyway::Config
+  on_load do
+    # @type self : MyConfig
+    raise_validation_error("host is invalid") if host.start_with?("localhost")
+  end
+end
+```
+
+Yeah, a lot of annotations 😞 Welcome to the type-safe world!
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/anyway_config](https://github.com/palkan/anyway_config).

data/lib/.rbnext/2.7/anyway/auto_cast.rb

@@ -4,30 +4,50 @@ module Anyway
   module AutoCast
     # Regexp to detect array values
     # Array value is a values that contains at least one comma
-    # and doesn't start/end with quote
-    ARRAY_RXP = /\A[^'"].*\s*,\s*.*[^'"]\z/
+    # and doesn't start/end with quote or curly braces
+    ARRAY_RXP = /\A[^'"{].*\s*,\s*.*[^'"}]\z/
 
-    def self.call(val)
-      return val unless String === val
+    class << self
+      def call(val)
+        return val unless val.is_a?(::Hash) || val.is_a?(::String)
 
-      case val
-      when ARRAY_RXP
-        val.split(/\s*,\s*/).map { |_1| call(_1) }
-      when /\A(true|t|yes|y)\z/i
-        true
-      when /\A(false|f|no|n)\z/i
-        false
-      when /\A(nil|null)\z/i
-        nil
-      when /\A\d+\z/
-        val.to_i
-      when /\A\d*\.\d+\z/
-        val.to_f
-      when /\A['"].*['"]\z/
-        val.gsub(/(\A['"]|['"]\z)/, "")
-      else
-        val
+        case val
+        when Hash
+          val.transform_values { |_1| call(_1) }
+        when ARRAY_RXP
+          val.split(/\s*,\s*/).map { |_1| call(_1) }
+        when /\A(true|t|yes|y)\z/i
+          true
+        when /\A(false|f|no|n)\z/i
+          false
+        when /\A(nil|null)\z/i
+          nil
+        when /\A\d+\z/
+          val.to_i
+        when /\A\d*\.\d+\z/
+          val.to_f
+        when /\A['"].*['"]\z/
+          val.gsub(/(\A['"]|['"]\z)/, "")
+        else
+          val
+        end
+      end
+
+      def cast_hash(obj)
+        obj.transform_values do |val|
+          val.is_a?(::Hash) ? cast_hash(val) : call(val)
+        end
+      end
+
+      def coerce(_key, val)
+        call(val)
       end
     end
   end
+
+  module NoCast
+    def self.call(val) ;  val; end
+
+    def self.coerce(_key, val) ;  val; end
+  end
 end

data/lib/.rbnext/2.7/anyway/config.rb

@@ -44,6 +44,7 @@ module Anyway # :nodoc:
       to_h
       to_source_trace
       write_config_attr
+      __type_caster__
     ].freeze
 
     class Error < StandardError; end
@@ -196,6 +197,47 @@ module Anyway # :nodoc:
 
       def new_empty_config() ;  {}; end
 
+      def coerce_types(mapping)
+        Utils.deep_merge!(coercion_mapping, mapping)
+      end
+
+      def coercion_mapping
+        return @coercion_mapping if instance_variable_defined?(:@coercion_mapping)
+
+        @coercion_mapping = if superclass < Anyway::Config
+          superclass.coercion_mapping.deep_dup
+        else
+          {}
+        end
+      end
+
+      def type_caster(val = nil)
+        return @type_caster unless val.nil?
+
+        @type_caster ||=
+          if coercion_mapping.empty?
+            fallback_type_caster
+          else
+            ::Anyway::TypeCaster.new(coercion_mapping, fallback: fallback_type_caster)
+          end
+      end
+
+      def fallback_type_caster(val = nil)
+        return (@fallback_type_caster = val) unless val.nil?
+
+        return @fallback_type_caster if instance_variable_defined?(:@fallback_type_caster)
+
+        @fallback_type_caster = if superclass < Anyway::Config
+          superclass.fallback_type_caster.deep_dup
+        else
+          ::Anyway::AutoCast
+        end
+      end
+
+      def disable_auto_cast!
+        @fallback_type_caster = ::Anyway::NoCast
+      end
+
       private
 
       def define_config_accessor(*names)
@@ -373,7 +415,7 @@ module Anyway # :nodoc:
         values[name].nil? || (values[name].is_a?(String) && values[name].empty?)
       end.then do |missing|
         next if missing.empty?
-        raise_validation_error "The following config parameters are missing or empty: #{missing.join(", ")}"
+        raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"
       end
     end
 
@@ -381,11 +423,16 @@ module Anyway # :nodoc:
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)
 
+      val = __type_caster__.coerce(key, val)
       public_send(:"#{key}=", val)
     end
 
     def raise_validation_error(msg)
       raise ValidationError, msg
     end
+
+    def __type_caster__
+      self.class.type_caster
+    end
   end
 end

data/lib/.rbnext/2.7/anyway/rails/loaders/yaml.rb

@@ -8,7 +8,11 @@ module Anyway
           parsed_yml = super
           return parsed_yml unless environmental?(parsed_yml)
 
-          super[::Rails.env] || {}
+          env_config = parsed_yml[::Rails.env] || {}
+          return env_config if Anyway::Settings.default_environmental_key.blank?
+
+          default_config = parsed_yml[Anyway::Settings.default_environmental_key] || {}
+          Utils.deep_merge!(default_config, env_config)
         end
 
         private
@@ -18,7 +22,9 @@ module Anyway
           # likely
           return true if parsed_yml.key?(::Rails.env)
           # less likely
-          ::Rails.application.config.anyway_config.known_environments.any? { |_1| parsed_yml.key?(_1) }
+          return true if ::Rails.application.config.anyway_config.known_environments.any? { |_1| parsed_yml.key?(_1) }
+          # strange, but still possible
+          Anyway::Settings.default_environmental_key.present? && parsed_yml.key?(Anyway::Settings.default_environmental_key)
         end
 
         def relative_config_path(path)

data/lib/.rbnext/2.7/anyway/rbs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+using RubyNext;
+module Anyway
+  module RBSGenerator
+    TYPE_TO_CLASS = {
+      string: "String",
+      integer: "Integer",
+      float: "Float",
+      date: "Date",
+      datetime: "DateTime",
+      uri: "URI",
+      boolean: "bool"
+    }.freeze
+
+    # Generate RBS signature from a config class
+    def to_rbs
+      *namespace, class_name = name.split("::")
+
+      buf = []
+      indent = 0
+      interface_name = "_Config"
+
+      if namespace.empty?
+        interface_name = "_#{class_name}"
+      else
+        buf << "module #{namespace.join("::")}"
+        indent += 1
+      end
+
+      # Using interface emulates a module we include to provide getters and setters
+      # (thus making `super` possible)
+      buf << "#{"  " * indent}interface #{interface_name}"
+      indent += 1
+
+      # Generating setters and getters for config attributes
+      config_attributes.each do |param|
+        type = coercion_mapping[param] || defaults[param.to_s]
+
+        type =
+          case; when ((__m__ = type)) && false 
+          when (NilClass === __m__)
+            "untyped"
+          when (Symbol === __m__)
+            TYPE_TO_CLASS.fetch(type) { defaults[param] ? "Symbol" : "untyped" }
+          when (Array === __m__)
+            "Array[untyped]"
+          when ((__m__.respond_to?(:deconstruct_keys) && (((__m_hash__src__ = __m__.deconstruct_keys(nil)) || true) && (Hash === __m_hash__src__ || Kernel.raise(TypeError, "#deconstruct_keys must return Hash"))) && (__m_hash__ = __m_hash__src__.dup)) && ((__m_hash__.key?(:array) && __m_hash__.key?(:type)) && (((array = __m_hash__.delete(:array)) || true) && (((type = __m_hash__.delete(:type)) || true) && __m_hash__.empty?))))
+            "Array[#{TYPE_TO_CLASS.fetch(type, "untyped")}]"
+          when (Hash === __m__)
+            "Hash[string,untyped]"
+          when ((TrueClass === __m__) || (FalseClass === __m__))
+            "bool"
+          else
+            type.class.to_s
+          end
+
+        getter_type = type
+        getter_type = "#{type}?" unless required_attributes.include?(param)
+
+        buf << "#{"  " * indent}def #{param}: () -> #{getter_type}"
+        buf << "#{"  " * indent}def #{param}=: (#{type}) -> void"
+
+        if type == "bool" || type == "bool?"
+          buf << "#{"  " * indent}def #{param}?: () -> #{getter_type}"
+        end
+      end
+
+      indent -= 1
+      buf << "#{"  " * indent}end"
+
+      buf << ""
+
+      buf << "#{"  " * indent}class #{class_name} < #{superclass.name}"
+      indent += 1
+
+      buf << "#{"  " * indent}include #{interface_name}"
+
+      indent -= 1
+      buf << "#{"  " * indent}end"
+
+      unless namespace.empty?
+        buf << "end"
+      end
+
+      buf << ""
+
+      buf.join("\n")
+    end
+  end
+
+  Config.extend RBSGenerator
+end

data/lib/.rbnext/2.7/anyway/tracing.rb

@@ -34,13 +34,11 @@ module Anyway
 
       def record_value(val, *path, **opts)
         key = path.pop
-        (__m__ = if val.is_a?(Hash)
-  Trace.new.tap { |_1|
-    _1.merge_values(val, **opts)
-  }
-else
-  Trace.new(:value, val, **opts)
-end) && (((trace = __m__) || true) || Kernel.raise(NoMatchingPatternError, __m__.inspect))
+        trace = if val.is_a?(Hash)
+          Trace.new.tap { |_1| _1.merge_values(val, **opts) }
+        else
+          Trace.new(:value, val, **opts)
+        end
 
         target_trace = path.empty? ? self : value.dig(*path)
         target_trace.value[key.to_s] = trace