yaml_settings

= 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[http://yaml.org], which typically use the +.yml+ or +.yaml+ file extension. For information on how to craft YAML, see the spec[http://yaml.org/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.

== Links

Homepage :: https://ecentryx.com/gems/yaml_settings Ruby Gem :: https://rubygems.org/gems/yaml_settings Source Code :: https://bitbucket.org/pachl/yaml_settings/src Bug Tracker :: https://bitbucket.org/pachl/yaml_settings/issues

== History

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

== License

({ISC License}[https://opensource.org/licenses/ISC])

Copyright (c) 2013-2017, Clint Pachl [e-mail]

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.