nero 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a87cd3e7e7ebac49f614c881c242634459409e9578686de3afb50d1f771d293
-  data.tar.gz: 0c8c81360ec1fc2d66460bf4849d162fc773a15bd5088913bdf00be6ff190533
+  metadata.gz: 9822fcc078e4b2c0e9f049da7cf6f37a98a5b9cf607434057f266a393154296e
+  data.tar.gz: b71a5be94f469b564e3a80c80a0545246afbc053f619201f8a0c6c0923a776a4
 SHA512:
-  metadata.gz: 14d8c46a0a012c020b64ba2c4a850ba8b8881f6ab96c41b2ffc12bfe3311240348fc95d0da17f5adcff54c2a54768efbaebae66a51d3fb29b8fb217aa3f439e8
-  data.tar.gz: 3d5f679720c0c89c019000fde2892b01d8fe7ce2cf9648c2a47db74c3541cd97ac685a2934b7c9082a051c80a57377dd9cf4ae251c41fddd00c1dc80819a4a00
+  metadata.gz: 863f2c0fbeb21286a0d0f51219e07351a93489688eb7c49be5c1c720a3e414d8e43129e2c0e4d23c6e44213e8547a03c28df128210026414e9e3e209bb7ef472
+  data.tar.gz: c431e49a4d5d422b554a891973c0e24b7c1810dd922492d56b39ca6157dc70e3110114d7474d0d2ed3b5076f2bea63d8493b2cd9db64c3354ea051022f8887cb

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "psych-3" do
+  gem "psych", "< 4"
+end
+
+appraise "psych-4" do
+  gem "psych", "< 5"
+end

data/CHANGELOG.md

@@ -1,4 +1,57 @@
 ## [Unreleased]
+...
+
+## [0.4.0] - 2025-02-15
+
+- Add `!ref`-tag:
+  ```ruby
+  Nero.load(<<~YAML)
+    min_threads: !env [MIN_THREADS, !ref [max_threads]]
+    max_threads: 5
+  end
+  # => {min_threads: 5, max_threads: 5}
+  ```
+- Support Psych v3  
+  ...so it can used with Rails v6
+
+## [0.3.0] - 2025-02-02
+
+- Add configuration  
+  For custom tags:
+  ```ruby
+  Nero.configure do |nero|
+    nero.add_tag("duration") do |coder|
+      num, duration = coder.seq
+      mult = case duration
+      when /^seconds?/ then 1
+      when /^minutes?$/ then 60
+      when /^hours?$/ then 60 *60
+      when /^days?$/ then 24 * 60 * 60
+      else
+        raise ArgumentError, "Unknown duration #{coder.seq.inspect}"
+      end
+      num * mult
+    end
+  end
+  ```
+  ...and config_dir:
+  ```ruby
+  Nero.configure {|nero| nero.config_dir = Rails.root / "config" }
+  ```
+- Allow for a `Rails.application.config_for` like experience
+  ```ruby
+  Nero.configure {|nero| nero.config_dir = Rails.root / "config" }
+  
+  Nero.load_config(:stripe, root: Rails.env)
+  # Returns content of Rails.root / "config/stripe.yml"
+  ```
+- Add `Nero.load` like `YAML.load`
+  ```ruby
+  Nero.load(<<~YAML)
+    cache_ttl: !duration [1, day]
+  end
+  # => {cache_ttl: 86400}
+  ```
 
 ## [0.1.0] - 2025-01-24
 

data/README.md

