nero 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6da9456128ceb0fd0eda54c862c013035f17306b8bb08d39ce56dd79407711a2
-  data.tar.gz: 3640f4c3c54ff2ebee72698906287a5284a5194a40e30e1e6309d1f48b18d517
+  metadata.gz: aefcd9c69dd9c20501632b97f8738fa7bbe95115f694c086c89b20da5b55359a
+  data.tar.gz: 63c7d94edc645ad1bf4912f7f7ef4256aec15b6ee063ffc568ab322c2a8299c0
 SHA512:
-  metadata.gz: d811147b8d78530b57babe751d7b9d95626d0ba691fbbe9baf4acc53dbb515a13520799b60ab5244ebec3bc373c7acd6b0969b821847e97edfe54d6eddc3fa2d
-  data.tar.gz: fc47ca669383bc056b6a6788fba0cc7079ef790371227f2054e3a2b9a0033c3ee4b5ee63efb7666a9fb92487426765435ea3e672069744951d7afe194da4b7fc
+  metadata.gz: 9911e7bf5881fe44a2524adc67e875ff1b44318306cd00661a52d698fe12e87ac0d4bfaf91e41ad0122d531ffa7f1426ce86a1d81e72e36baac9088f093d185e
+  data.tar.gz: c25d5bf01e86ace03358cd1a829e784cc4479910601cb69ba9eebe5c8e71c176ebb17f53e319a6e710d575c14f6dc862af156e46d86cfd58b6591d1e6b0f6116

data/README.md

@@ -1,51 +1,148 @@
-# Nero
+# 🔥 Nero 
 
