fat_config 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9402d73a4e16cab2a9088bece9dfa623d406858b5c0ae641df01ee988029e6a1
-  data.tar.gz: 042c81ad9c917ea1073db02259718a73792dd7e134f8c9c3aa4b60f7d9b756b4
+  metadata.gz: 79f4dfb77fd0ccc161c28ad847a93ce649930294a4d444ce5e9f83ac0b49b761
+  data.tar.gz: dd9db0f013fdcfb1bb36c84e085b4932d7d6a0a59a53db3b8d6088957701bc12
 SHA512:
-  metadata.gz: 9026e4d9b87df9db13e341e5e9af201388335db1a750e7e5d72ddea797787034545bdc03b0358acef9a16ae7fb37e31c7e305f23fc6f1023b5e3acf7fb7f2b72
-  data.tar.gz: 24b464de194eef9fb81afdcc23afd24dfcf4dcca35b6411d9befed18435dc6c98c3d147c5f6971d586a04e345fdc027be4b34e07fc6f75b6caf47a1ee4da7ccd
+  metadata.gz: 147f0b15e9431d4f3d9009eddecb87070c734d1d49858d18fcaabd2a98815c84cd2cb6c3b7d388f162656346e38d8486af211534b11c019a446d14207419ff2b
+  data.tar.gz: 7d404f53df4b4e5ae034b62728ec11a4eb155c320f92ccb993fd17d2dfd2721b8bed04e7768ad9f8ef02dc70ca36a15fc06fbc7536dcb2cb1e96ec47afbbacfd

data/CHANGELOG.org

@@ -6,6 +6,10 @@
    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
 

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/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.1"
+  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.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2026-02-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -125,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: []