@@ -2,37 +2,33 @@
 
 [![Gem Version](https://badge.fury.io/rb/nero.svg)](https://badge.fury.io/rb/nero)
 
-Nero is a RubyGem that offers predefined tags and allows you to effortlessly create custom ones for YAML configuration files.
+Nero is a RubyGem that offers declarative YAML-tags to simplify config files, e.g. for requiring and coercion of env-vars.  
+Additionally, it allows you to create your own.
 
-E.g. instead of having the following settings file in your Ruby/Rails project:
+**Sample:**
 
 ```yaml
 development:
-  # env-var with a fallback
-  secret: <%= ENV.fetch("SECRET", "dummy") %>
-  # NOTE *any* value provided is taken as `true`
-  debug?: <%= !!ENV["DEBUG"] %>
-production:
-  # NOTE we can't fail-fast on ENV-var absence (i.e. use `ENV.fetch`),
-  # as it would require the env-var for development as well
-  secret: <%= ENV["SECRET"] %>
-  max_threads: <%= ENV.fetch("MAX_THREADS", 5).to_i %>
-```
-
-...turn it into this:
-```yaml
-development:
-  # env-var with a fallback
+  # env-var with default value
   secret: !env [SECRET, "dummy"]
-  # Though the default is false, explicitly providing "false"/"off"/"n"/"no" is also possible.
+  # optional env-var with coercion
   debug?: !env/bool? DEBUG
 production:
-  # fail-fast on absence of SECRET
+  # required env-var (only when getting the production-root)
   secret: !env SECRET
-  # always an integer
+  # int coercion
   max_threads: !env/integer [MAX_THREADS, 5]
+  # something custom
+  cache_ttl: !duration [2, hours]
 ```
 
+## Highlights
+
+* 💎 declarative YAML-tags for e.g. requiring and coercing env-vars
+* 🛠️ add custom tags
+* 🛤️ `Rails.application.config_for` stand-in
+* ♻️ Zeitwerk-only dependency
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -52,7 +48,7 @@ Given the following config:
 development:
   # env-var with a fallback
   secret: !env [SECRET, "dummy"]
-  # Though the default is false, explicitly providing "false"/"off"/"n"/"no" is also possible.
+  # Though the default is false, explicitly providing "false"/"off"/"n"/"no" also works.
   debug?: !env/bool? DEBUG
 production:
   # fail-fast on absence of SECRET
@@ -65,7 +61,7 @@ Loading this config:
 
 ```ruby
 # Loading development
-Nero.load_config(Pathname.pwd / "config/settings.yml", root: :development)
+Nero.load_config("config/settings", root: :development)
 # ...and no ENV-vars were provided
 #=> {secret: "dummy", debug?: false}
 
@@ -73,7 +69,7 @@ Nero.load_config(Pathname.pwd / "config/settings.yml", root: :development)
 #=> {secret: "dummy", debug?: true}
 
 # Loading production
-Nero.load_config(Pathname.pwd / "config/settings.yml", root: :production)
+Nero.load_config("config/settings", root: :production)
 # ...and no ENV-vars were provided
 # raises error: key not found: "SECRET" (KeyError)
 
@@ -132,17 +128,42 @@ The following tags are provided:
     - smtps://%s:%s@smtp.gmail.com
     - !env SMTP_USER
     - !env SMTP_PASS
-  # using references
+  
+  # pass it a map (including a key 'fmt') to use references
   smtp_url: !str/format
     fmt: smtps://%<user>s:%<pass>s@smtp.gmail.com
     user: !env SMTP_USER
     pass: !env SMTP_PASS
   ```
+- `!ref`  
+  Include values from elsewhere:
+  ```yaml
+  # simple
+  min_threads: !env [MIN_THREADS, !ref [max_threads]]
+  max_threads: 5
+  
+  # oauth_callback -refs-> base.url -refs-> base.host
+  base:
+    host: !env [HOST]
+    url: !str/format ['https://%s', !ref[base, host]]
+  oauth_callback: !str/format
+    - '%s/oauth/callback'
+    - !ref[base, url]
+
+  # refs are resolved within the tree of the selected root.
+  # The following config won't work when doing `Nero.load_config(:app, root: :prod)`
+  dev:
+    max_threads: 5
+  prod:
+    max_threads: !env[MAX_THREADS, !ref[dev, max_threads]]
+  ```
+  NOTE future version should raise properly over ref-ing a non-existing path.
+  
 
-TBD Add one yourself:
+Add one yourself:
 ```ruby
-Nero.configure do
-  add_tag("foo") do |coder|
+Nero.configure do |nero|
+  nero.add_tag("foo") do |coder|
     # coder.type is one of :scalar, :seq or :map
     # e.g. respective YAML:
     # ---
@@ -156,7 +177,18 @@ Nero.configure do
     #
     # Find the value in the respective attribute, e.g. `coder.scalar`:
     coder.scalar.upcase
+
+    # NOTE when needing just one argument, supporting both scalar and seq allows for chaining:
+    # a: !my/inc 4 # scalar suffices
+    # ...but when chaining, a seq is required:
+    # a: !my/inc [!my/square 2]
   end
+
+  # Other configuration options:
+  #
+  # `config_dir` (default: Pathname.pwd) - path used for expanding non-Pathnames passed to `load_config`, e.g.
+  # `Nero.load_config(:app)` loads file `Pathname.pwd / "app.yml"`.
+  nero.config_dir = Rails.root / "config"
 end
 ```
 

data/gemfiles/psych_3.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "standard", "~> 1.3"
+gem "psych", "< 4"
+
+gemspec path: "../"

data/gemfiles/psych_4.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "standard", "~> 1.3"
+gem "psych", "< 5"
+
+gemspec path: "../"

data/lib/nero/version.rb

@@ -3,5 +3,5 @@
 module Nero
   # NOTE this is written upon release via:
   # $ rake gem:build[version=0.3.0]
-  VERSION = "0.2.2"
+  VERSION = "0.4.0"
 end

data/lib/nero.rb

@@ -5,6 +5,7 @@ loader = Zeitwerk::Loader.for_gem
 loader.setup
 
 require "uri" # why needed?
+require "yaml"
 
 # TODO fail on unknown tag
 # TODO show missing env's at once
@@ -30,7 +31,10 @@ module Nero
     end
   end
   extend Resolvable
-  private_class_method :try_resolve, :gen_resolve_tryer, :deep_resolve
+  private_class_method \
+    :deep_resolve,
+    :gen_resolve_tryer,
+    :try_resolve
 
   class TagResolver
     include Resolvable
@@ -41,7 +45,7 @@ module Nero
 
     def resolve(ctx)
       resolve_nested!(ctx)
-      ctx[:resolvers][@coder.tag].call(@coder)
+      ctx[:tags][@coder.tag].call(@coder, ctx)
     end
 
     def resolve_nested!(ctx)
@@ -54,106 +58,197 @@ module Nero
     end
   end
 
-  def self.add_resolver(name, &block)
-    (@resolvers ||= {})["!#{name}"] = block
-  end
-
-  def self.env_fetch(k, fallback = nil, all_optional: "dummy")
-    fallback ||= all_optional if ENV["NERO_ENV_ALL_OPTIONAL"]
+  class Configuration
+    attr_reader :tags
+    attr_accessor :config_dir
 
-    fallback.nil? ? ENV.fetch(k) : ENV.fetch(k, fallback)
+    def add_tag(name, &block)
+      (@tags ||= {})["!#{name}"] = block
+    end
   end
-  private_class_method :env_fetch
 
-  add_resolver("env/integer") do |coder|
-    Integer(env_fetch(*(coder.scalar || coder.seq), all_optional: "999"))
+  def self.configuration
+    @configuration ||= Configuration.new
   end
 
-  add_resolver("env/integer?") do |coder|
-    Integer(ENV[coder.scalar]) if ENV[coder.scalar]
+  def self.configure
+    yield configuration if block_given?
   end
 
-  add_resolver("env/bool") do |coder|
-    re_true = /y|Y|yes|Yes|YES|true|True|TRUE|on|On|ON/
-    re_false = /n|N|no|No|NO|false|False|FALSE|off|Off|OFF/
+  # helpers for configuration
+  # module TagHelpers
+  #  def to_boolean(s)
+  #  end
+  # end
 
-    coerce = ->(s) do
-      case s
-      when TrueClass, FalseClass then s
-      when re_true then true
-      when re_false then false
-      else
-        raise "bool value should be one of y(es)/n(o), on/off, true/false (got #{s.inspect})"
+  def self.add_default_tags!
+    # extend TagHelpers
+
+    configure do |config|
+      config.add_tag("ref") do |coder, ctx|
+        # validate: non-empty coder.seq, only strs, path must exists in ctx[:config]
+
+        path = coder.seq.map(&:to_sym)
+        deep_resolve(ctx[:config].dig(*path), **ctx)
       end
-    end
 
-    coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "false")]
-  end
+      config.add_tag("env/integer") do |coder|
+        Integer(env_fetch(*(coder.scalar || coder.seq), all_optional: "999"))
+      end
 
-  add_resolver("env/bool?") do |coder|
-    re_true = /y|Y|yes|Yes|YES|true|True|TRUE|on|On|ON/
-    re_false = /n|N|no|No|NO|false|False|FALSE|off|Off|OFF/
+      config.add_tag("env/integer?") do |coder|
+        Integer(ENV[coder.scalar]) if ENV[coder.scalar]
+      end
 
-    coerce = ->(s) do
-      case s
-      when TrueClass, FalseClass then s
-      when re_true then true
-      when re_false then false
-      else
-        raise "bool value should be one of y(es)/n(o), on/off, true/false (got #{s.inspect})"
+      config.add_tag("env/bool") do |coder|
+        re_true = /y|Y|yes|Yes|YES|true|True|TRUE|on|On|ON/
+        re_false = /n|N|no|No|NO|false|False|FALSE|off|Off|OFF/
+
+        coerce = ->(s) do
+          case s
+          when TrueClass, FalseClass then s
+          when re_true then true
+          when re_false then false
+          else
+            raise "bool value should be one of y(es)/n(o), on/off, true/false (got #{s.inspect})"
+          end
+        end
+
+        coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "false")]
       end
-    end
 
-    ENV[coder.scalar] ? coerce[ENV[coder.scalar]] : false
-  end
+      config.add_tag("env/bool?") do |coder|
+        re_true = /y|Y|yes|Yes|YES|true|True|TRUE|on|On|ON/
+        re_false = /n|N|no|No|NO|false|False|FALSE|off|Off|OFF/
+
+        coerce = ->(s) do
+          case s
+          when TrueClass, FalseClass then s
+          when re_true then true
+          when re_false then false
+          else
+            raise "bool value should be one of y(es)/n(o), on/off, true/false (got #{s.inspect})"
+          end
+        end
+
+        ENV[coder.scalar] ? coerce[ENV[coder.scalar]] : false
+      end
+
+      config.add_tag("env") do |coder|
+        env_fetch(*(coder.scalar || coder.seq))
+      end
+
+      config.add_tag("env?") do |coder|
+        fetch_args = coder.scalar ? [coder.scalar, nil] : coder.seq
+        ENV.fetch(*fetch_args)
+      end
+
+      config.add_tag("path") do |coder|
+        Pathname.new(coder.scalar || coder.seq.join("/"))
+      end
+
+      config.add_tag("uri") do |coder|
+        URI(coder.scalar || coder.seq.join)
+      end
 
