Module: Jac::Configuration

Defined in:
lib/jac/configuration.rb,
lib/jac/merger.rb

Overview

Configuration is loaded from well formed YAML streams. Each document expected to be key-value mapping where keys a profile names and values is a profile content. Profile itself is key-value mapping too. Except reserved key names (i.e. extends) each key in profile is a configuration field. For example following yaml document

“‘

foo:
  bar: 42
qoo:
  bar: 32

“‘

represents description of two profiles, foo and qoo, where field bar is set to 42 and 32 respectively.

Profile can be constructed using combination of other profiles for example having debug and release profiles for testing and production. And having remote and local profiles for building on local or remote machine. We cant get ‘debug,local`, `debug,remote`, `release,local` and `release,remote` profiles. Each of such profiles is a result of merging values of listed profiles. When merging profile with another configuration resolver overwrites existing fields. For example if debug and local for some reason have same field. In profile `debug,local` value from debug profile will be overwritten with value from local profile.

## Extending profiles

One profile can extend another. Or any amount of other profiles. To specify this one should use extends field like that

“‘

base:

application_name: my-awesome-app
port: 80

version:

version_name: 0.0.0
version_code: 42

debug:

extends: [base, version]
port: 9292

“‘

In this example debug will receive following fields:

“‘ application_name: my-awesome-app # from base profile port: 9292 # from debug profile version_name: 0.0.0 # from version profile version_code: 42 # from version profile “`

## Merging multiple configuration files

Configuration can be loaded from multiple YAML documents. Before resolve requested profile all described profiles are merged down together. Having sequence of files like .application.yml, .application.user.yml with following content

“‘ # .application.yml base:

user: deployer

debug:

extends: base
# ... other values

“‘

“‘ # .application.user.yml base:

user: developer

“‘

We’ll get user field overwritten with value from .application.user.yml. And only after that construction of resulting profile will begin (for example debug)

## String evaluation

Configuration resolver comes with powerful yet dangerous feature: it allows evaluate strings as ruby expressions like this:

“‘ foo:

build_time: "#{Time.now}" # Will be evaluated at configuration resolving step

“‘

Configuration values are available to and can be referenced with c:

“‘ base:

application_name: my-awesome-app

debug:

extends: base
server_name: "#{c.application_name}-debug"   # yields to my-awesome-app-debug

release:

extends: base
server_name: "#{c.application_name}-release" # yields to my-awesome-app-release

“‘

All strings evaluated after profile is constructed thus you don’t need to have declared values in current profile but be ready to get nil.

## Merging values

By default if one value definition overwrites another ### Merging hashes

### Merging sets

## Generic profiles

Same result as shown above can be achieved with generic profiles. Generic profile is a profile which name is regex (i.e. contained in /.../):

“‘ base:

application_name: my-awesome-app

/(release|debug)/: # Profile name is a regex, with single capture (1)

extends: base
server_name: "#{c.application_name}-#{c.captures[1]}"  # yields  my-awesome-app-release or  my-awesome-app-debug

“‘

If profile name matches multiple generic profiles it not defined which profile will be used.

Defined Under Namespace

Classes: ConfigurationEvaluator, ConfigurationReader, EvaluationContext, Merger, ProfileResolver

Constant Summary collapse

CONFIGURATION_FILES =

List of files where configuration can be placed

  • application.yml - expected to be main configuration file.

Usually it placed under version control.

  • application.user.yml - user defined overrides for main

configuration, sensitive data which can’t be placed under version control.

  • application.override.yml - final overrides.

%w[application.yml application.user.yml application.override.yml].freeze

Class Method Summary collapse

Class Method Details

.load(profile, files: CONFIGURATION_FILES, dir: Dir.pwd) ⇒ Object

Read configuration from configuration files.



397
398
399
400
401
402
403
404
 
# File 'lib/jac/configuration.rb', line 397

def load(profile, files: CONFIGURATION_FILES, dir: Dir.pwd)
  # Read all known files
  streams = files
            .map { |f| [File.join(dir, f), f] }
            .select { |path, _name| File.exist?(path) }
            .map { |path, name| [IO.read(path), name] }
  read(profile, *streams)
end

.read(profile, *streams) ⇒ OpenStruct

Generates configuration object for given profile and list of streams with YAML document names to read

Parameters:

  • profile (Array) —

    list of profile names to merge

  • streams (Array) —

    list of YAML documents and their

Returns:

  • (OpenStruct) —

    instance which contains all resolved profile fields



391
392
393
394
 
# File 'lib/jac/configuration.rb', line 391

def read(profile, *streams)
  profile = [ConfigurationReader::DEFAULT_PROFILE_NAME] if profile.empty?
  ConfigurationReader.new(streams).read(*profile)
end