:toc: macro :toclevels: 5 :figure-caption!:

Runcom

link=badge.fury.io/rb/runcom

image::badge.fury.io/rb/runcom.svg[Gem Version]

link=www.alchemists.io/projects/code_quality

image::img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]

link=circleci.com/gh/bkuhlmann/runcom

image::circleci.com/gh/bkuhlmann/runcom.svg?style=svg[Circle CI Status]

Runcom (short for https://en.wikipedia.org/wiki/Run_commands[Run Command]) 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 standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification] built atop the https://www.alchemists.io/projects/xdg[XDG] implementation. In other words, Runcom is an advanced version of XDG.

toc::[]

Features

** `+$XDG_CACHE_HOME+` ** `+$XDG_CONFIG_HOME+` ** `+$XDG_CONFIG_DIRS+` ** `+$XDG_DATA_HOME+` ** `+$XDG_DATA_DIRS+`

  • Enhances the XDG cache, config, and data implementation. For the config, the following is supported:

** Supports loading of CLI-specific yaml.org[YAML] configuration file. ** Supports loading and merging of nested/complex configurations. ** Supports hash representation of configuration.

Requirements

. www.ruby-lang.org[Ruby]

Setup

To install, run:

source,bash

gem install runcom


Add the following to your Gemfile:

source,ruby

gem “runcom”


Usage

The following describes the enhancements built atop the https://www.alchemists.io/projects/xdg[XDG] implementation.

Overview

While there isn’t an environment convenience object as found in the `XDG` namespace, 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”


Each of the above objects share the same 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.

  • `#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 `$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.

Using the `cache` object (created above) as an 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”


Variable Priority

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

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`.

. *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”


For further details, study the public interface as provided by the lib/runcom/config.rb[`Runcom::Config`] object.

Examples

Examples of gems built atop this gem are:

Development

To contribute, run:

source,bash

git clone github.com/bkuhlmann/runcom.git cd runcom bin/setup


You can also use the IRB console for direct access to all objects:

source,bash

bin/console


Tests

To test, run:

source,bash

bundle exec rake


Versioning

Read https://semver.org[Semantic Versioning] 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

Please note that this project is released with a CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By participating in this project you agree to abide by its terms.

Contributions

Read CONTRIBUTING.adoc[CONTRIBUTING] for details.

License

Read LICENSE.adoc[LICENSE] for details.

History

Read CHANGES.adoc[CHANGES] for details.

Credits

Engineered by https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].