-  add_resolver("env") do |coder|
-    env_fetch(*(coder.scalar || coder.seq))
+      config.add_tag("str/format") do |coder|
+        case coder.type
+        when :seq
+          sprintf(*coder.seq)
+        when :map
+          m = Util.deep_symbolize_keys(coder.map)
+          fmt = m.delete(:fmt)
+          sprintf(fmt, m)
+        else
+          coder.scalar
+        end
+      end
+    end
   end
+  private_class_method :add_default_tags!
+
+  def self.reset_configuration!
+    @configuration = nil
+
+    configure do |config|
+      config.config_dir = Pathname.pwd
+    end
 
-  add_resolver("env?") do |coder|
-    fetch_args = coder.scalar ? [coder.scalar, nil] : coder.seq
-    ENV.fetch(*fetch_args)
+    add_default_tags!
   end
+  reset_configuration!
+
+  def self.env_fetch(k, fallback = nil, all_optional: "dummy")
+    fallback ||= all_optional if ENV["NERO_ENV_ALL_OPTIONAL"]
 
-  add_resolver("path") do |coder|
-    Pathname.new(coder.scalar || coder.seq.join("/"))
+    fallback.nil? ? ENV.fetch(k) : ENV.fetch(k, fallback)
   end
+  private_class_method :env_fetch
 
