nero 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9822fcc078e4b2c0e9f049da7cf6f37a98a5b9cf607434057f266a393154296e
-  data.tar.gz: b71a5be94f469b564e3a80c80a0545246afbc053f619201f8a0c6c0923a776a4
+  metadata.gz: 136899b1a5b7fd355608891703ad0e8b0c628dfcb3ae74d9a5344fb0a78b41b8
+  data.tar.gz: 47fce2793b077af0a637d7cac6a5e31b471c16bbbff71561f97bdf4aa904a3d5
 SHA512:
-  metadata.gz: 863f2c0fbeb21286a0d0f51219e07351a93489688eb7c49be5c1c720a3e414d8e43129e2c0e4d23c6e44213e8547a03c28df128210026414e9e3e209bb7ef472
-  data.tar.gz: c431e49a4d5d422b554a891973c0e24b7c1810dd922492d56b39ca6157dc70e3110114d7474d0d2ed3b5076f2bea63d8493b2cd9db64c3354ea051022f8887cb
+  metadata.gz: 979f099766b6c33577346e608fa8e82f890d4d3ef5b49913a142cdbcb7385ecff78776882e5ee78420f0b285388972aef8e6c4c980d4aff120b8c142efec2212
+  data.tar.gz: e43d9f3916bfc43b3abe49939b3953a72679fec64e8de4de5b682600d6d5ef2f66f97557e262a5558046c9e332532bc908a4317d4a114bc46754d9ff60d3242c

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--title 'Nero Documentation'
+--charset utf-8
+--markup markdown
+--no-private
+'lib/**/*.rb' - '*.md'

data/CHANGELOG.md

@@ -1,6 +1,65 @@
 ## [Unreleased]
 ...
 
+## [0.6.0] - 2025-04-10
+
+### deprecations
+
+- `Nero.load_config` - use `Nero.load_file` or `Nero.config_for`.
+
+### other
+
+- API docs live at https://eval.github.io/nero/
+- Config for Rails  
+  The `config.config_dir` is automatically setup, so `Nero.config_for` (formerly `Nero.load_config`) just works.
+- `Nero::Config.dig!` ⛏️💥  
+  Any (Hash-)result from `Nero.load/load_file/config_for` is now an instance of `Nero::Config`.  
+  This class contains `dig!`, a fail-hard variant of `dig`:
+  ```ruby
+  Nero.load(<<~Y).dig!(:smtp_settings, :hose) # 💥 typo
+    smtp_settings:
+      host: 127.0.0.1
+      port: 1025
+  Y
+  #=> 'Nero::DigExt#dig!': path not found [:smtp_settings, :hose] (ArgumentError)
+  ```
+
+## [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:

data/README.md

@@ -11,14 +11,24 @@ Additionally, it allows you to create your own.
 development:
   # env-var with default value
   secret: !env [SECRET, "dummy"]
+
   # optional env-var with coercion
   debug?: !env/bool? DEBUG
+
 production:
-  # required env-var (only when getting the production-root)
+  # required env-var (not required during development)
   secret: !env SECRET
-  # int coercion
+
+  # coercion
   max_threads: !env/integer [MAX_THREADS, 5]
-  # something custom
+
+  # 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]
 ```
 
@@ -26,7 +36,7 @@ production:
 
 * 💎 declarative YAML-tags for e.g. requiring and coercing env-vars
 * 🛠️ add custom tags
-* 🛤️ `Rails.application.config_for` stand-in
+* 🛤️ `Rails.application.config_for` drop-in
 * ♻️ Zeitwerk-only dependency
 
 ## Installation
@@ -37,11 +47,28 @@ Install the gem and add to the application's Gemfile by executing:
 bundle add nero
 ```
 
