fat_config 0.4.2 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ef666d4760076d376efd8af772b85dd67dc15712ef31ff4b75785084ee54d4
-  data.tar.gz: bf2cf2d2dd2b1dfed14e11e36765036f2098297190755ca20036f49c0057b435
+  metadata.gz: 41cf78034335f9fd05433c7058f26fff973575eb0b6becf4f501a15027905c9c
+  data.tar.gz: 6987287fa5d625c0c97c1427add4d7777dea525100d220b8f28241720b85b340
 SHA512:
-  metadata.gz: 6a7926e8928f21508332d232e1dc76c7759f32aa12e8fb1b58f291026d67a9d3d2f9eb4e10d1e4ebf11d27c1b52e4fbe85b7b0ac04381496fd1f4cbdfeb43ed2
-  data.tar.gz: 19ac9abbed663c134ba2206923870feed023b98af5f166d97914e1cc3ba0df124018929429075de34b812e6c6177b581b8261c1a95e92268f61708c08b319b07
+  metadata.gz: b55c2816b7c7402a751242af54e6e6cf54c4b67965e1b276f743c8a4ae991c6e7752c62ca5ff27a69e64eab2b2eb6bb1c8573c4ec3e3a57d5b4eae072e2813aa
+  data.tar.gz: 5d8c20611e05bd4af1745fa00dd1e83295c066fa53d40d3e955df032aa71cf144c5331298f42740d0e26b06f94e5a2a2838a875614a1b8685405d427f269023c

data/.envrc

@@ -0,0 +1 @@
+PATH_add .bundle/bin

data/.rubocop.yml

@@ -1,15 +1,12 @@
-inherit_from: ./rubocop-global.yml
+inherit_gem:
+  rubocop-ddoherty: 'config/default.yml'
 
 AllCops:
-  TargetRubyVersion: 3.3
   Include:
     - 'lib/**/*'
-    - 'bin/**/*'
     - 'spec/**/*'
-#    - 'features/**/*'
   Exclude:
+    - 'test/tmp/**/*'
     - 'spec/tmp/**/*'
-    - 'spec/.examples.txt'
-    - 'bin/setup'
-    - '.simplecov'
-    - 'features/**/*'
+    - 'spec/.examples*'
+    - 'vendor/bundle/**/*'

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--output-dir doc
+--readme README.md
+lib/**/*.rb

data/README.md

