xdg 7.1.3 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1e5dcb9770dd9c770688a728dd49794579afbd3aaa033ec0d960a0080973086
-  data.tar.gz: 998ac4ed5c5460eb0bdae01621fcba4d4729daf3fca3976305f854f68821cacf
+  metadata.gz: a5ba853f70091e4dba915e9ef34a112bffe535bbe0c8fd0836101d35f98a7372
+  data.tar.gz: 987ec6392ec13cdb03bc8cf7cbc7348c9bfa33a69c67936d4a61f4914557aaab
 SHA512:
-  metadata.gz: 89a24c2391d201d63f03a465b3c91ff0b38aebe89e474a2102a58df819a5d11ac07aa8115144378711afd32e22a3f732f45383d32dc2f2ddaae7b0df93d64e9e
-  data.tar.gz: f1ad7240dcbfeddadd59066bac9a23d190a31ff46ea74a0ed0df3b1e8258d0b6c62f0c65dd06e3db19aac403d4b570f85b8988aa2b96747fff9e1fe7d5dcd81c
+  metadata.gz: 15218c612f1ca1bf9ad52bbdc3dc1fb0007383b99d62233fcf3a4aa8302f24281261ed9447f1f8b4d1f5fa9e3ea785155469f0403d919a6fbedc8011958414f1
+  data.tar.gz: 3b8d5106b0610e471e45e9370762a2f85eabc40dabc08ddc0b307fde81907ac53eba8e06b3b9c15ab55bde49696a5c892a5b6b05f86373e41fb94c1cb3f03158

data/README.adoc

@@ -2,13 +2,15 @@
 :toclevels: 5
 :figure-caption!:
 
+:dotfiles_link: link:https://alchemists.io/projects/dotfiles[Dotfiles]
+:runcom_link: link:https://alchemists.io/projects/runcom[Runcom]
+:sod_link: link:https://alchemists.io/projects/sod[Sod]
+
 = XDG
 
-Provides a Ruby implementation of the link:https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory
-Specification] for managing common configurations without polluting your dotfiles. XDG is great for command line interfaces or any application that needs a common configuration, cache, data, state, or runtime.
+Provides a Ruby implementation of the link:https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification] for managing common configurations without polluting your {dotfiles_link}. XDG is great for command line interfaces or any application that needs a common configuration, cache, data, state, or runtime.
 
-💡 If you write a lot of Command Line Interfaces and would like additional/advanced syntactic sugar that includes what is found in this gem, make sure to check out the
-link:https://alchemists.io/projects/runcom[Runcom] gem too.
+💡 If you write a lot of Command Line Interfaces (CLIs) and would like additional behavior built atop this gem, then check out the {runcom_link} gem or the more advanced {sod_link} gem.
 
 toc::[]
 
@@ -77,7 +79,7 @@ xdg.data_dirs    # Answers computed `$XDG_DATA_DIRS` value.
 xdg.state_home   # Answers computed `$XDG_STATE_HOME` value.
 ----
 
-Behinds the scenes, use of `XDG.new` provides a convenient wrapper of `XDG::Environment.new` which, in turn, provides a unified API to the following objects:
+Behinds the scenes, use of `XDG.new` wraps `XDG::Environment.new` which provides a unified Object API to the following objects:
 
 [source,ruby]
 ----
@@ -89,63 +91,79 @@ state = XDG::State.new
 
 Generally, use of `XDG.new` is all you need but knowing you can create a specialized instance of any aspect of the XDG specification can be handy for specific use cases. Additionally, the `cache`, `config`, `data`, and `state` objects share the same API which means you can send the following messages:
 
-* `#home` - Answers the home directory as computed via the `$XDG_*_HOME` key.
-* `#directories` - Answers an array directories as computed via the `$XDG_*_DIRS` key.
-* `#all` - Answers an array of _all_ directories as computed from the combined `$XDG_*_HOME` and
+* `#home`: Answers the home directory as computed via the `$XDG_*_HOME` key.
+* `#directories`: Answers an array directories as computed via the `$XDG_*_DIRS` key.
+* `#all`: Answers an array of _all_ directories as computed from the combined `$XDG_*_HOME` and
   `$XDG_*_DIRS` values (with `$XDG_*_HOME` prefixed at the start of the array).
