runcom 10.2.1 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b36f55daf5e33ad0b28c4a085b7eb52e3cfe0b7410680f3b73aed9df614c8aa3
-  data.tar.gz: af8e20a01d052c2adacb048b33e278a464c647eff4834c76a0df8a93d874e648
+  metadata.gz: 0feaa12d363465346d2ea56a8bdcdaba2ec353ebb1235a17cdc8ed38fe2a25da
+  data.tar.gz: '061918ad4c3d1806e42093a3e0ee4ec2e1f5b28cefad2ceb74664e77f7693f3b'
 SHA512:
-  metadata.gz: 6a4b6f740b7d74fac97d83fce62048dda898f543c21e191438a071e79cdd56987f684543630214357e2903c189ee78cda5a6b8688f64c8035779501085a1c80e
-  data.tar.gz: 2db839bfd2b1674a115177360ef8fbfaabb8c782f3069b0c43bd732081ccd3368c9a638c6cdc131b2acd41a2ecfbeba7200d6612989bf51f19ee061e0355085d
+  metadata.gz: 901d5075cd8ac4864120c397f8a245507ee192e9cd3f7b56ceaee161d6d553bc9688886cd3a9312b7ab65e132175701df4a8b4eda77e10e2be7ae0f655f6783b
+  data.tar.gz: 6f567a1ce2fd1855606acaf40bec452ebde5cc4e06254737cfbff93cb490f1ba9e5a0252ce0e3ec29c92a6418704470f3600ac1f0add5bc0096379b2209a99c2

data/README.adoc

@@ -7,21 +7,20 @@
 
 = Runcom
 
-Runcom is a link:https://en.wikipedia.org/wiki/Run_commands[Run Command] portmanteau (i.e. `run + [com]mand = runcom`) which provides common functionality for Command Line Interfaces (CLIs) in which to manage global/local caches, configurations, data, and/or state. It does this by leveraging the https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification] built atop the {xdg_link} implementation. In other words, Runcom is an enhanced version of {xdg_link}.
+Runcom is a link:https://en.wikipedia.org/wiki/Run_commands[Run Command] portmanteau (i.e. `run + [com]mand = runcom`) which provides common functionality for Command Line Interfaces (CLIs) in which to manage global/local caches, configurations, data, and/or state. This is done by leveraging the https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification] built atop the {xdg_link} implementation. In other words, Runcom is an enhanced version of {xdg_link} which specializes in dynamic global and local detection.
 
 toc::[]
 
 == Features
 
-* Wraps the {xdg_link} implementation which provides access to
-  the following environment variables:
+* Wraps the {xdg_link} implementation which provides access to the following environment variables:
 ** `+$XDG_CACHE_HOME+`
 ** `+$XDG_CONFIG_HOME+`
 ** `+$XDG_CONFIG_DIRS+`
 ** `+$XDG_DATA_HOME+`
 ** `+$XDG_DATA_DIRS+`
 ** `+$XDG_STATE_HOME+`
-* Enhances the {xdg_link} cache, config, data, and state implementations.
+* Enhances the {xdg_link} cache, config, data, and state implementations with dynamic global and local detection.
 
 == Requirements
 
@@ -65,7 +64,7 @@ The following describes the enhancements built atop the {xdg_link} implementatio
 
 === Overview
 
-While there isn’t an environment convenience object as found with the `XDG` gem, you can instantiate each object individually:
+While there isn’t a sole convenience object as found with the `XDG` gem, you can instantiate each object individually:
 
 [source,ruby]
 ----
@@ -75,46 +74,102 @@ data = Runcom::Data.new "demo/store.dat"
 state = Runcom::State.new "demo/history.log"
 ----
 
-💡 By default, each Runcom object expects a relative path but you can use a fully qualified path as well.
+By default, each Runcom object expects a relative file path but you can also use a fully qualified path when constructing a new instance.
 
 Each of the above objects share the same Object API:
 
