kanon 0.1.0

data/lib/kanon/node.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Kanon
+  class Node
+    def self.build(value)
+      case value
+      when Hash then new(value.each_with_object({}) { |(key, nested), result| result[key_for(key)] = build(nested) })
+      when Array then value.map { |nested| build(nested) }.freeze
+      else value
+      end
+    end
+
+    def self.key_for(key)
+      key.respond_to?(:to_sym) ? key.to_sym : key
+    end
+    private_class_method :key_for
+
+    def initialize(values)
+      @values = values.freeze
+      reject_reserved_keys
+      freeze
+    end
+
+    def [](key)
+      @values.fetch(lookup_key(key)) { raise UnknownKey, "no key #{key} here, keys: #{keys.join(', ')}" }
+    end
+
+    def key?(key)
+      @values.key?(lookup_key(key))
+    end
+
+    def keys
+      @values.keys
+    end
+
+    def dig(*path)
+      path.inject(self) do |level, key|
+        case level
+        when Node then level[key]
+        when Array then dig_into_array(level, key)
+        else raise UnknownKey, "no key #{key} inside a #{level.class}"
+        end
+      end
+    end
+
+    def to_h
+      @values.each_with_object({}) { |(key, value), result| result[key] = self.class.unwrap(value) }
+    end
+
+    def self.unwrap(value)
+      case value
+      when Node then value.to_h
+      when Array then value.map { |nested| unwrap(nested) }
+      else value
+      end
+    end
+
+    def ==(other)
+      other.is_a?(Node) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      "#<Kanon::Node keys: #{keys.join(', ')}>"
+    end
+
+    def as_json(*)
+      inspect
+    end
+
+    def to_json(*)
+      require 'json'
+      JSON.generate(as_json)
+    end
+
+    def encode_with(coder)
+      coder.represent_scalar(nil, inspect)
+    end
+
+    def instance_variables
+      []
+    end
+
+    def marshal_dump
+      raise TypeError, "#{inspect} refuses serialization that would expose its values"
+    end
+
+    private
+
+    def method_missing(name, *arguments)
+      return @values[name] if arguments.empty? && @values.key?(name)
+
+      raise NoMethodError, "undefined method `#{name}' for #{inspect}"
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @values.key?(name.to_sym) || super
+    end
+
+    def dig_into_array(array, key)
+      raise UnknownKey, "no index #{key} in an Array of #{array.size}" unless key.is_a?(Integer)
+
+      array.fetch(key) { raise UnknownKey, "no index #{key} in an Array of #{array.size}" }
+    end
+
+    def lookup_key(key)
+      key.respond_to?(:to_sym) ? key.to_sym : key
+    end
+
+    def reject_reserved_keys
+      reserved = keys.select { |key| key.is_a?(Symbol) && self.class.method_defined?(key) }
+      return if reserved.empty?
+
+      raise ReservedKey, "#{reserved.join(', ')} clash with node methods and cannot be config keys"
+    end
+  end
+end

data/lib/kanon/typecast.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Kanon
+  module Typecast
+    TRUE_VALUES = %w[1 true yes on].freeze
+    FALSE_VALUES = %w[0 false no off].freeze
+    TYPE_NAMES = %w[string integer float boolean list].freeze
+
+    private_constant :TRUE_VALUES, :FALSE_VALUES
+
+    module_function
+
+    def like_sample(raw_value, sample, source)
+      case sample
+      when true, false then boolean(raw_value, source)
+      when Integer then integer(raw_value, source)
+      when Float then float(raw_value, source)
+      when Array then list(raw_value)
+      else raw_value
+      end
+    end
+
+    def by_type_name(raw_value, type_name, source)
+      reject_unknown_type(type_name, source)
+
+      case type_name.to_s
+      when 'string' then raw_value.to_s
+      when 'integer' then integer(raw_value, source)
+      when 'float' then float(raw_value, source)
+      when 'boolean' then boolean(raw_value, source)
+      when 'list' then list(raw_value)
+      end
+    end
+
+    def reject_unknown_type(type_name, source)
+      return if TYPE_NAMES.include?(type_name.to_s)
+
+      raise InvalidValue, "#{source} declares unknown type #{type_name.inspect}"
+    end
+
+    def boolean(raw_value, source)
+      return true if TRUE_VALUES.include?(raw_value.to_s.downcase)
+      return false if FALSE_VALUES.include?(raw_value.to_s.downcase)
+
+      raise InvalidValue,
+            "#{source} must be one of #{(TRUE_VALUES + FALSE_VALUES).join(', ')}, got #{describe(raw_value)}"
+    end
+
+    # A list that leaves no items counts as no value, so a mandatory one fails
+    # rather than arriving empty.
+    def list(raw_value)
+      return raw_value if raw_value.is_a?(Array)
+
+      items = raw_value.to_s.split(',').map(&:strip).reject(&:empty?)
+      items.empty? ? nil : items
+    end
+
+    def describe(raw_value)
+      "#{raw_value.class} of #{raw_value.to_s.length} characters"
+    end
+
+    # The base is explicit: without it a leading zero would be read as octal, and
+    # port 010 would turn into 8.
+    def integer(raw_value, source)
+      raw_value.is_a?(Integer) ? raw_value : Integer(raw_value.to_s, 10)
+    rescue ArgumentError, TypeError
+      raise InvalidValue, "#{source} must be an integer, got #{describe(raw_value)}", cause: nil
+    end
+
+    def float(raw_value, source)
+      Float(raw_value)
+    rescue ArgumentError, TypeError
+      raise InvalidValue, "#{source} must be a number, got #{describe(raw_value)}", cause: nil
+    end
+  end
+end

