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.
Links¶ ↑
- Homepage
- Ruby Gem
- Source Code
- Bug Tracker
History¶ ↑
-
2017-06-30, v1.0.6
-
First public release
-
License¶ ↑
Copyright © 2013-2017, Clint Pachl <pachl@ecentryx.com>
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.