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.

using_yaml

Development