structure 0.2.0 → 0.3.0

data/README.md

@@ -1,8 +1,8 @@
 Structure
 =========
 
-Structure is a better struct.
-
+Structure is a better Struct and does wonders when modeling ephemeral
+data fed in from an API.
 
     #_                                                                       d
     ##_                                                                     d#
@@ -30,33 +30,51 @@ Structure is a better struct.
 Usage
 -----
 
-Structure, like Struct, is great for defining ephemeral models.
+Require:
 
     require 'structure'
 
+Define a model:
+
     class Person < Structure
       key :name
       key :age,     :type => Integer
-      key :friends, :type => Array
+      key :friends, :type => Array, :value => []
     end
 
-    john = Person.new(:name => "John",
-                      :age  => 28)
+Typecast values:
 
-    jane = Person.new(:name => "Jane",
-                      :age  => 24)
+    p1 = Person.new :name => 'John'
+    p1.age = '28'
+    p1.age
+    => 28
 
-    john.friends = [jane]
+Use ORM-esque association idioms:
 
-When it comes to dumping JSON, Structure is more aesthetically-minded.
+    p2 = Person.new :name => 'Jane'
+    p1.friends << p2
+
+Dump good-looking JSON:
 
     require 'structure/json'
 
-    json = john.to_json
-    => {"json_class":"Person","name":"John","age":28,"friends":[{"json_class":"Person","name":"Jane","age":24,"friends":null}]}
+    json = p1.to_json
+    => {"json_class":"Person","name":"John","age":28,"friends":[{"json_class":"Person","name": null,"age":null,"friends":[]}]}
+
+Load the JSON in a different app back into Ruby seamlessly, provided you
+have the same models defined there:
 
     person = JSON.parse(json)
-    person.friends.first.name
-    => "Jane"
-    person.friends.first.age
-    => 24
+    person.friends.first.class
+    => Person
+
+Types
+-----
+
+Structure supports the following types:
+* Array
+* Boolean
+* Float
+* Hash
+* Integer
+* String

data/Rakefile

@@ -1,5 +1,4 @@
 require 'bundler'
-require 'cucumber/rake/task'
 require 'rspec/core/rake_task'
 
 Bundler::GemHelper.install_tasks

data/lib/structure.rb

@@ -1,61 +1,88 @@
-require 'json'
-
-# A better struct.
+# A better Ruby Struct.
 class Structure
-
-  # Mix in the Enumerable module.
   include Enumerable
 
-  @@keys = []
+  # Ruby doesn't have a Boolean class, so let's feign one.
+  unless Object.const_defined?(:Boolean)
+    module ::Boolean; end
+    class ::TrueClass; include Boolean; end
+    class ::FalseClass; include Boolean; end
+  end
+
+  TYPES = [Array, Boolean, Float, Hash, Integer, String]
+
+  @@default_attributes = {}
 
   # Defines an attribute key.
   #
   # Takes a name and an optional hash of options. Available options are:
   #
-  # * :type, which can be Integer, Float, String, and Array.
+  # * :type, which can be Array, Boolean, Float, Integer, JSON, Pathname,
+  # String, or URI. If not specified, type defaults to String.
+  # * :default, which sets the default value for the attribute.
   #
   #    class Book
   #      key :title,   :type => String
-  #      key :authors, :type => Array
+  #      key :authors, :type => Array, :default => []
   #    end
   #
   def self.key(name, options={})
+    name = name.to_sym
     if method_defined?(name)
       raise NameError, "#{name} is already defined"
     end
 
-    name = name.to_sym
-    type = options[:type]
-    @@keys << name
+    type = options[:type] || String
+    unless TYPES.include? type
+      raise TypeError, "#{type} is not a valid type"
+    end
+
+    default = options[:default]
+    unless default.nil? || default.is_a?(type)
+      raise TypeError, "#{default} is not #{%w{AEIOU}.include?(type.to_s[0]) ? 'an' : 'a'} #{type}"
+    end
+
+    @@default_attributes[name] = default
 
     module_eval do
 