@@ -0,0 +1,289 @@
+- [Introduction](#org1f0d9bd)
+- [Installation](#org3f8a5fd)
+- [Usage:](#org5c5fe0f)
+  - [Following XDG Standards](#org7e6640a)
+  - [Following Classic UNIX Standards](#orgbc610e8)
+  - [Available Config File Styles](#orgacf5ac1)
+  - [Hash Keys](#orgf87b1a5)
+  - [Hash Values](#org451482b)
+    - [YAML](#orgef8563a)
+    - [TOML](#orgcf8804e)
+    - [JSON](#org549e838)
+    - [INI](#org12513cc)
+  - [Creating a Reader](#org7a0f2a9)
+  - [Calling the `read` method on a `Reader`](#org7e439f9)
+  - [Parsing Environment and Command Line Strings](#parsing-environment-and-command-line-strings)
+- [Development](#org1fdfa48)
+- [Contributing](#org4454a76)
+- [License](#org8a2eaa6)
+
+[![img](https://github.com/ddoherty03/fat_config/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/ddoherty03/fat_config/actions/workflows/main.yml)
+
+
+<a id="org1f0d9bd"></a>
+
+# Introduction
+
+Allowing a user to configure an application to change its behavior at runtime can be seen as constructing a ruby `Hash` that merges settings from a variety of sources in a hierarchical fashion: first from system-wide file settings, merged with user-level file settings, merged with environment variable settings, merged with command-line parameters. Constructing this Hash, while needed by nearly any command-line app, can be a tedious chore, especially when there are standards, such as the XDG standards and Unix tradition, that may or may not be followed.
+
+`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 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.
+
+
+<a id="org3f8a5fd"></a>
+
+# Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```sh
+bundle add fat_config
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```sh
+gem install fat_config
+```
+
+
+<a id="org5c5fe0f"></a>
+
+# Usage:
+
+```ruby
+require 'fat_config'
+
+reader = FatConfig::Reader.new('myapp')
+config = reader.read
+```
+
+```
+
+```
+
+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.
+
+
+<a id="org7e6640a"></a>
+
+## Following XDG Standards
+
+By default, `FatConfig::Reader#read` follows the [XDG Desktop Standards](https://specifications.freedesktop.org/basedir-spec/latest/), 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 earlier-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 in `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 files. 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.
+
+
+<a id="orgbc610e8"></a>
+
+## 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 [UNIX File Hierarchy Standard](https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s08.html#homeReferences) website:
+
+> 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.
+
+`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.
+
+
+<a id="orgacf5ac1"></a>
+
+## 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 [YAML Specs](https://yaml.org/spec/1.2.2/),
+-   **`toml`:** See [TOML Specs](https://toml.io/en/),
+-   **`json`:** See [JSON Specs](https://datatracker.ietf.org/doc/html/rfc8259), or
+-   **`ini`:** See [INI File on Wikipedia](https://en.wikipedia.org/wiki/INI_file)
+
+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).
+
+
+<a id="orgf87b1a5"></a>
+
+## 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' }`.
+
+
+<a id="org451482b"></a>
+
+## 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:
+
+
+<a id="orgef8563a"></a>
+
+### 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.
+
+
+<a id="orgcf8804e"></a>
+
+### TOML
+
+-   TrueClass (exactly the string 'true')
+-   FalseClass (exactly the string 'false')
+-   Integer (when it looks like an whole number or 0x&#x2026; or 0o&#x2026; 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 [&#x2026;], 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
+
+
+<a id="org549e838"></a>
+
+### 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 [&#x2026;], each typed by these rules)
+-   Hash, (when sub-elements enclosed in {&#x2026;}, each typed by these rules) and,
+-   Date and Time, NOT deserialized, returns a parse error
+
+
+<a id="org12513cc"></a>
+
+### INI
+
+-   TrueClass (exactly the string 'true')
+-   FalseClass (exactly the string 'false')
+-   Integer (when it looks like an whole number or 0x&#x2026; or 0o&#x2026; 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
+
+
+<a id="org7a0f2a9"></a>
+
+## 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`.
+
+```ruby
+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
+```
+
+
+<a id="org7e439f9"></a>
+
+## 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 parameters:
+
+-   **`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`.
+    
+    ```ruby
+    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)
+    ```
+
+
+<a id="parsing-environment-and-command-line-strings"></a>
+
+## 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:
+
+```
+--hello-thing='hello, world' --gb=goodbye world --doit --the_num=3.14159 --the-date=2024-11-27 --no-bueno --~junk
+```
+
+And it is parsed into this Hash:
+
+```ruby
+{
+ :hello_thing=>"hello, world",
+ :gb=>"goodbye",
+ :doit=>true,
+ :the_num=>"3.14159",
+ :the_date=>"2024-11-27",
+ :bueno=>false,
+ :junk=>false
+}
+```
+
+Here are the parsing rules:
+
+1.  A config element is either of the following, everything else is ignored:
+    1.  an "option," of the form "`--<option-name>=<value>`" or
+    
+    2.  a "flag" of the form "`--<flag-name>`"
+
+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.
+
+
+<a id="org1fdfa48"></a>
+
+# 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 [rubygems.org](https://rubygems.org).
+
+
+<a id="org4454a76"></a>
+
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/ddoherty03/fat_config>.
+
+
+<a id="org8a2eaa6"></a>
+
+# License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/README.org

@@ -1,11 +1,48 @@
-# FatConfig
+#+TITLE: FatConfig
+#+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
+#+PROPERTY: header-args:ruby+ :wrap example :session fat_config_session :eval yes
+#+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'fat_config'"
+#+PROPERTY: header-args:sh :exports code :eval no
+#+PROPERTY: header-args:bash :exports code :eval no
+
+[[https://github.com/ddoherty03/fat_config/actions/workflows/main.yml][https://github.com/ddoherty03/fat_config/actions/workflows/main.yml/badge.svg?branch=master]]
+
+* Introduction
+Allowing a user to configure an application to change its behavior at runtime
+can be seen as constructing a ruby ~Hash~ that merges settings from a variety
+of sources in a hierarchical fashion: first from system-wide file settings,
+merged with user-level file settings, merged with environment variable
+settings, merged with command-line parameters.  Constructing this Hash, while
+needed by nearly any command-line app, can be a tedious chore, especially when
+there are standards, such as the XDG standards and Unix tradition, that may or
+may not be followed.
 
 ~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.
+define a ~FatConfig::Reader~ and 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.
+
+* Table of Contents                                          :toc:noexport:
+- [[#introduction][Introduction]]
+- [[#installation][Installation]]
+- [[#usage][Usage:]]
+  - [[#following-xdg-standards][Following XDG Standards]]
+  - [[#following-classic-unix-standards][Following Classic UNIX Standards]]
+  - [[#available-config-file-styles][Available Config File Styles]]
+  - [[#hash-keys][Hash Keys]]
+  - [[#hash-values][Hash Values]]
+    - [[#yaml][YAML]]
+    - [[#toml][TOML]]
+    - [[#json][JSON]]
+    - [[#ini][INI]]
+  - [[#creating-a-reader][Creating a Reader]]
+  - [[#calling-the-read-method-on-a-reader][Calling the ~read~ method on a ~Reader~]]
+  - [[#parsing-environment-and-command-line-strings][Parsing Environment and Command Line Strings]]
+- [[#development][Development]]
+- [[#contributing][Contributing]]
+- [[#license][License]]
 
 * Installation
 
@@ -30,6 +67,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
   config = reader.read
 #+end_src
 
+#+RESULTS:
+#+begin_example
+#+end_example
+
 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.
@@ -49,26 +90,26 @@ from the following locations, from lowest priority to highest:
    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
+   will be visited in reverse order so that the earlier-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
+   it will look in ~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
+   the system- and user-level files.  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
+   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.
 
@@ -140,18 +181,21 @@ of option settings as explained below.  See, [[*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' }~.
+Any keys that are Strings will be converted to a symbol, using the names given
+in the config files, except that they will have any hyphens converted to the
+underscore so they are suitable for use as a method call.  Thus the config
+setting "page-width: 6.5in" in a config file will result in a Hash entry of ~{
+page_width: '6.5in' }~.
+
+Keys that are not Strings will be left alone, so that, for example, you might
+have Integer keys, which may be useful below the top level.
 
 ** 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:
+object is controlled by the style of the configuration files.
 
 *** YAML
-
+The ~:yaml~ style deserializes the following types:
   - TrueClass (the string 'true' of whatever case)
   - FalseClass (the string 'false' of whatever case)
   - NilClass (when no value given)
@@ -164,7 +208,7 @@ the ~:yaml~ style deserializes the following types:
     types deserialized by the default YAML library.
 
 *** TOML
-
+The ~:toml~ style deserializes the following types:
   - 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)
@@ -175,7 +219,7 @@ the ~:yaml~ style deserializes the following types:
   - Date and Time, when given in ISO form YYYY-MM-DD or YYYY-MM-DDThh:mm:ss
 
 *** JSON
-
+The ~:json~ style deserializes the following types:
   - TrueClass (exactly the string 'true')
   - FalseClass (exactly the string 'false')
   - Integer (when it looks like an decimal whole number, but NO provision hex
@@ -187,7 +231,7 @@ the ~:yaml~ style deserializes the following types:
   - Date and Time, NOT deserialized, returns a parse error
 
 *** INI
-
+The ~:ini~ style deserializes the following types:
   - 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)
@@ -210,18 +254,16 @@ sought.  It also takes a few optional keyword arguments:
 - ~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'
-
+#+begin_src ruby :eval no
   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~
+** 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:
+parameters:
 
 - ~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
@@ -235,9 +277,7 @@ parameter:
 - ~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'
-
+  #+begin_src ruby :eval no
     reader = FatConfig::Reader.new('labrat')
     reader.read  # YAML configs with basename 'labrat'; XDG conventions
 
@@ -252,6 +292,10 @@ parameter:
   #+end_src
 
 ** Parsing Environment and Command Line Strings
+:PROPERTIES:
+:CUSTOM_ID: parsing-environment-and-command-line-strings
+:END:
+
 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
@@ -268,9 +312,9 @@ should be something like this:
 
 And it is parsed into this Hash:
 
-#+begin_src ruby
+#+begin_src ruby :eval no
   {
-    :hello_thing=>"hello, world",
+   :hello_thing=>"hello, world",
    :gb=>"goodbye",
    :doit=>true,
    :the_num=>"3.14159",
@@ -282,9 +326,12 @@ And it is parsed into this Hash:
 
 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.
+1. A config element is either of the following, everything else is ignored:
+
+   a. an "option," of the form "~--<option-name>=<value>~" or
+
+   b. a "flag" of the form "~--<flag-name>~"
+
 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

data/Rakefile

@@ -5,8 +5,12 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+require 'gem_docs'
+GemDocs.install
+
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
 
 task default: %i[spec rubocop]

data/lib/fat_config/core_ext/array_ext.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Array
+  # Transform String 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.  Leave non-String keys alone, so, e.g., an
+  # Integer can be a key below the top-level
+  def methodize
+    new_arr = []
+    each do |v|
+      new_arr <<
+          case v
+          when Hash, Array
+            v.methodize
+          when Symbol, String
+            # In case the key is a Symbol like :"a key-for-me", convert it back to
+            # a String, then let #as_sym convert it to a proper Symbol that can be
+            # used as a method call.
+            v.as_sym
+          else
+            v
+          end
+    end
+    new_arr
+  end
+end

data/lib/fat_config/core_ext/hash_ext.rb

@@ -1,19 +1,24 @@
 # 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.
+  # Transform String 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.  Leave non-String keys alone, so, e.g., an
+  # Integer can be a key below the top-level
   def methodize
     new_hash = {}
     each_pair do |k, v|
-      new_val =
-        if v.is_a?(Hash)
-          v.methodize
-        else
-          v
-        end
-      new_hash[k.as_sym] = new_val
+      case k
+      when String
+        new_hash[k.as_sym] = v.kind_of?(Hash) ? v.methodize : v
+      when Symbol
+        # In case the key is a Symbol like :"a key-for-me", convert it back to
+        # a String, then let #as_sym convert it to a proper Symbol that can be
+        # used as a method call.
+        new_hash[k.to_s.as_sym] = v.kind_of?(Hash) ? v.methodize : v
+      else
+        new_hash[k] = v.kind_of?(Hash) ? v.methodize : v
+      end
     end
     new_hash
   end

data/lib/fat_config/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatConfig
   class ParseError < StandardError; end
 end

data/lib/fat_config/reader.rb

@@ -228,7 +228,7 @@ module FatConfig
     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))))
+      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]
@@ -251,7 +251,7 @@ module FatConfig
     # 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))))
+      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("~/"))

data/lib/fat_config/style.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 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
@@ -29,11 +31,10 @@ module FatConfig
         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]}"
+        unless file_hash.is_a?(Hash)
+          raise FatConfig::ParseError, "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)

data/lib/fat_config/styles/ini_style.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatConfig
   class INIStyle < Style
     def load_string(str)
@@ -11,7 +13,17 @@ module FatConfig
     end
 
     def load_file(file_name)
-      IniFile.load(file_name).to_h.methodize
+      ini = IniFile.load(file_name)
+      config = {}
+      ini.each_section do |sec|
+        case ini[sec]
+        when Hash
+          config[sec.to_sym] = ini[sec].methodize
+        else
+          config[sec.to_sym] = ini[sec]
+        end
+      end
+      config
     rescue IniFile::Error => ex
       raise FatConfig::ParseError, ex.to_s
     end

data/lib/fat_config/styles/json_style.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatConfig
   class JSONStyle < Style
     def load_string(str)

data/lib/fat_config/styles/toml_style.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatConfig
   class TOMLStyle < Style
     def load_string(str)

data/lib/fat_config/styles/yaml_style.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'date'
 
 module FatConfig
@@ -17,29 +19,46 @@ module FatConfig
   # - Array
   # - Hash
   #
-  # Recursive data structures are not allowed by default.  Arbitrary classes
-  # can be allowed by adding those classes to the permitted_classes
+  # Recursive data structures are not allowed by Psych 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(
+    def load_string(str, top_sym: :config)
+      data = Psych.safe_load(
         str,
-        symbolize_names: true,
+        symbolize_names: false,
         permitted_classes: [Date, DateTime, Time],
-      )&.methodize || {}
+      )
+      case data
+      when Hash
+        data.methodize
+      when Array
+        { top_sym => data.methodize }
+      when NilClass
+        {}
+      end
     rescue Psych::SyntaxError => ex
       raise FatConfig::ParseError, ex.to_s
     end
 
     def load_file(file_name)
-      Psych.safe_load_file(
+      top_sym = File.basename(file_name).sub(/\.[^\.]*$/, '').as_sym
+      data = Psych.safe_load_file(
         file_name,
-        symbolize_names: true,
+        symbolize_names: false,
         permitted_classes: [Date, DateTime, Time],
-      )&.methodize || {}
+      )
+      case data
+      when Hash
+        data.methodize
+      when Array
+        { top_sym => data.methodize }
+      when NilClass
+        {}
+      end
     rescue Psych::SyntaxError => ex
       raise FatConfig::ParseError, ex.to_s
     end

data/lib/fat_config/version.rb

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

data/lib/fat_config.rb

@@ -8,13 +8,30 @@ 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"
-
+# Gem Overview (extracted from README.org by gem_docs)
+#
+# * Introduction
+# Allowing a user to configure an application to change its behavior at runtime
+# can be seen as constructing a ruby ~Hash~ that merges settings from a variety
+# of sources in a hierarchical fashion: first from system-wide file settings,
+# merged with user-level file settings, merged with environment variable
+# settings, merged with command-line parameters.  Constructing this Hash, while
+# needed by nearly any command-line app, can be a tedious chore, especially when
+# there are standards, such as the XDG standards and Unix tradition, that may or
+# may not be followed.
+#
+# ~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 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.
 module FatConfig
   class Error < StandardError; end
-  # Your code goes here...
+  require_relative "fat_config/version"
+  require_relative "fat_config/errors"
+  require_relative "fat_config/core_ext/hash_ext"
+  require_relative "fat_config/core_ext/array_ext"
+  require_relative "fat_config/reader"
+  require_relative "fat_config/style"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fat_config
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.6.1
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2025-03-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -81,13 +81,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".envrc"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - LICENSE.txt
+- README.md
 - README.org
 - Rakefile
 - TODO.org
 - lib/fat_config.rb
+- lib/fat_config/core_ext/array_ext.rb
 - lib/fat_config/core_ext/hash_ext.rb
 - lib/fat_config/errors.rb
 - lib/fat_config/reader.rb
@@ -97,15 +101,14 @@ files:
 - 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
+homepage: https://github.com/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
+  homepage_uri: https://github.com/ddoherty.net/fat_config
+  source_code_uri: https://github.com/ddoherty.net/fat_config
 rdoc_options: []
 require_paths:
 - lib
@@ -120,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 4.0.0
 specification_version: 4
 summary: Library to read config from standard XDG or classic locations.
 test_files: []

data/rubocop-global.yml

@@ -1,180 +0,0 @@
-require:
-  - rubocop-rake
-
-plugins:
-  - rubocop-performance
-  - rubocop-rspec
-
-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