active_nomad 0.0.4 → 0.1.0

data/CHANGELOG

@@ -1,3 +1,8 @@
+== 0.1.0 2010-10-05
+
+ * Provide multiple serialization formats (query string, json).
+ * Add #{to,from}_serialized_attributes to easily define more.
+
 == 0.0.4 2010-10-01
 
  * Attributes are inheritable.

data/README.markdown

@@ -6,16 +6,15 @@ ActiveRecord objects with a customizable persistence strategy.
 
 Sometimes you want an Active Record object that does not live in the database.
 Perhaps it never needs to be persisted, or you'd like to store it in a cookie,
-or some other store, but it would still be handy to have ActiveRecord's ability
+or a key-value store, but it would still be handy to have ActiveRecord's ability
 to cast values, run validations, or fire callbacks.
 
-Ideally, the persistence strategy would be pluggable. With Active Nomad, it is!
+If only the persistence strategy was pluggable...
 
 ## How
 
-Subclass from ActiveNomad::Base and declare your attributes with the
-`attribute` class method. The arguments look just like creating a column in a
-migration:
+Subclass from ActiveNomad::Base and declare your attributes with the `attribute`
+class method. The arguments look just like creating a column in a migration:
 
     class Thing < ActiveNomad::Base
       attribute :name, :string, :limit => 20
@@ -25,27 +24,38 @@ To persist the record, Active Nomad calls `persist`, which calls a
 Proc registered by `to_save`. For example, here's how you could
 persist to a cookie:
 
-    thing = Thing.deserialize(cookies[:thing])
+    thing = Thing.from_json(cookies[:thing])
     thing.to_save do |thing|
-      cookies[:thing] = thing.serialize
+      cookies[:thing] = thing.to_json
       true
     end
 
 Things to note:
 
- * Active Nomad defines `serialize` and `deserialize` which will
-   serialize to and from a valid query string with predictable
-   attribute order (i.e., appropriate for a cookie).
  * The proc should return true if persistence was successful, false
    otherwise. This will be the return value of `save`, etc.
- * You may alternatively override `persist` in a subclass if you
-   don't want to register a proc for every instance.
+ * Active Nomad defines `to_json` and `from_json` which will serialize to and
+   from a JSON string with predictable attribute order (i.e., appropriate for a
+   cookie).
+ * You may alternatively override `persist` in a subclass if you don't want to
+   register a proc for every instance.
 
-## Transactions
+### Serialization formats
 
-In addition to customizing persistence, you can also customize
-transaction semantics by overriding the `transaction` class method in
-a base class. Example:
+Active Nomad provides serialization to and from:
+
+ * JSON (`to_json` and `from_json`)
+ * Query string (`to_query_string` and `from_query_string`)
+
+You can define your own formats easily using `to_serialized_attributes` and
+`from_serialized_attributes`. The former returns an `ActiveSupport::OrderedHash`
+of attribute names to serialized values (`String`s or `nil`s).
+
+### Transactions
+
+In addition to customizing persistence, you can also customize transaction
+semantics by overriding the `transaction` class method in a base class. Here's
+an example that implements transactions with Redis:
 
     class RedisNomad < ActiveNomad::Base
       def self.transaction
@@ -64,8 +74,8 @@ a base class. Example:
       end
     end
 
-`ActiveNomad::Base.transaction` simply calls the given block with no
-real transaction semantics.
+`ActiveNomad::Base.transaction` simply calls the given block with no real
+transaction semantics.
 
 ## Notes
 

data/lib/active_nomad.rb

@@ -13,34 +13,74 @@ module ActiveNomad
     end
 
     #
-    # Return the attributes of this object serialized as a valid query
-    # string.
+    # Return an ActiveSupport::OrderedHash of serialized attributes.
     #
-    # Attributes are sorted by name.
+    # Attributes are sorted by name. Each value is either a string or
+    # nil.
     #
-    def serialize
-      self.class.columns.map do |column|
-        name = column.name
-        value = serialize_value(send(name), column.type) or
+    def to_serialized_attributes
+      attributes = ActiveSupport::OrderedHash.new
+      columns = self.class.columns_hash
+      self.class.column_names.sort.each do |name|
+        column = columns[name] or
           next
-        "#{CGI.escape(name)}=#{value}"
-      end.compact.sort.join('&')
+        attributes[name] = serialize_value(send(name), column.type)
+      end
+      attributes
     end
 
     #
     # Recreate an object from a serialized string.
     #
-    def self.deserialize(string)
-      params = string ? CGI.parse(string.strip) : {}
+    def self.from_serialized_attributes(deserialized_attributes)
       instance = new
-      columns.map do |column|
-        next if !params.key?(column.name)
-        value = params[column.name].first
-        instance.send "#{column.name}=", deserialize_value(value, column.type)
+      deserialized_attributes.each do |name, serialized_value|
+        column = columns_hash[name.to_s] or
+          next
+        instance.send "#{column.name}=", deserialize_value(serialized_value, column.type)
       end
       instance
     end
 
+    #
+    # Serialize this record as a query string.
+    #
+    def to_query_string
+      to_serialized_attributes.map do |name, value|
+        next nil if value.nil?
+        "#{CGI.escape(name)}=#{CGI.escape(value)}"
+      end.compact.sort.join('&')
+    end
+
+    #
+    # Deserialize this record from a query string returned by
+    # #to_query_string.
+    #
+    def self.from_query_string(string)
+      return new if string.blank?
+      serialized_attributes = string.strip.split(/&/).map do |pair|
+        name, value = pair.split(/=/, 2)
+        [CGI.unescape(name), CGI.unescape(value)]
+      end
+      from_serialized_attributes(serialized_attributes)
+    end
+
+    #
+    # Serialize this record as a JSON string.
+    #
+    def to_json
+      to_serialized_attributes.to_json
+    end
+
+    #
+    # Deserialize this record from a JSON string returned by #to_json.
+    #
+    def self.from_json(string)
+      return new if string.blank?
+      serialized_attributes = JSON.parse(string)
+      from_serialized_attributes(serialized_attributes)
+    end
+
     protected
 
     #
@@ -115,11 +155,12 @@ module ActiveNomad
       return nil if value.nil?
       case type
       when :datetime, :timestamp, :time
-        value.to_time.to_i.to_s
+        # The day in RFC 2822 is optional - chop it.
+        value.rfc2822.sub(/\A[A-Za-z]{3}, /, '')
       when :date
-        (value.to_date - DATE_EPOCH).to_i.to_s
+        value.to_date.strftime(DATE_FORMAT)
       else
-        CGI.escape(value.to_s)
+        value.to_s
       end
     end
 
@@ -127,14 +168,14 @@ module ActiveNomad
       return nil if string.nil?
       case type
       when :datetime, :timestamp, :time
-        Time.at(string.to_i)
+        Time.parse(string)
       when :date
-        DATE_EPOCH + string.to_i
+        Date.parse(string)
       else
-        CGI.unescape(string)
+        string
       end
     end
 
-    DATE_EPOCH = Date.parse('1970-01-01')
+    DATE_FORMAT = '%d %b %Y'.freeze
   end
 end

data/lib/active_nomad/version.rb

@@ -1,5 +1,5 @@
 module ActiveNomad
-  VERSION = [0, 0, 4]
+  VERSION = [0, 1, 0]
 
   class << VERSION
     include Comparable

data/spec/unit/active_nomad_spec.rb

@@ -123,23 +123,138 @@ describe ActiveNomad::Base do
     end
   end
 
