nero 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3da331b2512fc63cf1a9258991a33dda876e8b0aed2445bca34ed207f8cfc1fb
-  data.tar.gz: 79c6afff69d21841b247de206f7b3f6482bf74496ad91c4986528fd0620e6551
+  metadata.gz: 4e28a4b8bcd989c20dd60dc592bfb31039314437b3d8ca5df33b79adefd5cb2e
+  data.tar.gz: f6eb0ec1e9ceb041088a7d2b850494e090f08d98f4e8369f82f0608a4449ab69
 SHA512:
-  metadata.gz: e80cb4098d709df1231e7ee1cfc077be097517709ffabee489cdce8bc9da30aac7e6f89157823c147e691042945c9da806f337f1ca64ab90dc376d390f46d0b9
-  data.tar.gz: 7637f0ae5983c3902a04092c2d1cf3ed9aacb0ae036f73d7c1067f7677a8c175ffe4c4826c972cb129c47cfe37517115e0bd51f81c1f6b4f132a8946b4311a3e
+  metadata.gz: 98dc2c475e0e164f47d1738dbe32d6dfeeba6b531f6db0b396a25d3e29219c312ac0750206fddea1d9ee450e9205425a5f0342c6b5b13d38867a364e1219bed0
+  data.tar.gz: e9daf1ee287679b10d4ea744c41d3f93bf50570394eb261f7c8b3587a1008efe57b58b7957141aeea48229b65efdaa614f23c181fbf08659a0a878a7a944e773

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,54 @@
 ## [Unreleased]
