philiprehberger-env_loader 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42735b84e3b28e4cbccc4f4e312f024047e529df42b5b603870536fae8a93d93
-  data.tar.gz: fd5d06f1205345406bcf637ffef0417a0742931bcd5bc6186c3e7c2d3f921b0f
+  metadata.gz: eb02740e5ccfd37833abf860aab8ab0c2f8a46cab63f1b1bcd17746384212c3a
+  data.tar.gz: 8641f1e44aa514fa8dfc5d1ca2643431ff0e48de19bc4ea0825ef10f2bde506e
 SHA512:
-  metadata.gz: f471d5d740157e74601daaf1fd6639192eef8d9161e96828503adb8be5860e71181dd9cf160153066f6f49c2fe7a283f20acd7e96d2bf0afe087c93e2067e50e
-  data.tar.gz: 3ce313f928805b5f06ed3f8575bbc6fa0006ff5c3ae790fbe7b77531ddda14a41cf3c09a06d1c3965188fbe4dd616ef0e4d6166e4349072b32088106ea7ba6a1
+  metadata.gz: 3e4a088a9664ff7325464b2eac8330178e7bb7a83a91869e9938c80195597aa668676b306cf850e62de2250e05c09b4a3b3c354ee84b63eef3a0ceac822cafed
+  data.tar.gz: c5b2552f169cbc78f043441ea105c517b4fabef753469b71bd3cfef41775ac335a7bc3785faf80137d0f82a93ac1f7724b75064556a295725e6c37aad6fdf552

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-29
+
+### Added
+- `EnvLoader.dump(hash)` serializes a hash to `.env`-formatted text suitable for `parse` or for writing to a file; alphabetically sorted keys, double-quotes for values containing whitespace/`=`/`#`/quotes, backslash-escapes inner `"` and `\`, trailing newline
+- `parse` now unescapes `\"`, `\\`, and `\n` inside double-quoted values so `parse(dump(h))` round-trips cleanly for values with inner quotes
+
+## [0.3.0] - 2026-05-01
+
+### Added
+- `EnvLoader.parse(content)` — parse `.env`-formatted content from a string into a hash without touching ENV; useful for tests and embedded configs
+
 ## [0.2.1] - 2026-04-15
 
 ### Changed

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-env_loader.svg)](https://rubygems.org/gems/philiprehberger-env_loader)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-env-loader)](https://github.com/philiprehberger/rb-env-loader/commits/main)
 
+![philiprehberger-env_loader](https://raw.githubusercontent.com/philiprehberger/rb-env-loader/main/package-card.webp)
+
 Multi-source environment variable loader with precedence and validation
 
 ## Requirements
@@ -73,6 +75,36 @@ Philiprehberger::EnvLoader.generate_template(
 )
 ```
 
+### Parse from a String
+
+Parse `.env`-formatted text without reading from disk and without touching ENV:
+
+```ruby
+content = <<~ENV
+  APP_HOST=localhost
+  APP_PORT=3000
+  # comments and blank lines are ignored
+ENV
+
+Philiprehberger::EnvLoader.parse(content)
+# => { "APP_HOST" => "localhost", "APP_PORT" => "3000" }
+```
+
+### Dump to `.env` Format
+
+Serialize a hash back to `.env`-formatted text. Round-trips with `parse` for any input. Values that contain whitespace, `=`, `#`, or quote characters are double-quoted with inner `"` and `\` backslash-escaped. Keys are sorted alphabetically.
+
+```ruby
+text = Philiprehberger::EnvLoader.dump(
+  'APP_HOST' => 'localhost',
+  'APP_PORT' => '3000',
+  'NOTE' => 'has "quote"'
+)
+# => "APP_HOST=localhost\nAPP_PORT=3000\nNOTE=\"has \\\"quote\\\"\"\n"
+
+File.write('.env', text)
+```
+
 ## API
 
 | Method | Description |
@@ -80,6 +112,8 @@ Philiprehberger::EnvLoader.generate_template(
 | `.load(*files, required:, types:, defaults:, prefix:, strip_prefix:)` | Load variables from .env files with options |
 | `.validate!(*keys)` | Raise if any keys are missing or empty in ENV |
 | `.generate_template(output:, keys:)` | Generate a .env.template file |
+| `.parse(content)` | Parse `.env`-formatted content from a string into a hash without touching ENV |
+| `.dump(hash)` | Serialize a hash to `.env`-formatted text (round-trips with `parse`) |
 | `EnvLoader::Error` | Base error class for all gem errors |
 | `EnvLoader::ValidationError` | Raised when required keys are missing or empty |
 

data/lib/philiprehberger/env_loader/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module EnvLoader
-    VERSION = '0.2.1'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/env_loader.rb

@@ -65,13 +65,18 @@ module Philiprehberger
       File.write(output, "#{content}\n")
     end
 
-    # Parse a .env file into a hash of key-value pairs.
+    # Parse `.env`-formatted content from a string into a hash.
     #
-    # @param path [String] the file path
-    # @return [Hash<String, String>] parsed key-value pairs
-    def self.parse_file(path)
+    # Useful for tests, embedded configurations, and any scenario where the
+    # `.env` content does not live in a file. Comments (`#`), blank lines,
+    # and surrounding whitespace are ignored. Single- and double-quoted
+    # values are unwrapped. ENV is not touched.
+    #
+    # @param content [String] the `.env`-formatted text
+    # @return [Hash{String => String}] parsed key-value pairs
+    def self.parse(content)
       result = {}
-      File.readlines(path).each do |line|
+      content.to_s.each_line do |line|
         line = line.strip
         next if line.empty? || line.start_with?('#')
 
@@ -80,14 +85,63 @@ module Philiprehberger
 
         key = key.strip
         value = value.strip
-        value = value[1..-2] if (value.start_with?('"') && value.end_with?('"')) ||
-                                (value.start_with?("'") && value.end_with?("'"))
+        if value.length >= 2 && value.start_with?('"') && value.end_with?('"')
+          value = value[1..-2].gsub(/\\(.)/) { Regexp.last_match(1) == 'n' ? "\n" : Regexp.last_match(1) }
+        elsif value.length >= 2 && value.start_with?("'") && value.end_with?("'")
+          value = value[1..-2]
+        end
         result[key] = value
       end
       result
     end
+
+    # Parse a .env file into a hash of key-value pairs.
+    #
+    # @param path [String] the file path
+    # @return [Hash<String, String>] parsed key-value pairs
+    def self.parse_file(path)
+      parse(File.read(path))
+    end
     private_class_method :parse_file
 
+    # Serialize a hash to `.env`-formatted text suitable for writing to a
+    # file or passing to {parse}.
+    #
+    # Keys are emitted in alphabetical order. Values that contain
+    # whitespace, `=`, `#`, or quote characters are wrapped in double
+    # quotes with inner `"` and `\` backslash-escaped. `nil` values become
+    # empty (`KEY=`). The output always ends with a single trailing
+    # newline.
+    #
+    # @example Round trip
+    #   Philiprehberger::EnvLoader.parse(
+    #     Philiprehberger::EnvLoader.dump('A' => '1', 'B' => 'two words')
+    #   )
+    #   # => { "A" => "1", "B" => "two words" }
+    #
+    # @param hash [Hash{String, Symbol => Object}] the key-value pairs to serialize
+    # @return [String] `.env`-formatted text
+    def self.dump(hash)
+      lines = hash.to_h
+                  .transform_keys(&:to_s)
+                  .sort_by(&:first)
+                  .map { |key, value| "#{key}=#{format_value(value)}" }
+      "#{lines.join("\n")}\n"
+    end
+
+    # @api private
+    def self.format_value(value)
+      return '' if value.nil?
+
+      str = value.to_s
+      return '' if str.empty?
+      return str unless str.match?(/[\s="'#]/)
+
+      escaped = str.gsub('\\') { '\\\\' }.gsub('"') { '\\"' }
+      %("#{escaped}")
+    end
+    private_class_method :format_value
+
     # Apply type coercions to ENV values.
     #
     # @param types [Hash<String, Symbol>] key => type mapping

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-env_loader
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-05-30 00:00:00.000000000 Z
 dependencies: []
 description: Load environment variables from multiple .env files with configurable
   precedence, type coercion, required key validation, default values, and template