fat_config 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6a9ee861c75317e6c334ccb6639eda669b794a3f7a6e33543e91cf9193d5fd1
+  data.tar.gz: 760c48576a7d7d2376a3524fc9301f0593261a9e6a9ebd75f431683e9e56b9bf
+SHA512:
+  metadata.gz: a111ad1acbdda7c5070910a1b78c3c9ab389b4ce45012a97642071d6fa7db21550b7806388b31827db0fbdda62ee16373550f0282daf20d68bfe5180ca9405a9
+  data.tar.gz: 64ee672822816a6ff7776537817ad2bdaa73c7b446ab86c50954ba38ee408f676006957734996a5ec454ade4c5ebdedd00fd274befb30bf2457751f5397226d9

data/.rspec

@@ -0,0 +1,3 @@
+--require 'spec_helper'
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,20 @@
+inherit_from: ./rubocop-global.yml
+
+require:
+  - rubocop-rspec
+  - rubocop-rake
+  - rubocop-obsession
+
+AllCops:
+  TargetRubyVersion: 3.3
+  Include:
+    - 'lib/**/*'
+    - 'bin/**/*'
+    - 'spec/**/*'
+#    - 'features/**/*'
+  Exclude:
+    - 'spec/tmp/**/*'
+    - 'spec/.examples.txt'
+    - 'bin/setup'
+    - '.simplecov'
+    - 'features/**/*'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Daniel E. Doherty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.org

