using_yaml 0.3.4 → 1.0.0

data/VERSION

@@ -1 +1 @@
-0.3.4
+1.0.0

data/lib/using_yaml/array.rb

@@ -0,0 +1,29 @@
+module UsingYAML
+  # Calls add_extensions on all children. Also defines a +save+ method
+  # iff this is a top-level UsingYAML object (see below for details).
+  def self.add_array_extensions(array, pathname)
+    # Here we define a Module to extend the array
+    extensions = Module.new do
+      # Iterate over the items
+      array.each do |item|
+        # Recursively continue to extend.
+        UsingYAML.add_extensions(item)
+      end
+      
+      # Define a save method if a pathname was supplied (only happens
+      # on the top-level object - that is, example.foo will have a
+      # +save+, but example.foo.bar will not).
+      if pathname
+        define_method(:save) do
+          # Serialise using +to_yaml+
+          File.open(pathname, 'w') do |f|
+            f.puts self.to_yaml
+          end
+        end
+      end
+    end
+
+    # Load in the extensions for this instance
+    array.extend(extensions)
+  end
+end

data/lib/using_yaml/hash.rb

@@ -0,0 +1,57 @@
+module UsingYAML
+  # Calls add_extensions on all children. Also defines a +save+ method
+  # iff this is a top-level UsingYAML object (see below for details).
+  def self.add_hash_extensions(hash, pathname)
+    # Here we define a Module to extend the hash
+    extensions = Module.new do
+      # Recursively continue to extend.
+      hash.each_pair do |key, value|
+        UsingYAML.add_extensions(value)
+      end
+
+      define_method(:method_missing) do |*args|
+        name = args.shift.to_s
+
+        if args.empty?
+          send(:[], name) || UsingYAML.add_extensions(nil)
+        elsif args.size == 1 && name =~ /(.+)=/
+          # This is an "alias" turning self.key= into self[key]=
+          # Also extends the incoming value so that it behaves
+          # consistently with the other key-value pairs.
+          key   = $1
+          value = args.first
+
+          # Save the value in the hashtable
+          send(:[]=, key, UsingYAML.add_extensions(value))
+
+          # Define the new reader (as above)
+          new_reader_extension = Module.new do
+            define_method(key) do
+              send(:[], key) || UsingYAML.add_extensions(nil)
+            end
+          end
+          extend(new_reader_extension)
+
+          value
+        else
+          super(name, args)
+        end
+      end
+
+      # Define a save method if a pathname was supplied (only happens
+      # on the top-level object - that is, example.foo will have a
+      # +save+, but example.foo.bar will not).
+      if pathname
+        define_method(:save) do
+          # Serialise using +to_yaml+
+          File.open(pathname, 'w') do |f|
+            f.puts self.to_yaml
+          end
+        end
+      end
+    end
+
+    # Load in the extensions for this instance
+    hash.extend(extensions)
+  end
+end

data/lib/using_yaml/nilclass.rb

@@ -0,0 +1,33 @@
+module UsingYAML
+  def self.add_nilclass_extensions(instance, pathname)
+    extensions = Module.new do
+      define_method(:method_missing) do
+        # Child objects should not have #save
+        if respond_to? :save
+          add_extensions(nil)
+        else
+          # One nil is the same as the next :)
+          self
+        end
+      end
+      
+      # Define a save method if a pathname was supplied (only happens
+      # on the top-level object - that is, example.foo will have a
+      # +save+, but example.foo.bar will not).
+      if pathname
+        # Being nil translates to "no file", not to "empty file", so we
+        # want to actually delete any existing file. This is a semantic
+        # difference, but important: there is a huge different between
+        # an _empty_ file and a _non-existant_ file. YAML does not
+        # reflect this difference, so we do.
+        define_method(:save) do
+          # If we can't delete it (permissions, ENOENT..), then there
+          # ain't much we can do, so just squelch the error.
+          FileUtils.rm(pathname) rescue nil
+        end
+      end
+    end
+
+    instance.extend(extensions)
+  end
+end

data/lib/using_yaml.rb

@@ -1,23 +1,69 @@
 require 'yaml'
 require 'pathname'
-require 'using_yaml/open_hash'
-require 'using_yaml/patches/array'
-require 'using_yaml/patches/hash'
+require 'using_yaml/array'
+require 'using_yaml/hash'
+require 'using_yaml/nilclass'
 
+# UsingYAML provides convenient class extensions which make it easy to
+# interact with YAML-storage of settings files by defining accessors
+# which allow one to talk to the files as if they were fully
+# implemented classes.
+#
+# Each of these files will be automagically enhanced to provide save
+# and clean methods of talking to your YAML files without needing to
+# worry about checking for nil's, re-serializing or long-winded hash
+# access.
+#
+# This module also provides some static access to make it easy to
+# enable/disable options such as squelching error messages (in
+# production) and tracking where instances should load their files
+# from.
+#
+# See +using_yaml+ for usage information.
 module UsingYAML
   class << self
+    # Extends the incoming Array/Hash with magic which makes it
+    # possible to +save+ and (in the case of Hashes) use methods
+    # instead of []-access.
+    def add_extensions(object, pathname = nil)
+      case object
+      when Array
+        add_array_extensions(object, pathname)
+      when Hash
+        add_hash_extensions(object, pathname)
+      when NilClass
+        add_nilclass_extensions(object, pathname)
+      end
+      
+      object
+    end
+  
+    # Returns the path where the given class will load from. See
+    # +using_yaml_path+ for information on how to override this on a
+    # per-instance basis.
     def path(klass)
       return @@path[klass] if defined?(@@path)
     end
 
+    # Sets the the path where the given class will load from. See
+    # +using_yaml_path+ for information on how to override this on a
+    # per-instance basis.
     def path=(args)
       (@@path ||= {})[args.first] = args.last
     end
 
+    # Because of the "safety" UsingYAML provides, it is easy for typos
+    # to creep in, which might result in unexpected nil's. UsingYAML
+    # therefore is verbose in warning about these potential errors.
+    #
+    # This method disables those warnings, which is useful in a
+    # production environment or if you are sure you aren't making mistakes.
     def squelch!
       @@squelched = true
     end
 
+    # Returns true if UsingYAML will warn about potential typos (or
+    # similar) which might otherwise be masked.
     def squelched?
       defined?(@@squelched) && @@squelched
     end
@@ -28,56 +74,113 @@ module UsingYAML
   end
 
   module ClassMethods
+    # Used to configure UsingYAML for a class by defining what files
+    # should be loaded and from where.
+    #
+    #   include UsingYAML
+    #   using_yaml :foo, :bar, :path => "/some/where"
+    #
+    # +args+ can contain either filenames or a hash which specifices a
+    # path which contains the corresponding files.
+    #
+    # The value of :path must either be a string or Proc (see
+    # +using_yaml_path+ for more information on overriding paths).
     def using_yaml(*args)
+      # Include the instance methods which provide accessors and
+      # mutators for reading/writing from/to the YAML objects.
       include InstanceMethods
-      
+
+      # Each argument is either a filename or a :path option
       args.each do |arg|
         case arg
         when Symbol, String
-          filename = arg.to_s
-          using_yaml_file(filename)
+          # Define accessors for this file
+          using_yaml_file(arg.to_s)
         when Hash
-          arg.each do |key, value|
-            case key
-            when :path
-              UsingYAML.path = [self.inspect, value]
-            else
-              filename = key
-              options  = value
-              using_yaml_file(filename)
-            end
-          end
+          # Currently only accepts { :path => ... }
+          next unless arg.size == 1 && arg.keys.first == :path
+          
+          # Take note of the path
+          UsingYAML.path = [self.inspect, arg.values.first]
         end
       end
     end
 
+    # Special attr_accessor for the suppiled +filename+ such that
+    # files are intelligently loaded/written to disk.
+    #
+    #   using_yaml_file(:foo) # => attr_accessor(:foo) + some magic
+    #
+    # If class Example is setup with the above, then:
+    #
+    #   example = Example.new
+    #   example.foo      # => loads from foo.yml
+    #   example.foo.bar  # => equivalent to example.foo['bar']
+    #   example.foo.save # => serialises to foo.yml
+    #
     def using_yaml_file(filename)
+      # Define an reader for filename such that the corresponding
+      # YAML file is loaded. Example: using_yaml_file(:foo) will look
+      # for foo.yml in the specified path.
       define_method(filename) do
+        # Work out the absolute path for the filename and get a handle
+        # on the cachestore for that file.
         pathname = using_yaml_path.join("#{filename}.yml").expand_path
-        cache    = (@using_yaml_cache ||= {})
-        data     = @using_yaml_cache[pathname]
-        return data if data
+        yaml     = (@using_yaml_cache ||= {})[pathname]
 
+        # If the yaml exists in our cache, then we don't need to hit
+        # the disk.
+        return yaml if yaml
+
+        # Safe disk read which either reads and parses a YAML object
+        # (and caches it against future reads) or graciously ignores
+        # the file's existence. Note that an error will appear on
+        # stderr to avoid typos (or similar) from causing unexpected
+        # behavior. See +UsingYAML.squelch!+ if you wish to hide the
+        # error.
         begin
-          data = YAML.load_file(pathname).to_ohash(pathname)
-          @using_yaml_cache[pathname] = data
+          @using_yaml_cache[pathname] = UsingYAML.add_extensions(YAML.load_file(pathname), pathname)
         rescue Exception => e
           $stderr.puts "(UsingYAML) Could not load #{filename}: #{e.message}" unless UsingYAML.squelched?
-          nil
+          UsingYAML.add_extensions(nil)
         end
       end
+
+      # Define a writer for filename such that the incoming object is
+      # treated as a UsingYAML-ized Hash (magical properties). Be
+      # aware that the incoming object will not be saved to disk
+      # unless you explicitly do so.
+      define_method("#{filename}=".to_sym) do |object|
+        # Work out the absolute path for the filename and get a handle
+        # on the cachestore for that file.
+        pathname = using_yaml_path.join("#{filename}.yml").expand_path
+        (@using_yaml_cache ||= {})[pathname] = UsingYAML.add_extensions(object, pathname)
+      end
     end
   end
 
+  # Instance methods which allow us to define where YAML files are
+  # read/written from/to.
   module InstanceMethods
-    attr_accessor :using_yaml_cache
-    
+    # Reader which determines where to find files according to the
+    # following recipe:
+    #
+    #   (1) Load the :path option from +using_yaml+, if set
+    #   (2) Possibly invoke a Proc (if supplied to step 1)
+    #   (3) Default to the current location if 1 & 2 failed
+    #
+    # You can, of course, overrite this method if you wish to supply
+    # your own logic.
     def using_yaml_path
+      return @using_yaml_path unless @using_yaml_path.nil?
+      
       path = UsingYAML.path(self.class.name)
       path = path.call(self) if path.is_a? Proc
-      @using_yaml_path ||= Pathname.new(path || ENV['HOME'])
+      @using_yaml_path = Pathname.new(path || '.')
     end
 
+    # Sets the YAML load path to the given argument by invoking
+    # +Pathname.new+ on +path+.
     def using_yaml_path=(path)
       @using_yaml_path = path && Pathname.new(path)
     end

data/spec/spec_helper.rb

@@ -21,6 +21,6 @@ def reset_person!
   end
 
   UsingYAML.path = ['Person', nil]
-  @person.using_yaml_path = nil
-  @person.using_yaml_cache = nil
+  @person.instance_variable_set('@using_yaml_path',  nil)
+  @person.instance_variable_set('@using_yaml_cache', nil)
 end

data/spec/using_yaml/path_spec.rb

@@ -5,8 +5,8 @@ describe "UsingYAML#paths" do
     @person = Person.new
   end
 
-  it "should return $HOME for non-existant pathnames" do
-    @person.using_yaml_path.expand_path.to_s.should == ENV['HOME']
+  it "should return pwd for non-existant pathnames" do
+    @person.using_yaml_path.expand_path.to_s.should == `pwd`.strip
   end
 
   it "should return path/to/defined for globally set pathnames" do

data/spec/using_yaml/using_yaml_spec.rb

@@ -1,23 +1,53 @@
 require File.dirname(__FILE__) + '/../spec_helper'
 
-describe 'UsingYAML#core' do
+describe 'UsingYAML' do
   before(:each) do
     @person = Person.new
   end
 
-  it "should return nil for invalid settings files" do
-    @person.children.should be_nil
+  describe 'robustness' do
+    it "should return nil for invalid settings files" do
+      @person.children.should be_nil
+    end
+
+    it "should gracefully handle nil.nil..." do
+      @person.children.invalid.call.should be_nil
+    end
+  end
+
+  describe 'hashes' do
+    it "should work" do
+      YAML.stubs(:load_file).with(anything).returns({ 'foo' => 'bar' })
+      @person.children.should == { 'foo' => 'bar' }
+      @person.children.foo.should == 'bar'
+    end
+
+    it "should define methods when a hash gets a new key" do
+      YAML.stubs(:load_file).with(anything).returns({})
+      @person.children.foo = 'bar'
+      @person.children.foo.should == 'bar'
+    end
+
+    it "should catchup when a hash gets a new key via []=" do
+      YAML.stubs(:load_file).with(anything).returns({})
+      @person.children['foo'] = 'bar'
+      @person.children.foo.should == 'bar'
+    end
   end
 
-  it "should return valid settings files" do
-    YAML.stubs(:load_file).with(anything).returns({ 'foo' => 'bar' })
-    @person.children.should == { 'foo' => 'bar' }
-    @person.children.foo.should == 'bar'
+  describe 'arrays' do
+    it "should work" do
+      YAML.stubs(:load_file).with(anything).returns([ { 'foo' => 'bar' } ])
+      @person.children.class.name.should == 'Array'
+      @person.children.first.should == { 'foo' => 'bar' }
+    end
   end
 
-  it "should work with arrays" do
-    YAML.stubs(:load_file).with(anything).returns([ { 'foo' => 'bar' } ])
-    @person.children.class.name.should == 'Array'
-    @person.children.first.should == { 'foo' => 'bar' }
+  describe 'assignments' do
+    it "should work" do
+      @person.children = [ :example ]
+      @person.children.should == [ :example ]
+      @person.children.respond_to?(:save).should == true
+    end
   end
 end

data/using_yaml.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{using_yaml}
-  s.version = "0.3.4"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Marc Bowes"]
-  s.date = %q{2010-02-15}
+  s.date = %q{2010-03-06}
   s.description = %q{"Load, save and use YAML files as if they were objects"}
   s.email = %q{marcbowes@gmail.com}
   s.extra_rdoc_files = [
@@ -24,9 +24,9 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "lib/using_yaml.rb",
-     "lib/using_yaml/open_hash.rb",
-     "lib/using_yaml/patches/array.rb",
-     "lib/using_yaml/patches/hash.rb",
+     "lib/using_yaml/array.rb",
+     "lib/using_yaml/hash.rb",
+     "lib/using_yaml/nilclass.rb",
      "spec/spec_helper.rb",
      "spec/using_yaml/path_spec.rb",
      "spec/using_yaml/using_yaml_spec.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: using_yaml
 version: !ruby/object:Gem::Version 
-  version: 0.3.4
+  version: 1.0.0
 platform: ruby
 authors: 
 - Marc Bowes
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-15 00:00:00 +02:00
+date: 2010-03-06 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -39,9 +39,9 @@ files:
 - Rakefile
 - VERSION
 - lib/using_yaml.rb
-- lib/using_yaml/open_hash.rb
-- lib/using_yaml/patches/array.rb
-- lib/using_yaml/patches/hash.rb
+- lib/using_yaml/array.rb
+- lib/using_yaml/hash.rb
+- lib/using_yaml/nilclass.rb
 - spec/spec_helper.rb
 - spec/using_yaml/path_spec.rb
 - spec/using_yaml/using_yaml_spec.rb

data/lib/using_yaml/open_hash.rb

@@ -1,46 +0,0 @@
-module OpenHash
-  class << self
-    def from_hash(hash, pathname = nil)
-      Module.new do
-        hash.each_pair do |key, value|
-          define_method(key) do
-            value.respond_to?(:to_ohash) ? value.to_ohash(value) : value
-          end
-
-          define_method("#{key}=") do |value|
-            case value
-            when Hash
-              send(:[]=, key, value.to_ohash)
-            else
-              send(:[]=, key, value)
-            end
-          end
-        end
-
-        if pathname
-          define_method(:save) do
-            File.open(pathname, 'w') do |f|
-              f.puts self.to_yaml
-            end
-          end
-        end
-      end
-    end
-
-    def from_array(array, pathname = nil)
-      Module.new do
-        array.each do |e|
-          e.to_ohash(e)
-        end
-        
-        if pathname
-          define_method(:save) do
-            File.open(pathname, 'w') do |f|
-              f.puts self.to_yaml
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/using_yaml/patches/array.rb

@@ -1,5 +0,0 @@
-class Array
-  def to_ohash(pathname)
-    self.extend OpenHash.from_array(self, pathname)
-  end
-end

data/lib/using_yaml/patches/hash.rb

@@ -1,5 +0,0 @@
-class Hash
-  def to_ohash(pathname)
-    self.extend OpenHash.from_hash(self, pathname)
-  end
-end