nero 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aefcd9c69dd9c20501632b97f8738fa7bbe95115f694c086c89b20da5b55359a
-  data.tar.gz: 63c7d94edc645ad1bf4912f7f7ef4256aec15b6ee063ffc568ab322c2a8299c0
+  metadata.gz: 3da331b2512fc63cf1a9258991a33dda876e8b0aed2445bca34ed207f8cfc1fb
+  data.tar.gz: 79c6afff69d21841b247de206f7b3f6482bf74496ad91c4986528fd0620e6551
 SHA512:
-  metadata.gz: 9911e7bf5881fe44a2524adc67e875ff1b44318306cd00661a52d698fe12e87ac0d4bfaf91e41ad0122d531ffa7f1426ce86a1d81e72e36baac9088f093d185e
-  data.tar.gz: c25d5bf01e86ace03358cd1a829e784cc4479910601cb69ba9eebe5c8e71c176ebb17f53e319a6e710d575c14f6dc862af156e46d86cfd58b6591d1e6b0f6116
+  metadata.gz: e80cb4098d709df1231e7ee1cfc077be097517709ffabee489cdce8bc9da30aac7e6f89157823c147e691042945c9da806f337f1ca64ab90dc376d390f46d0b9
+  data.tar.gz: 7637f0ae5983c3902a04092c2d1cf3ed9aacb0ae036f73d7c1067f7677a8c175ffe4c4826c972cb129c47cfe37517115e0bd51f81c1f6b4f132a8946b4311a3e

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 ## [Unreleased]
 
+## [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
 
 - Initial release

data/README.md

@@ -4,32 +4,28 @@
 
 Nero is a RubyGem that offers predefined tags and allows you to effortlessly create custom ones for YAML configuration files.
 
-E.g. instead of having the following settings file in your Ruby/Rails project:
+E.g. instead of having the following settings file in your Rails project:
 
 ```yaml
 development:
-  # env-var with a fallback
   secret: <%= ENV.fetch("SECRET", "dummy") %>
-  # NOTE *any* value provided is taken as `true`
-  debug?: <%= !!ENV["DEBUG"] %>
+  # custom logic how to get a boolean...
+  debug?: <%= ENV["DEBUG"] == "true" %>
 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
+  # 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 a fallback
   secret: !env [SECRET, "dummy"]
-  # Though the default is false, explicitly providing "false"/"off"/"n"/"no" is also possible.
   debug?: !env/bool? DEBUG
 production:
-  # fail-fast on absence of SECRET
+  # required _only_ when loading production
   secret: !env SECRET
-  # always an integer
   max_threads: !env/integer [MAX_THREADS, 5]
 ```
 
@@ -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)
 
@@ -139,10 +135,10 @@ The following tags are provided:
     pass: !env SMTP_PASS
   ```
 
-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:
     # ---
@@ -157,6 +153,12 @@ Nero.configure do
     # 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
 ```
 

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.1"
+  VERSION = "0.3.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)
     end
 
     def resolve_nested!(ctx)
@@ -54,106 +58,162 @@ 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/
+  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
 
-    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/integer?") do |coder|
+        Integer(ENV[coder.scalar]) if ENV[coder.scalar]
       end
-    end
 
-    coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "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
+
+        coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "false")]
+      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/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
 
-    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") do |coder|
+        env_fetch(*(coder.scalar || coder.seq))
       end
-    end
 
-    ENV[coder.scalar] ? coerce[ENV[coder.scalar]] : false
-  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
 
-  add_resolver("env?") do |coder|
-    fetch_args = coder.scalar ? [coder.scalar, nil] : coder.seq
-    ENV.fetch(*fetch_args)
+    configure do |config|
+      config.config_dir = Pathname.pwd
+    end
+
+    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
+
+  @yaml_options = {
+    permitted_classes: [Symbol, TagResolver],
+    aliases: true
+  }
+
+  def self.load_config(file, root: nil)
+    add_tags!
+
+    file = resolve_file(file)
 
-  add_resolver("uri") do |coder|
-    URI(coder.scalar || coder.seq.join)
+    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)
     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
 
-      deep_resolve(unresolved, resolvers: @resolvers)
-    else
-      raise "Can't find file #{file}"
+  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, tags: configuration.tags)
   end
+  private_class_method :process_yaml
 
   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.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Gert Goet
 bindir: exe
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk