xdg 10.2.0 → 10.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06a31c24e4993631bea67617b8aa4eb633a4c03cf2aabb31f07a6fbde8167831
-  data.tar.gz: deecaff5b5d508b5a5dc0c101987be209fde0adbc819a4bcf690964c13917473
+  metadata.gz: dff59b5802f4d0b6bd151e03e62e04de6313f7735f5d49e888922583156fc752
+  data.tar.gz: 96fff0863fbf4a5df4f7b52d77e488b967adbfc4b1e6c04bd865e6d8bd424110
 SHA512:
-  metadata.gz: 7f63c2819b381f97f44c6c097a6ee6cf92e391697c7cdc4af805ea8a63963fc5e6bbb14f7761dcde635b7154df7892c3f9d503e90773bd14a6cb2bcc4b469dc5
-  data.tar.gz: fa2201aedde553dc595fe9e02ed1f99f40af46eac8bac93a392c9d1c653627bc80c905b65a9138eed7f8e88e0094a5f08db8c3c978d90444ac6ae742d1c8f957
+  metadata.gz: ddf7eab480fde881d5c91cab56439eae63949b25c8acd8e449ef1660d132bd7792e8aebcdf11a5ee1bf5962b7b5b6e012cf3b3e9524ca18d24b4a4794f38623d
+  data.tar.gz: 77615ccaa6169c1bafc9851dd62fd28d78408859196fb811e5c50ffb66037205391483a44af3c89f109a3cdd34a0141dad3edb156aa852637bec1e734565388c

data/README.adoc

@@ -16,13 +16,14 @@ toc::[]
 
 == Features
 
-* Provides a `XDG` object that adheres to the _XDG Base Directory Specification_ with access to the following environment settings:
-** `$XDG_CACHE_HOME`
-** `$XDG_CONFIG_HOME`
-** `$XDG_CONFIG_DIRS`
-** `$XDG_DATA_HOME`
-** `$XDG_DATA_DIRS`
-** `$XDG_STATE_HOME`
+* Provides a `XDG` object that adheres to the _XDG Base Directory Specification_ with access to the following environment variables:
+** `XDG_CACHE_HOME`
+** `XDG_CONFIG_HOME`
+** `XDG_CONFIG_DIRS`
+** `XDG_DATA_HOME`
+** `XDG_DATA_DIRS`
+** `XDG_RUNTIME_DIR`
+** `XDG_STATE_HOME`
 
 == Requirements
 
@@ -71,12 +72,13 @@ To get up and running quickly, use `XDG.new` as follows:
 [source,ruby]
 ----
 xdg = XDG.new
-xdg.cache_home   # Answers computed `$XDG_CACHE_HOME` value.
-xdg.config_home  # Answers computed `$XDG_CONFIG_HOME` value.
-xdg.config_dirs  # Answers computed `$XDG_CONFIG_DIRS` value.
-xdg.data_home    # Answers computed `$XDG_DATA_HOME` value.
-xdg.data_dirs    # Answers computed `$XDG_DATA_DIRS` value.
-xdg.state_home   # Answers computed `$XDG_STATE_HOME` value.
+xdg.cache_home   # Answers computed `XDG_CACHE_HOME` value.
+xdg.config_home  # Answers computed `XDG_CONFIG_HOME` value.
+xdg.config_dirs  # Answers computed `XDG_CONFIG_DIRS` value.
+xdg.data_home    # Answers computed `XDG_DATA_HOME` value.
+xdg.data_dirs    # Answers computed `XDG_DATA_DIRS` value.
+xdg.runtime_dir  # Answers computed `XDG_RUNTIME_DIR` value.
+xdg.state_home   # Answers computed `XDG_STATE_HOME` value.
 ----
 
 Behinds the scenes, use of `XDG.new` wraps `XDG::Environment.new` which provides a unified Object API to the following objects:
@@ -86,15 +88,16 @@ Behinds the scenes, use of `XDG.new` wraps `XDG::Environment.new` which provides
 cache = XDG::Cache.new
 config = XDG::Config.new
 data = XDG::Data.new
+runtime = XDG::Runtime.new
 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