+* `#to_s`: Answers an _explicit_ string cast for the current environment.
+* `#to_str`: Answers an _implicit_ string cast for the current environment.
+* `#inspect`: Answers object inspection complete with object type, object ID, and all environment variables.
 
 The _computed_ value of each method is either the user-defined value of the key or the default value, per specification, when the key is not defined or empty. For more on this, scroll down to the _Variable Defaults_ section to learn more.
 
 === Examples
 
-The following are examples of what you would see when playing around with the XDG objects within an
-IRB console (taken from my own environment):
+The following are examples of what you will see when exploring the XDG objects within an IRB console:
 
 [source,ruby]
 ----
 require "xdg"
 
 # Initialization
+
 xdg = XDG.new
 cache = XDG::Cache.new
 config = XDG::Config.new
 data = XDG::Data.new
 state = XDG::State.new
 
-# Inspection
-xdg.inspect         # "XDG_CACHE_HOME=/Users/demo/.cache XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share XDG_STATE_HOME=/Users/demo/.local/state"
-cache.inspect       # "XDG_CACHE_HOME=/Users/demo/.cache"
-config.inspect      # "XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg"
-data.inspect        # "XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share"
-state.inspect       # "XDG_STATE_HOME=/Users/demo/.local/state"
-
 # Paths
-xdg.cache_home      # #<Pathname:/Users/demo/.cache>
-xdg.config_home     # #<Pathname:/Users/demo/.config>
-xdg.config_dirs     # [#<Pathname:/etc/xdg>]
-xdg.data_home       # #<Pathname:/Users/demo/.local/share>
-xdg.data_dirs       # [#<Pathname:/usr/local/share>, #<Pathname:/usr/share>]
-xdg.state_home      # #<Pathname:/Users/demo/.local/state>
-
-cache.home          # #<Pathname:/Users/demo/.cache>
+
+xdg.cache_home      # "#<Pathname:/Users/demo/.cache>"
+xdg.config_home     # "#<Pathname:/Users/demo/.config>"
+xdg.config_dirs     # ["#<Pathname:/etc/xdg>"]
+xdg.data_home       # "#<Pathname:/Users/demo/.local/share>"
+xdg.data_dirs       # ["#<Pathname:/usr/local/share>", "#<Pathname:/usr/share>"]
+xdg.state_home      # "#<Pathname:/Users/demo/.local/state>"
+
+cache.home          # "#<Pathname:/Users/demo/.cache>"
 cache.directories   # []
-cache.all           # [#<Pathname:/Users/demo/.cache>]
+cache.all           # ["#<Pathname:/Users/demo/.cache>"]
 
-config.home         # #<Pathname:/Users/demo/.config>
-config.directories  # [#<Pathname:/etc/xdg>]
-config.all          # [#<Pathname:/Users/demo/.config>, #<Pathname:/etc/xdg>]
+config.home         # "#<Pathname:/Users/demo/.config>"
+config.directories  # ["#<Pathname:/etc/xdg>"]
+config.all          # ["#<Pathname:/Users/demo/.config>", "#<Pathname:/etc/xdg>"]
 
-data.home           # #<Pathname:/Users/demo/.local/share>
-data.directories    # [#<Pathname:/usr/local/share>, #<Pathname:/usr/share>]
-data.all            # [#<Pathname:/Users/demo/.local/share>, #<Pathname:/usr/local/share>, #<Pathname:/usr/share>]
+data.home           # "#<Pathname:/Users/demo/.local/share>"
+data.directories    # ["#<Pathname:/usr/local/share>", "#<Pathname:/usr/share>"]
+data.all            # ["#<Pathname:/Users/demo/.local/share>", "#<Pathname:/usr/local/share>", "#<Pathname:/usr/share>"]
 
-state.home          # #<Pathname:/Users/demo/.local/state>
+state.home          # "#<Pathname:/Users/demo/.local/state>"
 state.directories   # []
-state.all           # [#<Pathname:/Users/demo/.local/state>]
-----
+state.all           # ["#<Pathname:/Users/demo/.local/state>"]
+
+# Casts (explicit and implicit)
+
+xdg.to_s            # "XDG_CACHE_HOME=/Users/demo/.cache XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share XDG_STATE_HOME=/Users/demo/.local/state"
+cache.to_s          # "XDG_CACHE_HOME=/Users/demo/.cache"
+config.to_s         # "XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg"
+data.to_s           # "XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share"
+state.to_s          # "XDG_STATE_HOME=/Users/demo/.local/state"
 
-As you can see from above, each XDG object answers back a `Pathname` which means you have the full
-`Pathname` API at your fingertips to build upon the output of these objects as needed.
+xdg.to_str          # "XDG_CACHE_HOME=/Users/demo/.cache XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share XDG_STATE_HOME=/Users/demo/.local/state"
+cache.to_str        # "XDG_CACHE_HOME=/Users/demo/.cache"
+config.to_str       # "XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg"
+data.to_str         # "XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share"
+state.to_str        # "XDG_STATE_HOME=/Users/demo/.local/state"
+
+# Inspection
+
+xdg.inspect         # "#<XDG::Environment:2020 XDG_CACHE_HOME=/Users/demo/.cache XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share XDG_STATE_HOME=/Users/demo/.local/state>"
+cache.inspect       # "#<XDG::Cache:2040 XDG_CACHE_HOME=/Users/demo/.cache>"
+config.inspect      # "#<XDG::Config:2060 XDG_CONFIG_HOME=/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg>"
+data.inspect        # "#<XDG::Data:2080 XDG_DATA_HOME=/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share>"
+state.inspect       # "#<XDG::State:2100 XDG_STATE_HOME=/Users/demo/.local/state>"
+----
 
 === Variable Defaults
 
@@ -161,9 +179,7 @@ objects:
 * `$XDG_RUNTIME_DIR`
 * `$XDG_STATE_HOME="$HOME/.local/state"`
 
-The `$XDG_RUNTIME_DIR` deserves special mention as it’s not, _currently_, implemented as part of
-this gem because it is more user/environment specific. Here is how the `$XDG_RUNTIME_DIR` is meant
-to be used should you choose to use it:
+The `$XDG_RUNTIME_DIR` environment variable deserves special mention because it’s not, _currently_, implemented as part of this gem because it is more user/environment specific. Here is how the `$XDG_RUNTIME_DIR` is meant to be used should you choose to use it:
 
 * _Must_ reference user-specific non-essential runtime files and other file objects (such as
 sockets, named pipes, etc.)
@@ -204,21 +220,21 @@ example, here is a situation where the `XDG_CONFIG_DIRS` key has a custom value:
 
 [source,bash]
 ----
-XDG_CONFIG_DIRS="/example/one/.config:/example/two/.settings:/example/three/.configuration"
+XDG_CONFIG_DIRS="/demo/one/.config:/demo/two/.settings:/demo/three/.configuration"
 ----
 
-Yields the following, colon delimited, array:
+The above then yields the following, colon delimited, array:
 
 [source,ruby]
 ----
 [
-  "/example/one/.config",
-  "/example/two/.settings",
-  "/example/three/.configuration"
+  "/demo/one/.config",
+  "/demo/two/.settings",
+  "/demo/three/.configuration"
 ]
 ----
 
-In the above example, the `"/example/one/.config"` path takes _highest_ priority since it was
+In the above example, the `"/demo/one/.config"` path takes _highest_ priority since it was
 defined first.
 
 ==== Homes
@@ -228,23 +244,23 @@ a modified version of the `$XDG_*_DIRS` example, shown above, we could have the
 
 [source,bash]
 ----
-XDG_CONFIG_HOME="/example/priority"
-XDG_CONFIG_DIRS="/example/one/.config:/example/two/.settings"
+XDG_CONFIG_HOME="/demo/priority"
+XDG_CONFIG_DIRS="/demo/one/.config:/demo/two/.settings"
 ----
 
