Using Yaml

This Gem allows you to easily associate YAML files with classes

Installation

From Gemcutter:

sudo gem install using_yaml

Usage

require 'rubygems'
require 'using_yaml'

class ExampleUsage
  include UsingYAML

  using_yaml :some, :settings
end

example = ExampleUsage.new

# Load "OpenHash" from pathname.join('some.yml')
example.some #=> { "key" => "value" }

# Behaves like a normal hash
example.some['key'] #=> "value"

# AND like an object
example.some.key #=> "value"

# Setter methods work too
example.some.key = "another value"

# Saves to original location
example.save #=> writes

# .. and the same for settings
example.settings #=> "{ ... }"

Pathname

By default, UsingYAML will look for .yml files in your home directory. There are several ways to configure this:

With strings:

class ExampleUsage
  include UsingYAML

  using_yaml :example, :path => '/your/path/here'
end

Using a Proc:

class ExampleUsage
  include UsingYAML

  using_yaml :example, :path => lambda { |c| c.pathname }
  attr_accessor :pathname
end

example = ExampleUsage.new
example.pathname = '/your/path/here'

Overriding using_yaml_path:

class ExampleUsage
  include UsingYAML

  using_yaml :example

  def using_yaml_path
    '/your/code/here'
  end
end

Error messages

By default, UsingYAML will return nil for missing files. It will also complain on STDERR. If you want to disable the complaint:

UsingYAML.squelch!

Benchmark

There are two extremes when navigating hashes. Either we hit a nil early, or we traverse successfully to the end. UsingYAML performs well regardless. Here are results using ‘ruby-1.8.7-p249 [ x86_64 ]`

Testing chains of nils

            user     system      total        real
normal      0.920000   0.040000   0.960000 (  0.980095)
chained     0.900000   0.060000   0.960000 (  0.973219)

Testing where the keys exist

            user     system      total        real
normal      2.780000   0.150000   2.930000 (  2.930808)
chained     0.960000   0.060000   1.020000 (  1.031477)

Results

While there are certainly other things to test, these benchmarks show that the method chaining performs either almost as well (in the case of nil.nil..) or significantly better (in the case of key.key..).

I’d definitely like to do some more testing. However, this is primarily a convenience library to improve programmer happiness, so these tests have made me happy enough for now.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.