-  `$XDG_*_DIRS` values (with `$XDG_*_HOME` prefixed at the start of the array).
+* `#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.
@@ -115,54 +118,63 @@ xdg = XDG.new
 cache = XDG::Cache.new
 config = XDG::Config.new
 data = XDG::Data.new
+runtime = XDG::Runtime.new
 state = XDG::State.new
 
 # 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>"
-cache.directories   # []
-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>"]
-
-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.directories   # []
-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"
-
-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"
+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.runtime_dir      # "#<Pathname:>"
+xdg.state_home       # "#<Pathname:/Users/demo/.local/state>"
+
+cache.home           # "#<Pathname:/Users/demo/.cache>"
+cache.directories    # []
+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>"]
+
+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>"]
+
+runtime.home         # "#<Pathname:>"
+runtime.directories  # []
+runtime.all          # ["#<Pathname:>"]
+
+state.home           # "#<Pathname:/Users/demo/.local/state>"
+state.directories    # []
+state.all            # ["#<Pathname:/Users/demo/.local/state>"]
+
+# Strings (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_RUNTIME_DIR= 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"
+runtime.to_s         # "XDG_RUNTIME_DIR="
+state.to_s           # "XDG_STATE_HOME=/Users/demo/.local/state"
+
+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_RUNTIME_DIR= 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"
+runtime.to_str       # "XDG_RUNTIME_DIR="
+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>"
+xdg.inspect          # "#<XDG::Environment:1456 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_RUNTIME_DIR= 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>"
+runtime.inspect      # "#<XDG::Runtime:1496 XDG_RUNTIME_DIR=>"
+state.inspect        # "#<XDG::State:2100 XDG_STATE_HOME=/Users/demo/.local/state>"
 ----
 
 === Variable Defaults
@@ -171,15 +183,15 @@ The _XDG Base Directory Specification_ defines environment variables and associa
 when not defined or empty. The following defaults, per specification, are implemented by the `XDG`
 objects:
 
-* `$XDG_CACHE_HOME="$HOME/.cache"`
-* `$XDG_CONFIG_HOME="$HOME/.config"`
-* `$XDG_CONFIG_DIRS="/etc/xdg"`
-* `$XDG_DATA_HOME="$HOME/.local/share"`
-* `$XDG_DATA_DIRS="/usr/local/share/:/usr/share/"`
-* `$XDG_RUNTIME_DIR`
-* `$XDG_STATE_HOME="$HOME/.local/state"`
+* `XDG_CACHE_HOME="$HOME/.cache"`
+* `XDG_CONFIG_HOME="$HOME/.config"`
+* `XDG_CONFIG_DIRS="/etc/xdg"`
+* `XDG_DATA_HOME="$HOME/.local/share"`
+* `XDG_DATA_DIRS="/usr/local/share/:/usr/share/"`
+* `XDG_RUNTIME_DIR=`
+* `XDG_STATE_HOME="$HOME/.local/state"`
 
-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:
+The `XDG_RUNTIME_DIR` environment variable deserves special mention because it is more user/environment specific and has no default value. Here is how `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.)
@@ -205,13 +217,18 @@ memory and cannot necessarily be swapped out to disk.
 
 === Variable Behavior
 
-The behavior of most XDG environment variables can be lumped into two categories:
+The behavior of the XDG environment variables can be broken down by category:
 
-* `$XDG_*_DIRS`
-* `$XDG_*_HOME`
+* `+XDG_*_DIR+`
+* `+XDG_*_DIRS+`
+* `+XDG_*_HOME+`
 
 Each is described in detail below.
 
+==== Directory
+
+The `+XDG_*_DIR+` category is unique in that it is specific to the `XDG_RUNTIME_DIR` and has no default value. This directory must adhere to all of the `XDG_RUNTIME_DIR` requirements as documented above.
+
 ==== Directories
 
 These variables are used to define a colon (`:`) delimited list of directories. Order is important
@@ -237,10 +254,10 @@ The above then yields the following, colon delimited, array:
 In the above example, the `"/demo/one/.config"` path takes _highest_ priority since it was
 defined first.
 
-==== Homes
+==== Home
 
-These variables take precedence over the corresponding `$XDG_*_DIRS` environment variables. Using
-a modified version of the `$XDG_*_DIRS` example, shown above, we could have the following setup:
+These variables take precedence over the corresponding `+XDG_*_DIRS+` environment variables. Using
+a modified version of the `+XDG_*_DIRS+` example, shown above, we could have the following setup:
 
 [source,bash]
 ----
@@ -266,8 +283,8 @@ _highest_ priority is: `"/demo/priority"`.
 
 Path precedence is determined in the following order (with the first taking highest priority):
 
-. `$XDG_*_HOME` - Will be used if defined. Otherwise, falls back to specification default.
-. `$XDG_*_DIRS` - Iterates through directories in order defined (with first taking highest
+. `+XDG_*_HOME+` - Will be used if defined. Otherwise, falls back to specification default.
+. `+XDG_*_DIRS+` - Iterates through directories in order defined (with first taking highest
   priority). Otherwise, falls back to specification default.
 
 == Development

data/lib/xdg/environment.rb

@@ -7,6 +7,7 @@ module XDG
       @cache = Cache.new(home:, directories:, environment:)
       @config = Config.new(home:, directories:, environment:)
       @data = Data.new(home:, directories:, environment:)
+      @runtime = Runtime.new(environment:)
       @state = State.new(home:, directories:, environment:)
       freeze
     end
@@ -21,9 +22,11 @@ module XDG
 
     def data_dirs = data.directories
 
+    def runtime_dir = runtime.home
+
     def state_home = state.home
 
-    def to_s = "#{cache} #{config} #{data} #{state}"
+    def to_s = "#{cache} #{config} #{data} #{runtime} #{state}"
 
     alias to_str to_s
 
@@ -31,6 +34,6 @@ module XDG
 
     private
 
-    attr_reader :cache, :config, :data, :state
+    attr_reader :cache, :config, :data, :runtime, :state
   end
 end

data/lib/xdg/paths/any.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module XDG
+  module Paths
+    # A XDG any path.
+    class Any
+      extend Forwardable
+
+      delegate %i[key value] => :pair
+
+      def initialize pair, environment = ENV
+        @pair = pair
+        @environment = environment
+        freeze
+      end
+
+      def default = expand String(value)
+
+      def dynamic = String(environment[key]).then { |path| path.empty? ? default : expand(path) }
+
+      def to_s = [pair.key, dynamic].compact.join XDG::DELIMITER
+
+      alias to_str to_s
+
+      def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
+      protected
+
+      attr_reader :pair, :environment
+
+      def expand(path) = Pathname(path).then { path.empty? ? it : it.expand_path }
+    end
+  end
+end

data/lib/xdg/paths/directory.rb

@@ -3,15 +3,9 @@
 module XDG
   module Paths
     # A collection of XDG directories.
-    class Directory
+    class Directory < Any
       DELIMITER = ":"
 
-      def initialize pair, environment = ENV
-        @pair = pair
-        @environment = environment
-        freeze
-      end
-
       def default = value.split(DELIMITER).map { |path| expand path }
 
       def dynamic
@@ -32,15 +26,9 @@ module XDG
         pairs.empty? ? "#<#{type}:#{object_id}>" : "#<#{type}:#{object_id} #{self}>"
       end
 
-      private
-
-      attr_reader :pair, :environment
-
       def key = String pair.key
 
       def value = String pair.value
-
-      def expand(path) = Pathname(path).expand_path
     end
   end
 end

data/lib/xdg/paths/home.rb

@@ -1,40 +1,25 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module XDG
   module Paths
     # A XDG home path.
-    class Home
-      extend Forwardable
-
+    class Home < Any
       KEY = "HOME"
 
-      delegate %i[key value] => :pair
-
-      def initialize pair, environment = ENV
-        @pair = pair
-        @environment = environment
-        freeze
+      def initialize pair, environment = ENV, default_key: KEY
+        @default_key = default_key
+        super(pair, environment)
       end
 
-      def default = expand String(value)
-
-      def dynamic = String(environment[key]).then { |path| path.empty? ? default : expand(path) }
-
-      def to_s = [pair.key, dynamic].compact.join XDG::DELIMITER
+      protected
 
-      alias to_str to_s
+      def expand(path) = home.join(path).expand_path
 
-      def inspect = "#<#{self.class}:#{object_id} #{self}>"
+      def home = Pathname environment.fetch(default_key)
 
       private
 
-      attr_reader :pair, :environment
-
-      def expand(path) = home.join(path).expand_path
-
-      def home = Pathname environment.fetch(KEY)
+      attr_reader :default_key
     end
   end
 end

data/lib/xdg/runtime.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "xdg/pair"
+
+module XDG
+  # Provides runtime support.
+  class Runtime
+    extend Forwardable
+
+    HOME_PAIR = Pair["XDG_RUNTIME_DIR", nil].freeze
+
+    delegate %i[home directories all to_s to_str] => :combined
+
+    def initialize home: Paths::Any, directories: Paths::Directory, environment: ENV
+      @combined = Paths::Combined.new home.new(HOME_PAIR, environment),
+                                      directories.new(Pair.new, environment)
+      freeze
+    end
+
+    def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
+    private
+
+    attr_reader :combined
+  end
+end

data/lib/xdg.rb

@@ -5,9 +5,11 @@ require "xdg/config"
 require "xdg/data"
 require "xdg/environment"
 require "xdg/pair"
+require "xdg/paths/any"
 require "xdg/paths/combined"
 require "xdg/paths/directory"
 require "xdg/paths/home"
+require "xdg/runtime"
 require "xdg/state"
 
 # Main namespace.

data/xdg.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "xdg"
-  spec.version = "10.2.0"
+  spec.version = "10.3.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/xdg"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xdg
 version: !ruby/object:Gem::Version
-  version: 10.2.0
+  version: 10.3.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -51,9 +51,11 @@ files:
 - lib/xdg/data.rb
 - lib/xdg/environment.rb
 - lib/xdg/pair.rb
+- lib/xdg/paths/any.rb
 - lib/xdg/paths/combined.rb
 - lib/xdg/paths/directory.rb
 - lib/xdg/paths/home.rb
+- lib/xdg/runtime.rb
 - lib/xdg/state.rb
 - xdg.gemspec
 homepage: https://alchemists.io/projects/xdg
@@ -81,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.15
 specification_version: 4
 summary: A XDG Base Directory Specification implementation.
 test_files: []