README.md in runcom-0.6.0 vs README.md in runcom-1.0.0
- old
+ new
@@ -2,24 +2,32 @@
[](http://badge.fury.io/rb/runcom)
[](https://codeclimate.com/github/bkuhlmann/runcom)
[](https://codeclimate.com/github/bkuhlmann/runcom)
[](https://gemnasium.com/bkuhlmann/runcom)
-[](https://travis-ci.org/bkuhlmann/runcom)
+[](https://circleci.com/gh/bkuhlmann/runcom)
[](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. -->
# Table of Contents
- [Features](#features)
- [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)
- [Contributions](#contributions)
- [License](#license)
@@ -28,13 +36,18 @@
<!-- Tocer[finish]: Auto-generated, don't remove. -->
# 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
0. [Ruby 2.4.x](https://www.ruby-lang.org)
@@ -58,28 +71,82 @@
gem "runcom"
# 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: