Runcom

Runcom (a.k.a. Run Command) 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. Read on for further details.

Table of Contents

Features

Requirements

  1. Ruby 2.4.x

Setup

For a secure install, type the following (recommended):

gem cert --add <(curl --location --silent https://www.alchemists.io/gem-public.pem)
gem install runcom --trust-policy MediumSecurity

NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.

For an insecure install, type the following (not recommended):

gem install runcom

Add the following to your Gemfile:

gem "runcom"

Usage

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 desired:

configuration = Runcom::Configuration.new project_name: "example", file_name: "example.yml"

Default settings can be initialized as well:

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

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

$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):

  1. $XDG_CONFIG_HOME - Will be used if defined and exists on the local file system. Otherwise, falls back to the $XDG_CONFIG_DIRS array.

  2. $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 any that don't exist.

Tests

To test, run:

bundle exec rake

Versioning

Read Semantic Versioning for details. Briefly, it means:

Code of Conduct

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

Contributions

Read CONTRIBUTING for details.

License

Copyright © 2016 Alchemists. Read LICENSE for details.

History

Read CHANGES for details. Built with Gemsmith.

Credits

Developed by Brooke Kuhlmann at Alchemists.