runcom 10.0.0 → 10.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8544b04b1234823a0f9edda9da1eceb5f33e945c5637d15261efa80be64d26f
-  data.tar.gz: ffbb52ac4c8127aa6cb81234d290d65da71099c40b6f3e389856f0878c0e47df
+  metadata.gz: 63df1b5963a9b53c660b18679037d055384c3d484093725d46a671b52ea16f9b
+  data.tar.gz: e3d84a1e66bb4fb4277651ee0e42a17845b8c1ea632f293c09e5bee490d5c81b
 SHA512:
-  metadata.gz: e0f75136a6d3a31858ae1d5876f3356e0a59b86915a3d9f982bc2465b0b14c3ce7ad6cd95473e7e3dad5f10918aa300398ef6e7d3eb72e04ab16a5a1184e283e
-  data.tar.gz: 2cfe9cb8e86b10cb1f98fa66cb44477a07acd9e680fe3adcb49dd743a56b711c80669bab1756ee5b111acd1fd7fbeef2833d7e40c2ad6c98dcb14d2c0adf38f9
+  metadata.gz: 2d6eec9d50e87743748e62dbc3165b38b6b766e149ecd36b7e1619b401b82820688c7a4d5d81d48c004470f1e268e008b877675ead850286596f66b9334ebdf0
+  data.tar.gz: 7fdd92df8806c6bdfa6a91a553e8b85153ae9eb0d0108266856e755adc59522569a7f8e2b4b7d5a23cb44fa99934c21f946fdea44e93bfe41b6d9a7a66af5145

data/README.adoc

@@ -15,12 +15,12 @@ toc::[]
 
 * 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`
+** `+$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.
 
 == Requirements
@@ -80,18 +80,14 @@ state = Runcom::State.new "demo/history.log"
 Each of the above objects share the same Object API:
 
 * `#relative`: Answers the relative path from which the object was constructed.
-* `#namespace`: Answers the relative namespace as a pathname object from which the object was
-  constructed. The namespace must be identical across the cache, config, and data objects as this is
-  what uniquely identifies and organizes all files associated with your program.
+* `#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.
-* `#global`: Answers the first _existing_ or _non-existing_ global file path only.
-* `#local`: Answers the first _existing_ or _non-existing_ local file path only.
-* `#all`: Answers all file system paths which is the combined `$XDG_*_HOME` and
-  `$XDG_*_DIRS` values in order defined. These paths _may_ or _may not_ exist on the file system.
-* `#inspect`: Answers a string representation of default XDG home and directory paths for debugging
-  purposes.
+* `#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.
+* `#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.
 
 Using a `cache` object, for example, here is what each method answers back:
 
@@ -103,6 +99,7 @@ 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>]
@@ -113,7 +110,7 @@ cache.inspect    # "XDG_CACHE_HOME=/Users/demo/Engineering/OSS/runcom/.cache:/Us
 
 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`.
@@ -122,7 +119,7 @@ Path precedence is determined in the following order (with the first taking high
 
 === Building Blocks
 
-While {xdg_link} and Runcom are powerful in their own right, a great building block you can add on top of this gem is the {etcher_link} gem which loads, transforms, validates, and produces structured data from raw Runcom information. For more sophisticated applications, this synergetic coupling of `XDG -> Runcom -> Etcher` makes for nicely designed architectures.
+While {xdg_link} and Runcom are powerful in their own right, a great building block you can add on top of this gem is the {etcher_link} gem which loads, transforms, validates, and produces structured data from raw Runcom information. For more sophisticated applications, this synergetic coupling of `XDG + Runcom + Etcher` makes for nicely designed architectures.
 
 === Examples
 

data/lib/runcom/cache.rb

@@ -9,7 +9,7 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::Cache
 
-    delegate %i[relative namespace file_name active global local all inspect] => :common
+    delegate %i[relative namespace file_name active passive global local all inspect] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:

data/lib/runcom/config.rb

@@ -9,7 +9,7 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::Config
 
-    delegate %i[relative namespace file_name active global local all inspect] => :common
+    delegate %i[relative namespace file_name active passive global local all inspect] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:

data/lib/runcom/data.rb

@@ -9,7 +9,7 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::Data
 
-    delegate %i[relative namespace file_name active global local all inspect] => :common
+    delegate %i[relative namespace file_name active passive global local all inspect] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:

data/lib/runcom/paths/common.rb

@@ -26,6 +26,8 @@ module Runcom
 
       def active = all.select(&:file?).find(&:exist?)
 
+      def passive = active || global
+
       def global
         all.tap { |paths| paths.delete local }
            .first

data/lib/runcom/state.rb

@@ -9,7 +9,7 @@ module Runcom
 
     CONTEXT = Context.new xdg: XDG::State
 
-    delegate %i[relative namespace file_name active global local all inspect] => :common
+    delegate %i[relative namespace file_name active passive global local all inspect] => :common
 
     def initialize path, context: CONTEXT
       @common = Paths::Common.new path, context:

data/runcom.gemspec

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runcom
 version: !ruby/object:Gem::Version
-  version: 10.0.0
+  version: 10.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-06-13 00:00:00.000000000 Z
+date: 2023-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -126,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
+rubygems_version: 3.4.16
 signing_key:
 specification_version: 4
 summary: A XDG enhanced run command manager for command line interfaces.