+...
+
+## [0.5.0] - 2025-03-20
+
+- tag-classes  
+  Added [`Nero::BaseTag`](https://rubydoc.info/github/eval/nero/main/Nero/BaseTag) that is the basis of all existing tags.  
+  This means that building upon existing tags is easier and custom tags can be more powerful.
+  
+  Create new tags can be done in 3 ways:  
+  By block (as before, but slightly changed interface):
+  ```ruby
+  Nero.configure do |nero|
+    nero.add_tag("foo") do |tag|
+      # tag of type Nero::BaseTag
+    end
+  end
+  ```
+  By re-using existing tags via options:
+  ```ruby
+  nero.add_tag("env/upcase", klass: Nero::EnvTag[coerce: :upcase])
+  ```
+  Finally, by subclassing [Nero::BaseTag](https://rubydoc.info/github/eval/nero/main/Nero/BaseTag). See the section ["custom tags"](https://github.com/eval/nero?tab=readme-ov-file#custom-tags) from the README.
+  
+- `!env/float` and `!env/float?`  
+- `!env/git_root` and `!env/rails_root`  
+  Construct a path relative to some root-path:
+  ```yaml
+  asset_path: !path/rails_root [ public/assets ]
+  ```
+  Easy to use for your own tags:
+  ```ruby
+  config.add_tag("path/project_root", klass: Nero::PathRootTag[containing: '.git']) do |path|
+    # possible post-processing
+  end
+  ```
+- [#2](https://github.com/eval/nero/pull/2) Add irb to gemfile (@dlibanori)
+- [#3](https://github.com/eval/nero/pull/3) Fix missing require (@dlibanori)
+
+## [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
 

data/README.md

@@ -2,33 +2,43 @@
 
 [![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 Rails project:
+**Sample:**
 
 ```yaml
 development:
-  secret: <%= ENV.fetch("SECRET", "dummy") %>
-  # custom logic how to get a boolean...
-  debug?: <%= ENV["DEBUG"] == "true" %>
-production:
-  # any ENV.fetch in this section would hamper local development...
-  secret: <%= ENV["SECRET"] %>
-  # custom coercion logic
-  max_threads: <%= ENV.fetch("MAX_THREADS", 5).to_i %>
-```
-
-...turn it into this:
-```yaml
-development:
+  # env-var with default value
   secret: !env [SECRET, "dummy"]
+
+  # optional env-var with coercion
   debug?: !env/bool? DEBUG
+
 production:
-  # required _only_ when loading production
+  # required env-var (not required during development)
   secret: !env SECRET
+
+  # coercion
   max_threads: !env/integer [MAX_THREADS, 5]
+
+  # refer to other keys
+  min_threads: !env/integer [MIN_THREADS, !ref max_threads ]
+
+  # descriptive names
+  asset_folder: !path/rails_root [ public/assets ]
+
+  # easy to add custom tags
+  cache_ttl: !duration [2, hours]
 ```
 
+## Highlights
+
+* 💎 declarative YAML-tags for e.g. requiring and coercing env-vars
+* 🛠️ add custom tags
+* 🛤️ `Rails.application.config_for` drop-in
+* ♻️ Zeitwerk-only dependency
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -42,6 +52,8 @@ bundle add nero
 > [!WARNING]  
 > It's early days - the API and included tags will certainly change. Check the CHANGELOG when upgrading.
 
+### loading a config
+
 Given the following config:
 ```yaml
 # config/settings.yml
@@ -76,6 +88,17 @@ Nero.load_config("config/settings", root: :production)
 # ...with ENV {"SECRET" => "s3cr3t", "MAX_THREADS" => "3"}
 #=> {secret: "s3cr3t", max_threads: 3}
 ```
+> [!TIP]  
+> The following configuration would make `Nero.load_config` a drop-in replacement for [Rails.application.config_for](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-config_for):
+```ruby
+Nero.configure do |config|
+  config.config_dir = Rails.root / "config"
+end
+
+Nero.load_config(:settings, env: Rails.env)
+```
+
+### built-in tags
 
 The following tags are provided:
 - `!env KEY`, `!env? KEY`  
@@ -90,10 +113,11 @@ The following tags are provided:
   secret: !env? SECRET
   ```
 - to coerce env-values:
-  - `env/integer`, `env/integer?`:  
+  - `env/integer`, `env/integer?`, `env/float`, `env/float?`:  
     ```yaml
     port: !env/integer [PORT, 3000]
     threads: !env/integer? THREADS # nil when not provided
+    threshold: !env/float CUTOFF
     ```
   - `env/bool`, `env/bool?`:  
     ```yaml
@@ -104,6 +128,11 @@ The following tags are provided:
     # ...or false:
     debug?: !env/bool? DEBUG
     ```
+> [!TIP]  
+> Make all env-var's optional by providing `ENV["NERO_ENV_ALL_OPTIONAL"]`, e.g.
+```shell
+$ env NERO_ENV_ALL_OPTIONAL=1 SECRET_KEY_BASE_DUMMY=1 rails asset:precompile
+```
 - `!path`  
   Create a [Pathname](https://rubyapi.org/3.4/o/pathname):
   ```yaml
@@ -113,6 +142,15 @@ The following tags are provided:
     - !env PROJECT_ROOT
     - /public/assets
   ```
+- `!path/git_root`, `!path/rails_root`  
+  Create a Pathname relative to some root-path.  
+  The root-path is expected to be an existing ancestor folder of the yaml-config being parsed.  
+  It's found by traversing up and checking for the presence of specific files/folders, e.g. '.git' (`!path/git_root`) or 'config.ru' (`!path/rails_root`).  
+  While the root-path needs to exist, the resulting Pathname doesn't need to.
+  ```yaml
+  project_root: !path/git_root
+  config_folder: !path/rails_root [ config ]
+  ```
 - `!uri`  
   Create a [URI](https://rubyapi.org/3.4/o/uri):
   ```yaml
@@ -128,39 +166,123 @@ 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/integer [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]
 
-Add one yourself:
-```ruby
-Nero.configure do |nero|
-  nero.add_tag("foo") do |coder|
-    # coder.type is one of :scalar, :seq or :map
-    # e.g. respective YAML:
-    # ---
-    # !foo bar
-    # ---
-    # !foo
-    #   - bar
-    # ---
-    # !foo
-    #   bar: baz
-    #
-    # Find the value in the respective attribute, e.g. `coder.scalar`:
-    coder.scalar.upcase
-  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
-```
+  # 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.
+
+### custom tags
+
+Three ways to do this:
+
+1. a block  
+    ```ruby
+    Nero.configure do |nero|
+      nero.add_tag("upcase") do |tag|
+        # `tag` is a `Nero::BaseTag`.
+        # In YAML args are provided as scalar, seq or map:
+        # ---
+        # k: !upcase bar
+        # ---
+        # k: !upcase [bar] # equivalent to:
+        # k: !upcase
+        #   - bar
+        # ---
+        # k: !upcase
+        #   bar: baz
+        #
+        # Find these args via `tag.args` (Array or Hash):
+        case tag.args
+        when Hash
+          tag.args.each_with_object({}) {|(k,v), acc| acc[k] = v.upcase }
+        else
+          tag.args.map(&:upcase)
+        end
+
+        # NOTE though you might just need one argument, it's helpful to accept a seq nonetheless
+        # as it allows for chaining:
+        # a: !my/inc 4 # scalar suffices
+        # ...but when chaining, it comes as a seq:
+        # a: !my/inc [!my/square 2]
+      end
+    end
+    ```
+1. re-use existing tag-class  
+   You can add an existing tag under a better fitting name this way.  
+   Also: some tag-classes have options that allow for simple customizations (like `coerce` below):
+    ```ruby
+    Nero.configure do |nero|
+      nero.add_tag("env/upcase", klass: Nero::EnvTag[coerce: :upcase])
+
+      # Alias for path/git_root:
+      nero.add_tag("path/project_root", klass: Nero::PathRootTag[containing: '.git'])
+    end
+    ```
+1. custom class  
+   ```ruby
+   class RotTag < Nero::BaseTag
+     # Configure:
+     # ```
+     # config.add_tag("rot/12", klass: RotTag[n: 12])
+     # config.add_tag("rot/10", klass: RotTag[n: 10]) do |secret|
+     #   "#{secret} (try breaking this!)"
+     # end
+     # ```
+     #
+     # Usage in YAML:
+     # ```
+     # secret: !rot/12 some message
+     # very_secret: !rot/10 [ !env [ MSG, some message ] ]
+     # ```
+     # => {secret: "EAyq yqEEmsq", very_secret: "Cywo woCCkqo (try breaking this!)"}
+   
+     # By overriding `init_options` we can restrict/require options,
+     # provide default values and do any other setup.  
+     # By default an option is available via `options[:foo]`.
+     def init_options(n: 10)
+       super # no specific assignments, so available via `options[:n]`.
+     end
+
+     def chars
+       @chars ||= (('a'..'z').to_a + ('A'..'Z').to_a + ('0'..'9').to_a)
+     end
+
+     def resolve(**) # currently no keywords are passed, but `**` allows for future ones.
+       # Here we actually do the work: get the args, rotate strings and delegate to the block.
+       # `args` are the resolved nested args (so e.g. `!env MSG` is already resolved).
+       # `config` is the tag's config, and contains e.g. the block.
+       block = config.fetch(:block, :itself.to_proc)
+       # String#tr replaces any character from the first collection with the same position in the other:
+       args.join.tr(chars.join, chars.rotate(options[:n]).join).then(&block)
+     end
+   end
+   ```
 
 ## Development
 

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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/nero.rb

@@ -4,8 +4,9 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
-require "uri" # why needed?
+require "uri"
 require "yaml"
+require "pathname"
 
 # TODO fail on unknown tag
 # TODO show missing env's at once
@@ -16,7 +17,7 @@ module Nero
   module Resolvable
     def try_resolve(ctx, object)
       if object.respond_to?(:resolve)
-        object.resolve(ctx)
+        object.resolve(**ctx)
       else
         object
       end
@@ -29,6 +30,15 @@ module Nero
     def deep_resolve(object, **ctx)
       Util.deep_transform_values(object, &gen_resolve_tryer(ctx))
     end
+
+    def resolve_nested!(coder, ctx = {})
+      case coder.type
+      when :seq
+        coder.seq.map!(&gen_resolve_tryer(ctx))
+      when :map
+        coder.map = deep_resolve(coder.map, **ctx)
+      end
+    end
   end
   extend Resolvable
   private_class_method \
@@ -36,37 +46,23 @@ module Nero
     :gen_resolve_tryer,
     :try_resolve
 
-  class TagResolver
-    include Resolvable
+  class Configuration
+    attr_reader :tags, :config_dir
 
-    def init_with(coder)
-      @coder = coder
+    def config_dir=(dir)
+      @config_dir = Pathname(dir).expand_path
     end
 
-    def resolve(ctx)
-      resolve_nested!(ctx)
-      ctx[:tags][@coder.tag].call(@coder)
-    end
+    def add_tag(name, klass: BaseTag, &block)
+      klass, klass_options = klass
 
-    def resolve_nested!(ctx)
-      case @coder.type
-      when :seq
-        @coder.seq.map!(&gen_resolve_tryer(ctx))
-      when :map
-        @coder.map = deep_resolve(@coder.map, **ctx)
+      (@tags ||= {})[name] = {klass:}.tap do |h|
+        h[:block] = block if block
+        h[:options] = klass_options if klass_options
       end
     end
   end
 
-  class Configuration
-    attr_reader :tags
-    attr_accessor :config_dir
-
-    def add_tag(name, &block)
-      (@tags ||= {})["!#{name}"] = block
-    end
-  end
-
   def self.configuration
     @configuration ||= Configuration.new
   end
@@ -75,77 +71,221 @@ module Nero
     yield configuration if block_given?
   end
 
-  def self.add_default_tags!
-    configure do |config|
-      config.add_tag("env/integer") do |coder|
-        Integer(env_fetch(*(coder.scalar || coder.seq), all_optional: "999"))
-      end
+  class BaseTag
+    include Resolvable
+
+    attr_reader :coder, :options, :ctx
+
+    def self.[](**options)
+      [self, options]
+    end
+
+    # used by YAML
+    def init_with(coder)
+      @coder = coder
+    end
 
-      config.add_tag("env/integer?") do |coder|
-        Integer(ENV[coder.scalar]) if ENV[coder.scalar]
+    def init(ctx:, options:)
+      init_ctx(ctx)
+      init_options(**options)
+    end
+
+    def init_ctx(ctx)
+      @ctx = ctx
+    end
+
+    def init_options(**options)
+      @options = options
+    end
+
+    def tag_name
+      coder.tag[1..]
+    end
+
+    def args
+      @args ||= begin
+        resolve_nested!(coder, {})
+        case coder.type
+        when :map then Util.deep_symbolize_keys(coder.map)
+        else
+          Array(coder.public_send(coder.type))
+        end
       end
+    end
+
+    def config
+      ctx.dig(:tags, tag_name)
+    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
+    def resolve(**)
+      if (block = config[:block])
+        if block.parameters.map(&:last).include?(:coder)
+          # legacy
+          block.call(coder, ctx)
+        else
+          block.call(self)
         end
+      else
+        args
+      end
+    end
+  end
 
-        coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "false")]
+  # Requires an env-var to be available and coerces the value.
+  # When tag-name ends with "?", the env-var is optional.
+  #
+  # Given config:
+  # config.add_tag("env/upcase", klass: Nero::EnvTag[coerce: :upcase])
+  # config.add_tag("env/upcase?", klass: Nero::EnvTag[coerce: :upcase])
+
+  # Then YAML => result:
+  # "--- env/upcase [MSG, Hello World]" => "HELLO WORLD"
+  # "--- env/upcase MSG" => raises when not ENV.has_key? "MSG"
+  # "--- env/upcase? MSG" => nil
+  #
+  # Args supported:
+  # - scalar
+  #  name of env-var, e.g. `!env HOME`
+  # - seq
+  #  name of env-var and fallback, e.g. `!env [HOME, /root]`
+
+  # Options:
+  # - coerce - symbol or proc to be applied to value of env-var.
+  #   when using coerce, the block is ignoerd.
+  #
+  class EnvTag < BaseTag
+    def resolve(**)
+      if coercer
+        coercer.call(env_value) unless env_value.nil?
+      elsif ctx.dig(:tags, tag_name, :block)
+        super
+      else
+        env_value
       end
+    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
+    def coercer
+      return unless @coerce
+
+      @coercer ||= case @coerce
+      when Symbol then @coerce.to_proc
+      else
+        @coerce
+      end
+    end
+
+    def init_options(coerce: nil)
+      @coerce = coerce
+    end
+
+    def optional
+      tag_name.end_with?("?") || !!ENV["NERO_ENV_ALL_OPTIONAL"]
+    end
+    alias_method :optional?, :optional
 
-        ENV[coder.scalar] ? coerce[ENV[coder.scalar]] : false
+    def env_value
+      self.class.env_value(*args, optional:)
+    end
+
+    def self.env_value(k, fallback = nil, optional: false)
+      if fallback.nil? && !optional
+        ENV.fetch(k)
+      else
+        ENV.fetch(k, fallback)
       end
+    end
 
-      config.add_tag("env") do |coder|
-        env_fetch(*(coder.scalar || coder.seq))
+    def self.coerce_bool(v)
+      return false unless v
+
+      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/
+
+      case v
+      when TrueClass, FalseClass then v
+      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 #{v.inspect})"
       end
+    end
+  end
+
+  # Construct path relative to some root-path.
+  # Root-paths are expected to be ancestors of the yaml-file being parsed.
+  # They are found by traversing up and checking for specific files/folders, e.g. '.git' or 'Gemfile'.
+  # Any argument is appended to the root-path, constructing a path-instance that may exist.
+  class PathRootTag < BaseTag
+    # Config:
+    # config.add_tag("path/git_root", klass: PathRootTag[containing: ".git"])
+    # config.add_tag("path/rails_root", klass: PathRootTag[containing: "Gemfile"])
+    #
+    # YAML:
+    # project_root: !path/git_root
+    # config_path: !path/git_root [ config ]
+    def init_options(containing:)
+      super
+    end
 
-      config.add_tag("env?") do |coder|
-        fetch_args = coder.scalar ? [coder.scalar, nil] : coder.seq
-        ENV.fetch(*fetch_args)
+    def resolve(**)
+      # TODO validate upfront
+      raise <<~ERR unless root_path
+        #{tag_name}: failed to find root-path (ie an ancestor of #{ctx[:yaml_file]} containing #{options[:containing].inspect}).
+      ERR
+      root_path.join(*args).then(&config.fetch(:block, :itself.to_proc))
+    end
+
+    def root_path
+      find_up(ctx[:yaml_file], options[:containing])
+    end
+
+    def find_up(path, containing)
+      (path = path.parent) until path.root? || (path / containing).exist?
+      path unless path.root?
+    end
+  end
+
+  def self.add_default_tags!
+    configure do |config|
+      config.add_tag("ref") do |tag|
+        # validate: non-empty coder.seq, only strs, path must exists in ctx[:config]
+
+        path = tag.args.map(&:to_sym)
+        deep_resolve(tag.ctx[:yaml].dig(*path), **{})
       end
 
-      config.add_tag("path") do |coder|
-        Pathname.new(coder.scalar || coder.seq.join("/"))
+      config.add_tag("env", klass: EnvTag)
+      config.add_tag("env?", klass: EnvTag)
+      config.add_tag("env/float", klass: EnvTag[coerce: :to_f])
+      config.add_tag("env/float?", klass: EnvTag[coerce: :to_f])
+
+      config.add_tag("env/integer", klass: EnvTag[coerce: :to_i])
+      config.add_tag("env/integer?", klass: EnvTag[coerce: :to_i])
+
+      config.add_tag("env/bool", klass: EnvTag) do |tag|
+        EnvTag.coerce_bool(tag.env_value)
+      end
+      config.add_tag("env/bool?", klass: EnvTag) do |tag|
+        EnvTag.coerce_bool(tag.env_value)
       end
 
-      config.add_tag("uri") do |coder|
-        URI(coder.scalar || coder.seq.join)
+      config.add_tag("path") do |tag|
+        Pathname.new(tag.args.join("/"))
       end
+      config.add_tag("path/git_root", klass: PathRootTag[containing: ".git"])
+      config.add_tag("path/rails_root", klass: PathRootTag[containing: "config.ru"])
 
-      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)
+      config.add_tag("uri") do |tag|
+        URI.join(*tag.args.join)
+      end
+
+      config.add_tag("str/format") do |tag|
+        case tag.args
+        when Hash
+          fmt = tag.args.delete(:fmt)
+          sprintf(fmt, tag.args)
         else
-          coder.scalar
+          sprintf(*tag.args)
         end
       end
     end
@@ -163,27 +303,24 @@ module Nero
   end
   reset_configuration!
 
-  def self.env_fetch(k, fallback = nil, all_optional: "dummy")
-    fallback ||= all_optional if ENV["NERO_ENV_ALL_OPTIONAL"]
-
-    fallback.nil? ? ENV.fetch(k) : ENV.fetch(k, fallback)
+  def self.yaml_options
+    {
+      permitted_classes: [Symbol] + configuration.tags.values.map { _1[:klass] },
+      aliases: true
+    }
   end
-  private_class_method :env_fetch
-
-  @yaml_options = {
-    permitted_classes: [Symbol, TagResolver],
-    aliases: true
-  }
+  private_class_method :yaml_options
 
-  def self.load_config(file, root: nil)
+  def self.load_config(file, root: nil, env: nil, resolve: true)
+    root ||= env
     add_tags!
 
-    file = resolve_file(file)
+    config_file = resolve_file(file)
 
-    if file.exist?
-      process_yaml(YAML.load_file(file, **@yaml_options), root:)
+    if config_file.exist?
+      process_yaml(yaml_load_file(config_file, yaml_options), root:, config_file:, resolve:)
     else
-      raise "Can't find file #{file}"
+      raise "Can't find file #{config_file}"
     end
   end
 
@@ -197,27 +334,83 @@ module Nero
   end
   private_class_method :resolve_file
 
-  def self.load(raw, root: nil)
+  def self.load(raw, root: nil, env: nil, resolve: true)
+    root ||= env
     add_tags!
 
-    process_yaml(YAML.load(raw, **@yaml_options), root:)
+    process_yaml(yaml_load(raw, yaml_options), root:, resolve:)
   end
 
-  def self.process_yaml(yaml, root: nil)
+  def self.process_yaml(yaml, root: nil, resolve: true, config_file: nil)
+    config_file ||= (Pathname.pwd / __FILE__)
+
     unresolved = Util.deep_symbolize_keys(yaml).then do
       root ? _1[root.to_sym] : _1
     end
+    ctx = {tags: configuration.tags, yaml: unresolved, yaml_file: config_file}
+    init_tags!(collect_tags(unresolved), ctx:)
 
-    deep_resolve(unresolved, tags: configuration.tags)
+    return unresolved unless resolve
+
+    # NOTE originally ctx was passed at this point. Maybe delete this.
+    deep_resolve(unresolved, **{})
   end
   private_class_method :process_yaml
 
+  def self.init_tags!(tags, ctx:)
+    tags.each do |tag|
+      options = ctx.dig(:tags, tag.tag_name, :options) || {}
+      tag.init(ctx:, options:)
+    end
+  end
+  private_class_method :init_tags!
+
+  def self.yaml_load_file(file, opts = {})
+    if Psych::VERSION < "4"
+      YAML.load_file(file)
+    else
+      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!
-    configuration.tags.keys.each do
-      YAML.add_tag(_1, TagResolver)
+    configuration.tags.each do |tag_name, tag|
+      YAML.add_tag("!#{tag_name}", tag[:klass])
     end
   end
   private_class_method :add_tags!
+
+  def self.collect_tags(obj)
+    case obj
+    when Hash
+      obj.each_value.flat_map { collect_tags(_1) }.compact
+    when Nero::BaseTag
+      [obj] +
+        case obj.coder.type
+        when :seq
+          collect_tags(obj.coder.seq)
+        when :map
+          collect_tags(obj.coder.map)
+        else
+          []
+        end
+    when Array
+      obj.flat_map { collect_tags(_1) }.compact
+    else
+      []
+    end
+  end
+  private_class_method :collect_tags
 end
 
 loader.eager_load if ENV.key?("CI")

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nero
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gert Goet
 bindir: exe
 cert_chain: []
-date: 2025-02-02 00:00:00.000000000 Z
+date: 2025-03-20 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