-* `#relative`: Answers the relative path from which the object was constructed.
+* `#initial`: Answers the initial path -- which can be a relative or absolute path -- from which the object was constructed.
 * `#namespace`: Answers the namespace as a pathname object from which the instance was constructed. The namespace must be unique and identical across the cache, config, data, and state objects since this is what identifies and organizes all files associated with your program.
 * `#file_name`: Answers the file name from which the object was constructed.
 * `#active`: Answers first _existing file path_ as computed by `+$XDG_*_HOME+` followed by each computed `+$XDG_*_DIRS+` path in order defined. Otherwise, `nil` is answered back when no path exists.
 * `#passive`: Answers first path as computed by `+$XDG_*_HOME+` followed by each computed `+$XDG_*_DIRS+` path in order defined which _may_ or _may not_ exist. This behaves like `#active`  but doesn't care if the path exists. Handy for situations where you'd like the active path but can  fallback to creating the global path if otherwise.
-* `#global`: Answers the first _existing_ or _non-existing_ global path only.
-* `#local`: Answers the first _existing_ or _non-existing_ local path only.
+* `#global`: Answers the first _existing_ or _non-existing_ global path.
+* `#local`: Answers the first _existing_ or _non-existing_ local path.
 * `#all`: Answers all paths which is the combined `+$XDG_*_HOME+` and `+$XDG_*_DIRS+` values in order defined. These paths _may_ or _may not_ exist.
-* `#inspect`: Answers a string representation of default XDG home and directory paths for debugging purposes.
+* `#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.
 
-Using a `cache` object, for example, here is what each method answers back:
+=== Examples
+
+The following are examples of what you will see when exploring the Runcom objects within an IRB console:
 
 [source,ruby]
 ----
-cache = Runcom::Cache.new "demo/content.json"
-
-cache.relative   # => #<Pathname:demo/content.json>
-cache.namespace  # #<Pathname:demo>
-cache.file_name  # #<Pathname:content.json>
-cache.active     # nil
-cache.passive    # #<Pathname:/Users/demo/.cache/demo/content.json>
-cache.global     # #<Pathname:/Users/demo/.cache/demo/content.json>
-cache.local      # #<Pathname:/Users/demo/Engineering/OSS/runcom/.cache/demo/content.json>
-cache.all        # [#<Pathname:/Users/demo/Engineering/OSS/runcom/.cache/demo/content.json>, #<Pathname:/Users/demo/.cache/demo/content.json>]
-cache.inspect    # "XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache"
+# Initialization
+
+cache = XDG::Cache.new "demo/projects.json"
+config = XDG::Config.new "demo/settings.yml"
+data = XDG::Data.new "demo/vault.store"
+state = XDG::State.new "demo/history.log"
+
+# Paths
+
+cache.initial     # "#<Pathname:demo/projects.json>"
+cache.namespace   # "#<Pathname:demo>"
+cache.file_name   # "#<Pathname:projects.json>"
+cache.active      # nil
+cache.passive     # "#<Pathname:/Users/demo/.cache/demo/projects.json>"
+cache.global      # "#<Pathname:/Users/demo/.cache/demo/projects.json>"
+cache.local       # "#<Pathname:/Users/demo/Engineering/OSS/runcom/.cache/demo/projects.json>"
+cache.all         # ["#<Pathname:/Users/demo/Engineering/OSS/runcom/.cache/demo/projects.json>", "#<Pathname:/Users/demo/.cache/demo/projects.json>"]
+
+config.initial    # "#<Pathname:demo/settings.yml>"
+config.namespace  # "#<Pathname:demo>"
+config.file_name  # "#<Pathname:settings.yml>"
+config.active     # nil
+config.passive    # "#<Pathname:/Users/demo/.config/demo/settings.yml>"
+config.global     # "#<Pathname:/Users/demo/.config/demo/settings.yml>"
+config.local      # "#<Pathname:/Users/demo/Engineering/OSS/runcom/.config/demo/settings.yml>"
+config.all        # ["#<Pathname:/Users/demo/Engineering/OSS/runcom/.config/demo/settings.yml>", "#<Pathname:/Users/demo/.config/demo/settings.yml>", "#<Pathname:/etc/xdg/demo/settings.yml>"]
+
+data.initial      # "#<Pathname:demo/vault.store>"
+data.namespace    # "#<Pathname:demo>"
+data.file_name    # "#<Pathname:vault.store>"
+data.active       # nil
+data.passive      # "#<Pathname:/Users/demo/.local/share/demo/vault.store>"
+data.global       # "#<Pathname:/Users/demo/.local/share/demo/vault.store>"
+data.local        # "#<Pathname:/Users/demo/Engineering/OSS/runcom/.local/share/demo/vault.store>"
+data.all          # ["#<Pathname:/Users/demo/Engineering/OSS/runcom/.local/share/demo/vault.store>", "#<Pathname:/Users/demo/.local/share/demo/vault.store>", "#<Pathname:/usr/local/share/demo/vault.store>", "#<Pathname:/usr/share/demo/vault.store>"]
+
+state.initial     # "#<Pathname:demo/history.log>"
+state.namespace   # "#<Pathname:demo>"
+state.file_name   # "#<Pathname:history.log>"
+state.active      # nil
+state.passive     # "#<Pathname:/Users/demo/.local/state/demo/history.log>"
+state.global      # "#<Pathname:/Users/demo/.local/state/demo/history.log>"
+state.local       # "#<Pathname:/Users/demo/Engineering/OSS/runcom/.local/state/demo/history.log>"
+state.all         # ["#<Pathname:/Users/demo/Engineering/OSS/runcom/.local/state/demo/history.log>", "#<Pathname:/Users/demo/.local/state/demo/history.log>"]
+
+# Casts (explicit and implicit)
+
+cache.to_s        # "XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache"
+config.to_s       # "XDG_CONFIG_HOME=/Users/demo/Engineering/OSS/runcom/.config:/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg"
+data.to_s         # "XDG_DATA_HOME=/Users/demo/Engineering/OSS/runcom/.local/share:/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share"
+state.to_s        # "XDG_STATE_HOME=/Users/demo/Engineering/OSS/runcom/.local/state:/Users/demo/.local/state"
+
+cache.to_str      # "XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache"
+config.to_str     # "XDG_CONFIG_HOME=/Users/demo/Engineering/OSS/runcom/.config:/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg"
+data.to_str       # "XDG_DATA_HOME=/Users/demo/Engineering/OSS/runcom/.local/share:/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share"
+state.to_str      # "XDG_STATE_HOME=/Users/demo/Engineering/OSS/runcom/.local/state:/Users/demo/.local/state"
+
+# Inspection
+
+cache.inspect     # "#<Runcom::Cache:2040 XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Users/demo/.cache>"
+config.inspect    # "#<Runcom::Config:2060 XDG_CONFIG_HOME=/Users/demo/Engineering/OSS/runcom/.config:/Users/demo/.config XDG_CONFIG_DIRS=/etc/xdg>"
+data.inspect      # "#<Runcom::Data:2080 XDG_DATA_HOME=/Users/demo/Engineering/OSS/runcom/.local/share:/Users/demo/.local/share XDG_DATA_DIRS=/usr/local/share:/usr/share>"
+state.inspect     # "#<Runcom::State:2100 XDG_STATE_HOME=/Users/demo/Engineering/OSS/runcom/.local/state:/Users/demo/.local/state>"
 ----
 
 === Variable Priority
 
 Path precedence is determined in the following order (with the first taking highest priority):
 
-. *Local Configuration* - If a `+$XDG_*_HOME+` or `+$XDG_*_DIRS+` path relative to the
+. *Local Configuration*: If a `+$XDG_*_HOME+` or `+$XDG_*_DIRS+` path relative to the
   current working directory is detected, it will take precedence over the global configuration.
   This is the same behavior as found in Git where the local `.git/config` takes precedence over the
   global `$HOME/.gitconfig`.
-. *Global Configuration* - When a local configuration isn’t found, the global configuration is used
+. *Global Configuration*: When a local configuration isn’t found, the global configuration is used
   as defined by the _XDG Base Directory Specification_.
 
 === Building Blocks
@@ -160,6 +215,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/runcom/cache.rb

@@ -9,12 +9,14 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::Cache
 
-    delegate %i[relative namespace file_name active passive global local all inspect] => :common
+    delegate %i[initial namespace file_name active passive global local all to_s to_str] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{common}>"
+
     private
 
     attr_reader :common

data/lib/runcom/config.rb

@@ -9,12 +9,14 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::Config
 
-    delegate %i[relative namespace file_name active passive global local all inspect] => :common
+    delegate %i[initial namespace file_name active passive global local all to_s to_str] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{common}>"
+
     private
 
     attr_reader :common

data/lib/runcom/context.rb

@@ -2,15 +2,10 @@
 
 module Runcom
   # A common context for all XDG custom objects.
-  Context = Struct.new :home, :environment, :xdg do
-    def initialize(**)
-      super
-
-      self[:home] ||= Paths::Home
-      self[:environment] ||= ENV
-      self[:xdg] = xdg.new(home:, environment:) if xdg
-
-      freeze
+  Context = ::Data.define :home, :environment, :xdg do
+    def initialize home: Paths::Home, environment: ENV, xdg: nil
+      computed_xdg = xdg.is_a?(Class) ? xdg.new(home:, environment:) : xdg
+      super home:, environment:, xdg: computed_xdg
     end
   end
 end

data/lib/runcom/data.rb

@@ -9,12 +9,14 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::Data
 
-    delegate %i[relative namespace file_name active passive global local all inspect] => :common
+    delegate %i[initial namespace file_name active passive global local all to_s to_str] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{common}>"
+
     private
 
     attr_reader :common

data/lib/runcom/paths/common.rb

@@ -1,28 +1,23 @@
 # frozen_string_literal: true
 
-require "forwardable"
-require "refinements/pathnames"
+require "refinements/pathname"
 
 module Runcom
   module Paths
     # Provides common path/functionality for all XDG enhanced objects.
     class Common
-      extend Forwardable
+      using Refinements::Pathname
 
-      using Refinements::Pathnames
+      attr_reader :initial
 
-      delegate %i[inspect] => :xdg
-
-      attr_reader :relative
-
-      def initialize relative, context: Context.new
-        @relative = Pathname relative
+      def initialize initial, context: Context.new
+        @initial = Pathname initial
         @context = context
       end
 
-      def namespace = relative.parent
+      def namespace = initial.parent
 
-      def file_name = relative.basename
+      def file_name = initial.basename
 
       def active = all.select(&:file?).find(&:exist?)
 
@@ -35,7 +30,13 @@ module Runcom
 
       def local = all.first
 
-      def all = xdg.all.map { |root| root.join relative }
+      def all = xdg.all.map { |root| root.join initial }
+
+      def to_s = xdg.to_s
+
+      alias to_str to_s
+
+      def inspect = "#<#{self.class}:#{object_id} #{xdg}>"
 
       private
 

data/lib/runcom/paths/home.rb

@@ -20,10 +20,14 @@ module Runcom
                      .then { |path| [path.expand_path, standard.dynamic] }
       end
 
-      def inspect
+      def to_s
         [standard.key, dynamic.join(XDG::Paths::Directory::DELIMITER)].compact.join XDG::DELIMITER
       end
 
+      alias to_str to_s
+
+      def inspect = "#<#{self.class}:#{object_id} #{self}>"
+
       private
 
       attr_reader :standard

data/lib/runcom/state.rb

@@ -9,12 +9,14 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::State
 
-    delegate %i[relative namespace file_name active passive global local all inspect] => :common
+    delegate %i[initial namespace file_name active passive global local all to_s to_str] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:
     end
 
+    def inspect = "#<#{self.class}:#{object_id} #{common}>"
+
     private
 
     attr_reader :common

data/runcom.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "runcom"
-  spec.version = "10.2.1"
+  spec.version = "11.0.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/runcom"
@@ -22,9 +22,9 @@ 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.add_dependency "refinements", "~> 11.0"
-  spec.add_dependency "xdg", "~> 7.1"
+  spec.required_ruby_version = "~> 3.3"
+  spec.add_dependency "refinements", "~> 12.0"
+  spec.add_dependency "xdg", "~> 8.0"
   spec.add_dependency "zeitwerk", "~> 2.6"
 
   spec.files = Dir["*.gemspec", "lib/**/*"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runcom
 version: !ruby/object:Gem::Version
-  version: 10.2.1
+  version: 11.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:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -43,28 +43,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '12.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
   name: xdg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -117,10 +117,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
@@ -129,7 +126,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 enhanced run command manager for command line interfaces.