+## Configuration
+
+```ruby
+Nero.configure do |nero|
+  # Path that `Nero.config_for` uses to resolve Symbol or String files, e.g. `Nero.config_for(:app)`
+  nero.config_dir = "config"
+
+  # Add custom tags (also see section about custom tags)
+  nero.add_tag("upcase") do |tag|
+    # tag is an instance of [Nero::BaseTag](https://eval.github.io/nero/Nero/BaseTag.html).
+    tag.args.join.upcase
+  end
+end
+```
+
 ## Usage
 
 > [!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
@@ -61,7 +88,7 @@ Loading this config:
 
 ```ruby
 # Loading development
-Nero.load_config("config/settings", root: :development)
+Nero.load_file("config/settings", root: :development)
 # ...and no ENV-vars were provided
 #=> {secret: "dummy", debug?: false}
 
@@ -69,13 +96,27 @@ Nero.load_config("config/settings", root: :development)
 #=> {secret: "dummy", debug?: true}
 
 # Loading production
-Nero.load_config("config/settings", root: :production)
+Nero.load_file("config/settings", root: :production)
 # ...and no ENV-vars were provided
 # raises error: key not found: "SECRET" (KeyError)
 
 # ...with ENV {"SECRET" => "s3cr3t", "MAX_THREADS" => "3"}
 #=> {secret: "s3cr3t", max_threads: 3}
 ```
+> [!TIP]  
+> You can also use `Nero.config_for` (similar to [Rails.application.config_for](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-config_for)).  
+> In Rails applications this gets configured for you. For other application you might need to adjust the `config_dir`:
+```ruby
+Nero.configure do |config|
+  config.config_dir = "config"
+end
+
+Nero.config_for(:settings, env: Rails.env)
+```
+
+[API Documentation](https://eval.github.io/nero/).
+
+### built-in tags
 
 The following tags are provided:
 - `!env KEY`, `!env? KEY`  
@@ -90,10 +131,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 +146,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 +160,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
@@ -139,7 +195,7 @@ The following tags are provided:
   Include values from elsewhere:
   ```yaml
   # simple
-  min_threads: !env [MIN_THREADS, !ref [max_threads]]
+  min_threads: !env/integer [MIN_THREADS, !ref [max_threads]]
   max_threads: 5
   
   # oauth_callback -refs-> base.url -refs-> base.host
@@ -158,39 +214,96 @@ The following tags are provided:
     max_threads: !env[MAX_THREADS, !ref[dev, max_threads]]
   ```
   NOTE future version should raise properly over ref-ing a non-existing path.
-  
 
-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
-
-    # 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
+### custom tags
 
-  # 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
-```
+There's three ways to create your own tags.
+
+For all these methods it's helpful to see the API-docs for [Nero::BaseTag](https://eval.github.io/nero/Nero/BaseTag.html).
+
+1. **a proc**
+    ```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 a tag might just need one argument (ie scalar),
+        # it's helpful to accept a seq as it allows for chaining:
+        # a: !my/inc 4 # scalar suffices
+        # ...but when chaining, it needs to be a seq:
+        # a: !my/inc [ !my/square 2 ]
+      end
+    end
+    ```
+    Blocks are passed instances of [Nero::BaseTag](https://eval.github.io/nero/Nero/BaseTag.html).
+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/lib/nero/railtie.rb

@@ -0,0 +1,10 @@
+module Nero
+  # @private
+  class Railtie < ::Rails::Railtie
+    config.before_configuration do
+      Nero.configure do |nero|
+        nero.config_dir = Rails.application.paths["config"].existent.first
+      end
+    end
+  end
+end

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.4.0"
+  VERSION = "0.6.0"
 end

data/lib/nero.rb

@@ -2,10 +2,12 @@
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
+loader.do_not_eager_load("#{__dir__}/nero/railtie.rb")
 loader.setup
 
-require "uri" # why needed?
+require "uri"
 require "yaml"
+require "pathname"
 
 # TODO fail on unknown tag
 # TODO show missing env's at once
@@ -13,57 +15,105 @@ require "yaml"
 module Nero
   class Error < StandardError; end
 
+  module DigExt
+    # ⛏️💥 Like `dig`, but raises `ArgumentError` when `path` does not exist.
+    # @example like dig
+    #   {a: {b: 2}}.dig!(:a, :b) #=> 2
+    #   {a: {b: 2}}.dig!(:a, :c) #=> ArgumentError, path not found [:a, :c] (ArgumentError)
+    # @raise [ArgumentError] when `path` does not exist.
+    # @overload dig!(*path)
+    #   @param path nested keys into config
+    def dig!(k0, *k)
+      k.unshift(k0)
+
+      unless paths.include?(k)
+        raise ArgumentError, "path not found #{k}"
+      end
+      dig(*k)
+    end
+
+    private
+
+    def paths
+      @paths ||= gather_paths(self).to_set
+    end
+
+    def gather_paths(item, acc: [], path: [])
+      acc += [path]
+
+      case item
+      when NilClass
+        []
+      when Hash
+        item.flat_map { |(k, v)| gather_paths(v, acc: acc, path: path + [k]) }
+      when Array
+        item.each_with_index.flat_map do |item, ix|
+          gather_paths(item, acc: acc, path: path + [ix])
+        end
+      else
+        acc
+      end
+    end
+  end
+
+  class Config < Hash
+    include DigExt
+
+    def self.for(v)
+      case v
+      when self then v
+      when Hash then self.[](v)
+      else
+        v
+      end
+    end
+  end
+
   module Resolvable
-    def try_resolve(ctx, object)
+    def try_resolve(object)
       if object.respond_to?(:resolve)
-        object.resolve(ctx)
+        object.resolve
       else
         object
       end
     end
 
-    def gen_resolve_tryer(ctx)
-      method(:try_resolve).curry.call(ctx)
+    def deep_resolve(object)
+      Util.deep_transform_values(object, &method(:try_resolve))
     end
 
-    def deep_resolve(object, **ctx)
-      Util.deep_transform_values(object, &gen_resolve_tryer(ctx))
+    def resolve_nested!(coder)
+      case coder.type
+      when :seq
+        coder.seq.map!(&method(:try_resolve))
+      when :map
+        coder.map = deep_resolve(coder.map)
+      end
     end
   end
   extend Resolvable
   private_class_method \
     :deep_resolve,
-    :gen_resolve_tryer,
     :try_resolve
 
-  class TagResolver
-    include Resolvable
-
-    def init_with(coder)
-      @coder = coder
-    end
+  class Configuration
+    attr_reader :config_dir
 
-    def resolve(ctx)
-      resolve_nested!(ctx)
-      ctx[:tags][@coder.tag].call(@coder, ctx)
+    def tags
+      @tags ||= {}
     end
 
-    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)
-      end
+    def config_dir=(dir)
+      @config_dir = Pathname(dir).expand_path
     end
-  end
 
-  class Configuration
-    attr_reader :tags
-    attr_accessor :config_dir
+    def add_tag(name, klass: BaseTag, &block)
+      klass, klass_options = klass
 
-    def add_tag(name, &block)
-      (@tags ||= {})["!#{name}"] = block
+      tags[name] = {klass:}.tap do |h|
+        h[:block] = block if block
+        h[:options] = klass_options if klass_options
+      end
     end
   end
 
@@ -71,96 +121,295 @@ module Nero
     @configuration ||= Configuration.new
   end
 
+  def self.add_tags!
+    configuration.tags.each do |tag_name, tag|
+      YAML.add_tag("!#{tag_name}", tag[:klass])
+    end
+  end
+  private_class_method :add_tags!
+
   def self.configure
     yield configuration if block_given?
+  ensure
+    add_tags!
   end
 
-  # helpers for configuration
-  # module TagHelpers
-  #  def to_boolean(s)
-  #  end
+  # Superclass for all tags.
+  #
+  # Writing your own tag-class would look something like this:
+  #
+  # Wanted usage in YAML:
+  # ```ruby
+  # Nero.load(<<~YAML)
+  #   secret: !rot/12 "some message"
+  #   other_secret: !rot/13 [ !env [SECRET, some message] ]
+  # YAML
+  # ```
+  #
+  # Required config:
+  # ```ruby
+  # config.add_tag("rot/12", klass: RotTag[n: 12])
+  # config.add_tag("rot/13", klass: RotTag[n: 13]) do |secret|
+  #   "#{secret} (try breaking this!)"
+  # end
+  # ```
+  # The class then would look like this:
+  # ```ruby
+  # class RotTag < Nero::BaseTag
+  #   attr_reader :n
+  #
+  #   # Overriding this method...:
+  #   # - restricts options
+  #   #   ie `RotTag[x: 1]` would raise.
+  #   # - sets default values
+  #   # - makes options available via getters
+  #   #   (otherwise available via `options[:n]`).
+  #   def init_options(n: 10)
+  #     super
+  #     @n = n
+  #   end
+  #
+  #   # This is where the magic happens.
+  #   # (Accepting any keyword arguments keeps the method fw-compatible).
+  #   def resolve(**)
+  #     # `args` are the resolved arguments (Array or Hash).
+  #     # `config` the config of the tag (containing e.g. the proc).
+  #     block = config.fetch(:block, :itself.to_proc)
+  #     args.join.tr(chars.join, chars.rotate(n).join).then(&block)
+  #   end
+  #
+  #   # Just some helper method with all characters that can be rotated.
+  #   def chars
+  #     %w(a b c) # etc
+  #   end
   # end
+  # ```
+  #
+  class BaseTag
+    include Resolvable
 
-  def self.add_default_tags!
-    # extend TagHelpers
+    attr_reader :coder, :options, :ctx
 
-    configure do |config|
-      config.add_tag("ref") do |coder, ctx|
-        # validate: non-empty coder.seq, only strs, path must exists in ctx[:config]
+    # Convenience method simplifying {Nero::Configuration#add_tag}:
+    #
+    # ```ruby
+    #   config.add_tag("foo", klass: SomeTag[some_option: 1])
+    # ```
+    def self.[](**options)
+      [self, options]
+    end
+
+    # @private used by YAML
+    def init_with(coder)
+      @coder = coder
+    end
 
-        path = coder.seq.map(&:to_sym)
-        deep_resolve(ctx[:config].dig(*path), **ctx)
+    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
+
+    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
 
-      config.add_tag("env/integer") do |coder|
-        Integer(env_fetch(*(coder.scalar || coder.seq), all_optional: "999"))
+  # Requires an env-var to be available and coerces the value.
+  # When tag-name ends with "?", the env-var is optional.
+  #
+  # Given config:
+  # ```ruby
+  # config.add_tag("env/upcase", klass: Nero::EnvTag[coerce: :upcase])
+  # config.add_tag("env/upcase?", klass: Nero::EnvTag[coerce: :upcase])
+  # ```
+  #
+  # Then YAML => result:
+  # ```ruby
+  # "--- env/upcase [MSG, Hello World]" #=> "HELLO WORLD"
+  # "--- env/upcase MSG" #=> raises when not ENV.has_key? "MSG"
+  # "--- env/upcase? MSG" #=> nil
+  # ```
+  #
+  # YAML-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 ignored.
+  #
+  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
+
+    def coercer
+      return unless @coerce
 
-      config.add_tag("env/integer?") do |coder|
-        Integer(ENV[coder.scalar]) if ENV[coder.scalar]
+      @coercer ||= case @coerce
+      when Symbol then @coerce.to_proc
+      else
+        @coerce
       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 init_options(coerce: nil)
+      @coerce = coerce
+    end
+
+    def optional
+      tag_name.end_with?("?") || !!ENV["NERO_ENV_ALL_OPTIONAL"]
+    end
+    alias_method :optional?, :optional
 
-        coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "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/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 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/
 
-        ENV[coder.scalar] ? coerce[ENV[coder.scalar]] : false
+      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
+
+    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]
 
-      config.add_tag("env") do |coder|
-        env_fetch(*(coder.scalar || coder.seq))
+        path = tag.args.map(&:to_sym)
+        deep_resolve(tag.ctx[:yaml].dig(*path))
       end
 
-      config.add_tag("env?") do |coder|
-        fetch_args = coder.scalar ? [coder.scalar, nil] : coder.seq
-        ENV.fetch(*fetch_args)
+      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("path") do |coder|
-        Pathname.new(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("uri") do |coder|
-        URI(coder.scalar || coder.seq.join)
+      config.add_tag("uri") do |tag|
+        URI.join(*tag.args.join)
       end
 
-      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("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
@@ -171,64 +420,128 @@ module Nero
     @configuration = nil
 
     configure do |config|
-      config.config_dir = Pathname.pwd
+      config.config_dir = Pathname.new("config").expand_path
     end
 
     add_default_tags!
+    add_tags!
   end
   reset_configuration!
 
-  def self.env_fetch(k, fallback = nil, all_optional: "dummy")
-    fallback ||= all_optional if ENV["NERO_ENV_ALL_OPTIONAL"]
+  def self.default_yaml_options
+    {
+      permitted_classes: [Symbol] + configuration.tags.values.map { _1[:klass] },
+      aliases: true
+    }
+  end
+  private_class_method :default_yaml_options
+
+  def self.yaml_options(yaml_options)
+    epc = yaml_options.delete(:extra_permitted_classes)
+    default_yaml_options.merge(yaml_options).tap do
+      _1[:permitted_classes].push(*epc)
+    end
+  end
+  private_class_method :yaml_options
+
+  # Like `YAML.load` with extra options.
+  #
+  # @param [Symbol, String] root return the value of this root key.
+  # @param [Boolean] resolve (for debug purposes) not resolving would leave the Nero-tags as-is.
+  # @param [Array<ClassName>] extra_permitted_classes classes that are added
+  #   to the default permitted_classes and passed to `YAML.load`.
+  # @param [Hash] yaml_options options passed to `YAML.load`.
+  # @return [Nero::Config (when the data is a Hash)]
+  # @example
+  #   Nero.load(<<~YAML, extra_permitted_classes: [Time])
+  #     home: !env HOME,
+  #     created_at: 2010-02-11 11:02:57
+  #     project_root: !path/git_root
+  #   YAML
+  #   #=> {
+  #   #    home: "/Users/gert",
+  #   #    created_at: 2010-02-11 12:02:57 +0100,
+  #   #    project_root: #<Pathname:/Users/gert/projects/nero>
+  #   #  }
+  def self.load(yaml, root: nil, resolve: true, **yaml_options)
+    process_yaml(yaml_load(yaml, yaml_options(yaml_options)), root:, resolve:)
+  end
 
-    fallback.nil? ? ENV.fetch(k) : ENV.fetch(k, fallback)
+  # Like `YAML.load_file`. See {load} for options.
+  # @return [Nero::Config (when the YAML-data is a Hash)]
+  def self.load_file(file, root: nil, resolve: true, **yaml_options)
+    config_file = (file.is_a?(Pathname) ? file : Pathname.new(file)).expand_path
+    process_yaml(yaml_load_file(config_file, yaml_options(yaml_options)), root:, config_file:, resolve:)
   end
-  private_class_method :env_fetch
 
-  @yaml_options = {
-    permitted_classes: [Symbol, TagResolver],
-    aliases: true
-  }
+  # Convenience wrapper for {load_file} that works like `Rails.application.config_for`.
+  # @see https://api.rubyonrails.org/classes/Rails/Application.html#method-i-config_for Rails' config_for documentation
+  #
+  # The file-argument is expanded like so `(configuration.config_dir / "#{file}.yml").expand_path`.
+  #
+  # @param [Symbol, String, Pathname] file `Symbol` or `String` are expanded as shown above. A `Pathname` is used as-is.
+  # @param [Symbol, String] env return the value of this root key.
+  # @param [Symbol, String] root return the value of this root key.
+  # @param [Boolean] resolve (for debug purposes) not resolving would leave the Nero-tags as-is.
+  # @param [Array<ClassName>] extra_permitted_classes classes that are added
+  #   to the default permitted_classes and passed to `YAML.load`.
+  # @param [Hash] yaml_options options passed to `YAML.load_file`.
+  # @return [Nero::Config (when the data is a Hash)]
+  # @example
+  #   Nero.config_for(:app, env: Rails.env) #=> {...}
+  def self.config_for(file, root: nil, env: nil, **yaml_options)
+    root ||= env
+
+    load_file(resolve_file(file), root:, **yaml_options)
+  end
 
-  def self.load_config(file, root: nil, env: nil)
+  # @deprecated Use `load_file` or `config_for` instead.
+  def self.load_config(file, root: nil, env: nil, resolve: true)
+    warn "[DEPRECATION] `load_config` is deprecated. Use `load_file` or `config_for` instead."
     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
 
   def self.resolve_file(file)
     case file
     when Pathname then file
-    # TODO expand full path
     else
-      configuration.config_dir / "#{file}.yml"
+      (configuration.config_dir / "#{file}.yml").expand_path
     end
   end
   private_class_method :resolve_file
 
-  def self.load(raw, root: nil, env: nil)
-    root ||= env
-    add_tags!
-
-    process_yaml(yaml_load(raw, @yaml_options), root:)
-  end
+  def self.process_yaml(yaml, root: nil, resolve: true, config_file: nil)
+    config_file ||= (Pathname.pwd / __FILE__)
 
-  def self.process_yaml(yaml, root: nil)
     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, config: unresolved)
+    return unresolved unless resolve
+
+    Config.for(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)
@@ -247,12 +560,29 @@ module Nero
   end
   private_class_method :yaml_load
 
-  def self.add_tags!
-    configuration.tags.keys.each do
-      YAML.add_tag(_1, TagResolver)
+  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 :add_tags!
+  private_class_method :collect_tags
 end
 
+require "nero/railtie" if defined?(Rails::Railtie)
+
 loader.eager_load if ENV.key?("CI")

data/rakelib/yard.rake

@@ -0,0 +1,12 @@
+require "yard"
+
+YARD::Rake::YardocTask.new(:docs) do |t|
+  # Options defined in `.yardopts` are read first, then merged with
+  # options defined here.
+  #
+  # It's recommended to define options in `.yardopts` instead of here,
+  # as `.yardopts` can be read by external YARD tools, like the
+  # hot-reload YARD server `yard server --reload`.
+
+  # t.options += ['--title', "Something custom"]
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nero
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gert Goet
 bindir: exe
 cert_chain: []
-date: 2025-02-15 00:00:00.000000000 Z
+date: 2025-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -53,6 +53,7 @@ files:
 - ".envrc"
 - ".rspec"
 - ".standard.yml"
+- ".yardopts"
 - Appraisals
 - CHANGELOG.md
 - LICENSE.txt
@@ -61,9 +62,11 @@ files:
 - gemfiles/psych_3.gemfile
 - gemfiles/psych_4.gemfile
 - lib/nero.rb
+- lib/nero/railtie.rb
 - lib/nero/util.rb
 - lib/nero/version.rb
 - rakelib/gem.rake
+- rakelib/yard.rake
 - sig/nero.rbs
 homepage: https://github.com/eval/nero
 licenses: