using_yaml

= 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.

== Copyright

Copyright (c) 2010 Marc Bowes. See LICENSE for details.