YAML Settings

Load and merge application settings from YAML files.

At load time, settings are merged in two stages. First, all YAML data are recursively merged in reverse file order. Settings in succeeding files override all duplicate settings in preceding files. Second, the user selected settings—specified by key (e.g., environment key)—are recursively merged with the default settings.

This class can load multiple settings files, which provides a few benefits:

Confidential settings can be stored separately and securely from non-confidential settings; for example, in a public repository.
Settings for each application component or service (e.g., database, payment gateway, logger, CDN) can be stored in their respective files.
Shared or system-wide settings can be merged with application settings.

Settings File Examples

The following are settings files, defined using YAML, which typically use the .yml or .yaml file extension. For information on how to craft YAML, see the spec.

Absolute minimal settings

default:

Above is the mandatory default stanza, which must be present in at least one of the YAML settings files, even if it is empty. This isn’t very useful, so lets add a couple of default settings.

default:
  setting_1: on
  setting_2: off

Database settings

Here we have settings that specify the database name, user, host, and password file. There are three additional top-level stanzas: development, production, and test. These stanzas can be defined for any reason and have any name, but typically represent the runtime environment or mode of the application. Zero or more non-default top-level stanzas can be defined.

# database.yaml
default:
  db:
    host: db.example.com
    user: dbusr
    pass: config/db-access

development:
  db:
    name: myapp_dev

production:
  db:
    name: myapp
    pass: /var/www/sites/myapp/db-access

test:
  db:
    name: myapp_test

With these settings, the default will always provide the database host and user because it is not overridden in any other stanza. However, the database name is not specified in default because it is set in each environment. In production, the database password file is unique—and secure of course—thus overrides default.

Usage Examples

First things first!

require 'yaml_settings'

Load database settings

Load production using the database settings above. The production settings are merged into default.

settings = YAMLSettings.new('database.yaml', :production)
settings.db.host    # => "db.example.com"
settings.db.user    # => "dbusr"
settings.db.name    # => "myapp"
settings.db.pass    # => "/var/www/sites/myapp/db-access"

The settings are accessed using methods. The db setting is actually a Hash and can also be accessed as such.

settings.db['host']   # => "db.example.com"

The difference is that method access raises an error if a setting is nonexistent.

settings.db.mia       # KeyError: key not found: "mia"
settings.db['mia']    # => nil

Method access is only available for string and symbol keys of Hash settings.

Load multiple settings files

It may be helpful to store settings for each application component separately. Or perhaps, settings are in a shared location. Here’s how to initialize for such a situation:

settings = YAMLSettings.new '/etc/app-defaults.yml',         # system wide
                            '/etc/payment-gateway.yml',      # system wide
                            '/var/www/share/config/cdn.yml', # common for sites
                            'config/app.yml',                # app specific
                            'config/database.yml',           # app specific
                            ENV['APP_MODE']

The settings variable above is a compilation of four merges. First, config/database.yml will merge with and override config/app.yml; the result will merge with and override cdn.yml; and so on. Therefore, specify files with more generic settings first.

History

2017-06-30, v1.0.6
- First public release

License

(ISC License)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.