runcom 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 979adb538efd3077c571dae93b8cc570ebc0bc62
-  data.tar.gz: '0639625144dec6f05ecd65ffd96673ec0dc5fbea'
+  metadata.gz: '0079d1916af6b0a44c839bbd3f61988c5efe1bff'
+  data.tar.gz: 2d41953a849b8c6b7a41f881ff552934876b160b
 SHA512:
-  metadata.gz: 0ed9a641bafd1d4bb47ec29bb85edb9a069ecfde639c5da14c30e8edf8f7b97a80dbeed3fba6cc481fd9dede81ef027692d2fa9f12fa146eee706aef8e846a3d
-  data.tar.gz: a047ed159c36d0ba6d9b87f9ed8c7b8c6ddae470a8ab49bde642a922024f40279f42e069d28f471797566834ebf250dd5f6f7e8f56d3bba9c6cb5060e2db0063
+  metadata.gz: ba0a18fb05999333917446f60d817df0256d68c9987ef66b55c54f2e4e753b687b0c699783ba99d3fa0cc1577e55887877d8137c097801c9c4fb6ef210e88396
+  data.tar.gz: 340f0063f2ddf39d5bd90ffa82d59c771238a1a17011f3993c01611df8c44612e003dc97974119914cc1dde9b811133bc0dfefba7140d3045d1c96bd7522ab4f

data/README.md

@@ -4,11 +4,14 @@
 [![Code Climate GPA](https://codeclimate.com/github/bkuhlmann/runcom.svg)](https://codeclimate.com/github/bkuhlmann/runcom)
 [![Code Climate Coverage](https://codeclimate.com/github/bkuhlmann/runcom/coverage.svg)](https://codeclimate.com/github/bkuhlmann/runcom)
 [![Gemnasium Status](https://gemnasium.com/bkuhlmann/runcom.svg)](https://gemnasium.com/bkuhlmann/runcom)
-[![Travis CI Status](https://secure.travis-ci.org/bkuhlmann/runcom.svg)](https://travis-ci.org/bkuhlmann/runcom)
+[![Circle CI Status](https://circleci.com/gh/bkuhlmann/runcom.svg?style=svg)](https://circleci.com/gh/bkuhlmann/runcom)
 [![Patreon](https://img.shields.io/badge/patreon-donate-brightgreen.svg)](https://www.patreon.com/bkuhlmann)
 
-A [run command manager](https://en.wikipedia.org/wiki/Run_commands) for command line interfaces
-(CLI). It manages/resolves local or global resource (i.e. `.<program>rc`) settings for CLIs.
+Runcom (a.k.a. [Run Command](https://en.wikipedia.org/wiki/Run_commands)) provides common
+functionality for Command Line Interfaces (CLIs) in which to manage global, local, or multiple
+configurations in general. It does this by leveraging the
+[XDG Base Directory Specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+Read on for further details.
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -18,6 +21,11 @@ A [run command manager](https://en.wikipedia.org/wiki/Run_commands) for command
 - [Requirements](#requirements)
 - [Setup](#setup)
 - [Usage](#usage)
+  - [`Runcom::Configuration`](#runcomconfiguration)
+  - [XDG Configurations](#xdg-configurations)
+    - [`$XDG_CONFIG_DIRS`](#xdg_config_dirs)
+    - [`$XDG_CONFIG_HOME`](#xdg_config_home)
+    - [Variable Priority](#variable-priority)
 - [Tests](#tests)
 - [Versioning](#versioning)
 - [Code of Conduct](#code-of-conduct)
@@ -30,9 +38,14 @@ A [run command manager](https://en.wikipedia.org/wiki/Run_commands) for command
 
 # Features
 
-- Loads local or global YAML resource configurations.
-- Automatically detects and resolves local or global resource configurations.
-- Provides support for merging of nested/complex configurations.
+- Provides run command customization by loading a CLI-specific configuration from a
+  [YAML](http://yaml.org) file.
+- Automatically detects and resolves resource configuration file path based on XDG environment
+  variables which provides several benefits:
+  - Uses the `$XDG_CONFIG_HOME` or `$XDG_CONFIG_DIRS` variables to define configuration paths.
+  - Improves configuration organization by not littering your `$HOME` directory with `*rc` files and
+    keeping them within a central configuration folder.
+- Supports loading and merging of nested/complex configurations.
 - Supports hash representation of configuration.
 
 # Requirements
@@ -60,26 +73,80 @@ Add the following to your Gemfile:
 
 # Usage
 
-Start by leveraging the `Runcom::Configuration` object as follows:
+## `Runcom::Configuration`
 
-    configuration = Runcom::Configuration.new file_name: ".examplerc"
+An object can be initialized as follows:
 
-There is optional support for default settings too:
+    configuration = Runcom::Configuration.new project_name: "example"
 
-    configuration = Runcom::Configuration.new file_name: ".examplerc", defaults: {name: "Example"}
+The default file name for a configuration is `configuration.yml` but a custom name can be used if
+desired:
 
-Default settings will be overwitten if matching local or global setting keys are detected. Order of
-precedence is determined as follows:
+    configuration = Runcom::Configuration.new project_name: "example", file_name: "example.yml"
 
-0. Local (i.e. `<current working directory>/.examplerc`)
-0. Global (i.e. `$HOME/.examplerc`)
-0. Defaults (i.e. `{}` unless specified upon initialization).
+Default settings can be initialized as well:
 
-If multiple settings are detected, only the first one found will be used.
+    configuration = Runcom::Configuration.new project_name: "example", defaults: {name: "Example"}
+
+Once a configuration has been initialized, a hash representation can be obtained:
+
+    configuration.to_h
+
+A configuration can be merged with another hash (handy for runtime overrides)
+
+    updated_configuration = configuration.merge {name: "Updated Name"}
+
+The computed path of the configuration can be asked for as well:
+
+    configuration.path # "~/.config/example/configuration.yml"
 
 For further details, study the public interface as provided by the
 [`Runcom::Configuration`](lib/runcom/configuration.rb) object.
 
+## XDG Configurations
+
+This gem leverages the XDG `$XDG_CONFIG_DIRS` and `$XDG_CONFIG_HOME` environment variables which are
+used to compute the configuration path (as mentioned above). The following details how to take
+advantage of the XDG variables (additional details can be found by reading the
+[XDG Specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html)).
+
+### `$XDG_CONFIG_DIRS`
+
+This variable is used to define a colon delimited list of configuration directories. The order is
+important as the first directory defined will take precedent over the following directory and so
+forth. Example:
+
+    XDG_CONFIG_DIRS="/example/one/.config:/example/two/.settings:/example/three/.configuration"
+
+    # Yields the following array:
+    [
+      "/example/one/.config",
+      "/example/two/.settings",
+      "/example/three/.configuration"
+    ]
+
+In the above example, the `"/example/one/.config"` path will take highest priority since it was
+defined first.
+
+When the `$XDG_CONFIG_DIRS` is not defined, it will default to the following array: `["/etc/xdg"]`.
+
+### `$XDG_CONFIG_HOME`
+
+This is the environment variable you'll want to use the most as it takes precidence over
+`$XDG_CONFIG_DIRS` environment variable. It is not required to be defined as it defaults to
+`$HOME/.config` which is generally want you want.
+
+### Variable Priority
+
+Configuration path precedence is determined in the following order (with the first taking highest
+priority):
+
+0. `$XDG_CONFIG_HOME` - Will be used if defined *and* an exists on the local file system. Otherwise,
+   falls back to the `$XDG_CONFIG_DIRS` array.
+0. `$XDG_CONFIG_DIRS` - Iterates through defined directories starting with the first one defined
+   (highest priority). It will choose the first directory, in priority, that exists on the file
+   system while skipping those that don't exist.
+
 # Tests
 
 To test, run:

data/lib/runcom.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 require "runcom/identity"
+require "runcom/xdg/configuration"
 require "runcom/configuration"

data/lib/runcom/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pathname"
 require "yaml"
 require "refinements/hashes"
 
@@ -8,32 +9,14 @@ module Runcom
   class Configuration
     using Refinements::Hashes
 
-    def initialize file_name:, defaults: {}
-      @file_name = file_name
+    attr_reader :path
+
+    def initialize project_name:, file_name: "configuration.yml", defaults: {}
+      @path = Pathname "#{XDG::Configuration.computed_dir}/#{project_name}/#{file_name}"
       @defaults = defaults
       @settings = defaults.deep_merge load_settings
     end
 
-    def local?
-      File.exist? local_path
-    end
-
-    def global?
-      File.exist? global_path
-    end
-
-    def local_path
-      File.join Dir.pwd, file_name
-    end
-
-    def global_path
-      File.join ENV["HOME"], file_name
-    end
-
-    def computed_path
-      local? ? local_path : global_path
-    end
-
     def merge custom_settings
       settings.deep_merge custom_settings
     end
@@ -44,10 +27,10 @@ module Runcom
 
     private
 
-    attr_reader :file_name, :defaults, :settings
+    attr_reader :file_path, :defaults, :settings
 
     def load_settings
-      yaml = YAML.load_file computed_path
+      yaml = YAML.load_file path
       yaml.is_a?(Hash) ? yaml : {}
     rescue
       defaults

data/lib/runcom/identity.rb

@@ -12,7 +12,7 @@ module Runcom
     end
 
     def self.version
-      "0.6.0"
+      "1.0.0"
     end
 
     def self.version_label

data/lib/runcom/xdg/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Runcom
+  module XDG
+    # Represents X Desktop Group (XGD) configuration support. XGD is also known as
+    # [Free Desktop](https://www.freedesktop.org). Here is the exact
+    # [specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) being
+    # for this implementation.
+    class Configuration
+      def self.home_dir
+        ENV.fetch "XDG_CONFIG_HOME", File.join(ENV["HOME"], ".config")
+      end
+
+      def self.dirs
+        ENV.fetch("XDG_CONFIG_DIRS", "/etc/xdg").split ":"
+      end
+
+      def self.computed_dirs
+        directories = dirs.unshift(home_dir).map { |directory| Pathname(directory).expand_path }
+        directories.select(&:exist?)
+      end
+
+      def self.computed_dir
+        computed_dirs.first
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: runcom
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-06 00:00:00.000000000 Z
+date: 2017-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '9.4'
+        version: '9.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '9.4'
+        version: '9.6'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -142,28 +142,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.6'
+        version: '4.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.6'
+        version: '4.7'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.48'
+        version: '0.49'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.48'
+        version: '0.49'
 - !ruby/object:Gem::Dependency
   name: codeclimate-test-reporter
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +192,7 @@ files:
 - lib/runcom.rb
 - lib/runcom/configuration.rb
 - lib/runcom/identity.rb
+- lib/runcom/xdg/configuration.rb
 homepage: https://github.com/bkuhlmann/runcom
 licenses:
 - MIT