@@ -0,0 +1,315 @@
+# FatConfig
+
+~FatConfig~ eliminates the tedium of reading configuration files and the
+environment to populate a Hash of configuration settings.  You need only
+define a ~FatConfig::Reader~ and you can call its ~#read~ method to look for,
+read, translate, and merge any config files into a single Hash that
+encapsulates all the files in the proper priority.  It can be set to read
+~YAML~, ~TOML~, ~JSON~, or ~INI~ config files.
+
+* Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+#+begin_src sh
+  bundle add fat_config
+#+end_src
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+#+begin_src sh
+  gem install fat_config
+#+end_src
+
+* Usage:
+
+#+begin_src ruby
+  require 'fat_config'
+
+  reader = FatConfig::Reader.new('myapp')
+  config = reader.read
+#+end_src
+
+The ~reader.read~ method will parse the config files (by default assumed to be
+YAML files), config environment variable, and optional command-line parameters
+and return the composite config as a Hash.
+
+** Following XDG Standards
+By default, ~FatConfig::Reader#read~ follows the [[https://specifications.freedesktop.org/basedir-spec/latest/][XDG Desktop Standards]],
+reading configuration settings for a hypothetical application called ~myapp~
+from the following locations, from lowest priority to highest:
+
+1. If the environment variable ~MYAPP_SYS_CONFIG~ is set to the name of a
+   file, it will look in that file for any system-level config file.
+2. If the environment variable ~MYAPP_SYS_CONFIG~ is NOT set, it will read any
+   system-level config file from ~/etc/xdg/myapp~ or, if the ~XDG_CONFIG_DIRS~
+   environment variable is set to a list of colon-separated directories, it
+   will look in each of those instead of ~/etc/xdg~ for config directories
+   called ~myapp~.  If more than one ~XDG_CONFIG_DIRS~ is given, they are
+   treated as listed in order of precedence, so the first-listed directory
+   will be given priority over later ones.  All such directories will be read,
+   and any config file found will be merged into the resulting Hash, but they
+   will be visited in reverse order so that the first-named directories
+   override the earlier ones.
+3. If the environment variable ~MYAPP_CONFIG~ is set to a file name, it will
+   look in that file any user-level config file.
+4. If the environment variable ~MYAPP_CONFIG~ is NOT set, it will read any
+   user-level config file from ~$HOME/.config/myapp~ or, if the
+   ~XDG_CONFIG_HOME~ environment variable is set to an alternative directory,
+   it will look ~XDG_CONFIG_HOME/.config~ for a config directory called
+   'myapp'.  Note that in this case, ~XDG_CONFIG_HOME~ is intended to contain
+   the name of a single directory, not a list of directories as with the
+   system-level config files.
+5. It will then merge in any options set in the environment variable
+   ~MYAPP_OPTIONS~, overriding any conflicting settings gotten from reading
+   the system- and user-level file.  It will interpret the String from the
+   environment variable as discussed below in [[*Parsing Environment and Command Line Strings][Parsing Environment and Command
+   Line Strings]].
+6. Finally, it will merge in any options given in the optional ~command_line:~
+   named parameter to the ~#read~ method.  That parameter can either be a
+   ~Hash~ or a ~String~.  If it is a ~String~, it is interpreted the same way
+   as the environment variable ~MYAPP_OPTIONS~ as explained below in [[*Parsing Environment and Command Line Strings][Parsing
+   Environment and Command Line Strings]]; if it is a ~Hash~, it is used
+   directly and merged into the hash returned from the prior methods.
+
+** Following Classic UNIX Standards
+With the optional ~:xdg~ keyword parameter to ~FatConfig::Reader#read~ set to
+~false~, it will follow "classic" UNIX config file conventions.  There is no
+"standard" here, but there are some conventions, and the closest thing I can
+find to describe the conventions is this from the [[https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s08.html#homeReferences][UNIX File Hierarchy Standard]]
+website:
+
+#+begin_quote
+ User specific configuration files for applications are stored in the user's
+ home directory in a file that starts with the '.' character (a "dot
+ file"). If an application needs to create more than one dot file then they
+ should be placed in a subdirectory with a name starting with a '.' character,
+ (a "dot directory"). In this case the configuration files should not start
+ with the '.' character.
+#+end_quote
+
+~FatConfig~'s implementation of this suggestion are as follows for a
+hypothetical application called ~myapp~:
+
+1. If the environment variable ~MYAPP_SYS_CONFIG~ is set to a file name, it
+   will look in that file for any system-level config file.
+2. If the environment variable ~MYAPP_SYS_CONFIG~ is NOT set, then either
+   - if the file ~/etc/my_app~ exists and is readable, it is considered the
+     system-wide config file for ~my_app~, or
+   - if the file ~/etc/my_apprc~ exists and is readable, it is considered the
+     system-wide config file for ~my_app~, or
+   - if the /directory/ ~/etc/my_app~ exists, the first file named ~config~,
+     ~config.yml~, ~config.yaml~ (this assumes the default YAML style, the
+     extensions looked for will be adjusted for other styles) ,
+     ~myapp.config~, or ~myapp.cfg~ that is readable will be considered the
+     system-wide config file for ~my_app~
+3. If the environment variable ~MYAPP_CONFIG~ is set to a file name, it will
+   look in that file for any user-level config file.
+4. If the environment variable ~MYAPP_CONFIG~ is NOT set, then either,
+   - if the file, =~/.my_app= or =~/.my_apprc~= exist and are readable, that
+     file is used as the user-level config file,
+   - otherwise, if the directory =~/.my_app/= exists, the first file in that
+     directory named ~config~, ~config.yml~, ~config.yaml~, ~myapp.config~, or
+     ~myapp.cfg~ that is readable will be considered the user-level config
+     file for ~my_app~
+5. It will then merge in any options set in the environment variable
+   ~MYAPP_OPTIONS~, overriding any conflicting settings gotten from reading
+   the system- and user-level file.  It will interpret the environment setting
+   as explained below in [[*Parsing Environment and Command Line Strings][Parsing Environment and Command Line Strings]].
+6. Finally, it will merge in any options given in the optional ~command_line:~
+   named parameter to the ~#read~ method.  That parameter can either be a
+   ~Hash~ or a ~String~.  If it is a ~String~, it will interpret the string as
+   explained below in [[*Parsing Environment and Command Line Strings][Parsing Environment and Command Line Strings]]; if it is a
+   ~Hash~, it is used directly and merged into the hash returned from the
+   prior methods.
+
+** Available Config File Styles
+~FatConfig::Reader.new~ takes the optional keyword argument, ~:style~, to
+indicate what style to use for config files.  It can be one of:
+
+- ~yaml~ :: See [[https://yaml.org/spec/1.2.2/][YAML Specs]],
+- ~toml~ :: See [[https://toml.io/en/][TOML Specs]],
+- ~json~ :: See [[https://datatracker.ietf.org/doc/html/rfc8259][JSON Specs]], or
+- ~ini~ :: See [[https://en.wikipedia.org/wiki/INI_file][INI File on Wikipedia]]
+
+By default, the style is ~yaml~.  Note that the style only pertains to the
+syntax of on-disk configuration files.  Configuration can also be set by an
+environment variable, ~MYAPP_OPTIONS~ and by a command-line string optionally
+provided to the ~#read~ method.  Those are simple parsers that parse strings
+of option settings as explained below.  See, [[*Parsing Environment and Command Line Strings][Parsing Environment and Command
+Line Strings]].
+
+** Hash Keys
+The returned Hash will have symbols as keys, using the names given in the
+config files, except that they will have any hyphens converted to the
+underscore.  Thus the config setting "page-width: 6.5in" in a config file will
+result in a Hash entry of ~{ page_width: '6.5in' }~.
+
+** Hash Values
+Whether the values of the returned Hash will be 'deserialized' into a Ruby
+object is controlled by the style of the configuration files.  For example,
+the ~:yaml~ style deserializes the following types:
+
+*** YAML
+
+  - TrueClass (the string 'true' of whatever case)
+  - FalseClass (the string 'false' of whatever case)
+  - NilClass (when no value given)
+  - Integer (when it looks like an whole number)
+  - Float (when it looks like an decimal number)
+  - String (if not one of the other classes or if enclosed in single- or double-quotes)
+  - Array (when sub-elements introduced with '-', each typed by these rules)
+  - Hash, (when sub-elements introduced with 'key:', each typed by these rules) and,
+  - Date, DateTime, and Time, which FatConfig adds to the foregoing default
+    types deserialized by the default YAML library.
+
+*** TOML
+
+  - TrueClass (exactly the string 'true')
+  - FalseClass (exactly the string 'false')
+  - Integer (when it looks like an whole number or 0x... or 0o... hex or octal)
+  - Float (when it looks like an decimal number)
+  - String (only if enclosed in single- or double-quotes)
+  - Array (when sub-elements enclosed in [...], each typed by these rules)
+  - Hash, ([hash-key] followed by sub-elements, each typed by these rules) and,
+  - Date and Time, when given in ISO form YYYY-MM-DD or YYYY-MM-DDThh:mm:ss
+
+*** JSON
+
+  - TrueClass (exactly the string 'true')
+  - FalseClass (exactly the string 'false')
+  - Integer (when it looks like an decimal whole number, but NO provision hex
+    or octal)
+  - Float (when it looks like an decimal number)
+  - String (only if enclosed in single- or double-quotes)
+  - Array (when sub-elements enclosed in [...], each typed by these rules)
+  - Hash, (when sub-elements enclosed in {...}, each typed by these rules) and,
+  - Date and Time, NOT deserialized, returns a parse error
+
+*** INI
+
+  - TrueClass (exactly the string 'true')
+  - FalseClass (exactly the string 'false')
+  - Integer (when it looks like an whole number or 0x... or 0o... hex or octal)
+  - Float (when it looks like an decimal number)
+  - String (anything else)
+  - Array NOT deserialized, returned as a String
+  - Hash, NOT deserialized, returned as a String
+  - Date and Time, NOT deserialized, returned as a String
+
+** Creating a Reader
+When creating a ~Reader~, the ~#new~ method takes a mandatory argument that
+specifies the name of the application for which configuration files are to be
+sought.  It also takes a few optional keyword arguments:
+
+- ~style:~ specify a style for the config files other than YAML, the choices
+  are ~yaml~, ~toml~, ~json~, and ~ini~.  This can be given either as a String
+  or Symbol in upper or lower case.
+- ~xdg:~ either ~true~, to follow the XDG standard for where to find config
+  files, or ~false~, to follow classic UNIX conventions.
+- ~root_prefix:~, to locate the root of the file system somewhere other than
+  ~/~.  This is probably only useful in testing ~FatConfig~.
+
+#+begin_src ruby
+  require 'fat_config'
+
+  reader1 = FatConfig.new('labrat')  # Use XDG and YAML
+  reader2 = FatConfig.new('labrat', style: 'toml')  # Use XDG and TOML
+  reader3 = FatConfig.new('labrat', style: 'ini', xdg: false)  # Use classic UNIX and INI style
+#+end_src
+
+** Calling the ~#read~ method on a ~Reader~
+Once a ~Reader~ is created, you can get the completely merged configuration as
+a Hash by calling ~Reader#read~.  The ~read~ method can take several
+parameter:
+
+- ~alternative base~ :: as the first positional parameter, you can give an
+  alternative base name to use for the config files other than the app_name
+  given in the ~Reader.new~ constructor.  This is useful for applications that
+  may want to have more than one set of configuration files.  If given, this
+  name only affects the base names of the config files, not the directory in
+  which they are to be sought: those always use the app name.
+- ~command_line:~ :: if you want a command-line to override config values, you
+  can supply one as either a String or a Hash to the ~command_line:~ keyword
+  parameter.  See below for how a String is parsed.
+- ~verbose:~ :: if you set ~verbose:~ true as a keyword argument, the ~read~
+  method will report details of how the configuration was built on ~$stderr~.
+
+  #+begin_src ruby
+    require 'fat_config'
+
+    reader = FatConfig::Reader.new('labrat')
+    reader.read  # YAML configs with basename 'labrat'; XDG conventions
+
+    # Now read another config set in directories named 'labrat' but with base
+    # names of 'labeldb'.  Overrride any setting named fog_psi with command-line
+    # value, and report config build on $stderr.
+    reader.read('labeldb', command_line: "--fog-psi=3.41mm", verbose: true)
+
+    # Similar with a Hash for the command-line
+    cl = { fog_psi: '3.41mm' }
+    reader.read('labeldb', command_line: cl, verbose: true)
+  #+end_src
+
+** Parsing Environment and Command Line Strings
+The highest priority configs are those contained in the environment variable
+or in any ~command-line:~ key-word parameter given to the ~#read~ method.  In
+the case of the environment variable, the setting is always a String read from
+the environment.
+
+The ~command_line:~ key-word parameter can be set to either a String or a
+Hash.  When a Hash is provided, it is used unaltered as a config hash.  When a
+String is provided (and in the case of the environment variable), the string
+should be something like this:
+
+#+begin_example
+--hello-thing='hello, world' --gb=goodbye world --doit --the_num=3.14159 --the-date=2024-11-27 --no-bueno --~junk
+#+end_example
+
+And it is parsed into this Hash:
+
+#+begin_src ruby
+  {
+    :hello_thing=>"hello, world",
+   :gb=>"goodbye",
+   :doit=>true,
+   :the_num=>"3.14159",
+   :the_date=>"2024-11-27",
+   :bueno=>false,
+   :junk=>false
+  }
+#+end_src
+
+Here are the parsing rules:
+
+1. A config element is either an "option," of the form
+   "--<option-name>=<value>" or a "flag" of the form "--<flag-name>",
+   everything else is ignored.
+2. All option values are returned as String's and are not deserialized into
+   Ruby objects,
+3. All flags are returned as a boolean ~true~ or ~false~.  If the flag name
+   starts with 'no', 'no-', 'no_', '!', or '~', it is set to =false= and the
+   option name has the negating prefix stripped; otherwise, it is set to
+   =true=.
+4. These rules apply regardless of style being used for config files.
+
+* 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.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, update the version number in `version.rb`,
+and then run `bundle exec rake release`, which will create a git tag for the
+version, push git commits and the created tag, and push the `.gem` file to
+[[https://rubygems.org][rubygems.org]].
+
+* Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/ddoherty03/fat_config.
+
+* License
+
+The gem is available as open source under the terms of the [[https://opensource.org/licenses/MIT][MIT License]].

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/TODO.org

@@ -0,0 +1,11 @@
+* Programming TODOS
+** Write the README.org
+
+* Finished
+** DONE Verbose
+CLOSED: [2024-11-27 Wed 07:04]
+Ensure that the verbose option provides useful feedback on how the options got to be what they end up as.
+** DONE Command-line and Environment
+CLOSED: [2024-11-28 Thu 10:58]
+Add a parameter to the Reader#read method to merge in command-line parameters
+and environment variables.

data/lib/fat_config/core_ext/hash_ext.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class Hash
+  # Transform hash keys to symbols suitable for calling as methods, i.e.,
+  # translate any hyphens to underscores.  This is the form we want to keep
+  # config hashes in Labrat.
+  def methodize
+    new_hash = {}
+    each_pair do |k, v|
+      new_val =
+        if v.is_a?(Hash)
+          v.methodize
+        else
+          v
+        end
+      new_hash[k.to_s.tr('-', '_').to_sym] = new_val
+    end
+    new_hash
+  end
+
+  # Print to $stderr the changes wrought by merging new_hash into this one.
+  def report_merge(new_hash, indent: 2)
+    space = ' ' * indent
+    if new_hash.empty?
+      warn "#{space}Empty config"
+      return self
+    end
+
+    new_keys = new_hash.keys
+    old_keys = keys
+    unchanged_keys = old_keys - new_keys
+    added_keys = new_keys - old_keys
+    changed_keys = old_keys & new_keys
+    (keys + added_keys).sort.each do |k|
+      if (self[k].nil? || self[k].is_a?(Hash)) && new_hash[k].is_a?(Hash)
+        # Recurse if the value is a Hash
+        warn "#{space}Config key: #{k}:"
+        (self[k] || {}).report_merge(new_hash[k], indent: indent + 2)
+        next
+      end
+      if unchanged_keys.include?(k)
+        warn "#{space}Unchanged: #{k}: #{self[k]}"
+      elsif added_keys.include?(k)
+        warn "#{space}Added:     #{k}: #{new_hash[k]}"
+      elsif changed_keys.include?(k)
+        if self[k] != new_hash[k]
+          warn "#{space}Changed:   #{k}: #{self[k]} -> #{new_hash[k]}"
+        else
+          warn "#{space}Unchanged: #{k}: #{self[k]} -> #{new_hash[k]}"
+        end
+      else
+        raise ArgumentError, "FatConfig report_merge has unmatched key: #{k}"
+      end
+    end
+    self
+  end
+
+  require 'fat_core/string'
+
+  # Parse a string of the form "--key-one=val1 --flag --key2=val2" into a
+  # Hash,
+  #
+  # 1. where normal option values can be surrounded by single- or double-quotes
+  #    if they are meant to include any spaced and
+  # 2. where the value of any "flag", such as --flag (with no value given) is
+  #    set to ~true~ unless its name starts with "no" or "no_" or "!" or "~",
+  #    then set it to false and its name is stripped of the leading negator.
+  #
+  # It also converts all the keys to symbols suitable as Ruby id's using
+  # Hash#methodize.  It ignores anything that doesn't look like an option or
+  # flag.
+  def self.parse_opts(str)
+    hsh = Hash[str.scan(/--?([^=\s]+)(?:=("[^"]*"|'[^']*'|\S+))?/)]
+    result = {}
+    hsh.each_pair do |k, v|
+      if v.nil?
+        if k =~ /\A((no[-_]?)|!|~)(?<name>.*)\z/
+          new_key = Regexp.last_match["name"]
+          result[new_key] = false
+        else
+          result[k] = true
+        end
+      elsif v.match?(/\A['"].*['"]\z/)
+        result[k] = v.clean.sub(/\A['"]/, '').sub(/['"]\z/, '')
+      else
+        result[k] = v
+      end
+    end
+    result.methodize
+  end
+end

data/lib/fat_config/errors.rb

@@ -0,0 +1,3 @@
+module FatConfig
+  class ParseError < StandardError; end
+end

data/lib/fat_config/reader.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module FatConfig
+  # This class is responsible for finding a config files, reading them, and
+  # returning a Hash to reflect the configuration.  We use YAML as the
+  # configuration format and look for the config file in the standard places.
+  class Reader
+    VALID_CONFIG_STYLES = [:yaml, :toml, :json, :ini]
+
+    # - ~app_name~ :: used to form environment variables for config locations.
+    # - ~style~ :: either :yaml or :toml or :json or :ini
+    # - ~xdg~ :: whether follow XDG desktop conventions, by default true; if
+    #   false, use "classic" UNIX config practices with /etc/ and ~/.baserc.
+    # - ~root_prefix~ :: an alternate root of the assumed file system, by
+    #   default ''.  This facilitated testing.
+    attr_reader :app_name, :style, :root_prefix, :xdg
+
+    # Config file may be located in either the xdg locations (containing any
+    # variant of base: base, base.yml, or base.yaml) or in the classic
+    # locations (/etc/app_namerc, /etc/app_name, ~/.app_namerc~, or
+    # ~/.app_name/base.ext). Return a hash that reflects the merging of
+    # those files according to the following priorities, from highest to
+    # lowest:
+    #
+    # 1. Options passed in the String or Hash parameter, command_line
+    # 2. Options passed by an environment variable APPNAME_OPTIONS
+    # 3. If the xdg parameter is true:
+    #    a. Either:
+    #       A. The file pointed to by the environment variable APPNAME_CONFIG or
+    #       B. User xdg config files for app_name,
+    #    b. Then, either:
+    #       A. The file pointed to by the environment variable APPNAME_SYS_CONFIG or
+    #       B. System xdg config files for for app_name,
+    # 4. If the xdg parameter is false:
+    #    a. Either:
+    #       A. The file pointed to by the environment variable APPNAME_CONFIG or
+    #       B. User classic config files
+    #    b. Then, either:
+    #       A. The file pointed to by the environment variable APPNAME_SYS_CONFIG or
+    #       B. System classic config files,
+    def initialize(app_name, style: :yaml, xdg: true, root_prefix: '')
+      @app_name = app_name.strip.downcase
+      raise ArgumentError, "reader app name may not be blank" if @app_name.blank?
+
+      msg = "reader app name may only contain letters, numbers, and underscores"
+      raise ArgumentError, msg unless app_name.match?(/\A[a-z][a-z0-9_]*\z/)
+
+      @root_prefix = root_prefix
+      @xdg = xdg
+
+      style = style.to_s.downcase.to_sym
+      @style =
+        case style
+        when :yaml
+          YAMLStyle.new
+        when :toml
+          TOMLStyle.new
+        when :ini
+          INIStyle.new
+        when :json
+          JSONStyle.new
+        else
+          msg = "config style must be one of #{VALID_CONFIG_STYLES.join(', ')}"
+          raise ArgumentError, msg
+        end
+    end
+
+    # Return a Hash of the config files for app_name directories.  For
+    # applications that want to have more than one config file, a base name
+    # for the config file other than the app's name can be optionally
+    # provided.
+    #
+    # If you want a command-line to override config values, you can supply one
+    # as either a String or a Hash to the ~command_line:~ keyword parameter.
+    # If given a String, it must use the long-option form with equal signs for
+    # options to be given a value.  If no equal sign and value are given, the
+    # option is assumed to be a boolean set to ~true~ unless the options
+    # starts with one of 'no', 'no-', or '!', in wich case the option is
+    # stripped of the negating prefix and the value is set to false.  If given
+    # a Hash, it will be used unaltered.
+    #
+    # Finally, you can add a 'verbose: true' parameter to report the details
+    # of how the final Hash was formed on $stderr.
+    def read(alt_base = app_name, command_line: {}, verbose: false)
+      paths = config_paths(alt_base)
+      sys_configs = paths[:system]
+      usr_configs = paths[:user]
+      if verbose
+        if sys_configs.empty?
+          warn "No system config files found."
+        else
+          warn "System config files found: #{sys_configs.join('; ')}"
+        end
+        if usr_configs.empty?
+          warn "No user config files found."
+        else
+          warn "User config files found: #{usr_configs.join('; ')}"
+        end
+      end
+      result = style.merge_files(sys_configs, usr_configs, verbose: verbose)
+      result = merge_environment(result, verbose: verbose)
+      merge_command_line(result, command_line, verbose: verbose)
+    end
+
+    def merge_environment(start_hash, verbose: false)
+      return start_hash if ENV[env_name].blank?
+
+      env_hash = Hash.parse_opts(ENV[env_name])
+      if verbose
+        warn "Merging environment from #{env_name}:"
+        start_hash.report_merge(env_hash)
+      end
+      start_hash.merge(env_hash)
+    end
+
+    def merge_command_line(start_hash, command_line, verbose: false)
+      return start_hash unless command_line
+
+      return start_hash if command_line.empty?
+
+      cl_hash =
+        case command_line
+        when String
+          Hash.parse_opts(command_line)
+        when Hash
+          command_line
+        else
+          raise ArgumentError, "command_line must be a String or Hash"
+        end
+      if verbose
+        warn "Merging command-line:"
+        start_hash.report_merge(cl_hash)
+      end
+      start_hash.merge(cl_hash)
+    end
+
+    def env_name
+      "#{app_name.upcase}_OPTIONS"
+    end
+
+    def config_paths(base = app_name)
+      sys_configs = []
+      sys_env_name = "#{app_name.upcase}_SYS_CONFIG"
+      if ENV[sys_env_name]
+        sys_fname = File.join(root_prefix, File.expand_path(ENV[sys_env_name]))
+        sys_configs << sys_fname if File.readable?(sys_fname)
+      else
+        sys_configs +=
+          if xdg
+            find_xdg_sys_config_files(base)
+          else
+            find_classic_sys_config_files(base)
+          end
+      end
+
+      usr_configs = []
+      usr_env_name = "#{app_name.upcase}_CONFIG"
+      if ENV[usr_env_name]
+        usr_fname = File.join(root_prefix, File.expand_path(ENV[usr_env_name]))
+        usr_configs << usr_fname if File.readable?(usr_fname)
+      else
+        usr_configs <<
+          if xdg
+            find_xdg_user_config_file(base)
+          else
+            find_classic_user_config_file(base)
+          end
+      end
+      { system: sys_configs.compact, user: usr_configs.compact }
+    end
+
+    ########################################################################
+    # XDG config files
+    ########################################################################
+
+    # From the XDG standard:
+    # Your application should store and load data and configuration files to/from
+    # the directories pointed by the following environment variables:
+    #
+    # $XDG_CONFIG_HOME (default: "$HOME/.config"): user-specific configuration files.
+    # $XDG_CONFIG_DIRS (default: "/etc/xdg"): precedence-ordered set of system configuration directories.
+
+    # Return the absolute path names of all XDG system config files for
+    # app_name with the basename variants of base. Return the lowest priority
+    # files first, highest last. Prefix the search locations with dir_prefix
+    # if given.
+    def find_xdg_sys_config_files(base = app_name)
+      configs = []
+      xdg_search_dirs = ENV['XDG_CONFIG_DIRS']&.split(':')&.reverse || ['/etc/xdg']
+      xdg_search_dirs.each do |dir|
+        dir = File.expand_path(File.join(dir, app_name))
+        dir = File.join(root_prefix, dir) unless root_prefix.nil? || root_prefix.strip.empty?
+        base_candidates = style.dir_constrained_base_names(base)
+        config_fname = base_candidates.find { |b| File.readable?(File.join(dir, b)) }
+        configs << File.join(dir, config_fname) if config_fname
+      end
+      configs
+    end
+
+    # Return the absolute path name of any XDG user config files for app_name
+    # with the basename variants of base. The XDG_CONFIG_HOME environment
+    # variable for the user configs is intended to be the name of a single xdg
+    # config directory, not a list of colon-separated directories as for the
+    # system config. Return the name of a config file for this app in
+    # XDG_CONFIG_HOME (or ~/.config by default).  Prefix the search location
+    # with dir_prefix if given.
+    def find_xdg_user_config_file(base = app_name)
+      xdg_search_dir = ENV['XDG_CONFIG_HOME'] || ['~/.config']
+      dir = File.expand_path(File.join(xdg_search_dir, app_name))
+      dir = File.join(root_prefix, dir) unless root_prefix.strip.empty?
+      return unless Dir.exist?(dir)
+
+      base_candidates = style.dir_constrained_base_names(base)
+      config_fname = base_candidates.find { |b| File.readable?(File.join(dir, b)) }
+      if config_fname
+        File.join(dir, config_fname)
+      end
+    end
+
+    ########################################################################
+    # Classic config files
+    ########################################################################
+
+    # Return the absolute path names of all "classic" system config files for
+    # app_name with the basename variants of base. Return the lowest priority
+    # files first, highest last.  Prefix the search locations with dir_prefix
+    # if given.
+    def find_classic_sys_config_files(base = app_name)
+      configs = []
+      env_config = ENV["#{app_name.upcase}_SYS_CONFIG"]
+      if env_config && File.readable?((config = File.join(root_prefix, File.expand_path(env_config))))
+        configs = [config]
+      elsif File.readable?(config = File.join(root_prefix, "/etc/#{base}"))
+        configs = [config]
+      elsif File.readable?(config = File.join(root_prefix, "/etc/#{base}rc"))
+        configs = [config]
+      else
+        dir = File.join(root_prefix, "/etc/#{app_name}")
+        if Dir.exist?(dir)
+          base_candidates = style.classic_base_names(base)
+          config = base_candidates.find { |b| File.readable?(File.join(dir, b)) }
+          configs = [File.join(dir, config)] if config
+        end
+      end
+      configs
+    end
+
+    # Return the absolute path names of all "classic" system config files for
+    # app_name with the basename variants of base. Return the lowest priority
+    # files first, highest last.  Prefix the search locations with dir_prefix if
+    # given.
+    def find_classic_user_config_file(base = app_name)
+      env_config = ENV["#{app_name.upcase}_CONFIG"]
+      if env_config && File.readable?((config = File.join(root_prefix, File.expand_path(env_config))))
+        config
+      else
+        config_dir = File.join(root_prefix, File.expand_path("~/"))
+        base_candidates = style.dotted_base_names(base)
+        base_fname = base_candidates.find do |b|
+          File.file?(File.join(config_dir, b)) && File.readable?(File.join(config_dir, b))
+        end
+        if base_fname
+          File.join(config_dir, base_fname)
+        elsif Dir.exist?(config_dir = File.join(root_prefix, File.expand_path("~/.#{app_name}")))
+          base_candidates = style.dir_constrained_base_names(base)
+          base_fname = base_candidates.find { |b| File.readable?(File.join(config_dir, b)) }
+          File.join(config_dir, base_fname) if base_fname
+        end
+      end
+    end
+  end
+end

data/lib/fat_config/style.rb

@@ -0,0 +1,73 @@
+module FatConfig
+  # This class acts as a super class for specific styles of config files.  The
+  # subclass must provide a load_file method that takes a file name, reads it
+  # according to the rules of the Config style, and returns a Hash of the
+  # config values.  The extent to which values are de-serialized from string
+  # is up to the subclass.
+  class Style
+    # Read the file with the given name and return a Hash represented by the
+    # config file.
+    def load_file(file_name)
+      raise NotImplementedError, "Style#load_file must be defined in a subclass of Style"
+    end
+
+    # The possible file extensions for files of this Style.  Here, we give the
+    # generic config extensions, but the subclass should supplement it.
+    def possible_extensions
+      ['cfg', 'config']
+    end
+
+    # Read all the given system and user-level config files in order from
+    # lower priority to higher priority, merging each along the way to build
+    # the final Hash.  If requested, report the details to $stderr.
+    def merge_files(sys_files = [], usr_files = [], verbose: false)
+      hash = {}
+      files = (sys_files + usr_files).compact
+      files.each do |f|
+        next unless File.readable?(f)
+
+        file_hash = load_file(f)
+        next unless file_hash
+
+        if file_hash.is_a?(Hash)
+          file_hash = file_hash.methodize
+        else
+          raise "Error loading file #{f}:\n#{File.read(f)[0..500]}"
+        end
+        if verbose
+          warn "Merging system config from file '#{f}':" if sys_files.include?(f)
+          warn "Merging user config from file '#{f}':" if usr_files.include?(f)
+          hash.report_merge(file_hash)
+        end
+        hash.deep_merge!(file_hash)
+      end
+      hash
+    end
+
+    # Return a list of possible configuration file basenames where the
+    # directory path DOES NOT already include the app_name so that the
+    # basename itself must be distingashable as belonging to the app.
+    def constrained_base_names(base)
+      [base] + possible_extensions.map { |ext| "#{base}.#{ext}" }
+    end
+
+    # Return a list of possible configuration file basenames where the
+    # directory path DOES already includes the app_name so that it need not be
+    # included in the basename itself.
+    def dir_constrained_base_names(base)
+      constrained_base_names(base) + ['config'] + possible_extensions.map { |ext| "config.#{ext}" }
+    end
+
+    # Return a list of possible configuration file basenames as might be
+    # placed in the user's home directory as a hidden file, but which need to
+    # contain a component of the app_name to distinguish it.
+    def dotted_base_names(base)
+      [".#{base}", ".#{base}rc"] + possible_extensions.map { |ext| ".#{base}.#{ext}" }
+    end
+  end
+end
+
+require_relative 'styles/yaml_style'
+require_relative 'styles/toml_style'
+require_relative 'styles/ini_style'
+require_relative 'styles/json_style'

data/lib/fat_config/styles/ini_style.rb

@@ -0,0 +1,23 @@
+module FatConfig
+  class INIStyle < Style
+    def load_string(str)
+      # Since INIFile does not have a method for parsing strings, we have to
+      # create a file with the string as content.
+      tmp_path = File.join("/tmp", "fat_config/ini#{$PID}")
+      File.write(tmp_path, str)
+      load_file(tmp_path)
+    rescue IniFile::Error => ex
+      raise FatConfig::ParseError, ex.to_s
+    end
+
+    def load_file(file_name)
+      IniFile.load(file_name).to_h.methodize
+    rescue IniFile::Error => ex
+      raise FatConfig::ParseError, ex.to_s
+    end
+
+    def possible_extensions
+      super + ['ini']
+    end
+  end
+end

data/lib/fat_config/styles/json_style.rb

@@ -0,0 +1,17 @@
+module FatConfig
+  class JSONStyle < Style
+    def load_string(str)
+      JSON.parse(str, symbolize_name: true).methodize
+    rescue JSON::ParserError => ex
+      raise FatConfig::ParseError, ex.to_s
+    end
+
+    def load_file(file_name)
+      load_string(File.read(file_name))
+    end
+
+    def possible_extensions
+      super + ['json']
+    end
+  end
+end

data/lib/fat_config/styles/toml_style.rb

@@ -0,0 +1,17 @@
+module FatConfig
+  class TOMLStyle < Style
+    def load_string(str)
+      Tomlib.load(str)&.methodize
+    rescue Tomlib::ParseError => ex
+      raise FatConfig::ParseError, ex.to_s
+    end
+
+    def load_file(file_name)
+      load_string(File.read(file_name))
+    end
+
+    def possible_extensions
+      super + ['toml']
+    end
+  end
+end

data/lib/fat_config/styles/yaml_style.rb

@@ -0,0 +1,51 @@
+require 'date'
+
+module FatConfig
+  # NOTE: from the Psych documentation, some types are 'deserialized',
+  # meaning they are converted to Ruby objects.  For example, a value of
+  # '10' for a property will be converted to the integer 10.
+  #
+  # Safely load the yaml string in yaml.  By default, only the
+  # following classes are allowed to be deserialized:
+  #
+  # - TrueClass
+  # - FalseClass
+  # - NilClass
+  # - Integer
+  # - Float
+  # - String
+  # - Array
+  # - Hash
+  #
+  # Recursive data structures are not allowed by default.  Arbitrary classes
+  # can be allowed by adding those classes to the permitted_classes
+  # keyword argument.  They are additive.  For example, to allow Date
+  # deserialization:
+  #
+  # Config.read adds Date, etc., to permitted classes, but provides for no others.
+  class YAMLStyle < Style
+    def load_string(str)
+      Psych.safe_load(
+        str,
+        symbolize_names: true,
+        permitted_classes: [Date, DateTime, Time],
+      )&.methodize || {}
+    rescue Psych::SyntaxError => ex
+      raise FatConfig::ParseError, ex.to_s
+    end
+
+    def load_file(file_name)
+      Psych.safe_load_file(
+        file_name,
+        symbolize_names: true,
+        permitted_classes: [Date, DateTime, Time],
+      )&.methodize || {}
+    rescue Psych::SyntaxError => ex
+      raise FatConfig::ParseError, ex.to_s
+    end
+
+    def possible_extensions
+      super + ['yml', 'yaml']
+    end
+  end
+end

data/lib/fat_config/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FatConfig
+  VERSION = "0.4.1"
+end

data/lib/fat_config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash'
+require 'fileutils'
+require 'psych'
+require 'tomlib'
+require 'inifile'
+require 'json'
+
+require_relative "fat_config/version"
+require_relative "fat_config/errors"
+require_relative "fat_config/core_ext/hash_ext"
+require_relative "fat_config/reader"
+require_relative "fat_config/style"
+
+module FatConfig
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/rubocop-global.yml

@@ -0,0 +1,178 @@
+require:
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
+
+inherit_gem:
+    rubocop-shopify: rubocop.yml
+
+AllCops:
+  NewCops: enable
+  # TargetRubyVersion: 3.0
+
+Style/DateTime:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/MethodCallWithArgsParentheses:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false
+
+Style/ClassMethodsDefinitions:
+  Enabled: true
+  EnforcedStyle: def_self
+
+Layout/LineLength:
+  Enabled: true
+  Max: 120
+  # To make it possible to copy or click on URIs in the code, we allow lines
+  # containing a URI to be longer than Max.
+  AllowHeredoc: true
+  AllowURI: true
+  URISchemes:
+    - http
+    - https
+
+Layout/ArgumentAlignment:
+  Enabled: true
+  EnforcedStyle: with_first_argument
+
+Naming/InclusiveLanguage:
+  Enabled: false
+
+Metrics/AbcSize:
+  # The ABC size is a calculated magnitude, so this number can be a Fixnum or
+  # a Float.
+  Enabled: false
+  Max: 50
+
+Metrics/BlockNesting:
+  Enabled: false
+  Max: 3
+
+Metrics/BlockLength:
+  Enabled: false
+  Max: 25
+
+Metrics/ClassLength:
+  Enabled: false
+  CountComments: false  # count full line comments?
+  Max: 100
+
+Metrics/ModuleLength:
+  Enabled: false
+  CountComments: false  # count full line comments?
+  Max: 100
+
+Metrics/MethodLength:
+  Enabled: false
+  CountComments: false  # count full line comments?
+  Max: 10
+
+# Avoid complex methods.
+Metrics/CyclomaticComplexity:
+  Enabled: false
+  Max: 20
+
+Metrics/ParameterLists:
+  Max: 5
+  CountKeywordArgs: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+  Max: 8
+
+Layout/MultilineOperationIndentation:
+  EnforcedStyle: aligned
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver
+  SupportedStyles:
+    - aligned
+    - indented
+    - indented_relative_to_receiver
+  # By default, the indentation width from Style/IndentationWidth is used
+  # But it can be overridden by setting this parameter
+  IndentationWidth: ~
+
+# Though the style guides recommend against them, I like perl back references.
+# They are much more concise than the recommended: $2 vs. Regexp.last_match(2).
+# Two characters versus 18!
+# Cop supports --auto-correct.
+Style/PerlBackrefs:
+  Enabled: false
+
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles, ProceduralMethods, FunctionalMethods, IgnoredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# IgnoredMethods: lambda, proc, it
+Style/BlockDelimiters:
+  EnforcedStyle: braces_for_chaining
+  ProceduralMethods: expect
+
+# Cop supports --auto-correct.
+# Configuration parameters: AllowForAlignment, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: format, sprintf, percent
+Style/FormatString:
+  Enabled: false
+
+# Configuration parameters: NamePrefix, NamePrefixBlacklist, NameWhitelist.
+# NamePrefix: is_, has_, have_
+# NamePrefixBlacklist: is_, has_, have_
+# NameWhitelist: is_a?
+Naming/PredicateName:
+  AllowedMethods: has_overlaps_within?
+  Exclude:
+    - 'spec/**/*'
+
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: always, never
+Style/FrozenStringLiteralComment:
+  Enabled: false
+  EnforcedStyle: always
+
+# I like using !! to convert a value to boolean.
+Style/DoubleNegation:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/DescribedClass:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/NestedGroups:
+  Max: 5

data/sig/fat_config.rbs

@@ -0,0 +1,4 @@
+module FatConfig
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: fat_config
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+platform: ruby
+authors:
+- Daniel E. Doherty
+bindir: bin
+cert_chain: []
+date: 2024-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fat_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: inifile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tomlib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2+
+
+  This library provides a reader for configuration files, looking for them in places
+  designated by (1) a user-set environment variable, (2) in the standard XDG
+  locations (e.g., /etc/xdg/app.yml), or (3) in the classical UNIX locations
+  (e.g. /etc/app/config.yml or ~/.apprc).  Config files can be written in one of
+  YAML, TOML, INI-style, or JSON.  It enforces precedence of user-configs over
+  system-level configs, and enviroment or command-line configs over the file-based
+  configs.
+
+email:
+- ded@ddoherty.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- LICENSE.txt
+- README.org
+- Rakefile
+- TODO.org
+- lib/fat_config.rb
+- lib/fat_config/core_ext/hash_ext.rb
+- lib/fat_config/errors.rb
+- lib/fat_config/reader.rb
+- lib/fat_config/style.rb
+- lib/fat_config/styles/ini_style.rb
+- lib/fat_config/styles/json_style.rb
+- lib/fat_config/styles/toml_style.rb
+- lib/fat_config/styles/yaml_style.rb
+- lib/fat_config/version.rb
+- rubocop-global.yml
+- sig/fat_config.rbs
+homepage: https://git.ddoherty.net/fat_config
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://git.ddoherty.net/fat_config
+  source_code_uri: https://git.ddoherty.net/fat_config
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Library to read config from standard XDG or classic locations.
+test_files: []
+...