nero 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e28a4b8bcd989c20dd60dc592bfb31039314437b3d8ca5df33b79adefd5cb2e
-  data.tar.gz: f6eb0ec1e9ceb041088a7d2b850494e090f08d98f4e8369f82f0608a4449ab69
+  metadata.gz: 136899b1a5b7fd355608891703ad0e8b0c628dfcb3ae74d9a5344fb0a78b41b8
+  data.tar.gz: 47fce2793b077af0a637d7cac6a5e31b471c16bbbff71561f97bdf4aa904a3d5
 SHA512:
-  metadata.gz: 98dc2c475e0e164f47d1738dbe32d6dfeeba6b531f6db0b396a25d3e29219c312ac0750206fddea1d9ee450e9205425a5f0342c6b5b13d38867a364e1219bed0
-  data.tar.gz: e9daf1ee287679b10d4ea744c41d3f93bf50570394eb261f7c8b3587a1008efe57b58b7957141aeea48229b65efdaa614f23c181fbf08659a0a878a7a944e773
+  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,29 @@
 ## [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  

data/README.md

@@ -47,6 +47,21 @@ 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]  
@@ -73,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}
 
@@ -81,7 +96,7 @@ 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)
 
@@ -89,15 +104,18 @@ Nero.load_config("config/settings", root: :production)
 #=> {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):
+> 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 = Rails.root / "config"
+  config.config_dir = "config"
 end
 
-Nero.load_config(:settings, env: Rails.env)
+Nero.config_for(:settings, env: Rails.env)
 ```
 
+[API Documentation](https://eval.github.io/nero/).
+
 ### built-in tags
 
 The following tags are provided:
@@ -199,9 +217,11 @@ $ env NERO_ENV_ALL_OPTIONAL=1 SECRET_KEY_BASE_DUMMY=1 rails asset:precompile
 
 ### custom tags
 
-Three ways to do this:
+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 block  
+1. **a proc**
     ```ruby
     Nero.configure do |nero|
       nero.add_tag("upcase") do |tag|
@@ -225,15 +245,16 @@ Three ways to do this:
           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:
+        # 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 comes as a seq:
-        # a: !my/inc [!my/square 2]
+        # ...but when chaining, it needs to be a seq:
+        # a: !my/inc [ !my/square 2 ]
       end
     end
     ```
-1. re-use existing tag-class  
+    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
@@ -244,7 +265,7 @@ Three ways to do this:
       nero.add_tag("path/project_root", klass: Nero::PathRootTag[containing: '.git'])
     end
     ```
-1. custom class  
+1. **custom class**  
    ```ruby
    class RotTag < Nero::BaseTag
      # Configure:

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

data/lib/nero.rb

@@ -2,6 +2,7 @@
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
+loader.do_not_eager_load("#{__dir__}/nero/railtie.rb")
 loader.setup
 
 require "uri"
@@ -14,40 +15,93 @@ require "pathname"
 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))
-    end
-
-    def resolve_nested!(coder, ctx = {})
+    def resolve_nested!(coder)
       case coder.type
       when :seq
-        coder.seq.map!(&gen_resolve_tryer(ctx))
+        coder.seq.map!(&method(:try_resolve))
       when :map
-        coder.map = deep_resolve(coder.map, **ctx)
+        coder.map = deep_resolve(coder.map)
       end
     end
   end
   extend Resolvable
   private_class_method \
     :deep_resolve,
-    :gen_resolve_tryer,
     :try_resolve
 
   class Configuration
-    attr_reader :tags, :config_dir
+    attr_reader :config_dir
+
+    def tags
+      @tags ||= {}
+    end
 
     def config_dir=(dir)
       @config_dir = Pathname(dir).expand_path
@@ -56,7 +110,7 @@ module Nero
     def add_tag(name, klass: BaseTag, &block)
       klass, klass_options = klass
 
-      (@tags ||= {})[name] = {klass:}.tap do |h|
+      tags[name] = {klass:}.tap do |h|
         h[:block] = block if block
         h[:options] = klass_options if klass_options
       end
@@ -67,20 +121,85 @@ 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
 
+  # 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
 
     attr_reader :coder, :options, :ctx
 
+    # Convenience method simplifying {Nero::Configuration#add_tag}:
+    #
+    # ```ruby
+    #   config.add_tag("foo", klass: SomeTag[some_option: 1])
+    # ```
     def self.[](**options)
       [self, options]
     end
 
-    # used by YAML
+    # @private used by YAML
     def init_with(coder)
       @coder = coder
     end
@@ -104,7 +223,7 @@ module Nero
 
     def args
       @args ||= begin
-        resolve_nested!(coder, {})
+        resolve_nested!(coder)
         case coder.type
         when :map then Util.deep_symbolize_keys(coder.map)
         else
@@ -135,23 +254,28 @@ module Nero
   # 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:
-  # "--- env/upcase [MSG, Hello World]" => "HELLO WORLD"
-  # "--- env/upcase MSG" => raises when not ENV.has_key? "MSG"
-  # "--- env/upcase? MSG" => nil
+  # ```ruby
+  # "--- env/upcase [MSG, Hello World]" #=> "HELLO WORLD"
+  # "--- env/upcase MSG" #=> raises when not ENV.has_key? "MSG"
+  # "--- env/upcase? MSG" #=> nil
+  # ```
   #
-  # Args supported:
-  # - scalar
+  # YAML-args supported:
+  # - scalar —
   #  name of env-var, e.g. `!env HOME`
-  # - seq
+  # - 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.
+  # - `coerce` —
+  #  symbol or proc to be applied to value of env-var.
+  #  when using coerce, the block is ignored.
   #
   class EnvTag < BaseTag
     def resolve(**)
@@ -251,7 +375,7 @@ module Nero
         # 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), **{})
+        deep_resolve(tag.ctx[:yaml].dig(*path))
       end
 
       config.add_tag("env", klass: EnvTag)
@@ -296,22 +420,84 @@ 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.yaml_options
+  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
+
+  # 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
+
+  # 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
+
+  # @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!
 
@@ -327,20 +513,12 @@ module Nero
   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, resolve: true)
-    root ||= env
-    add_tags!
-
-    process_yaml(yaml_load(raw, yaml_options), root:, resolve:)
-  end
-
   def self.process_yaml(yaml, root: nil, resolve: true, config_file: nil)
     config_file ||= (Pathname.pwd / __FILE__)
 
@@ -352,8 +530,7 @@ module Nero
 
     return unresolved unless resolve
 
-    # NOTE originally ctx was passed at this point. Maybe delete this.
-    deep_resolve(unresolved, **{})
+    Config.for(deep_resolve(unresolved))
   end
   private_class_method :process_yaml
 
@@ -383,13 +560,6 @@ module Nero
   end
   private_class_method :yaml_load
 
-  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.collect_tags(obj)
     case obj
     when Hash
@@ -413,4 +583,6 @@ module Nero
   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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gert Goet
 bindir: exe
 cert_chain: []
-date: 2025-03-20 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: