README.md in runcom-1.1.0 vs README.md in runcom-1.2.0

- old
+ new

@@ -13,32 +13,32 @@ [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 +## Table of Contents -- [Features](#features) -- [Requirements](#requirements) + - [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) -- [History](#history) -- [Credits](#credits) + - [Usage](#usage) + - [`Runcom::Configuration`](#runcomconfiguration) + - [XDG](#xdg) + - [`$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) + - [History](#history) + - [Credits](#credits) <!-- Tocer[finish]: Auto-generated, don't remove. --> -# Features +## Features - 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: @@ -46,11 +46,11 @@ - 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 +## Requirements 0. [Ruby 2.4.x](https://www.ruby-lang.org) # Setup @@ -69,14 +69,17 @@ Add the following to your Gemfile: gem "runcom" -# Usage +## Usage -## `Runcom::Configuration` +### `Runcom::Configuration` +This object provides support for loading custom CLI configurations directly from the command line or +from custom locations. It is meant to be used within your CLI program(s). + An object can be initialized as follows: configuration = Runcom::Configuration.new project_name: "example" The default file name for a configuration is `configuration.yml` but a custom name can be used if @@ -101,18 +104,18 @@ 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 +### XDG 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` +#### `$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: @@ -128,59 +131,59 @@ 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` +#### `$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 +#### 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, +0. `$XDG_CONFIG_HOME` - Will be used if defined *and* 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. + system while skipping any that don't exist. -# Tests +## Tests To test, run: bundle exec rake -# Versioning +## Versioning Read [Semantic Versioning](http://semver.org) for details. Briefly, it means: - Major (X.y.z) - Incremented for any backwards incompatible public API changes. - Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes. - Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes. -# Code of Conduct +## Code of Conduct Please note that this project is released with a [CODE OF CONDUCT](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. -# Contributions +## Contributions Read [CONTRIBUTING](CONTRIBUTING.md) for details. -# License +## License Copyright (c) 2016 [Alchemists](https://www.alchemists.io). Read [LICENSE](LICENSE.md) for details. -# History +## History Read [CHANGES](CHANGES.md) for details. Built with [Gemsmith](https://github.com/bkuhlmann/gemsmith). -# Credits +## Credits Developed by [Brooke Kuhlmann](https://www.alchemists.io) at [Alchemists](https://www.alchemists.io).