-  describe "#serialize" do
+  describe "#to_serialized_attributes" do
+    it "should return a list of attribute names with serialized attributes, sorted by name" do
+      klass = Class.new(ActiveNomad::Base) do
+        attribute :integer_attribute, :integer
+        attribute :string_attribute, :string
+        attribute :text_attribute, :text
+        attribute :float_attribute, :float
+        attribute :decimal_attribute, :decimal
+        attribute :datetime_attribute, :datetime
+        attribute :timestamp_attribute, :timestamp
+        attribute :time_attribute, :time
+        attribute :date_attribute, :date
+        attribute :binary_attribute, :binary
+        attribute :boolean_attribute, :boolean
+        attribute :nil_attribute, :string
+      end
+      instance = klass.new(
+        :integer_attribute => 5,
+        :string_attribute => 'string',
+        :text_attribute => 'text',
+        :float_attribute => 1.23,
+        :decimal_attribute => BigDecimal.new('123.45'),
+        :datetime_attribute => Time.parse('03 Feb 2001 12:34:56 -0000'),
+        :timestamp_attribute => Time.parse('03 Feb 2001 12:34:56 -0000'),
+        :time_attribute => Time.parse('03 Feb 2001 12:34:56 -0000'),
+        :date_attribute => Date.parse('03 Feb 2001'),
+        :binary_attribute => "\0\1",
+        :boolean_attribute => true,
+        :nil_attribute => nil
+      )
+      instance.to_serialized_attributes.to_a.should == [
+        ['binary_attribute', "\0\1"],
+        ['boolean_attribute', 'true'],
+        ['date_attribute', '03 Feb 2001'],
+        ['datetime_attribute', '03 Feb 2001 12:34:56 -0000'],
+        ['decimal_attribute', '123.45'],
+        ['float_attribute', '1.23'],
+        ['integer_attribute', '5'],
+        ['nil_attribute', nil],
+        ['string_attribute', 'string'],
+        ['text_attribute', 'text'],
+        ['time_attribute', '03 Feb 2001 12:34:56 -0000'],
+        ['timestamp_attribute', '03 Feb 2001 12:34:56 -0000'],
+      ]
+    end
+  end
+
+  describe ".from_serialized_attributes" do
+    it "should create a new record with attributes deserialized from the given parameter list" do
+      klass = Class.new(ActiveNomad::Base) do
+        attribute :integer_attribute, :integer
+        attribute :string_attribute, :string
+        attribute :text_attribute, :text
+        attribute :float_attribute, :float
+        attribute :decimal_attribute, :decimal
+        attribute :datetime_attribute, :datetime
+        attribute :timestamp_attribute, :timestamp
+        attribute :time_attribute, :time
+        attribute :date_attribute, :date
+        attribute :binary_attribute, :binary
+        attribute :boolean_attribute, :boolean
+        attribute :nil_attribute, :boolean
+      end
+      instance = klass.from_serialized_attributes([
+        [:integer_attribute, '5'],
+        [:string_attribute, 'string'],
+        [:text_attribute, 'text'],
+        [:float_attribute, '1.23'],
+        [:decimal_attribute, '123.45'],
+        [:datetime_attribute, '03 Feb 2001 12:34:56 -0000'],
+        [:timestamp_attribute, '03 Feb 2001 12:34:56 -0000'],
+        [:time_attribute, '03 Feb 2001 12:34:56 -0000'],
+        [:date_attribute, '03 Feb 2001'],
+        [:binary_attribute, "\0\1"],
+        [:boolean_attribute, 'true'],
+        [:nil_attribute, nil]
+      ])
+      instance.integer_attribute.should == 5
+      instance.string_attribute.should == 'string'
+      instance.text_attribute.should == 'text'
+      instance.float_attribute.should == 1.23
+      instance.decimal_attribute.should == BigDecimal.new('123.45')
+      instance.datetime_attribute.should == Time.parse('03 Feb 2001 12:34:56 -0000')
+      instance.timestamp_attribute.should == Time.parse('03 Feb 2001 12:34:56 -0000')
+      instance.time_attribute.should == Time.parse('03 Feb 2001 12:34:56 -0000')
+      instance.date_attribute.should == Date.parse('03 Feb 2001')
+      instance.binary_attribute.should == "\0\1"
+      instance.boolean_attribute.should be_true
+      instance.nil_attribute.should be_nil
+    end
+
+    it "should work with any enumerable" do
+      klass = Class.new(ActiveNomad::Base) do
+        attribute :name, :string
+      end
+      params = Object.new
+      class << params
+        def each
+          yield :name, 'joe'
+        end
+      end
+      params.extend Enumerable
+      instance = klass.from_serialized_attributes(params)
+      instance.name.should == 'joe'
+    end
+
+    it "should leave defaults alone for attributes which are not set" do
+      klass = Class.new(ActiveNomad::Base) do
+        attribute :name, :string, :default => 'Joe'
+      end
+      instance = klass.from_serialized_attributes({})
+      instance.name.should == 'Joe'
+    end
+  end
+
+  describe "#to_query_string" do
     it "should serialize the attributes as a query string" do
       klass = Class.new(ActiveNomad::Base) do
         attribute :first_name, :string
         attribute :last_name, :string
       end
       instance = klass.new(:first_name => 'Joe', :last_name => 'Blow')