-Have some convenient tags in YAML config files:
+[![Gem Version](https://badge.fury.io/rb/nero.svg)](https://badge.fury.io/rb/nero)
 
-```yaml
-development:
-  # required value from ENV
-  github_token: !env GH_TOKEN
+Nero is a RubyGem that offers predefined tags and allows you to effortlessly create custom ones for YAML configuration files.
 
-  # optional
-  sentry_dsn: !env? SENTRY_DSN
+E.g. instead of having the following settings file in your Ruby/Rails project:
 
-  # env-value coerced to integer with default value
-  port: !env/integer [PORT, 3000]
+```yaml
+development:
+  # env-var with a fallback
+  secret: <%= ENV.fetch("SECRET", "dummy") %>
+  # NOTE *any* value provided is taken as `true`
+  debug?: <%= !!ENV["DEBUG"] %>
+production:
+  # NOTE we can't fail-fast on ENV-var absence (i.e. use `ENV.fetch`),
+  # as it would require the env-var for development as well
+  secret: <%= ENV["SECRET"] %>
+  max_threads: <%= ENV.fetch("MAX_THREADS", 5).to_i %>
+```
 
-  # combining tags
-  assets_folder: !path
-    - !env PROJECT_ROOT
-    - public/upload/assets
+...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
+  secret: !env SECRET
+  # always an integer
+  max_threads: !env/integer [MAX_THREADS, 5]
+```
 
-  option: !env/integer? PORT
+## Installation
 
-  # Allows for: config[:log].debug?
-  log: !str/inquirer
-    - !env LOG_LEVEL
+Install the gem and add to the application's Gemfile by executing:
 
-  payment_url: !uri
-    - https://
-    - !env STRIP_HOST
-    - /payment/setup
+```bash
+bundle add nero
+```
 
-  url: !str/format
-    - https://%s%s
-    - !env HOST
-    - /login
+## Usage
 
-  debug: !env/bool [DEBUG, false]
+> [!WARNING]  
+> It's early days - the API and included tags will certainly change. Check the CHANGELOG when upgrading.
 
+Given the following config:
+```yaml
+# config/settings.yml
+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:
-  # this won't raise an error when absent when selecting
-  # :development as
+  # fail-fast on absence of SECRET
   secret: !env SECRET
+  # always an integer
+  max_threads: !env/integer [MAX_THREADS, 5]
 ```
 
-Add one yourself:
+Loading this config:
+
+```ruby
+# Loading development
+Nero.load_config(Pathname.pwd / "config/settings.yml", root: :development)
+# ...and no ENV-vars were provided
+#=> {secret: "dummy", debug?: false}
+
+# ...with ENV {"debug" => "true"}
+#=> {secret: "dummy", debug?: true}
+
+# Loading production
+Nero.load_config(Pathname.pwd / "config/settings.yml", 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}
+```
+
+The following tags are provided:
+- `!env KEY`, `!env? KEY`  
+  Resp. to fetch or get a value from `ENV`:
+  ```yaml
+  ---
+  # required
+  secret: !env SECRET
+  # optional, with fallback:
+  secret: !env [SECRET, "dummy-fallback"]
+  # ...or nil
+  secret: !env? SECRET
+  ```
+- to coerce env-values:
+  - `env/integer`, `env/integer?`:  
+    ```yaml
+    port: !env/integer [PORT, 3000]
+    threads: !env/integer? THREADS # nil when not provided
+    ```
+  - `env/bool`, `env/bool?`:  
+    ```yaml
+    # required (valid values 'y(es)'/'n(o)', 'true'/'false', 'on'/'off')
+    over18: !env/bool OVER18
+    # optional, with fallback:
+    secure: !env/bool [SECURE, true]
+    # ...or false:
+    debug?: !env/bool? DEBUG
+    ```
+- `!path`  
+  Create a [Pathname](https://rubyapi.org/3.4/o/pathname):
+  ```yaml
+  config: !path config
+  # combining tags:
+  asset_folder: !path
+    - !env PROJECT_ROOT
+    - /public/assets
+  ```
+- `!uri`  
+  Create a [URI](https://rubyapi.org/3.4/o/uri):
+  ```yaml
+  smtp_url: !uri
+    - smtps://
+    - !env SMTP_CREDS
+    - @smtp.gmail.com
+  ```
+- `!str/format`  
+  Using Ruby's [format specifications](https://docs.ruby-lang.org/en/master/format_specifications_rdoc.html):
+  ```yaml
+  smtp_url: !str/format
+    - smtps://%s:%s@smtp.gmail.com
+    - !env SMTP_USER
+    - !env SMTP_PASS
+  # using references
+  smtp_url: !str/format
+    fmt: smtps://%<user>s:%<pass>s@smtp.gmail.com
+    user: !env SMTP_USER
+    pass: !env SMTP_PASS
+  ```
+
+TBD Add one yourself:
 ```ruby
 Nero.configure do
-  add_resolver("foo") do |coder|
+  add_tag("foo") do |coder|
     # coder.type is one of :scalar, :seq or :map
     # e.g. respective YAML:
     # ---
@@ -63,32 +160,6 @@ Nero.configure do
 end
 ```
 
-
-
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/nero`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-## Installation
-
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
-
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
-```
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
-```
-
-## Usage
-
-TODO: Write usage instructions here
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/nero/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Nero
-  VERSION = "0.1.0"
+  # NOTE this is written upon release via:
+  # $ rake gem:build[version=0.3.0]
+  VERSION = "0.2.1"
 end

data/lib/nero.rb

@@ -8,6 +8,7 @@ require "uri" # why needed?
 
 # TODO fail on unknown tag
 # TODO show missing env's at once
+# TODO raise when missing arg(s) for tag
 module Nero
   class Error < StandardError; end
 
@@ -57,8 +58,15 @@ module Nero
     (@resolvers ||= {})["!#{name}"] = block
   end
 
+  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)
+  end
+  private_class_method :env_fetch
+
   add_resolver("env/integer") do |coder|
-    Integer(ENV.fetch(*(coder.scalar || coder.seq)))
+    Integer(env_fetch(*(coder.scalar || coder.seq), all_optional: "999"))
   end
 
   add_resolver("env/integer?") do |coder|
@@ -79,7 +87,7 @@ module Nero
       end
     end
 
-    coerce[ENV.fetch(*(coder.scalar || coder.seq))]
+    coerce[env_fetch(*(coder.scalar || coder.seq), all_optional: "false")]
   end
 
   add_resolver("env/bool?") do |coder|
@@ -100,7 +108,7 @@ module Nero
   end
 
   add_resolver("env") do |coder|
-    ENV.fetch(*(coder.scalar || coder.seq))
+    env_fetch(*(coder.scalar || coder.seq))
   end
 
   add_resolver("env?") do |coder|
@@ -135,7 +143,7 @@ module Nero
     if file.exist?
       unresolved = Util.deep_symbolize_keys(YAML.load_file(file,
         permitted_classes: [Symbol, TagResolver], aliases: true)).then do
-        root ? _1[root] : _1
+        root ? _1[root.to_sym] : _1
       end
 
       deep_resolve(unresolved, resolvers: @resolvers)

data/rakelib/gem.rake

@@ -0,0 +1,25 @@
+namespace :gem do
+  task "write_version", [:version] do |_task, args|
+    if args[:version]
+      version = args[:version].split("=").last
+      version_file = File.expand_path("../../lib/nero/version.rb", __FILE__)
+
+      system(<<~CMD, exception: true)
+        ruby -pi -e 'gsub(/VERSION = ".*"/, %{VERSION = "#{version}"})' #{version_file}
+      CMD
+      Bundler.ui.confirm "Version #{version} written to #{version_file}."
+    else
+      Bundler.ui.warn "No version provided, keeping version.rb as is."
+    end
+  end
+
+  desc "Build [version]"
+  task "build", [:version] => %w[write_version] do
+    Rake::Task["build"].invoke
+  end
+
+  desc "Build and push [version] to rubygems"
+  task "release", [:version] => %w[build] do
+    Rake::Task["release:rubygem_push"].invoke
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nero
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Gert Goet
 bindir: exe
 cert_chain: []
-date: 2025-01-27 00:00:00.000000000 Z
+date: 2025-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -46,6 +46,7 @@ files:
 - lib/nero.rb
 - lib/nero/util.rb
 - lib/nero/version.rb
+- rakelib/gem.rake
 - sig/nero.rbs
 homepage: https://github.com/eval/nero
 licenses:
@@ -68,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Convenience YAML-tags
 test_files: []