philiprehberger-env_validator 0.2.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7880d4b817b1eb742182c5967ba6881626978a31303900cb1e7428674beab40
-  data.tar.gz: b20afee2c7ca8ebe026e1c10bf52126466e9d2bd2488ac2bd61c295c90e582d0
+  metadata.gz: cb9d6d9b1aeee1b8eb35392807aec880212627edbcbb426c8108e1056824dc07
+  data.tar.gz: 0366aba96e46ec24ba6a769b4ba17271d29fa89ccf24bc99ca08a528e056d845
 SHA512:
-  metadata.gz: 44de6ab04e8c33df4a7692c96feef5da5073e72659bf1068129231e5707b60423779d180eab81c7993d7d0dcdc3e36f952ef05a4cd6ce9b5546d9c02b1a54fca
-  data.tar.gz: db17df01d68d556079242e450ddb28cd3cfe96c737fb9cfbc1891fd2ddcd77bfc83de16da869c5cb683bf072f56adb10b8c20a05ea1da9e6b01daffa5d456bbd
+  metadata.gz: 176cf272fcecb3fbb9e88acd9d11daaf509751265ef6eab0f4c7fddeb45c16550984525a48eb8f7e7711ba8b776bd7c34934da2c3c011c789d69970342aae6d1
+  data.tar.gz: 266c6471e7c5d11e0933edce3f639add0bf0a0252c8ab43253af0e5eae6652cc03018edcfd1b7540b7954a3a11b4c5626509741538cded0dcba97008253fd043

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-16
+
+### Added
+- `Schema#array(name, item_type:, separator:, required:, default:)` for parsing delimited ENV values as lists with per-element type casting (`:string`, `:integer`, `:float`, `:boolean`)
+
+## [0.3.0] - 2026-04-10
+
+### Added
+- `prefix:` option for `EnvValidator.define` to group related variables under a shared prefix
+
+### Changed
+- Trim `.rubocop.yml` to minimal config per guide standards
+- Update issue templates to match guide (add gem version field, alternatives field)
+
+### Fixed
+- Merge duplicate `[0.2.2]` CHANGELOG entries into single entry
+
 ## [0.2.9] - 2026-04-08
 
 ### Changed
@@ -50,8 +67,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Update rubocop configuration for Windows compatibility
 
-## [0.2.2] - 2026-03-21
-
 ### Fixed
 - Standardize Installation section in README
 

data/README.md

@@ -82,6 +82,25 @@ config.key?(:PORT)     # => true
 config.slice(:PORT)    # => { "PORT" => 3000 }
 ```
 
+### Prefix
+
+Group related variables with a shared prefix:
+
+```ruby
+env = { "REDIS_HOST" => "localhost", "REDIS_PORT" => "6379", "REDIS_PASSWORD" => "secret" }
+
+config = Philiprehberger::EnvValidator.define(env: env, prefix: "REDIS_") do
+  string  :HOST, required: true
+  integer :PORT, default: 6379
+  string  :PASSWORD
+end
+
+config[:HOST] # => "localhost"
+config[:PORT] # => 6379
+```
+
+The prefix is prepended when looking up each variable in the environment. Result keys use the short name (without prefix). Error messages include the full prefixed name.
+
 ### Validation Errors
 
 ```ruby
@@ -94,6 +113,30 @@ end
 #    Missing required variable: DATABASE_URL; Missing required variable: API_KEY
 ```
 
+### Arrays (Delimited Lists)
+
+Parse a delimited ENV value into an array of typed elements:
+
+```ruby
+env = {
+  "TAGS"    => "ruby,rails,hotwire",
+  "PORTS"   => "3000,3001,3002",
+  "PATHS"   => "/usr/bin:/usr/local/bin"
+}
+
+config = Philiprehberger::EnvValidator.define(env: env) do
+  array :TAGS
+  array :PORTS, item_type: :integer
+  array :PATHS, separator: ":"
+end
+
+config[:TAGS]  # => ["ruby", "rails", "hotwire"]
+config[:PORTS] # => [3000, 3001, 3002]
+config[:PATHS] # => ["/usr/bin", "/usr/local/bin"]
+```
+
+Each element is stripped of surrounding whitespace and cast to `item_type`. An empty or missing ENV value yields `[]` (or the configured `default:`). If any element fails to cast a `ValidationError` is raised.
+
 ### Supported Types
 
 | Type | Method | Accepts |
@@ -102,12 +145,14 @@ end
 | Integer | `integer` | Numeric strings (`"42"`, `"-1"`) |
 | Float | `float` | Numeric strings (`"3.14"`, `"1"`) |
 | Boolean | `boolean` | `true/false/1/0/yes/no/on/off` (case-insensitive) |
+| Array | `array` | Delimited string cast to a list of typed elements |
 
 ## API
 
 | Method / Class | Description |
 |----------------|-------------|
-| `EnvValidator.define(env:, &block)` | Define schema and validate |
+| `EnvValidator.define(env:, prefix:, &block)` | Define schema and validate |
+| `Schema#array(name, item_type:, separator:, required:, default:)` | Declare a delimited list ENV var parsed into a typed array |
 | `Result#fetch(name)` / `Result#[name]` | Get a validated value |
 | `Result#keys` | List all defined variable names |
 | `Result#key?(name)` | Check if a variable was defined |

data/lib/philiprehberger/env_validator/schema.rb

@@ -52,6 +52,29 @@ module Philiprehberger
       def boolean(name, required: false, default: nil, choices: nil)
         @definitions[name.to_s] = { type: :boolean, required: required, default: default, choices: choices }
       end
+
+      # Define an array variable parsed from a delimited string.
+      #
+      # The ENV value is split on `separator`, each element is stripped of
+      # surrounding whitespace, and each element is cast to `item_type`
+      # using the same type caster the other schema methods use.
+      #
+      # @param name [Symbol, String] the ENV variable name
+      # @param item_type [Symbol] element type (:string, :integer, :float, :boolean)
+      # @param separator [String] delimiter between elements (default: ',')
+      # @param required [Boolean] whether the variable is required
+      # @param default [Array, nil] default value if not set
+      # @return [void]
+      def array(name, item_type: :string, separator: ',', required: false, default: nil)
+        @definitions[name.to_s] = {
+          type: :array,
+          item_type: item_type,
+          separator: separator,
+          required: required,
+          default: default,
+          choices: nil
+        }
+      end
     end
   end
 end

data/lib/philiprehberger/env_validator/validator.rb

@@ -9,9 +9,11 @@ module Philiprehberger
 
       # @param schema [Schema] the schema to validate against
       # @param env [Hash] the environment hash (default: ENV)
-      def initialize(schema, env: ENV)
+      # @param prefix [String, nil] optional prefix prepended to variable names during lookup
+      def initialize(schema, env: ENV, prefix: nil)
         @schema = schema
         @env = env
+        @prefix = prefix
       end
 
       # Validate and return a Result.
@@ -36,25 +38,46 @@ module Philiprehberger
       private
 
       def resolve(name, definition)
-        raw = @env[name]
+        env_key = @prefix ? "#{@prefix}#{name}" : name
+        raw = @env[env_key]
 
-        return resolve_missing(name, definition) if raw.nil? || raw.empty?
+        return resolve_array(env_key, raw, definition) if definition[:type] == :array
+        return resolve_missing(env_key, definition) if raw.nil? || raw.empty?
 
-        value = cast(raw, definition[:type], name)
-        validate_choices(name, value, definition[:choices])
+        value = cast(raw, definition[:type], env_key)
+        validate_choices(env_key, value, definition[:choices])
         [value, nil]
       rescue CastError => e
         [nil, e.message]
       end
 
-      def resolve_missing(name, definition)
+      def resolve_missing(env_key, definition)
         if definition[:required] && definition[:default].nil?
-          [nil, "Missing required variable: #{name}"]
+          [nil, "Missing required variable: #{env_key}"]
         else
           [definition[:default], nil]
         end
       end
 
+      def resolve_array(env_key, raw, definition)
+        return resolve_missing_array(env_key, definition) if raw.nil?
+        return [[], nil] if raw.empty?
+
+        elements = raw.split(definition[:separator]).map(&:strip)
+        values = elements.map { |element| cast(element, definition[:item_type], env_key) }
+        [values, nil]
+      rescue CastError => e
+        [nil, e.message]
+      end
+
+      def resolve_missing_array(env_key, definition)
+        if definition[:required] && definition[:default].nil?
+          [nil, "Missing required variable: #{env_key}"]
+        else
+          [definition[:default] || [], nil]
+        end
+      end
+
       def validate_choices(name, value, choices)
         return if choices.nil? || choices.include?(value)
 

data/lib/philiprehberger/env_validator/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module EnvValidator
-    VERSION = '0.2.9'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/env_validator.rb

@@ -18,14 +18,15 @@ module Philiprehberger
     # Define and validate environment variables.
     #
     # @param env [Hash] the environment hash (default: ENV)
+    # @param prefix [String, nil] optional prefix prepended to variable names during lookup
     # @yield [schema] configure the schema
     # @yieldparam schema [Schema]
     # @return [Result] validated values
     # @raise [ValidationError] if validation fails
-    def self.define(env: ENV, &block)
+    def self.define(env: ENV, prefix: nil, &block)
       schema = Schema.new
       schema.instance_eval(&block)
-      Validator.new(schema, env: env).validate!
+      Validator.new(schema, env: env, prefix: prefix).validate!
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-env_validator
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies: []
 description: Define environment variable schemas with type casting, required/optional
   flags, and defaults. Validates at boot time and provides typed accessors.