unfig 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ff007a57b57a0e32f859b15cbdfb268353a34448499426561c04b4c2f0ca085
+  data.tar.gz: bc50b16f98ab7f74c8cf69fbda12f9af7b975107edc678fb41e383999dbf6b71
+SHA512:
+  metadata.gz: 12c22f5cfc6d564b46d84482bd0272680b41fa1cd461386009afb51833938f98d5305ead5195cd72d9f1f381843d489ef55834270f46d6a74bf6fd6dc29abdbe
+  data.tar.gz: f2230b52d0a0c6f4b08e98f03ee9733a25532b16c705704d38b4618fd95d6d794d1a3a812a7065570435f48e41d9e67c403a2430254136361c931a52a4af9ad6

data/.github/workflows/linters.yml

@@ -0,0 +1,37 @@
+name: Linters
+
+on: [push]
+
+jobs:
+  Linting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.3
+
+      - name: Cache gems
+        uses: actions/cache@v3
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-linters-${{ hashFiles('Gemfile.log') }}
+          restore-keys:
+            ${{ runner.os }}-linters-
+
+      - name: Install gems
+        run: bundle install --jobs 4 --retry 3
+
+      - name: Run StandardRB
+        run: bundle exec standardrb
+
+      - name: Run rubocop (complexity checks)
+        run: bundle exec rubocop --parallel
+
+      - name: Run markdownlint
+        run: bundle exec mdl .
+        
+
+

data/.github/workflows/rspec.yml

@@ -0,0 +1,33 @@
+name: RSpec
+
+on: [push]
+
+jobs:
+  RSpec:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.2', '3.3', '3.4', 'head']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+
+      - name: Cache gems
+        uses: actions/cache@v3
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-rspec-${{ matrix.ruby-version }}-${{ hashFiles('Gemfile.lock') }}
+          restore-keys:
+            ${{ runner.os }}-rspec-${{ matrix.ruby-version }}-
+
+      - name: Install gems
+        run: bundle install --jobs 4 --retry 3
+
+      - name: Run RSpec
+        run: SIMPLECOV=true bundle exec rspec

data/.gitignore