-      instance.serialize.should == 'first_name=Joe&last_name=Blow'
+      instance.to_query_string.should == 'first_name=Joe&last_name=Blow'
     end
   end
 
-  describe ".deserialize" do
+  describe ".from_query_string" do
     it "should create a new record with no attributes set if nil is given" do
       klass = Class.new(ActiveNomad::Base) do
         attribute :name, :string
       end
-      instance = klass.deserialize(nil)
+      instance = klass.from_query_string(nil)
       instance.name.should be_nil
     end
 
@@ -147,7 +262,7 @@ describe ActiveNomad::Base do
       klass = Class.new(ActiveNomad::Base) do
         attribute :name, :string
       end
-      instance = klass.deserialize('')
+      instance = klass.from_query_string('')
       instance.name.should be_nil
     end
 
@@ -155,7 +270,7 @@ describe ActiveNomad::Base do
       klass = Class.new(ActiveNomad::Base) do
         attribute :name, :string
       end
-      instance = klass.deserialize(" \t")
+      instance = klass.from_query_string(" \t")
       instance.name.should be_nil
     end
 
@@ -163,19 +278,84 @@ describe ActiveNomad::Base do
       klass = Class.new(ActiveNomad::Base) do
         attribute :name, :string, :default => 'Joe'
       end
-      instance = klass.deserialize(" \t")
+      instance = klass.from_query_string(" \t")
       instance.name.should == 'Joe'
     end
   end
 
-  describe "roundtripping through #serialize and .deserialize" do
+  def self.it_should_roundtrip_through(serializer, deserializer, &block)
+    describe "roundtripping through ##{serializer} and .#{deserializer}" do
+      class_eval(&block) if block
+
+      (class << self; self; end).class_eval do
+        define_method :it_should_roundtrip do |type, value|
+          value = Time.at(value.to_i) if value.is_a?(Time) # chop off subseconds
+          it "should roundtrip #{value.inspect} correctly as a #{type}" do
+            klass = Class.new(ActiveNomad::Base) do
+              attribute :value, type
+            end
+            instance = klass.new(:value => value)
+            roundtripped = klass.send(deserializer, instance.send(serializer))
+            roundtripped.value.should == value
+          end
+        end
+      end
+
+      it_should_roundtrip :integer, nil
+      it_should_roundtrip :integer, 0
+      it_should_roundtrip :integer, 123
+
+      it_should_roundtrip :string, nil
+      it_should_roundtrip :string, ''
+      it_should_roundtrip :string, 'hi'
+
+      it_should_roundtrip :text, nil
+      it_should_roundtrip :text, ''
+      it_should_roundtrip :text, 'hi'
+
+      it_should_roundtrip :float, nil
+      it_should_roundtrip :float, 0
+      it_should_roundtrip :float, 0.123
+
+      it_should_roundtrip :decimal, nil
+      it_should_roundtrip :decimal, BigDecimal.new('0')
+      it_should_roundtrip :decimal, BigDecimal.new('123.45')
+
+      it_should_roundtrip :datetime, nil
+      it_should_roundtrip :datetime, Time.now.in_time_zone
+      # TODO: Support DateTime here, which is used when the value is
+      # outside the range of a Time.
+
+      it_should_roundtrip :timestamp, nil
+      it_should_roundtrip :timestamp, Time.now.in_time_zone
+
+      it_should_roundtrip :time, nil
+      it_should_roundtrip :time, Time.parse('2000-01-01 01:23:34').in_time_zone
+
+      it_should_roundtrip :date, nil
+      it_should_roundtrip :date, Date.today
+
+      it_should_roundtrip :binary, nil
+      it_should_roundtrip :binary, ''
+      it_should_roundtrip :binary, "\t\n"
+      #it_should_roundtrip :binary, "\0\1" # TODO: the JSON gem does not handle this
+
+      it_should_roundtrip :boolean, nil
+      it_should_roundtrip :boolean, true
+      it_should_roundtrip :boolean, false
+    end
+  end
+
+  it_should_roundtrip_through(:to_serialized_attributes, :from_serialized_attributes)
+
+  it_should_roundtrip_through(:to_query_string, :from_query_string) do
     it "should not be tripped up by delimiters in the keys" do
       klass = Class.new(ActiveNomad::Base) do
         attribute :'a=x', :string
         attribute :'b&x', :string
       end
       original = klass.new("a=x" => "1", "b&x" => "2")
