The letter A styled as Alchemists logo. lchemists

Putin's War on Ukraine - Watch President Zelenskyy's speech and help Ukraine fight against the senseless cruelty of a dictator!

Brooke Kuhlmann's Avatar Brooke Kuhlmann
Published November 3, 2016 Updated March 7, 2023
Runcom Icon

Runcom

9.0.1

Circe CI Status. Alchemists Style Guide. Git Badge Sponsor Badge

Runcom is a Run Command portmanteau (i.e. run
[com]mand = runcom) which 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 XDG Base Directory Specification built atop the XDG implementation. In other words, Runcom is an advanced version of XDG.

Features

  • Wraps the XDG implementation which provides access to the following environment variables:

    • $XDG_CACHE_HOME

    • $XDG_CONFIG_HOME

    • $XDG_CONFIG_DIRS

    • $XDG_DATA_HOME

    • $XDG_DATA_DIRS

    • $XDG_STATE_HOME

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

    • Supports loading of CLI-specific YAML configuration file.

    • Supports loading and merging of nested/complex configurations.

    • Supports hash representation of configuration.

Requirements

  1. Ruby

Setup

To install, run:

gem install runcom

Add the following to your Gemfile:

gem "runcom"

Usage

The following describes the enhancements built atop the XDG implementation.

Overview

While there isn’t an environment convenience object as found in the XDG namespace, you can instantiate each object individually:

cache = Runcom::Cache.new "example/data.json"
config = Runcom::Config.new "example/configuration.yml"
data = Runcom::Data.new "example/store.dat"
state = Runcom::State.new "example/history.log"

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:

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

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

  2. 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:

configuration = Runcom::Config.new "example/configuration.yml"

Default settings can be initialized as well:

configuration = Runcom::Config.new "example/configuration.yml", 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"}

A configuration can also be merged with another configuration:

updated_configuration = configuration.merge Runcom::Config.new("other", defaults: {a: 1})

The current path of the configuration can be asked for as well:

configuration.current # "~/.config/example/configuration.yml"

For further details, study the public interface as provided by the Runcom::Config object.

Examples

Examples of gems built atop this gem are:

  • Rubysmith - A command line interface for smithing Ruby projects.

  • Gemsmith - A command line interface for smithing new Ruby gems.

  • Git Lint - Enforces consistent Git commits.

  • Milestoner - A command line interface for releasing Git repository milestones.

  • Pennyworth - A command line interface that enhances and extends Alfred with Ruby support.

  • Pragmater - A command line interface for managing/formatting source file pragma comments.

  • Sublime Text Kit - A command line interface for managing Sublime Text metadata.

  • Tocer - A command line interface for generating table of contents for Markdown files.

Development

To contribute, run:

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

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

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Versions

Community

Credits