runcom 9.0.3 → 10.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a96b20d63816d654787104617640a3cc19bf9808ce2c4da2c94ee3590090889b
-  data.tar.gz: 24ca43e372e232b67ed5215000057fa45cd84a3f107306b44f85122142e3c325
+  metadata.gz: bb75c89d8e38336ecfb2ca85d3d641299f137150978fddb3dfbc51f8c0d3ef09
+  data.tar.gz: 81c3ac00d58e8e963ea60f0f0af89ede2dae3928c0ab16f845e72987e3cb6281
 SHA512:
-  metadata.gz: 8879b8d5b5811e4d0c998fc46813af39d83be386b69fc3cdde40104dbcc8066a242ee23af46945dc0c3b9d42aeb06b9fdf29ef7eaecd98d4741e4b8f9cd3d7d1
-  data.tar.gz: d397c7d6616f515f5435b535e785e501517c14ebf1e1597f60d9f68dd18e604edbbda477abcde674a43cde2951ab6b2a417e5a5026e119333ee4de3a6495ad10
+  metadata.gz: a8b7486ae122faed212ef572045dcd8450979eaeefba8406f8ebad4f8444e7ce57d14498d271363b0b7fff199c79f78e932f57a5e969103a8bf1c17e7a55e7af
+  data.tar.gz: 58a719fe2be256df2f8104da75a987df809b0f1b18786fe789fb3e785cf9651d9c42862d491caae9aac1fbde34e5cff673171b9f26f1b2759d38272dd5033118

data/README.adoc

@@ -2,20 +2,18 @@
 :toclevels: 5
 :figure-caption!:
 
+:xdg_link: link:https://alchemists.io/projects/xdg[XDG]
+:etcher_link: link:https://alchemists.io/projects/etcher[Etcher]
+
 = 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, or multiple caches, configurations, or data in general. It does this by
-leveraging the https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base
-Directory Specification] built atop the link:https://alchemists.io/projects/xdg[XDG]
-implementation. In other words, Runcom is an advanced version of XDG.
+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}.
 
 toc::[]
 
 == Features
 
-* Wraps the link:https://alchemists.io/projects/xdg[XDG] implementation which provides access to
+* Wraps the {xdg_link} implementation which provides access to
   the following environment variables:
 ** `$XDG_CACHE_HOME`
 ** `$XDG_CONFIG_HOME`
@@ -23,11 +21,7 @@ toc::[]
 ** `$XDG_DATA_HOME`
 ** `$XDG_DATA_DIRS`
 ** `$XDG_STATE_HOME`
-* Enhances the XDG cache, config, data, and state implementation. For the config, the following is
-  supported:
-** Supports loading of CLI-specific http://yaml.org[YAML] configuration file.
-** Supports loading and merging of nested/complex configurations.
-** Supports hash representation of configuration.
+* Enhances the {xdg_link} cache, config, data, and state implementations.
 
 == Requirements
 
@@ -67,46 +61,52 @@ require "runcom"
 
 == Usage
 
-The following describes the enhancements built atop the
-link:https://alchemists.io/projects/xdg[XDG] implementation.
+The following describes the enhancements built atop the {xdg_link} implementation.
 
 === Overview
 
-While there isn’t an environment convenience object as found in the `+XDG+` namespace, you can
-instantiate each object individually:
+While there isn’t an environment convenience object as found with the `XDG` gem, you can instantiate each object individually:
 
 [source,ruby]
 ----
-cache = Runcom::Cache.new "example/data.json"
-config = Runcom::Config.new "example/configuration.yml"
-data = Runcom::Data.new "example/store.dat"
-state = Runcom::State.new "example/history.log"
+cache = Runcom::Cache.new "demo/data.json"
+config = Runcom::Config.new "demo/configuration.yml"
+data = Runcom::Data.new "demo/store.dat"
+state = Runcom::State.new "demo/history.log"
 ----
 
-Each of the above objects share the same API:
+💡 By default, each Runcom object expects a relative path but you can use a fully qualified path as well.
+
+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
+* `#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.
-* `#file_name` - Answers the file name from which the object was constructed.
-* `#current` - Answers first _existing_ file system path computed by `$XDG_*_HOME` followed by each
-  computed `$XDG_*_DIRS` path in order defined. Otherwise, `nil` is answered back.
-* `#all` - Answers all file system paths which is the combined `$XDG_*_HOME` and
+* `#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
+* `#inspect`: Answers a string representation of default XDG home and directory paths for debugging
   purposes.
 
-Using the `cache` object (created above) as an example, here is what each method answers back:
+Using a `cache` object, for example, here is what each method answers back:
 
 [source,ruby]
 ----
-cache.relative # => #<Pathname:example/data.json>
-cache.namespace # #<Pathname:example>
-cache.file_name # #<Pathname:data.json>
-cache.current # #<Pathname:/Users/bkuhlmann/.cache/example/data.json>
-cache.all # [#<Pathname:/Users/bkuhlmann/.cache/example/data.json>]
-cache.inspect # "XDG_CACHE_HOME=/Users/bkuhlmann/.cache"
+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.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"
 ----
 
 === Variable Priority
@@ -120,76 +120,30 @@ Path precedence is determined in the following order (with the first taking high
 . *Global Configuration* - When a local configuration isn’t found, the global configuration is used
   as defined by the _XDG Base Directory Specification_.
 
-=== Configuration Specialization
-
-The `Runcom::Config` deserves additional highlighting as it provides support for loading custom
-CLI configurations directly from the command line or from custom locations. It is meant to be used
-within your program(s).
-
-An object is initialized as follows:
-
-[source,ruby]
-----
-configuration = Runcom::Config.new "example/configuration.yml"
-----
-
-Default settings can be initialized as well:
-
-[source,ruby]
-----
-configuration = Runcom::Config.new "example/configuration.yml", defaults: {name: "Example"}
-----
-
-Once a configuration has been initialized, a hash representation can be obtained:
-
-[source,ruby]
-----
-configuration.to_h
-----
-
-A configuration can be merged with another hash (handy for runtime overrides):
-
-[source,ruby]
-----
-updated_configuration = configuration.merge {name: "Updated Name"}
-----
-
-A configuration can also be merged with another configuration:
-
-[source,ruby]
-----
-updated_configuration = configuration.merge Runcom::Config.new("other", defaults: {a: 1})
-----
-
-The current path of the configuration can be asked for as well:
-
-[source,ruby]
-----
-configuration.current # "~/.config/example/configuration.yml"
-----
+=== Building Blocks
 
-For further details, study the public interface as provided by the
-link:lib/runcom/config.rb[`Runcom::Config`] object.
+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
 
 Examples of gems built atop this gem are:
 
-* link:https://alchemists.io/projects/rubysmith[Rubysmith] - A command line interface for
+* link:https://alchemists.io/projects/rubysmith[Rubysmith]: A command line interface for
   smithing Ruby projects.
-* link:https://alchemists.io/projects/gemsmith[Gemsmith] - A command line interface for smithing
+* link:https://alchemists.io/projects/gemsmith[Gemsmith]: A command line interface for smithing
   new Ruby gems.
-* link:https://alchemists.io/projects/git-lint[Git Lint] - Enforces consistent Git commits.
-* link:https://alchemists.io/projects/milestoner[Milestoner] - A command line interface for
+* link:https://alchemists.io/projects/hanamismith[Hanamismith]: A command line interace for smithing link:https://hanamirb.org[Hanami] projects.
+* link:https://alchemists.io/projects/git-lint[Git Lint]: Enforces consistent Git commits.
+* link:https://alchemists.io/projects/milestoner[Milestoner]: A command line interface for
   releasing Git repository milestones.
-* link:https://alchemists.io/projects/pennyworth[Pennyworth] - A command line interface that
+* link:https://alchemists.io/projects/pennyworth[Pennyworth]: A command line interface that
   enhances and extends link:https://www.alfredapp.com[Alfred] with Ruby support.
-* link:https://alchemists.io/projects/pragmater[Pragmater] - A command line interface for
+* link:https://alchemists.io/projects/pragmater[Pragmater]: A command line interface for
   managing/formatting source file pragma comments.
-* link:https://alchemists.io/projects/sublime_text_kit[Sublime Text Kit] - A command line
+* link:https://alchemists.io/projects/sublime_text_kit[Sublime Text Kit]: A command line
   interface for managing Sublime Text metadata.
-* link:https://alchemists.io/projects/tocer[Tocer] - A command line interface for generating
-  table of contents for Markdown files.
+* link:https://alchemists.io/projects/tocer[Tocer]: A command line interface for generating
+  Markdown table of contents.
 
 == Development
 

data/lib/runcom/cache.rb

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

data/lib/runcom/config.rb

@@ -1,53 +1,22 @@
 # frozen_string_literal: true
 
-require "refinements/hashes"
-require "yaml"
+require "forwardable"
 
 module Runcom
   # A developer friendly wrapper of XDG config.
   class Config
     extend Forwardable
-    using Refinements::Hashes
 
-    DEFAULT_CONTEXT = Context.new xdg: XDG::Config
+    CONTEXT = Context.new xdg: XDG::Config
 
-    delegate %i[relative namespace file_name current all inspect] => :common
+    delegate %i[relative namespace file_name active global local all inspect] => :common
 
-    def initialize path, defaults: {}, context: DEFAULT_CONTEXT
-      @common = Paths::Common.new path, context: @context = context
-      @settings = defaults.deep_merge process_settings
-      freeze
+    def initialize path, context: CONTEXT
+      @common = Paths::Common.new path, context:
     end
 
-    def merge other
-      self.class.new common.relative, defaults: settings.deep_merge(other.to_h), context:
-    end
-
-    # :reek:FeatureEnvy
-    def ==(other) = other.is_a?(Config) && (hash == other.hash)
-
-    alias eql? ==
-
-    def hash = [common.relative, to_h, self.class].hash
-
-    def to_h = settings
-
     private
 
-    attr_reader :common, :context, :settings
-
-    def process_settings
-      load_settings
-    rescue Psych::SyntaxError
-      raise Error, "Invalid configuration: #{common.current}."
-    rescue StandardError
-      context.defaults
-      {}
-    end
-
-    def load_settings
-      yaml = YAML.load_file common.current
-      yaml.is_a?(Hash) ? yaml : {}
-    end
+    attr_reader :common
   end
 end

data/lib/runcom/context.rb

@@ -2,8 +2,8 @@
 
 module Runcom
   # A common context for all XDG custom objects.
-  Context = Struct.new :defaults, :home, :environment, :xdg, keyword_init: true do
-    def initialize *arguments
+  Context = Struct.new :home, :environment, :xdg do
+    def initialize(**)
       super
 
       self[:home] ||= Paths::Home

data/lib/runcom/data.rb

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

data/lib/runcom/paths/common.rb

@@ -24,7 +24,14 @@ module Runcom
 
       def file_name = relative.basename
 
-      def current = all.select(&:file?).find(&:exist?)
+      def active = all.select(&:file?).find(&:exist?)
+
+      def global
+        all.tap { |paths| paths.delete local }
+           .first
+      end
+
+      def local = all.first
 
       def all = xdg.all.map { |root| root.join relative }
 

data/lib/runcom/state.rb

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

data/runcom.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name = "runcom"
-  spec.version = "9.0.3"
+  spec.version = "10.0.1"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/runcom"
-  spec.summary = "An XDG enhanced run command manager for command line interfaces."
+  spec.summary = "A XDG enhanced run command manager for command line interfaces."
   spec.license = "Hippocratic-2.1"
 
   spec.metadata = {
@@ -23,8 +23,8 @@ Gem::Specification.new do |spec|
   spec.cert_chain = [Gem.default_cert_path]
 
   spec.required_ruby_version = "~> 3.2"
-  spec.add_dependency "refinements", "~> 10.0"
-  spec.add_dependency "xdg", "~> 7.0"
+  spec.add_dependency "refinements", "~> 11.0"
+  spec.add_dependency "xdg", "~> 7.1"
   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: 9.0.3
+  version: 10.0.1
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-04-30 00:00:00.000000000 Z
+date: 2023-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -43,28 +43,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '11.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '11.0'
 - !ruby/object:Gem::Dependency
   name: xdg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -126,8 +126,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.12
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
-summary: An XDG enhanced run command manager for command line interfaces.
+summary: A XDG enhanced run command manager for command line interfaces.
 test_files: []