Sting - Minimal Settings Library

Sting is a minimal, lightweight, multi-YAML settings library.

Installation

$ gem install sting

Features

Aggressively minimalistic.
Settings are accessible through a globally available class.
Can be used either as a singleton class or as an instance.
Load and merge one or more YAML files or hashes.
Settings objects are standard ruby hashes, arrays and basic types.
Ability to update settings at runtime.
Ability to extend (import) other YAML files.
ERB code in the YAML files will be evaluated.

Nonfeatures

No dot notation access to nested values - Use Settings.server['host'] instead of Settings.server.host.
No special generators for Rails. Usage with rails is still trivial.

Usage

Using as a singleton class

require 'sting'

# If you want to use a different name than Sting (optional)
Settings = Sting

# Load some YAML files. If the provided filename does not end with '.yml' or 
# '.yaml', we will add '.yml' to it.
Settings << 'one'
Settings << 'two.yml'

# Adding additional files can also be done with `#push`. These two are the 
# same.
Settings << 'one'
Settings.push 'one'

# Merge with another options hash
Settings << { port: 3000, host: 'localhost' }

# Load all files from a directory
Settings << "dir/that-contains/yamls"

# Load all files from a directory, recursively
Settings << "dir/that-contains/yamls/**/*.yml"

# Access values
p Settings.host
p Settings['host']
p Settings[:host]

# Access nested values
p Settings.server['host']

# Access nested values safely (get nil if any of the keys does not exist)
p Settings[:server, :host]
p Settings[:server, :production, :host]

# Get the hash of all values
p Settings.settings

# Check if a key is defined
p Settings.has_key? :hello

# Access value, but raise an exception if it does not exist
p Settings.host!

# Access boolean values, or check if a key exists
p Settings.host?

# Update a value (in memory only, not in file)
Settings.port = 3000

# Reset (erase) all values
Settings.reset!

Using as an instance

All the above operations are also available to instances of Sting.

require 'sting'

# Create an instance.
config = Sting.new

# Or, create an instance, and provide the first source file to it.
config = Sting.new 'settings'

# Load additional YAML files. 
config << 'local_settings'

Extending YAML files

Sting uses ExtendedYAML, which means you can use the extends key to load one or more YAML files into your loaded configuration files:

# Extend a single file (extension is optional)
extends: some-other-file.yml

# Extend multiple files
extends:
- some-file
- another-file

Using with Rails

You can use this however you wish in Rails. This is the recommended implementation:

Add sting to your Gemfile:

gem 'sting'

Create an initializer:

# config/initializers/settings.rb
Settings = Sting
Settings << "#{Rails.root}/config/settings"
Settings << "#{Rails.root}/config/settings/#{Rails.env}"

Create four config files:

config/settings.yml
config/settings/development.yml
config/settings/production.yml
config/settings/test.yml

sting

Runtime