fat_config 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d987b854bd4105f55ead3efbc73a77a1e168b4c5bcfc6caa487e248463df95e
-  data.tar.gz: 8d65e3589a6402eb4f4fa374a815ffad56902162d4f0e107c0ef6f676ed39252
+  metadata.gz: 79f4dfb77fd0ccc161c28ad847a93ce649930294a4d444ce5e9f83ac0b49b761
+  data.tar.gz: dd9db0f013fdcfb1bb36c84e085b4932d7d6a0a59a53db3b8d6088957701bc12
 SHA512:
-  metadata.gz: f19a80712d34593aa39ebf5f5763a48aa5cce085b721b90a6a591417da9ce878c466800938f482aa88b5c6dac4c2ebdfb2250c7d798e8a0a8cbf415867e8b353
-  data.tar.gz: 0c8575cf4ffc410eba8c6d14e194e802f0e8505f266e0e08e4a63c7905c2cd5c2c184c6114b870bcec8b86dc56758035a4a8c8b2c5d48fbb871e17423224e073
+  metadata.gz: 147f0b15e9431d4f3d9009eddecb87070c734d1d49858d18fcaabd2a98815c84cd2cb6c3b7d388f162656346e38d8486af211534b11c019a446d14207419ff2b
+  data.tar.gz: 7d404f53df4b4e5ae034b62728ec11a4eb155c320f92ccb993fd17d2dfd2721b8bed04e7768ad9f8ef02dc70ca36a15fc06fbc7536dcb2cb1e96ec47afbbacfd

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+- [Version 0.7.1 <span class="timestamp-wrapper"><span class="timestamp">[2026-02-06 Fri]</span></span>](#org48cabe8)
+- [Version 0.7.0 <span class="timestamp-wrapper"><span class="timestamp">[2026-02-05 Thu]</span></span>](#orga2f16a3)
+
+
+<a id="org48cabe8"></a>
+
+# Version 0.7.1 <span class="timestamp-wrapper"><span class="timestamp">[2026-02-06 Fri]</span></span>
+
+-   Improved error diagnostics on ParseError
+
+
+<a id="orga2f16a3"></a>
+
+# Version 0.7.0 <span class="timestamp-wrapper"><span class="timestamp">[2026-02-05 Thu]</span></span>
+
+-   Parsing error dignostics added

data/CHANGELOG.org

@@ -0,0 +1,17 @@
+* COMMENT CHANGELOG tips:
+1. Don't dump your git change logs into this file, write them yourself.
+2. Keep entries short and user-focused,
+3. Use non-technical language, but do speak in the vocabulary of your gem.
+4. Don't document changes only of interest to the programmers, just those the
+   user would find useful.
+5. Give each heading a version number and an inactive date (C-c ! is useful here).
+
+* Version 0.8.0
+- Allow user to specify an explicit user or system config directory, ignoring
+  XDG and classic convention.
+
+* Version 0.7.1 [2026-02-06 Fri]
+- Improved error diagnostics on ParseError
+
+* Version 0.7.0 [2026-02-05 Thu]
+- Parsing error dignostics added

data/README.md

@@ -1,26 +1,26 @@
-- [Introduction](#org6ea1400)
-- [Installation](#org0bfc9c4)
-- [Usage:](#orgb03325f)
-  - [Following XDG Standards](#orgcc49e5b)
-  - [Following Classic UNIX Standards](#orgb094a10)
-  - [Available Config File Styles](#org77efd19)
-  - [Hash Keys](#org2489659)
-  - [Hash Values](#org3c327fd)
-    - [YAML](#org47246cf)
-    - [TOML](#orgcd934bb)
-    - [JSON](#orge3c0568)
-    - [INI](#org479cf72)
-  - [Creating a Reader](#org195ed64)
-  - [Calling the `read` method on a `Reader`](#org0c26613)
+- [Introduction](#orgc4b482f)
+- [Installation](#orgbce0696)
+- [Usage:](#org7684da4)
+  - [Following XDG Standards](#orga8e28a3)
+  - [Following Classic UNIX Standards](#orgd716a45)
+  - [Available Config File Styles](#org152041e)
+  - [Hash Keys](#orgb744014)
+  - [Hash Values](#org02d5c86)
+    - [YAML](#org73fadf6)
+    - [TOML](#orge78f21a)
+    - [JSON](#org22479cd)
+    - [INI](#org850bdf4)
+  - [Creating a Reader](#org570f7c5)
+  - [Calling the `read` method on a `Reader`](#org9637e7b)
   - [Parsing Environment and Command Line Strings](#parsing-environment-and-command-line-strings)
-- [Development](#orgadf9605)
-- [Contributing](#org00f8770)
-- [License](#orgbb61eac)
+- [Development](#orgda3ea75)
+- [Contributing](#orgfb56ba2)
+- [License](#org0377369)
 
 [![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="org6ea1400"></a>
+<a id="orgc4b482f"></a>
 
 # Introduction
 
@@ -29,7 +29,7 @@ Allowing a user to configure an application to change its behavior at runtime ca
 `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="org0bfc9c4"></a>
+<a id="orgbce0696"></a>
 
 # Installation
 
@@ -46,7 +46,7 @@ gem install fat_config
 ```
 
 
-<a id="orgb03325f"></a>
+<a id="org7684da4"></a>
 
 # Usage:
 
@@ -64,7 +64,7 @@ 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="orgcc49e5b"></a>
+<a id="orga8e28a3"></a>
 
 ## Following XDG Standards
 
@@ -78,7 +78,7 @@ By default, `FatConfig::Reader#read` follows the [XDG Desktop Standards](https:/
 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="orgb094a10"></a>
+<a id="orgd716a45"></a>
 
 ## Following Classic UNIX Standards
 
@@ -101,7 +101,7 @@ With the optional `:xdg` keyword parameter to `FatConfig::Reader#read` set to `f
 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="org77efd19"></a>
+<a id="org152041e"></a>
 
 ## Available Config File Styles
 
@@ -115,7 +115,7 @@ With the optional `:xdg` keyword parameter to `FatConfig::Reader#read` set to `f
 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="org2489659"></a>
+<a id="orgb744014"></a>
 
 ## Hash Keys
 
@@ -124,14 +124,14 @@ Any keys that are Strings will be converted to a symbol, using the names given i
 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.
 
 
-<a id="org3c327fd"></a>
+<a id="org02d5c86"></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.
 
 
-<a id="org47246cf"></a>
+<a id="org73fadf6"></a>
 
 ### YAML
 
@@ -148,7 +148,7 @@ The `:yaml` style deserializes the following types:
 -   Date, DateTime, and Time, which FatConfig adds to the foregoing default types deserialized by the default YAML library.
 
 
-<a id="orgcd934bb"></a>
+<a id="orge78f21a"></a>
 
 ### TOML
 
@@ -164,7 +164,7 @@ The `:toml` style deserializes the following types:
 -   Date and Time, when given in ISO form YYYY-MM-DD or YYYY-MM-DDThh:mm:ss
 
 
-<a id="orge3c0568"></a>
+<a id="org22479cd"></a>
 
 ### JSON
 
@@ -180,7 +180,7 @@ The `:json` style deserializes the following types:
 -   Date and Time, NOT deserialized, returns a parse error
 
 
-<a id="org479cf72"></a>
+<a id="org850bdf4"></a>
 
 ### INI
 
@@ -196,7 +196,7 @@ The `:ini` style deserializes the following types:
 -   Date and Time, NOT deserialized, returned as a String
 
 
-<a id="org195ed64"></a>
+<a id="org570f7c5"></a>
 
 ## Creating a Reader
 
@@ -213,7 +213,7 @@ reader3 = FatConfig.new('labrat', style: 'ini', xdg: false)  # Use classic UNIX
 ```
 
 
-<a id="org0c26613"></a>
+<a id="org9637e7b"></a>
 
 ## Calling the `read` method on a `Reader`
 
@@ -276,7 +276,7 @@ Here are the parsing rules:
 4.  These rules apply regardless of style being used for config files.
 
 
-<a id="orgadf9605"></a>
+<a id="orgda3ea75"></a>
 
 # Development
 
@@ -285,14 +285,14 @@ After checking out the repo, run \`bin/setup\` to install dependencies. Then, ru
 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="org00f8770"></a>
+<a id="orgfb56ba2"></a>
 
 # Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/ddoherty03/fat_config>.
 
 
-<a id="orgbb61eac"></a>
+<a id="org0377369"></a>
 
 # License
 

data/README.org

@@ -30,6 +30,7 @@ the files in the proper priority.  It can be set to read ~YAML~, ~TOML~,
 - [[#usage][Usage:]]
   - [[#following-xdg-standards][Following XDG Standards]]
   - [[#following-classic-unix-standards][Following Classic UNIX Standards]]
+  - [[#explicitly-providing-config-directories][Explicitly Providing Config Directories]]
   - [[#available-config-file-styles][Available Config File Styles]]
   - [[#hash-keys][Hash Keys]]
   - [[#hash-values][Hash Values]]
@@ -164,6 +165,11 @@ hypothetical application called ~myapp~:
    ~Hash~, it is used directly and merged into the hash returned from the
    prior methods.
 
+** Explicitly Providing Config Directories
+ When the =Reader= is created, the user can give an explicit =user_dir:=,
+ =sys_dir:= parameter or both.  If given, the XDG or classic conventions for
+ locating config files are ignored regardless of the setting of the =xdg:=
+ parameter.
 ** 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:
@@ -253,11 +259,19 @@ sought.  It also takes a few optional keyword arguments:
   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~.
+- =user_dir:=, to explicitly set the name of the user directory in which to
+  look for the app's config files, thus ignoring the setting of =xdg:= for the
+  user-level settings.
+- =sys_dir:=, to explicitly set the name of the system directory in which to
+  look for the app's config files, thus ignoring the setting of =xdg:= for the
+  system-level settings.
 
 #+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
+  reader4 = FatConfig.new('labrat', user_dir: '~/labrat')  # Look in ~/labrat for user settings
+  reader5 = FatConfig.new('labrat', sys_dir: '/etc/labrat')  # Look in /etc/labrat for system settings
 #+end_src
 
 ** Calling the ~read~ method on a ~Reader~

data/lib/fat_config/errors.rb

@@ -15,39 +15,26 @@ module FatConfig
     end
 
     def self.snippet_from_string(str, line:, column:)
-      snippet = nil
-
+      line = line&.to_i || 1
+      column = column&.to_i || 0
       if str && line && line.to_i > 0
-        lines = str.lines
-        idx = line.to_i - 1
-        if idx >= 0 && idx < lines.length
-          src = lines[idx].chomp
-          caret =
-            if column
-              (" " * column.to_i) + "^"
-            end
-          snippet = [src, caret].compact.join("\n")
-        end
+        lines = str.lines.map(&:chomp)
+        (lines[0..line - 1] +
+          [(' ' * column) + '^'] +
+          lines[line..]).join("\n")
       end
-
-      snippet
     end
 
     def self.snippet_from_file(file_name, line:, column:)
       text = nil
-
       begin
         text = File.read(file_name, encoding: "UTF-8")
       rescue StandardError
         text = nil
       end
-
-      snippet = nil
       if text
-        snippet = snippet_from_string(text, line: line, column: column)
+        snippet_from_string(text, line: line, column: column)
       end
-
-      snippet
     end
 
     private
@@ -61,17 +48,17 @@ module FatConfig
         else
           ""
         end
-
-      msg = +"#{format.to_s.upcase} parse error in #{file}#{loc}: #{problem}"
-
+      msg = +"#{format.to_s.upcase} parse error in:\n  #{file}\n  #{loc}:\n\nERROR:#{problem}"
       if snippet && !snippet.empty?
-        msg << "\n\n#{snippet}"
+        msg << "\n\n===========================\n"
+        msg << snippet
+        msg << "\n===========================\n\n"
       end
-
       if context && !context.empty?
-        msg << "\n\n#{context}"
+        msg << "\n\n==========================="
+        msg << context
+        msg << "===========================\n\n"
       end
-
       msg
     end
   end

data/lib/fat_config/reader.rb

@@ -12,8 +12,9 @@ module FatConfig
     # - ~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.
+    #   default ''.  This facilitates testing.
     attr_reader :app_name, :style, :root_prefix, :xdg
+    attr_reader :user_dir, :sys_dir
 
     # 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
@@ -38,7 +39,7 @@ module FatConfig
     #    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: '')
+    def initialize(app_name, style: :yaml, xdg: true, root_prefix: '', user_dir: nil, sys_dir: nil)
       @app_name = app_name.strip.downcase
       raise ArgumentError, "reader app name may not be blank" if @app_name.blank?
 
@@ -63,6 +64,10 @@ module FatConfig
           msg = "config style must be one of #{VALID_CONFIG_STYLES.join(', ')}"
           raise ArgumentError, msg
         end
+      # Optional override of directories instead of locating them by XDG or
+      # classical conventions.
+      @user_dir = user_dir
+      @sys_dir = sys_dir
     end
 
     # Return a Hash of the config files for app_name directories.  For
@@ -102,6 +107,50 @@ module FatConfig
       merge_command_line(result, command_line, verbose: verbose)
     end
 
+    # Return a Hash of Arrays with the outer Hash having the key system:
+    # pointing to an Array of system paths and the key :user pointing to an
+    # Array of user paths.
+    #
+    # @param base [String] base name to use for finding config paths
+    # @param user_dir [String] optional override of directory with user config files
+    # @param sys_dir [String] optional override of directory with system config files
+    def config_paths(base = app_name)
+      sys_configs = []
+      sys_env_name = "#{app_name.upcase}_SYS_CONFIG"
+      if sys_dir
+        sys_configs = find_config_files_in_dir(base, sys_dir)
+      elsif 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 user_dir
+        usr_configs = find_config_files_in_dir(base, user_dir)
+      elsif 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
+
+    private
+
     def merge_environment(start_hash, verbose: false)
       return start_hash if ENV[env_name].blank?
 
@@ -138,35 +187,25 @@ module FatConfig
       "#{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
+    ########################################################################
+    # Explicit config files
+    ########################################################################
 
-      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
+    # Return a list of readable config files with basename base for the
+    # current style in directory dir.
+    #
+    # @param base [String] base name of config file
+    # @param dir [String] directory to search for config giles
+    def find_config_files_in_dir(base, dir)
+      configs = []
+      dir = File.expand_path(dir)
+      base_candidates = style.dir_constrained_base_names(base)
+      base_candidates.each do |f|
+        if File.readable?(File.join(dir, f))
+          configs << File.join(dir, f)
+        end
       end
-      { system: sys_configs.compact, user: usr_configs.compact }
+      configs
     end
 
     ########################################################################
@@ -181,9 +220,9 @@ module FatConfig
     # $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.
+    # app_name in the current style 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']
@@ -198,16 +237,16 @@ module FatConfig
     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.
+    # in the current style 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?
+      dir = File.join(root_prefix, dir) unless root_prefix.to_s.strip.empty?
       return unless Dir.exist?(dir)
 
       base_candidates = style.dir_constrained_base_names(base)
@@ -222,9 +261,9 @@ module FatConfig
     ########################################################################
 
     # 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.
+    # app_name in the current style 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"]
@@ -246,9 +285,9 @@ module FatConfig
     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.
+    # app_name in the current style 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)))

data/lib/fat_config/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fat_config
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -85,6 +85,8 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".yardopts"
+- CHANGELOG.md
+- CHANGELOG.org
 - LICENSE.txt
 - README.md
 - README.org
@@ -123,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.0
 specification_version: 4
 summary: Library to read config from standard XDG or classic locations.
 test_files: []