-  add_resolver("uri") do |coder|
-    URI(coder.scalar || coder.seq.join)
+  @yaml_options = {
+    permitted_classes: [Symbol, TagResolver],
+    aliases: true
+  }
+
+  def self.load_config(file, root: nil, env: nil)
+    root ||= env
+    add_tags!
+
+    file = resolve_file(file)
+
+    if file.exist?
+      process_yaml(yaml_load_file(file, @yaml_options), root:)
+    else
+      raise "Can't find file #{file}"
+    end
   end
 
-  add_resolver("str/format") do |coder|
-    case coder.type
-    when :seq
-      sprintf(*coder.seq)
-    when :map
-      m = Util.deep_symbolize_keys(coder.map)
-      fmt = m.delete(:fmt)
-      sprintf(fmt, m)
+  def self.resolve_file(file)
+    case file
+    when Pathname then file
+    # TODO expand full path
     else
-      coder.scalar
+      configuration.config_dir / "#{file}.yml"
     end
   end
+  private_class_method :resolve_file
 
-  def self.load_config(file, root: nil)
+  def self.load(raw, root: nil, env: nil)
+    root ||= env
     add_tags!
 
-    if file.exist?
-      unresolved = Util.deep_symbolize_keys(YAML.load_file(file,
-        permitted_classes: [Symbol, TagResolver], aliases: true)).then do
-        root ? _1[root.to_sym] : _1
-      end
+    process_yaml(yaml_load(raw, @yaml_options), root:)
+  end
+
+  def self.process_yaml(yaml, root: nil)
+    unresolved = Util.deep_symbolize_keys(yaml).then do
+      root ? _1[root.to_sym] : _1
+    end
 
-      deep_resolve(unresolved, resolvers: @resolvers)
+    deep_resolve(unresolved, tags: configuration.tags, config: unresolved)
+  end
+  private_class_method :process_yaml
+
+  def self.yaml_load_file(file, opts = {})
+    if Psych::VERSION < "4"
+      YAML.load_file(file)
     else
-      raise "Can't find file #{file}"
+      YAML.load_file(file, **opts)
+    end
+  end
+  private_class_method :yaml_load_file
+
+  def self.yaml_load(file, opts = {})
+    if Psych::VERSION < "4"
+      YAML.load(file)
+    else
+      YAML.load(file, **opts)
     end
   end
+  private_class_method :yaml_load
 
   def self.add_tags!
-    @resolvers.keys.each do
+    configuration.tags.keys.each do
       YAML.add_tag(_1, TagResolver)
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nero
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Gert Goet
 bindir: exe
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Some convenient YAML-tags...
   - to get environment values: env, env?, env/integer, env/integer?, env/bool, env/bool?.
@@ -39,10 +53,13 @@ files:
 - ".envrc"
 - ".rspec"
 - ".standard.yml"
+- Appraisals
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- gemfiles/psych_3.gemfile
+- gemfiles/psych_4.gemfile
 - lib/nero.rb
 - lib/nero/util.rb
 - lib/nero/version.rb