@@ -0,0 +1,7 @@
+.ruby-version
+.ruby-gemset
+Gemfile.lock
+*.gem
+coverage/
+tmp/*
+.DS_Store

data/.mdl_rules.rb

@@ -0,0 +1,2 @@
+all
+rule "MD013", ignore_code_blocks: true

data/.mdlrc

@@ -0,0 +1,2 @@
+style File.expand_path("../.mdl_rules.rb", __FILE__)
+git_recurse true

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+---
+AllCops:
+  SuggestExtensions: false
+  DisabledByDefault: true
+
+Metrics/AbcSize:
+  Max: 15
+Metrics/CyclomaticComplexity:
+  Max: 8
+Metrics/PerceivedComplexity:
+  Max: 7
+
+Metrics/ClassLength:
+  CountComments: false
+  Max: 150
+Metrics/MethodLength:
+  CountComments: false
+  Max: 15
+Metrics/ParameterLists:
+  Max: 5
+  CountKeywordArgs: true

data/.standard.yml

@@ -0,0 +1,3 @@
+---
+format: progress
+ruby_version: 3.2

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://gem.coop"
+
+gemspec

data/README.md

@@ -0,0 +1,100 @@
+# Unfig
+
+We've written code that merges/cascades some combination of defaults, config-files,
+environment-variables, and cli-supplied parameters *too many times*. In one of my
+gems, _half of the code_ is concerned with managing those various ways to supply
+its 20+ control parameters. That's ridiculous.
+
+The intent of `unfig` is to consolidate all of that capability, so that we
+just need to specify what configuration exists (and optionally how it can be
+supplied) in a straightforward way, and stop worrying about it.
+
+## Usage Example (currently tentative)
+
+Let's invoke Unfig like this, as an example:
+
+```ruby
+require "unfig"
+
+@options = Unfig.load_options(
+  config: File.expand_path("~/.mygem.yml"),
+  values: {
+    verbose: {
+      description: "Expose much more information in the logs",
+      type: "boolean",
+      default: false,
+    },
+    parallel: {
+      description: "Run in parallel instead of serially",
+      type: "boolean",
+      default: false,
+    }
+  }
+)
+```
+
+Now I'll have an `@options` object (a Hash, since we didn't specify), and the
+user can supply either of those options on the command-line, in the environment,
+or in a config-file in their home directory.
+
+It's more configurable than that of course. At the top-level, it accepts these
+options:
+
+* `argv` - Usually this is `ARGV` (the default), but if you want to interact
+  with the separately, you could supply `argv: ARGV.dup`, or just an array
+  of arguments.
+* `env` - Usually this is `ENV` (the default), but if you want, you can just
+  pass an arbitrary Hash(String => String) here instead.
+* `config` - where to search for the (yaml) config file that might specify some
+  of these parameters. Optional - if not supplied, no config-file will be used.
+* `banner` - what to say on the command-line when help is invoked (usually a
+  usage example). Optional - if not supplied, no banner is present.
+* `format` - what sort of object comes out of the `load` call; one of
+  `[:hash, :struct, :openstruct]`. If not supplied, defaults to `:hash`.
+* `params` - the parameter configurations; keys are parameter names (symbol or
+  string), and values are parameter configs.
+
+And for each parameter, we have these options:
+
+* `name` - this is the key in the params hash. It can be a String or Symbol,
+  it must start with a letter, and it may contain only letters, numbers, and
+  underscores. No more than 64 characters long.
+* `description` - this will be used as the description of the parameter on the
+  cli - it is required, must be a non-blank string, and may contain no newlines.
+* `type` - this is the type to cast the supplied values into - it is required,
+  and must be one of "boolean", "string", "integer", or "float" (a String).
+* `multi` - this specifies whether the parameter can be "multi-valued" (default
+  is false). If true, supplying the flag more than once, or supplying an array
+  of values in the config file, or (more awkwardly) setting multiple environment
+  variables with numeric suffixes (`FOO_0` through `FOO_9` for an option `foo`)
+  will allow you to supply multiple values, and the parameter will return an
+  Array (whether you actually do so or not).
+* `enabled` - which configuration methods are supported for the parameter. By
+  default all of them will be, but you can for example exclude `verbose` from
+  being supplied via the config file if you want to, or only support the _long_
+  flag (`--verbose` works but not `-v`).
+* `default` - what value should this parameter have if they don't supply one?
+  If you supplied `multi: true`, this is required to be an array of defaults;
+  in either case, the _type_ of the default will be validated against the
+  supplied `type`.
+* `long`/`short` - these can override the default long/short cli flags. This is
+  particularly important for `short`, since two parameters that start with the
+  same letter will automatically collide unless it's supplied for one of them.
+  The default values are (a) the parameter-name, but with underscores mapped to
+  dashes and (b) the first letter of the parameter name.
+* `env` - the name of the environment variable to consult. By default, it's the
+  parameter name up-cased, but like.. if your parameter is `user`, you may need
+  to look at `MYGEM_USER` instead for example (unless you _want_ the unix USER).
+
+The configurations will be loaded from all four sources, in this priority order:
+
+* cli flags - if the user supplies these, they are likely intending to override
+  default or configured behaviors.
+* environment variables - these are a typical way to configure a machine with
+  its intended behavior, though specifying a parameter in a *personal* config
+  file _and_ an environment variable is infrequent, sometimes config files are
+  committed to a repository, and an individual may want to consistently override
+  values supplied in that way.
+* config file - this could be a personal config (in your home directory) or a
+  provided config (committed to your rails app's config/ directory, for example).
+* default value - supplied when invoking Unfig in the script.

data/lib/unfig/argv_loader.rb

@@ -0,0 +1,94 @@
+module Unfig
+  class ArgvLoader
+    def initialize(params:, argv:)
+      @params = params
+      @argv = argv
+      @options = {}
+      @stop_early = false
+    end
+
+    def read
+      return @_read if defined?(@_read)
+      option_parser.parse!(argv)
+      @_read = @stop_early ? nil : @options
+    end
+
+    private
+
+    attr_reader :params, :argv
+
+    def short_enabled?(p) = p.enabled.include?("short")
+
+    def long_enabled?(p) = p.enabled.include?("long")
+
+    def enabled?(p) = short_enabled?(p) || long_enabled?(p)
+
+    def option_parser
+      @_option_parser ||= OptionParser.new do |opts|
+        opts.banner = params.banner if params.banner
+        add_help_option(opts)
+
+        params.params.each do |p|
+          next unless enabled?(p)
+
+          add_option_for(opts, p)
+        end
+      end
+    end
+
+    def short_arg(p)
+      if p.type == "boolean"
+        "-#{p.short}"
+      else
+        "-#{p.short}#{p.name.upcase}"
+      end
+    end
+
+    def long_arg(p)
+      if p.type == "boolean"
+        "--[no-]#{p.long}"
+      else
+        "--#{p.long}=#{p.name.upcase}"
+      end
+    end
+
+    def type_arg(p)
+      case p.type
+      when "string" then String
+      when "boolean" then TrueClass
+      when "integer" then Integer
+      when "float" then Numeric
+      else
+        raise Invalid, "ArgvLoader does not know how to handle type '#{p.type}'"
+      end
+    end
+
+    def option_args(p)
+      args = []
+      args << short_arg(p) if short_enabled?(p)
+      args << long_arg(p) if long_enabled?(p)
+      args << type_arg(p)
+      args << p.description
+    end
+
+    def add_option_for(opts, p)
+      opts.on(*option_args(p)) do |value|
+        if p.multi?
+          @options[p.name] ||= []
+          @options[p.name] << value
+        elsif @options.key?(p.name)
+          raise FlagError, "Cannot supply #{p.name} more than once"
+        else
+          @options[p.name] = value
+        end
+      end
+    end
+
+    def add_help_option(opts)
+      opts.on_tail("-h", "--help", "Print this help information") do
+        warn(opts)
+        @stop_early = true
+      end
+    end
+  end
+end

data/lib/unfig/env_loader.rb

@@ -0,0 +1,25 @@
+module Unfig
+  class EnvLoader
+    def initialize(params:, env:)
+      @params = params
+      @env = env
+    end
+
+    def read
+      return @_read if defined?(@_read)
+
+      @_read = {}
+      params.params.each do |p|
+        next unless p.enabled.include?("env")
+
+        reader = EnvReader.new(param: p, env: env)
+        @_read[p.name] = reader.value if reader.supplied?
+      end
+      @_read
+    end
+
+    private
+
+    attr_reader :params, :env
+  end
+end

data/lib/unfig/env_reader.rb

@@ -0,0 +1,72 @@
+module Unfig
+  class EnvReader
+    TRUTHY_STRINGS = %w[true yes on enable allow t y 1 ok okay].to_set.freeze
+    FALSEY_STRINGS = %w[false no off disabled disable deny f n 0 nope].to_set.freeze
+
+    def initialize(param:, env:)
+      @param = param
+      @env = env
+    end
+
+    def supplied? = multi? ? multi_keys_supplied? : key_supplied?
+
+    def value
+      if multi?
+        supplied? ? multi_values : []
+      else
+        supplied? ? single_value : nil
+      end
+    end
+
+    private
+
+    attr_reader :param, :env
+
+    def multi? = param.multi?
+
+    def multi_keys = @_multi_keys ||= [param.env] + (0..9).map { |n| "#{param.env}_#{n}" }
+
+    def supplied_multi_keys = multi_keys.select { |k| env.key?(k) }
+
+    def multi_keys_supplied?
+      return @_multi_keys_supplied if defined?(@_multi_keys_supplied)
+
+      @_multi_keys_supplied = multi_keys.any? { |key| env.key?(key) }
+    end
+
+    def multi_values = supplied_multi_keys.map { |k| cast_env(k, env.fetch(k)) }
+
+    def single_value = cast_env(param.env, env.fetch(param.env))
+
+    def key_supplied? = env.key?(param.env)
+
+    def cast_env(name, uncast)
+      case param.type
+      when "string" then uncast
+      when "boolean" then cast_to_boolean(name, uncast)
+      when "integer" then cast_to_integer(name, uncast)
+      when "float" then cast_to_float(name, uncast)
+      else
+        raise Invalid, "Unfig::EnvLoader does not know how to handle parameter type '#{param.type}'"
+      end
+    end
+
+    def cast_to_boolean(name, s)
+      return true if TRUTHY_STRINGS.include?(s.strip.downcase)
+      return false if FALSEY_STRINGS.include?(s.strip.downcase)
+      raise InvalidBooleanText, "ENV['#{name}'] had unexpected content for a boolean: '#{s}'"
+    end
+
+    def cast_to_integer(name, s)
+      return s.to_i if /\A-?\d+\z/.match?(s.strip)
+
+      raise InvalidIntegerText, "ENV['#{name}'] had unexpected content for an integer: '#{s}'"
+    end
+
+    def cast_to_float(name, s)
+      return s.to_f if /\A-?\d+(\.\d+)?\z/.match?(s.strip)
+
+      raise InvalidFloatingPointText, "ENV['#{name}'] had unexpected content for a float: '#{s}'"
+    end
+  end
+end

data/lib/unfig/file_loader.rb

@@ -0,0 +1,76 @@
+module Unfig
+  class FileLoader
+    def initialize(params:, path:)
+      @params = params
+      @path = path
+    end
+
+    def read
+      return @_read if defined?(@_read)
+
+      @_read = {}
+      params.params.each do |p|
+        next unless p.enabled.include?("file")
+        @_read[p.name] = read_for(p) if data.key?(p.name)
+      end
+      @_read
+    end
+
+    private
+
+    attr_reader :params, :path
+
+    def text = File.read(path)
+
+    def data = @_data ||= YAML.safe_load(text)
+
+    def read_for(p)
+      data[p.name].tap do |value|
+        p.multi? ? validate_types!(p, value) : validate_type!(p, value)
+      end
+    end
+
+    def validate_type!(p, value)
+      case p.type
+      when "string" then validate_string!(p.name, value)
+      when "boolean" then validate_boolean!(p.name, value)
+      when "integer" then validate_integer!(p.name, value)
+      when "float" then validate_float!(p.name, value)
+      else
+        raise Invalid, "Unfig::FileLoader does not know how to handle the parameter type '#{p.type}'"
+      end
+    end
+
+    def validate_types!(p, value)
+      if value.is_a?(Array)
+        value.each { |v| validate_type!(p, v) }
+      else
+        raise(InvalidYamlValue, "FileLoader expected an array for #{p.name}, because it's multi-valued")
+      end
+    end
+
+    def validate_string!(name, value)
+      return if value.nil? || value.is_a?(String)
+
+      raise InvalidYamlValue, "Unfig::FileLoader expected a string for #{name}, but got #{value.class}"
+    end
+
+    def validate_boolean!(name, value)
+      return if [nil, true, false].include?(value)
+
+      raise InvalidYamlValue, "Unfig::FileLoader expected a boolean for #{name}, but got #{value.class}"
+    end
+
+    def validate_integer!(name, value)
+      return if value.nil? || value.is_a?(Integer)
+
+      raise InvalidYamlValue, "Unfig::FileLoader expected an integer for #{name}, but got #{value.class}"
+    end
+
+    def validate_float!(name, value)
+      return if value.nil? || value.is_a?(Numeric)
+
+      raise InvalidYamlValue, "Unfig::FileLoader expected a float for #{name}, but got #{value.class}"
+    end
+  end
+end

data/lib/unfig/loader.rb

@@ -0,0 +1,68 @@
+module Unfig
+  class Loader
+    def initialize(values:, argv: UNSUPPLIED, env: UNSUPPLIED, config: UNSUPPLIED, **options)
+      @argv = argv
+      @env = env
+      @config = config
+      @values = values
+      @format = options.fetch(:format, :hash)
+      @banner = options.fetch(:banner, nil)
+    end
+
+    def read
+      @_read ||=
+        case format.to_s
+        when "hash" then hashed_values
+        when "struct" then struct_values
+        when "openstruct" then openstruct_values
+        else
+          raise ArgumentError, "Unfig::Loader cannot return results in the format '#{format}'"
+        end
+    end
+
+    private
+
+    attr_reader :config, :values, :format, :banner
+
+    def argv = (@argv == UNSUPPLIED) ? ARGV : @argv
+
+    def env = (@env == UNSUPPLIED) ? ENV.to_h : @env
+
+    def params = @_params ||= ParamsConfig.new(banner:, params: values)
+
+    def loaded_argv
+      return @_loaded_argv if defined?(@_loaded_argv)
+      @_loaded_argv = argv.nil? ? {} : ArgvLoader.new(params:, argv:).read
+    end
+
+    def loaded_env
+      return @_loaded_env if defined?(@_loaded_env)
+      @_loaded_env = env.nil? ? {} : EnvLoader.new(params:, env:).read
+    end
+
+    def loaded_file
+      return @_loaded_file if defined?(@_loaded_file)
+      @_loaded_file = (config == UNSUPPLIED || config.nil?) ? {} : FileLoader.new(params:, path: config).read
+    end
+
+    def defaults = @_defaults ||= params.params.map { |p| [p.name, p.default] }.to_h
+
+    def merged_values = @_merged_values ||= defaults.merge(loaded_file).merge(loaded_env).merge(loaded_argv)
+
+    def hashed_values = merged_values.transform_keys(&:to_sym)
+
+    def struct_values
+      struct_keys = params.params.map(&:name).map(&:to_sym)
+      struct = Struct.new(*struct_keys, keyword_init: true)
+      struct.new(**merged_values)
+    end
+
+    def openstruct_values
+      # Don't require ostruct unless they try to use it (we don't want to make it one of _our_
+      # dependencies, but if they try to use it without making it one of _theirs_, ruby will
+      # inform them)
+      require "ostruct"
+      OpenStruct.new(merged_values)
+    end
+  end
+end

data/lib/unfig/param_config.rb

@@ -0,0 +1,70 @@
+module Unfig
+  # ParamConfig wraps the configuration of an individual param value, and all of
+  # the ways it can be supplied (a long flag, a short flag, a config-file entry,
+  # or an environment variable).
+  #
+  # It enforces the allowed values on each piece of configuration, constructs
+  # defaults for several of them (based on the name), and exposes which of those
+  # methods are _enabled_ for that variable (you can decide that `--verbose` is
+  # not suppliable through the config file for example). Each parameter can also
+  # be designated as `multi?`, meaning that it can be supplied multiple times
+  # (or supplied as an array, in the config-file case), and produces an array of
+  # values in any case.
+  class ParamConfig
+    KNOWN_ENABLED_VALUES = ["long", "short", "env", "file"].to_set.freeze
+
+    def self.load(params_data) = params_data.map { |key, value| new(key, value) }
+
+    def initialize(name, data)
+      @name = name
+      @data = data.transform_keys(&:to_sym)
+      ParamValidator.new(@name, @data).validate!
+    end
+
+    def name = @name.to_s
+
+    def description = data.fetch(:description)
+
+    def type = data.fetch(:type)
+
+    def default = data.fetch(:default)
+
+    def multi? = data.fetch(:multi, false)
+
+    def enabled
+      if data.key?(:enabled)
+        data.fetch(:enabled)
+      else
+        KNOWN_ENABLED_VALUES.to_a.sort
+      end
+    end
+
+    def long
+      if data.key?(:long)
+        data.fetch(:long)
+      else
+        name.tr("_", "-").downcase
+      end
+    end
+
+    def short
+      if data.key?(:short)
+        data.fetch(:short)
+      else
+        name[0]
+      end
+    end
+
+    def env
+      if data.key?(:env)
+        data.fetch(:env, nil)
+      else
+        name.upcase
+      end
+    end
+
+    private
+
+    attr_reader :data
+  end
+end

data/lib/unfig/param_validator.rb

@@ -0,0 +1,157 @@
+module Unfig
+  class ParamValidator
+    MAX_NAME = 64
+    MAX_LONG_FLAG = 64
+    MAX_ENV_LENGTH = 64
+    KNOWN_TYPES = ["boolean", "string", "integer", "float"].to_set.freeze
+    KNOWN_ENABLEMENTS = ParamConfig::KNOWN_ENABLED_VALUES.dup.freeze
+
+    def initialize(name, data)
+      @name = name
+      @data = data
+    end
+
+    def validate!
+      validate_name!
+      validate_description!
+      validate_type!
+      validate_multi!
+      validate_enabled!
+      validate_default!
+      validate_long!
+      validate_short!
+      validate_env!
+    end
+
+    private
+
+    attr_reader :name, :data
+
+    # accessors
+
+    [:description, :type, :multi, :enabled, :default, :long, :short, :env].each do |key|
+      define_method(key) { data[key] }
+    end
+
+    # helpers
+
+    def invalid!(msg) = raise(Invalid, "Param '#{name}': #{msg}")
+
+    def missing?(key) = !data.key?(key)
+
+    def nonstring?(s) = !s.is_a?(String)
+
+    def nonstringlike?(s) = !(s.is_a?(String) || s.is_a?(Symbol))
+
+    def blank?(s) = !/\S/.match?(s)
+
+    def whitespace?(s) = /\s/.match?(s)
+
+    def multi_line?(s) = /\n/.match?(s)
+
+    def alphanumeric?(s) = /\A[a-zA-Z0-9_]+\z/.match?(s)
+
+    def boolean?(v) = [true, false].include?(v)
+
+    def array?(v) = v.is_a?(Array)
+
+    def known_type?(t) = KNOWN_TYPES.include?(t)
+
+    def known_enablement?(e) = KNOWN_ENABLEMENTS.include?(e)
+
+    def unrecognized_enablements = enabled.reject { |e| known_enablement?(e) }.sort
+
+    def types_list = KNOWN_TYPES.to_a.sort.map(&:to_s).join(", ")
+
+    # validators
+
+    def validate_name!
+      invalid!("Name is not a string") if nonstringlike?(name)
+      invalid!("Name may contain only alphanumerics and underscores") unless alphanumeric?(name)
+      invalid!("Name contains more than #{MAX_NAME} characters") if name.length > MAX_NAME
+    end
+
+    def validate_description!
+      invalid!("Description must be supplied") if missing?(:description)
+      invalid!("Description must be supplied as a string") if nonstring?(description)
+      invalid!("Description must not be blank") if blank?(description)
+      invalid!("Description may not include newlines") if multi_line?(description)
+    end
+
+    def validate_type!
+      invalid!("Type was not supplied") if missing?(:type)
+      invalid!("Type must be supplied as a string") if nonstring?(type)
+      invalid!("Type not recognized - expected #{types_list}") unless known_type?(type)
+    end
+
+    def validate_multi!
+      return unless data.key?(:multi)
+
+      invalid!("Multi must be a boolean") unless boolean?(multi)
+    end
+
+    def validate_enabled!
+      return if missing?(:enabled)
+
+      invalid!("Enabled must be an array") unless array?(enabled)
+      invalid!("Enabled must not be empty") if enabled.empty?
+
+      if unrecognized_enablements.any?
+        invalid!("Enabled includes unrecognized values: #{unrecognized_enablements.join(", ")}")
+      end
+    end
+
+    def validate_multi_default!
+      invalid!("Multi-valued, but default is not an Array") unless array?(default)
+
+      if default.any? { |entry| !correct_default_type?(type, entry) }
+        invalid!("Default includes non-#{type} values")
+      end
+    end
+
+    def validate_single_default!
+      return if correct_default_type?(type, default)
+      invalid!("Default is not a #{type}")
+    end
+
+    def validate_default!
+      invalid!("Default not supplied") if missing?(:default)
+      return if default.nil?
+
+      multi ? validate_multi_default! : validate_single_default!
+    end
+
+    def correct_default_type?(type, value)
+      case type
+      when "boolean" then [true, false].include?(value)
+      when "string" then value.is_a?(String)
+      when "integer" then value.is_a?(Integer)
+      when "float" then value.is_a?(Numeric)
+      end
+    end
+
+    def validate_long!
+      return if missing?(:long)
+
+      invalid!("Long flag is not a string") if nonstring?(long)
+      invalid!("Long flag includes whitespace") if whitespace?(long)
+      invalid!("Long flag is over #{MAX_LONG_FLAG} characters") if long.length > MAX_LONG_FLAG
+    end
+
+    def validate_short!
+      return if missing?(:short)
+
+      invalid!("Short flag is not a string") if nonstring?(short)
+      invalid!("Short flag must be a single letter or digit") unless /\A[a-z0-9]\z/i.match?(short)
+    end
+
+    def validate_env!
+      return if missing?(:env)
+
+      invalid!("ENV name is not a string") if nonstring?(env)
+      invalid!("ENV name may only contain alphanumerics and underscores") unless alphanumeric?(env)
+      invalid!("ENV name must begin with a letter") unless /\A[a-z]/i.match?(env)
+      invalid!("ENV name is over #{MAX_ENV_LENGTH} characters") if env.length > MAX_ENV_LENGTH
+    end
+  end
+end

data/lib/unfig/params_config.rb

@@ -0,0 +1,63 @@
+module Unfig
+  # ParamsConfig wraps the configuration of _all_ of the possible parameters,
+  # and enforces uniqueness validations - you can't have two parameters with
+  # the same flag, or the same name; they'll collide in the implementation.
+  class ParamsConfig
+    def initialize(data)
+      raise(Invalid, "Params-config must be a Hash") unless data.is_a?(Hash)
+      raise(Invalid, "Params-config must supply some params (as a Hash)") unless data[:params].is_a?(Hash)
+      @data = data
+    end
+
+    def params
+      return @_params if defined?(@_params)
+      validate!
+      @_params = built
+    end
+
+    def banner = data[:banner]
+
+    private
+
+    attr_reader :data
+
+    def built = @_built ||= data[:params].map { |k, v| ParamConfig.new(k, v) }
+
+    def validate!
+      validate_no_duplicate_names!
+      validate_no_duplicate_long_flags!
+      validate_no_duplicate_short_flags!
+      validate_no_duplicate_envs!
+    end
+
+    def repeats(items) = items.tally.select { |_k, v| v > 1 }.keys.sort
+
+    def validate_no_duplicate_names!
+      dups = repeats(built.map(&:name))
+      return if dups.none?
+
+      raise Invalid, "Duplicate parameter names: #{dups.join(", ")}"
+    end
+
+    def validate_no_duplicate_long_flags!
+      dups = repeats(built.map(&:long))
+      return if dups.none?
+
+      raise Invalid, "Duplicate long-flags: #{dups.join(", ")}"
+    end
+
+    def validate_no_duplicate_short_flags!
+      dups = repeats(built.map(&:short))
+      return if dups.none?
+
+      raise Invalid, "Duplicate short-flags: #{dups.join(", ")}"
+    end
+
+    def validate_no_duplicate_envs!
+      dups = repeats(built.map(&:env))
+      return if dups.none?
+
+      raise Invalid, "Duplicate env-names: #{dups.join(", ")}"
+    end
+  end
+end

data/lib/unfig/version.rb

@@ -0,0 +1,3 @@
+module Unfig
+  VERSION = "0.1.0"
+end

data/lib/unfig.rb

@@ -0,0 +1,29 @@
+require "yaml"
+require "optparse"
+
+module Unfig
+  UNSUPPLIED = Object.new.freeze
+
+  Error = Class.new(StandardError)
+  Invalid = Class.new(Error)
+
+  InvalidEnv = Class.new(Error)
+  InvalidBooleanText = Class.new(InvalidEnv)
+  InvalidIntegerText = Class.new(InvalidEnv)
+  InvalidFloatingPointText = Class.new(InvalidEnv)
+
+  InvalidYamlValue = Class.new(Error)
+  FlagError = Class.new(Error)
+
+  def self.load_options(**) = Loader.new(**).read
+end
+
+require_relative "unfig/version"
+require_relative "unfig/param_config"
+require_relative "unfig/param_validator"
+require_relative "unfig/params_config"
+require_relative "unfig/env_reader"
+require_relative "unfig/env_loader"
+require_relative "unfig/file_loader"
+require_relative "unfig/argv_loader"
+require_relative "unfig/loader"

data/unfig.gemspec

@@ -0,0 +1,45 @@
+require_relative "lib/unfig/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "unfig"
+  spec.version = Unfig::VERSION
+  spec.authors = ["Eric Mueller"]
+  spec.email = ["nevinera@gmail.com"]
+
+  spec.summary = "Build CLIs that are configured via args, file, and/or environment"
+  spec.description = <<~DESC
+    We've written code that merges/cascades default configuration, config-files,
+    environment variables, and cli-passed arguments _too many times_. This gem
+    intends to distill that into a configuration config-file describing those
+    controls and relationships.
+  DESC
+  spec.homepage = "https://github.com/nevinera/unfig"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.require_paths = ["lib"]
+  spec.bindir = "bin"
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`
+      .split("\x0")
+      .reject { |f| f.start_with?("spec") }
+  end
+  spec.executables = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z bin/`
+      .split("\x0")
+      .map { |path| path.sub(/^bin\//, "") }
+  end
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rspec-its", "~> 1.3"
+  spec.add_development_dependency "rspec-collection_matchers", "~> 1.2.1"
+  spec.add_development_dependency "simplecov", "~> 0.22.0"
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "standard", ">= 1.35.1"
+  spec.add_development_dependency "rubocop", ">= 1.62"
+  spec.add_development_dependency "mdl", "~> 0.12"
+  spec.add_development_dependency "ostruct"
+end

metadata

@@ -0,0 +1,196 @@
+--- !ruby/object:Gem::Specification
+name: unfig
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eric Mueller
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rspec-collection_matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.35.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.35.1
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.62'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.62'
+- !ruby/object:Gem::Dependency
+  name: mdl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  We've written code that merges/cascades default configuration, config-files,
+  environment variables, and cli-passed arguments _too many times_. This gem
+  intends to distill that into a configuration config-file describing those
+  controls and relationships.
+email:
+- nevinera@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/linters.yml"
+- ".github/workflows/rspec.yml"
+- ".gitignore"
+- ".mdl_rules.rb"
+- ".mdlrc"
+- ".rspec"
+- ".rubocop.yml"
+- ".standard.yml"
+- Gemfile
+- README.md
+- lib/unfig.rb
+- lib/unfig/argv_loader.rb
+- lib/unfig/env_loader.rb
+- lib/unfig/env_reader.rb
+- lib/unfig/file_loader.rb
+- lib/unfig/loader.rb
+- lib/unfig/param_config.rb
+- lib/unfig/param_validator.rb
+- lib/unfig/params_config.rb
+- lib/unfig/version.rb
+- unfig.gemspec
+homepage: https://github.com/nevinera/unfig
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nevinera/unfig
+  source_code_uri: https://github.com/nevinera/unfig
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Build CLIs that are configured via args, file, and/or environment
+test_files: []