data/lib/kanon/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kanon
+  VERSION = '0.1.0'
+end

data/lib/kanon.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'monitor'
+require 'yaml'
+require 'erb'
+require_relative 'kanon/version'
+require_relative 'kanon/errors'
+require_relative 'kanon/document'
+require_relative 'kanon/node'
+require_relative 'kanon/typecast'
+require_relative 'kanon/env_declarations'
+
+module Kanon
+  DEFAULT_DIRECTORY = 'config'
+  DEFAULT_ENVIRONMENT = 'development'
+  ENVIRONMENT_VARIABLES = %w[APP_ENV RAILS_ENV RACK_ENV].freeze
+
+  @monitor = Monitor.new
+  @storage = {}
+
+  class << self
+    def directory
+      @monitor.synchronize { @directory ||= DEFAULT_DIRECTORY }
+    end
+
+    def directory=(path)
+      raise EmptyDirectory, 'configuration directory cannot be empty' if blank?(path)
+
+      @monitor.synchronize do
+        @directory = path.to_s.strip
+        clear
+      end
+    end
+
+    def environment
+      @monitor.synchronize { @environment ||= given_environment || DEFAULT_ENVIRONMENT }
+    end
+
+    def environment=(name)
+      raise EmptyEnvironment, 'environment name cannot be empty' if blank?(name)
+
+      @monitor.synchronize do
+        @environment = name.to_s.strip
+        clear
+      end
+    end
+
+    def read_config(file_name)
+      data = build(file_name.to_s.to_sym)
+      data = { file_name.to_s.to_sym => data } unless data.is_a?(Hash)
+
+      Kanon::Node.build(data)
+    end
+
+    def [](file_name)
+      load_config(file_name)
+    end
+
+    def load_config(file_name)
+      name = file_name.to_s.to_sym
+
+      @monitor.synchronize { @storage[name] ||= read_config(name) }
+    end
+
+    def load_configs(*file_names)
+      file_names.to_h { |file_name| [file_name.to_s.to_sym, load_config(file_name)] }
+    end
+
+    def loaded_files
+      @monitor.synchronize { @storage.keys }
+    end
+
+    def expected_variables(file_name)
+      declarations, schema = prepare(file_name.to_s.to_sym)
+
+      declarations.expected(schema)
+    end
+
+    private
+
+    def clear
+      @monitor.synchronize { @storage.clear }
+    end
+
+    def given_environment
+      ENVIRONMENT_VARIABLES.map { |name| ENV.fetch(name, nil) }.find { |value| !blank?(value) }&.strip
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def build(file_name)
+      declarations, schema = prepare(file_name)
+
+      deep_freeze(declarations.resolve(schema))
+    end
+
+    def prepare(file_name)
+      prefix, schema = Kanon::Document.new(directory, file_name, environment).schema
+
+      [Kanon::EnvDeclarations.new(file_name, prefix), schema]
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |nested| deep_freeze(nested) }.freeze
+      when Array then value.each { |nested| deep_freeze(nested) }.freeze
+      else value.freeze
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: kanon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maksimenko Pavel
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-15 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A YAML file becomes a frozen tree of nodes with dotted access, and the values
+  that belong to the environment are declared in that same file. A read that
+  misses a mandatory value fails naming every absent variable at once, and a
+  typo in a key raises instead of returning nil. ERB tags keep working, so a
+  file that already reads the environment that way needs no rewriting. The
+  standard library only, with the config directory and the environment name
+  injected from outside.
+email:
+- pavel.g.maksimenko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/decisions.md
+- docs/specification.md
+- kanon.gemspec
+- lib/kanon.rb
+- lib/kanon/document.rb
+- lib/kanon/env_declarations.rb
+- lib/kanon/errors.rb
+- lib/kanon/node.rb
+- lib/kanon/typecast.rb
+- lib/kanon/version.rb
+homepage: https://github.com/MaksimenkoPG/kanon
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MaksimenkoPG/kanon
+  source_code_uri: https://github.com/MaksimenkoPG/kanon
+  changelog_uri: https://github.com/MaksimenkoPG/kanon/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A YAML config becomes a frozen tree of nodes, and declares the environment
+  variables it needs
+test_files: []