+      # Define a proc to typecast value.
+      typecast =
+        if type == Boolean
+          lambda do |value|
+            case value
+            when String
+             !(value =~ /false/i)
+            else
+             !!value
+            end
+          end
+        elsif type == Hash
+          lambda do |value|
+            unless value.is_a? Hash
+              raise TypeError, "#{value} is not a Hash"
+            end
+            value
+          end
+        else
+          lambda { |value| Kernel.send(type.to_s, value) }
+        end
+
       # Define a getter.
       define_method(name) { @attributes[name] }
 
-      # Define a setter. The setter will optionally typecast.
+      # Define a setter.
       define_method("#{name}=") do |value|
-        modifiable[name] =
-          if type && value
-            Kernel.send(type.to_s, value)
-          else
-            value
-          end
+        modifiable[name] = value.nil? ? nil : typecast.call(value)
       end
     end
   end
 
   # Creates a new structure.
   #
-  # Optionally, populates the structure with a hash of attributes. Otherwise,
-  # all values default to nil.
+  # Optionally, seeds the structure with a hash of attributes.
   def initialize(seed = {})
-    @attributes =
-      @@keys.inject({}) do |attributes, name|
-        attributes[name] = nil
-        attributes
-      end
-
+    initialize_attributes
     seed.each { |key, value| self.send("#{key}=", value) }
   end
 
@@ -85,11 +112,19 @@ class Structure
 
   private
 
+  def initialize_attributes
+    @attributes =
+      @@default_attributes.inject({}) do |attributes, (key, value)|
+        attributes[key] = value
+        attributes
+      end
+  end
+
   def modifiable
     begin
       @modifiable = true
     rescue
-      raise TypeError, "can't modify frozen #{self.class}", caller(3)
+      raise TypeError, "can't modify frozen #{self.class}"
     end
     @attributes
   end

data/lib/structure/version.rb

@@ -1,3 +1,3 @@
 class Sucker
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/spec/models/person.rb

@@ -1,5 +1,5 @@
 class Person < Structure
   key :name
   key :age, :type => Integer
-  key :friends
+  key :friends, :type => Array, :default => []
 end

data/spec/structure/json_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 describe Structure do
   context "when `structure/json' is required" do
     let(:person) { Person.new(:name => 'Joe', :age => 28) }
-    let(:json) { '{"json_class":"Person","name":"Joe","age":28,"friends":null}' }
+    let(:json) { '{"json_class":"Person","name":"Joe","age":28,"friends":[]}' }
 
     before do
       require 'structure/json'
@@ -22,9 +22,9 @@ describe Structure do
         person.friends = [Person.new(:name => 'Jane')]
       end
 
-      it "loads nested structures from JSON" do
+      it "loads them into their corresponding structures" do
         json = person.to_json
-        JSON.parse(json).friends.first.name.should eql 'Jane'
+        JSON.parse(json).friends.first.should be_a Person
       end
     end
   end

data/spec/structure_spec.rb

@@ -4,11 +4,10 @@ describe Structure do
   let(:person) { Person.new }
 
   it "is enumerable" do
-    person.name ="Joe"
-    person.map { |key, value| value }.should include "Joe"
+    person.should respond_to :map
   end
 
-  context "when object is frozen" do
+  context "when frozen" do
     before do
       person.freeze
     end
@@ -25,29 +24,116 @@ describe Structure do
       %w{name name=}.each { |method| person.should respond_to method }
     end
 
-    context "when name clashes with an existing method" do
+    context "when a key name clashes with a method name" do
       it "raises an error" do
         expect do
-          Person.key :name
+          Person.key :class
         end.to raise_error NameError
       end
     end
 
+    context "when an invalid type is specified" do
+      it "raises an error" do
+        expect do
+          Person.key :location, :type => Object
+        end.to raise_error TypeError
+      end
+    end
+
+    context "when default value is not of the specified type" do
+      it "raises an error" do
+        expect do
+          Person.key :location, :type => String, :default => 0
+        end.to raise_error TypeError
+      end
+    end
+  end
+
+  describe "attribute getter" do
+    it "returns the value of the attribute" do
+      person.instance_variable_get(:@attributes)[:name] = 'Joe'
+      person.name.should eql 'Joe'
+    end
+
+    context "when type is Array and default value is []" do
+      it "supports the `<<' idiom" do
+        person.friends << Person.new
+        person.friends.count.should eql 1
+      end
+    end
+  end
+
+  describe "attribute setter" do
+    it "sets the value of the attribute" do
+      person.name = "Joe"
+      person.instance_variable_get(:@attributes)[:name].should eql 'Joe'
+    end
+
     context "when a type is specified" do
-      context "when setting the attribute to a non-nil value" do
-        it "casts the value" do
-          person.age = "28"
-          person.age.should eql 28
+      it "casts the value" do
+        person.age = "28"
+        person.age.should be_an Integer
+      end
+    end
+
+    context "when a type is not specified" do
+      it "casts to String" do
+        person.name = 123
+        person.name.should be_a String
+      end
+    end
+
+    context "when type is Boolean" do
+      context "when default value is true" do
+        it "does not raise an invalid type error" do
+          expect do
+            Person.key :single, :type => Boolean, :default => true
+          end.not_to raise_error
         end
       end
 
-      context "when setting the attribute to nil" do
-        it "does not set the value" do
-          person.age = nil
-          person.age.should be_nil
+      context "when default value is false" do
+        it "does not raise an invalid type error" do
+          expect do
+            Person.key :married, :type => Boolean, :default => false
+          end.not_to raise_error
+        end
+      end
+    end
+
+    context "when type is Hash" do
+      before(:all) do
+        Person.key :education, :type => Hash
+      end
+
+      context "when setting to a value is not a Hash" do
+        it "raises an error" do
+          expect do
+            person.education = 'foo'
+          end.to raise_error TypeError
         end
       end
     end
+
+    context "when a default is specified" do
+      it "defaults to that value" do
+        Person.key :location, :default => 'New York'
+        person.location.should eql 'New York'
+      end
+    end
+
+    context "when a default is not specified" do
+      it "defaults to nil" do
+        person.age.should be_nil
+      end
+    end
+
+    context "when setting the value of an attribute to nil" do
+      it "does not typecast the value" do
+        person.age = nil
+        person.age.should be_a NilClass
+      end
+    end
   end
 
   describe ".new" do

data/structure.gemspec

@@ -9,12 +9,12 @@ Gem::Specification.new do |s|
   s.authors     = ["Paper Cavalier"]
   s.email       = ["code@papercavalier.com"]
   s.homepage    = "http://rubygems.com/gems/structure"
-  s.summary     = "Structure is a better Struct."
+  s.summary     = "A better Struct"
   s.description = <<-END_OF_DESCRIPTION.strip
-    Structure is a better Struct.
-
-    Like Struct, it is great for setting up ephemeral models. It also handles
-    typecasting and, unlike Struct, dumps nicely-formatted JSON.
+    Structure is a better Struct and does wonders when modeling ephemeral data
+    fed in from an API. It typecasts values, works with ORM-esque association
+    idioms, dumps good-looking JSON, and loads the same JSON seamlessly back
+    into Ruby.
     END_OF_DESCRIPTION
 
   s.rubyforge_project = "structure"

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Paper Cavalier
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-26 00:00:00 +01:00
+date: 2011-05-27 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -48,10 +48,10 @@ dependencies:
   type: :development
   version_requirements: *id002
 description: |-
-  Structure is a better Struct.
-  
-      Like Struct, it is great for setting up ephemeral models. It also handles
-      typecasting and, unlike Struct, dumps nicely-formatted JSON.
+  Structure is a better Struct and does wonders when modeling ephemeral data
+      fed in from an API. It typecasts values, works with ORM-esque association
+      idioms, dumps good-looking JSON, and loads the same JSON seamlessly back
+      into Ruby.
 email: 
 - code@papercavalier.com
 executables: []
@@ -104,7 +104,7 @@ rubyforge_project: structure
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Structure is a better Struct.
+summary: A better Struct
 test_files: 
 - spec/models/person.rb
 - spec/spec_helper.rb