-      roundtripped = klass.deserialize(original.serialize)
+      roundtripped = klass.from_query_string(original.to_query_string)
       roundtripped.send("a=x").should == "1"
       roundtripped.send("b&x").should == "2"
     end
@@ -186,64 +366,30 @@ describe ActiveNomad::Base do
         attribute :b, :string
       end
       original = klass.new(:a => "1=2", :b => "3&4")
-      roundtripped = klass.deserialize(original.serialize)
+      roundtripped = klass.from_query_string(original.to_query_string)
       roundtripped.a.should == "1=2"
       roundtripped.b.should == "3&4"
     end
+  end
 
-    def self.it_should_roundtrip(type, value)
-      value = Time.at(value.to_i) if value.is_a?(Time) # chop off subseconds
-      it "should roundtrip #{value.inspect} correctly as a #{type}" do
-        klass = Class.new(ActiveNomad::Base) do
-          attribute :value, type
-        end
-        instance = klass.new(:value => value)
-        roundtripped = klass.deserialize(instance.serialize)
-        roundtripped.value.should == value
+  it_should_roundtrip_through(:to_json, :from_json) do
+    it "should not be tripped up by delimiters in the keys" do
+      klass = Class.new(ActiveNomad::Base) do
+        attribute :"'a':b,c", :string
       end
+      original = klass.new("'a':b,c" => "1")
+      roundtripped = klass.from_json(original.to_json)
+      roundtripped.send("'a':b,c").should == "1"
     end
 
-    it_should_roundtrip :integer, nil
-    it_should_roundtrip :integer, 0
-    it_should_roundtrip :integer, 123
-
-    it_should_roundtrip :string, nil
-    it_should_roundtrip :string, ''
-    it_should_roundtrip :string, 'hi'
-
-    it_should_roundtrip :text, nil
-    it_should_roundtrip :text, ''
-    it_should_roundtrip :text, 'hi'
-
-    it_should_roundtrip :float, nil
-    it_should_roundtrip :float, 0
-    it_should_roundtrip :float, 0.123
-
-    it_should_roundtrip :decimal, nil
-    it_should_roundtrip :decimal, BigDecimal.new('0')
-    it_should_roundtrip :decimal, BigDecimal.new('123.45')
-
-    it_should_roundtrip :datetime, nil
-    it_should_roundtrip :datetime, Time.now.in_time_zone
-    # TODO: Support DateTime here, which is used when the value is
-    # outside the range of a Time.
-
-    it_should_roundtrip :timestamp, nil
-    it_should_roundtrip :timestamp, Time.now.in_time_zone
-
-    it_should_roundtrip :time, nil
-    it_should_roundtrip :time, Time.parse('2000-01-01 01:23:34').in_time_zone
-
-    it_should_roundtrip :date, nil
-    it_should_roundtrip :date, Date.today
-
-    it_should_roundtrip :binary, nil
-    it_should_roundtrip :binary, ''
-    it_should_roundtrip :binary, "\0\1"
-
-    it_should_roundtrip :boolean, nil
-    it_should_roundtrip :boolean, true
-    it_should_roundtrip :boolean, false
+    it "should not be tripped up by delimiters in the values" do
+      klass = Class.new(ActiveNomad::Base) do
+        attribute :a, :string
+      end
+      original = klass.new(:a => "'a':b,c")
+      roundtripped = klass.from_json(original.to_json)
+      roundtripped.a.should == "'a':b,c"
+    end
   end
 
   describe ".transaction" do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: active_nomad
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 27
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 4
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - George Ogata
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-01 00:00:00 -04:00
+date: 2010-10-05 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency