Construct is extensible, persistent, structured configuration for Ruby and humans with text editors. What do I mean?

You have a ruby program. Maybe it’s a Ramaze app. It needs to store some configuration data. It should be easily serialized to YAML so anyone can edit the file easily. It should support nested structures. It should minimize typing, and make access unambiguous. It should take no effort to create and extend multi-layer configuration with many data types and accessors. Moreover, it should allow you to define a schema for the options that are available, making documentation easy. That’s where Construct comes in.

gem install construct

config = Construct.new

Hey, we have a configuration object. Let’s describe a web site. Keys are always symbols, but can be accessed via methods just like an OpenStruct.

config.name = "Aphyr"
config.base_url = "http://aphyr.com"

And getting at them is easy, too.

config.name
  => "Aphyr"

If the key you want is already a method, just use config#[] and config#[]=. Construct converts strings to symbols for you..

How about a database connection? Those parameters all belong together.

config.db = {
  :user => 'cr',
  :password => 'some password',
}

Secretly, Construct converted that hash into another Construct. You can chain methods to easily access nested options.

config.db.user
  => 'cr'

Databases need a host. Let’s define a host field.

config.db.define(:host,
  :default => '127.0.0.1',
  :desc => 'The host the database adapter connects to.'
)
config.db.host
  => '127.0.0.1'

You can override this, naturally.

config.db.host = 'db.aphyr.com'
config.db.host
  => 'db.aphyr.com'

The schema is accessible as a hash via #schema, so you can easily pump out configuration docs, HTML forms, whatever.

Construct serializes neatly to YAML. Keys are expressed as strings, to save typing and make things look clean.

config.to_yaml =>
--- 
db: 
  user: cr
  password: some password
name: Aphyr
base_url: http://aphyr.com

Hey, this is easy! Now let’s load that configuration from a string.

config = Construct.load yaml

Maybe you need to implement extra logic in your config–perhaps you can specify either a db hash as shown above, or a connection string. Just subclass Construct::Construct or define methods directly on the construct.

class DBConfig < Construct
  def db_str
    self[:db_str] || make_db_string_from_hash(db)
  end
end

Defining schemas at the class level, as opposed to creating a Construct instance and operating on its schema is easy. Just use Construct.define to operate on the class schema. When you create an instance of that class, the class schema is used as a default for the instance.

class UserConfig < Construct
  define :state,
    :desc => "The user's home state"
    :default => "Oregon"
  end
end

conf = UserConfig.new
conf.state # => "Oregon"

Problem solved. Now get back to having fun instead of worrying about configuration!

Contributors

---

Kyle Kingsbury <aphyr@aphyr.com> Spencer Miles <spencer@vodpod.com>