-Yields the following, colon delimited, array:
+The above then yields the following, colon delimited, array:
 
 [source,ruby]
 ----
 [
-  "/example/priority",
-  "/example/one/.config",
-  "/example/two/.settings"
+  "/demo/priority",
+  "/demo/one/.config",
+  "/demo/two/.settings"
 ]
 ----
 
 Due to `XDG_CONFIG_HOME` taking precedence over the `XDG_CONFIG_DIRS`, the path with the
-_highest_ priority in this example is: `"/example/priority"`.
+_highest_ priority is: `"/demo/priority"`.
 
 === Variable Priority
 
@@ -272,6 +288,13 @@ You can also use the IRB console for direct access to all objects:
 bin/console
 ----
 
+Lastly, there is a `bin/demo` script which displays default functionality for quick visual reference. This is the same script used to generate the usage examples shown at the top of this document.
+
+[source,bash]
+----
+bin/demo
+----
+
 == Tests
 
 To test, run:

data/lib/xdg/cache.rb

@@ -10,13 +10,15 @@ module XDG
 
     HOME_PAIR = Pair["XDG_CACHE_HOME", ".cache"].freeze
 
-    delegate %i[home directories all inspect] => :combined
+    delegate %i[home directories all to_s to_str] => :combined
 
     def initialize home: Paths::Home, directories: Paths::Directory, environment: ENV
       @combined = Paths::Combined.new home.new(HOME_PAIR, environment),
                                       directories.new(Pair.new, environment)
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
     private
 
     attr_reader :combined

data/lib/xdg/config.rb

@@ -11,13 +11,15 @@ module XDG
     HOME_PAIR = Pair["XDG_CONFIG_HOME", ".config"].freeze
     DIRS_PAIR = Pair["XDG_CONFIG_DIRS", "/etc/xdg"].freeze
 
-    delegate %i[home directories all inspect] => :combined
+    delegate %i[home directories all to_s to_str] => :combined
 
     def initialize home: Paths::Home, directories: Paths::Directory, environment: ENV
       @combined = Paths::Combined.new home.new(HOME_PAIR, environment),
                                       directories.new(DIRS_PAIR, environment)
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
     private
 
     attr_reader :combined

data/lib/xdg/data.rb

@@ -11,13 +11,15 @@ module XDG
     HOME_PAIR = Pair["XDG_DATA_HOME", ".local/share"].freeze
     DIRS_PAIR = Pair["XDG_DATA_DIRS", "/usr/local/share:/usr/share"].freeze
 
-    delegate %i[home directories all inspect] => :combined
+    delegate %i[home directories all to_s to_str] => :combined
 
     def initialize home: Paths::Home, directories: Paths::Directory, environment: ENV
       @combined = Paths::Combined.new home.new(HOME_PAIR, environment),
                                       directories.new(DIRS_PAIR, environment)
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
     private
 
     attr_reader :combined

data/lib/xdg/environment.rb

@@ -22,7 +22,11 @@ module XDG
 
     def state_home = state.home
 
-    def inspect = [cache, config, data, state].map(&:inspect).join " "
+    def to_s = "#{cache} #{config} #{data} #{state}"
+
+    alias to_str to_s
+
+    def inspect = "#<#{self.class}:#{object_id} #{self}>"
 
     private
 

data/lib/xdg/pair.rb

@@ -7,14 +7,21 @@ module XDG
       super
     end
 
-    def to_env = {key => value}
-
     def key? = key.to_s.size.positive?
 
     def value? = value.to_s.size.positive?
 
     def empty? = !(key? && value?)
 
-    def inspect = key? || value? ? "#{key}#{DELIMITER}#{value}" : ""
+    def to_env = {key => value}
+
+    def to_s = key? || value? ? "#{key}#{DELIMITER}#{value}" : ""
+
+    alias_method :to_str, :to_s
+
+    def inspect
+      type = self.class
+      key? || value? ? "#<data #{type} #{key}#{DELIMITER}#{value}>" : "#<data #{type}>"
+    end
   end
 end

data/lib/xdg/paths/combined.rb

@@ -17,7 +17,11 @@ module XDG
 
       def all = directories.prepend(*home)
 
-      def inspect = [initial_home.inspect, initial_directories.inspect].reject(&:empty?).join " "
+      def to_s = [initial_home.to_s, initial_directories.to_s].reject(&:empty?).join " "
+
+      alias to_str to_s
+
+      def inspect = "#<#{self.class}:#{object_id} #{self}>"
 
       private
 

data/lib/xdg/paths/directory.rb

@@ -22,7 +22,16 @@ module XDG
                                 .map { |path| expand path }
       end
 
-      def inspect = [key, dynamic.join(DELIMITER)].reject(&:empty?).join XDG::DELIMITER
+      def to_s = [key, dynamic.join(DELIMITER)].reject(&:empty?).join XDG::DELIMITER
+
+      alias to_str to_s
+
+      def inspect
+        pairs = to_s
+        type = self.class
+
+        pairs.empty? ? "#<#{type}:#{object_id}>" : "#<#{type}:#{object_id} #{self}>"
+      end
 
       private
 

data/lib/xdg/paths/home.rb

@@ -22,7 +22,11 @@ module XDG
 
       def dynamic = String(environment[key]).then { |path| path.empty? ? default : expand(path) }
 
-      def inspect = [pair.key, dynamic].compact.join XDG::DELIMITER
+      def to_s = [pair.key, dynamic].compact.join XDG::DELIMITER
+
+      alias to_str to_s
+
+      def inspect = "#<#{self.class}:#{object_id} #{self}>"
 
       private
 

data/lib/xdg/state.rb

@@ -10,13 +10,15 @@ module XDG
 
     HOME_PAIR = Pair["XDG_STATE_HOME", ".local/state"].freeze
 
-    delegate %i[home directories all inspect] => :combined
+    delegate %i[home directories all to_s to_str] => :combined
 
     def initialize home: Paths::Home, directories: Paths::Directory, environment: ENV
       @combined = Paths::Combined.new home.new(HOME_PAIR, environment),
                                       directories.new(Pair.new, environment)
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
     private
 
     attr_reader :combined

data/xdg.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "xdg"
-  spec.version = "7.1.3"
+  spec.version = "8.0.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/xdg"
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.signing_key = Gem.default_key_path
   spec.cert_chain = [Gem.default_cert_path]
 
-  spec.required_ruby_version = [">= 3.2", "<= 3.3"]
+  spec.required_ruby_version = "~> 3.3"
 
   spec.files = Dir["*.gemspec", "lib/**/*"]
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

data.tar.gz.sig

@@ -1,3 +1,4 @@
->$�9�ݪ��B��"�O��_��}��M_�s%�B$;�#8i�hg����`�"�w�]:������l�9
-��
��G�g���mr��ӍH��/d8��!���9�
r�{�>��d��9��	B���d�K�e	�|2~|��|���1Ӕ_x��'e��W�~���We��r/�6�h��J!��4�����O�s2�;�
-Ϸ9�	�e
�
ׅ��6
+�E�p%b�;�֎UJ�g�G���_0��=�QU�GN}��Y�]sj�[G%�FUއ��B���������s'��Am	�r9
+W:��9�=`��+�2���J"�ܙ����Jn��U��،;��t��d\�&C��h���[]���1����-^Lm��Y*i{<�m�F����T�
+�+�.��78��3A�����b:�m#�%v��r�kg�ò3x@
+2������RaZDž���~�k�x�pF7�h��N�B�MW�B�M���.��?�!�.�6i��咒�rQ�tѐ��CL�$q�/�(���+S��x�^Nm�F�+ JUW�WH��d����<�群N����c

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xdg
 version: !ruby/object:Gem::Version
-  version: 7.1.3
+  version: 8.0.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-11-16 00:00:00.000000000 Z
+date: 2024-01-01 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -76,10 +76,7 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
-    - !ruby/object:Gem::Version
-      version: '3.2'
-  - - "<="
+  - - "~>"
     - !ruby/object:Gem::Version
       version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -88,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: A XDG Base Directory Specification implementation.