fat_config 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41cf78034335f9fd05433c7058f26fff973575eb0b6becf4f501a15027905c9c
-  data.tar.gz: 6987287fa5d625c0c97c1427add4d7777dea525100d220b8f28241720b85b340
+  metadata.gz: 3d987b854bd4105f55ead3efbc73a77a1e168b4c5bcfc6caa487e248463df95e
+  data.tar.gz: 8d65e3589a6402eb4f4fa374a815ffad56902162d4f0e107c0ef6f676ed39252
 SHA512:
-  metadata.gz: b55c2816b7c7402a751242af54e6e6cf54c4b67965e1b276f743c8a4ae991c6e7752c62ca5ff27a69e64eab2b2eb6bb1c8573c4ec3e3a57d5b4eae072e2813aa
-  data.tar.gz: 5d8c20611e05bd4af1745fa00dd1e83295c066fa53d40d3e955df032aa71cf144c5331298f42740d0e26b06f94e5a2a2838a875614a1b8685405d427f269023c
+  metadata.gz: f19a80712d34593aa39ebf5f5763a48aa5cce085b721b90a6a591417da9ce878c466800938f482aa88b5c6dac4c2ebdfb2250c7d798e8a0a8cbf415867e8b353
+  data.tar.gz: 0c8575cf4ffc410eba8c6d14e194e802f0e8505f266e0e08e4a63c7905c2cd5c2c184c6114b870bcec8b86dc56758035a4a8c8b2c5d48fbb871e17423224e073

data/README.md

@@ -1,26 +1,26 @@
-- [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)
+- [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)
   - [Parsing Environment and Command Line Strings](#parsing-environment-and-command-line-strings)
-- [Development](#org1fdfa48)
-- [Contributing](#org4454a76)
-- [License](#org8a2eaa6)
+- [Development](#orgadf9605)
+- [Contributing](#org00f8770)
+- [License](#orgbb61eac)
 
 [![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>
+<a id="org6ea1400"></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="org3f8a5fd"></a>
+<a id="org0bfc9c4"></a>
 
 # Installation
 
@@ -46,7 +46,7 @@ gem install fat_config
 ```
 
 
-<a id="org5c5fe0f"></a>
+<a id="orgb03325f"></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="org7e6640a"></a>
+<a id="orgcc49e5b"></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="orgbc610e8"></a>
+<a id="orgb094a10"></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="orgacf5ac1"></a>
+<a id="org77efd19"></a>
 
 ## Available Config File Styles
 
@@ -115,24 +115,28 @@ 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="orgf87b1a5"></a>
+<a id="org2489659"></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' }`.
+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.
 
-<a id="org451482b"></a>
+
+<a id="org3c327fd"></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:
+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="orgef8563a"></a>
+<a id="org47246cf"></a>
 
 ### 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)
@@ -144,10 +148,12 @@ Whether the values of the returned Hash will be 'deserialized' into a Ruby objec
 -   Date, DateTime, and Time, which FatConfig adds to the foregoing default types deserialized by the default YAML library.
 
 
-<a id="orgcf8804e"></a>
+<a id="orgcd934bb"></a>
 
 ### 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&#x2026; or 0o&#x2026; hex or octal)
@@ -158,10 +164,12 @@ Whether the values of the returned Hash will be 'deserialized' into a Ruby objec
 -   Date and Time, when given in ISO form YYYY-MM-DD or YYYY-MM-DDThh:mm:ss
 
 
-<a id="org549e838"></a>
+<a id="orge3c0568"></a>
 
 ### 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 or octal)
@@ -172,10 +180,12 @@ Whether the values of the returned Hash will be 'deserialized' into a Ruby objec
 -   Date and Time, NOT deserialized, returns a parse error
 
 
-<a id="org12513cc"></a>
+<a id="org479cf72"></a>
 
 ### 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&#x2026; or 0o&#x2026; hex or octal)
@@ -186,7 +196,7 @@ Whether the values of the returned Hash will be 'deserialized' into a Ruby objec
 -   Date and Time, NOT deserialized, returned as a String
 
 
-<a id="org7a0f2a9"></a>
+<a id="org195ed64"></a>
 
 ## Creating a Reader
 
@@ -203,7 +213,7 @@ reader3 = FatConfig.new('labrat', style: 'ini', xdg: false)  # Use classic UNIX
 ```
 
 
-<a id="org7e439f9"></a>
+<a id="org0c26613"></a>
 
 ## Calling the `read` method on a `Reader`
 
@@ -266,7 +276,7 @@ Here are the parsing rules:
 4.  These rules apply regardless of style being used for config files.
 
 
-<a id="org1fdfa48"></a>
+<a id="orgadf9605"></a>
 
 # Development
 
@@ -275,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="org4454a76"></a>
+<a id="org00f8770"></a>
 
 # Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/ddoherty03/fat_config>.
 
 
-<a id="org8a2eaa6"></a>
+<a id="orgbb61eac"></a>
 
 # License
 

data/lib/fat_config/errors.rb

@@ -1,5 +1,78 @@
-# frozen_string_literal: true
-
+# in fat_config/parse_error.rb (or wherever ParseError lives)
 module FatConfig
-  class ParseError < StandardError; end
+  class ParseError < StandardError
+    attr_reader :file, :format, :line, :column, :problem, :context, :snippet
+
+    def initialize(file:, format:, problem:, line: nil, column: nil, context: nil, snippet: nil)
+      @file = file
+      @format = format
+      @problem = problem
+      @line = line
+      @column = column
+      @context = context
+      @snippet = snippet
+      super(build_message)
+    end
+
+    def self.snippet_from_string(str, line:, column:)
+      snippet = nil
+
+      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
+      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)
+      end
+
+      snippet
+    end
+
+    private
+
+    def build_message
+      loc =
+        if line && column
+          " at line #{line}, column #{column}"
+        elsif line
+          " at line #{line}"
+        else
+          ""
+        end
+
+      msg = +"#{format.to_s.upcase} parse error in #{file}#{loc}: #{problem}"
+
+      if snippet && !snippet.empty?
+        msg << "\n\n#{snippet}"
+      end
+
+      if context && !context.empty?
+        msg << "\n\n#{context}"
+      end
+
+      msg
+    end
+  end
 end

data/lib/fat_config/styles/ini_style.rb

@@ -5,31 +5,80 @@ module FatConfig
     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 = Tempfile.create
-      File.write(tmp_path, str)
-      load_file(tmp_path)
+      tmp = Tempfile.create("fat_config_ini")
+      tmp.write(str)
+      tmp.flush
+      load_file(tmp.path)
     rescue IniFile::Error => ex
-      raise FatConfig::ParseError, ex.to_s
+      snippet = snippet_from_inifile_error(ex)
+      raise(
+        ParseError.new(
+          file: "string",
+          format: :ini,
+          problem: ex.message,
+          line: nil,
+          column: nil,
+          context: nil,
+          snippet: snippet,
+        ),
+        cause: ex,
+      )
     end
 
     def load_file(file_name)
       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
+        config[sec.to_sym] =
+          case ini[sec]
+          when Hash
+            ini[sec].methodize
+          else
+            ini[sec]
+          end
       end
       config
     rescue IniFile::Error => ex
-      raise FatConfig::ParseError, ex.to_s
+      snippet = snippet_from_inifile_error(ex)
+      raise(
+        ParseError.new(
+          file: file_name,
+          format: :ini,
+          problem: ex.message,
+          line: nil,
+          column: nil,
+          context: nil,
+          snippet: snippet,
+        ),
+        cause: ex,
+      )
     end
 
     def possible_extensions
       super + ['ini']
     end
+
+    private
+
+    # IniFile::Error messages commonly end with the offending line via inspect,
+    # e.g. 'expected "=": "bad line"'. We can at least surface that line.
+    def snippet_from_inifile_error(ex)
+      line_text = nil
+      if ex&.message
+        m = ex.message.match(/:\s*(\".*\"|\'.*\')\s*\z/)
+        if m
+          begin
+            line_text = eval(m[1])
+          rescue StandardError
+            line_text = m[1]
+          end
+        end
+      end
+      snippet = nil
+      if line_text && !line_text.empty?
+        snippet = +"#{line_text}\n^\n"
+      end
+      snippet
+    end
   end
 end

data/lib/fat_config/styles/json_style.rb

@@ -2,18 +2,58 @@
 
 module FatConfig
   class JSONStyle < Style
-    def load_string(str)
-      JSON.parse(str, symbolize_name: true).methodize
+    def load_string(str, file: 'string')
+      JSON.parse(str).methodize
     rescue JSON::ParserError => ex
-      raise FatConfig::ParseError, ex.to_s
+      line, column = extract_line_column(ex.message)
+      snippet =
+        if line
+          ParseError.snippet_from_string(str, line: line, column: column)
+        end
+      raise(
+        ParseError.new(
+          file: file,
+          format: :json,
+          problem: ex.message,
+          line: line,
+          column: column,
+          context: nil,
+          snippet: snippet,
+        ),
+        cause: ex,
+      )
     end
 
     def load_file(file_name)
-      load_string(File.read(file_name))
+      str = File.read(file_name, encoding: "UTF-8")
+      load_string(str, file: file_name)
     end
 
     def possible_extensions
       super + ['json']
     end
+
+    private
+
+    # Best-effort: Ruby JSON error messages commonly include
+    # "... at line 3, column 12"
+    def extract_line_column(message)
+      line = nil
+      column = nil
+
+      if message
+        m = message.match(/line\s+(\d+)\s+.*column\s+(\d+)/i)
+        if m
+          line = m[1].to_i
+          column = m[2].to_i
+        else
+          m2 = message.match(/line\s+(\d+)/i)
+          if m2
+            line = m2[1].to_i
+          end
+        end
+      end
+      [line, column]
+    end
   end
 end

data/lib/fat_config/styles/toml_style.rb

@@ -2,18 +2,83 @@
 
 module FatConfig
   class TOMLStyle < Style
-    def load_string(str)
-      Tomlib.load(str)&.methodize
+    def load_string(str, file: "string")
+      data = Tomlib.load(str)
+      data ||= {}
+      data.methodize
     rescue Tomlib::ParseError => ex
-      raise FatConfig::ParseError, ex.to_s
+      line, column, problem, context = extract_error(ex)
+      snippet =
+        if line
+          ParseError.snippet_from_string(str, line: line, column: column)
+        end
+      raise(
+        ParseError.new(
+          file: file,
+          format: :toml,
+          problem: problem || ex.message,
+          line: line,
+          column: column,
+          context: context,
+          snippet: snippet,
+        ),
+        cause: ex,
+      )
     end
 
     def load_file(file_name)
-      load_string(File.read(file_name))
+      str = File.read(file_name, encoding: "UTF-8")
+      data = load_string(str, file: file_name)
+      data
     end
 
     def possible_extensions
       super + ['toml']
     end
+
+    private
+
+    def extract_error(ex)
+      line = nil
+      column = nil
+      context = nil
+
+      if ex.respond_to?(:line)
+        v = ex.line
+        line = v.to_i if v
+      elsif ex.respond_to?(:lineno)
+        v = ex.lineno
+        line = v.to_i if v
+      end
+
+      if ex.respond_to?(:column)
+        v = ex.column
+        column = v.to_i if v
+      elsif ex.respond_to?(:colno)
+        v = ex.colno
+        column = v.to_i if v
+      end
+
+      problem =
+        if ex.respond_to?(:problem)
+          ex.problem
+        else
+          ex.message
+        end
+
+      context = ex.context if ex.respond_to?(:context)
+
+      if (line.nil? || column.nil?) && ex.message
+        m = ex.message.match(/line\s+(\d+)\s*,?\s*(?:col(?:umn)?|column)\s+(\d+)/i)
+        if m
+          line ||= m[1].to_i
+          column ||= m[2].to_i
+        else
+          m2 = ex.message.match(/line\s+(\d+)/i)
+          line ||= m2[1].to_i if m2
+        end
+      end
+      [line, column, problem, context]
+    end
   end
 end

data/lib/fat_config/styles/yaml_style.rb

@@ -41,7 +41,19 @@ module FatConfig
         {}
       end
     rescue Psych::SyntaxError => ex
-      raise FatConfig::ParseError, ex.to_s
+      snippet = ParseError.snippet_from_string(str, line: ex.line, column: ex.column)
+      raise(
+        ParseError.new(
+          file: "string",
+          format: :yaml,
+          line: ex.line,
+          column: ex.column,
+          problem: ex.problem,
+          context: ex.context,
+          snippet: snippet,
+        ),
+        cause: ex,
+      )
     end
 
     def load_file(file_name)
@@ -60,7 +72,19 @@ module FatConfig
         {}
       end
     rescue Psych::SyntaxError => ex
-      raise FatConfig::ParseError, ex.to_s
+      snippet = ParseError.snippet_from_file(file_name, line: ex.line, column: ex.column)
+      raise(
+        ParseError.new(
+          file: file_name,
+          format: :yaml,
+          line: ex.line,
+          column: ex.column,
+          problem: ex.problem,
+          context: ex.context,
+          snippet: snippet,
+        ),
+        cause: ex,
+      )
     end
 
     def possible_extensions

data/lib/fat_config/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fat_config
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -123,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Library to read config from standard XDG or classic locations.
 test_files: []