model_attribute 0.0.1 → 2.0.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NjdhYmE2MDhjYmNiY2JhZWVmYzdjZTJmYjNiZjQ4YzJlNjM5MzlmMQ==
+    ZjY2MDhkZDI2ZjA0YjRjM2NkY2E5MTg0NWYxZmJhY2JmZTEyYWUzYg==
   data.tar.gz: !binary |-
-    ZTUyNGM5MGZjNzNjODMxZGZkNmQ0YjQxNzAzY2RiOWU5M2NmOTc4ZA==
+    MWRhZjRhOTUzNDQ5MzRhMWU5NTQwOTdkMmJjYmJlMDA1OTJhMzFiMA==
 SHA512:
   metadata.gz: !binary |-
-    ODdlNmY2ZDlhNzdkNmQ3Mjg5MjZiNGFkMDg5ZWYwNWJhOWFlMmZkNTE4NWVj
-    ZWJmZTk1MGY0ZjBkNDMzZmIzZTM1MjQyMzI2ODI1ZDc4ZmYxNzhiYjZkN2Rm
-    YTZiNWI0OTNlYzg2ZmU3YTA1ZDg3ZjM4Yzk5MWMxYTA0NjAxOTM=
+    ZjZmMjY3NzMzM2EyODAyMDM1MTA2NTgxNGRhOWJhNGNmMGJmZTA4NDVmMzJi
+    NWQ0MzEyYTFlZDNjZmI5N2I5Y2FjMDE3NWE0MDIyMDBlNWJmMzNkNzNmMjBh
+    YTQ2Y2MzMjU2ZGI4MzNhODE5NDJkMjEyMmZmNjU3NDUwYjAzNTI=
   data.tar.gz: !binary |-
-    NGU1NWU5YWUzMzc4YjI0ZGQ4M2QwNjFkMGM0ZDg3NGNmZjE1YzdjYTU1NTdh
-    NTNlNjZlMzhhMzRjYjE2NThkZmY1MWMyNGU2ZGRmNWNmNzhkMzZjZjg5N2Uw
-    NDgwZjdlNzFhNGRhZTE5NjczYzU2ODg2NDYzZDU3OWQwNmYyYzU=
+    ODg1MWVhYjI3N2ZmNDM0MWY1ZGE1NWVmYWM3YzI4ODdiZTEzMGY0MDQ5YjRh
+    YjA3MWNmMjlmYTJmNTU4ZjJjNzk2ZmUwOWRjZjhhMGJkYTUzNGZlZDZmZGNh
+    N2VhZGJjYWE1MzgxYjY4ZDQwNWI4YmE5ZGY0OWNjZjk4YmNjMGI=

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+## 2.0.0
+
+- **Breaking change**: Rename to `ModelAttribute` (no trailing 's') to avoid name
+  clash with another gem.
+
+## 1.4.0
+
+- **New method**: #changes_for_json  Returns a hash from attribute name to its
+  new value, suitable for serialization to a JSON string.  Easily generate the
+  payload to send in an HTTP PUT to a web service.
+
+- **New attribute type: json**  Store an array/hash/etc. built using the basic
+  JSON data types: nil, numeric, string, boolean, hash and array.
+
+## 1.3.0
+
+- **Breaking change**: Parsing an integer to a time attribute, the integer is
+  treated as the number of milliseconds since the epoch (not the number of
+  seconds).  `attributes_as_json` emits integers for time attributes.
+
+## 1.2.0
+
+- **Breaking change**: `attributes_as_json` removed; replaced with
+  `attributes_for_json`.  You will have to serialize this yourself:
+  `Oj.dump(attributes_for_json, mode: :strict)`.  This allows you to modify the
+  returned hash before serializing it.
+
+## 1.1.0
+
+- Initial release

data/Gemfile

@@ -1,4 +1,5 @@
 source 'https://rubygems.org'
+source 'http://gems.int.yammer.com/'
 
 # Specify your gem's dependencies in model_attribute.gemspec
 gemspec

data/Guardfile

@@ -0,0 +1,47 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec feature)
+
+## Uncomment to clear the screen before every task
+# clearing :on
+
+## Make Guard exit when config is changed so it can be restarted
+#
+## Note: if you want Guard to automatically start up again, run guard in a
+## shell loop, e.g.:
+#
+#  $ while bundle exec guard; do echo "Restarting Guard..."; done
+#
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), the you will want to move the Guardfile
+## to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+#
+watch ("Guardfile") do
+  UI.info "Exiting because Guard must be restarted for changes to take effect"
+  exit 0
+end
+
+guard :rspec, cmd: "bundle exec rspec --format=Nc --format=documentation" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  watch(%r{lib/*}) { 'spec' }
+end

data/LICENSE.txt

@@ -1,4 +1,8 @@
-Copyright (c) 2015 David Waller
+ModelAttribute
+
+Copyright (c) 2015 Microsoft Corporation
+
+All rights reserved.
 
 MIT License
 

data/README.md

@@ -1,6 +1,170 @@
 # ModelAttribute
 
-Placeholder while clearing gem release with legal.
+Simple attributes for a non-ActiveRecord model.
+
+ - Stores attributes in instance variables.
+ - Type casting and checking.
+ - Dirty tracking.
+ - List attribute names and values.
+ - Handles integers, booleans, strings and times - a set of types that are very
+   easy to persist to and parse from JSON.
+ - Supports efficient serialization of attributes to JSON.
+ - Mass assignment - handy for initializers.
+
+Why not [Virtus][virtus-gem]?  Virtus doesn't provide attribute tracking, and
+doesn't integrate with [ActiveModel::Dirty][am-dirty].  So if you're not using
+ActiveRecord, but you need attributes with dirty tracking, ModelAttribute may be
+what you're after.  For example, it works very well for a model that fronts an
+HTTP web service, and you want dirty tracking so you can PATCH appropriately.
+
+Also in favor of ModelAttribute:
+
+ - It's simple - less than [200 lines of code][source].
+ - It supports efficient serialization and deserialization to/from JSON.
+
+[virtus-gem]:https://github.com/solnic/virtus
+[am-dirty]:https://github.com/rails/rails/blob/v3.0.20/activemodel/lib/active_model/dirty.rb
+[source]:https://github.com/yammer/model_attribute/blob/master/lib/model_attribute.rb
+
+## Usage
+
+```ruby
+require 'model_attribute'
+class User
+  extend ModelAttribute
+  attribute :id,         :integer
+  attribute :paid,       :boolean
+  attribute :name,       :string
+  attribute :created_at, :time
+  attribute :grades,     :json
+
+  def initialize(attributes = {})
+    set_attributes(attributes)
+  end
+end
+
+User.attributes # => [:id, :paid, :name, :created_at, :grades]
+user = User.new
+
+user.attributes # => {:id=>nil, :paid=>nil, :name=>nil, :created_at=>nil, :grades=>nil}
+
+# An integer attribute
+user.id # => nil
+
+user.id = 3
+user.id # => 3
+
+# Stores values that convert cleanly to an integer
+user.id = '5'
+user.id # => 5
+
+# Protects you against nonsense assignment
+user.id = '5error'
+ArgumentError: invalid value for Integer(): "5error"
+
+# A boolean attribute
+user.paid # => nil
+user.paid = true
+
+# Booleans also define a predicate method (ending in '?')
+user.paid?  # => true
+
+# Conversion from strings used by databases.
+user.paid = 'f'
+user.paid # => false
+user.paid = 't'
+user.paid # => true
+
+# A :time attribute
+user.created_at = Time.now
+user.created_at # => 2015-01-08 15:57:05 +0000
+
+# Also converts from other reasonable time formats
+user.created_at = "2014-12-25 14:00:00 +0100"
+user.created_at # => 2014-12-25 13:00:00 +0000
+user.created_at = Date.parse('2014-01-08')
+user.created_at # => 2014-01-08 00:00:00 +0000
+user.created_at = DateTime.parse("2014-12-25 13:00:45")
+user.created_at # => 2014-12-25 13:00:45 +0000
+# Convert from seconds since the epoch
+user.created_at = Time.now.to_f
+user.created_at # => 2015-01-08 16:23:02 +0000
+# Or milliseconds since the epoch
+user.created_at = 1420734182000
+user.created_at # => 2015-01-08 16:23:02 +0000
+
+# A :json attribute is schemaless and accepts the basic JSON types - hash,
+# array, nil, numeric, string and boolean.
+user.grades = {'maths' => 'A', 'history' => 'C'}
+user.grades # => {"maths"=>"A", "history"=>"C"}
+user.grades = ['A', 'A*', 'C']
+user.grades # => ["A", "A*", "C"]
+user.grades = 'AAB'
+user.grades # => "AAB"
+user.grades = Time.now
+# => RuntimeError: JSON only supports nil, numeric, string, boolean and arrays and hashes of those.
+
+# read_attribute and write_attribute methods
+user.read_attribute(:created_at)
+user.write_attribute(:name, 'Fred')
+
+# View attributes
+user.attributes # => {:id=>5, :paid=>true, :name=>"Fred", :created_at=>2015-01-08 15:57:05 +0000, :grades=>{"maths"=>"A", "history"=>"C"}}
+user.inspect # => "#<User id: 5, paid: true, name: \"Fred\", created_at: 2015-01-08 15:57:05 +0000, grades: {\"maths\"=>\"A\", \"history\"=>\"C\"}>"
+
+# Mass assignment
+user.set_attributes(name: "Sally", paid: false)
+user.attributes # => {:id=>5, :paid=>false, :name=>"Sally", :created_at=>2015-01-08 15:57:05 +0000}
+
+# Efficient JSON serialization and deserialization.
+# Attributes with nil values are omitted.
+user.attributes_for_json
+# => {"id"=>5, "paid"=>true, "name"=>"Fred", "created_at"=>1421171317762}
+require 'oj'
+Oj.dump(user.attributes_for_json, mode: :strict)
+# => "{\"id\":5,\"paid\":true,\"name\":\"Fred\",\"created_at\":1421171317762}"
+user2 = User.new(Oj.load(json, strict: true))
+
+# Change tracking.  A much smaller set of function than that provided by
+# ActiveModel::Dity.
+user.changes # => {:id=>[nil, 5], :paid=>[nil, true], :created_at=>[nil, 2015-01-08 15:57:05 +0000], :name=>[nil, "Fred"]}
+user.name_changed?  # => true
+# If you need the new values to send as a PUT to a web service
+user.changes_for_json # => {"id"=>5, "paid"=>true, "name"=>"Fred", "created_at"=>1421171317762}
+# If you're imitating ActiveRecord behaviour, changes are cleared after
+# after_save callbacks, but before after_commit callbacks.
+user.changes.clear
+user.changes # => {}
+
+# Equality of all the attribute values match
+another = User.new
+another.id = 5
+another.paid = true
+another.created_at = user.created_at
+another.name = 'Fred'
+
+user == another   # => true
+user === another  # => true
+user.eql? another # => true
+
+# Making some attributes private
+
+class User
+  extend ModelAttribute
+  attribute :events, :string
+  private :events=
+
+  def initialize(attributes)
+    # Pass flag to set_attributes to allow setting attributes with private writers
+    set_attributes(attributes, true)
+  end
+
+  def add_event(new_event)
+    events ||= ""
+    events += new_event
+  end
+end
+```
 
 ## Installation
 
@@ -18,10 +182,6 @@ Or install it yourself as:
 
     $ gem install model_attribute
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/model_attribute/fork )

data/Rakefile

@@ -1,2 +1 @@
 require "bundler/gem_tasks"
-

data/lib/model_attribute.rb

@@ -1,5 +1,202 @@
 require "model_attribute/version"
+require "model_attribute/json"
+require "model_attribute/errors"
+require "time"
 
 module ModelAttribute
-  # Your code goes here...
+  SUPPORTED_TYPES = [:integer, :boolean, :string, :time, :json]
+
+  def self.extended(base)
+    base.send(:include, InstanceMethods)
+    base.instance_variable_set('@attribute_names', [])
+    base.instance_variable_set('@attribute_types', {})
+  end
+
+  def attribute(name, type)
+    name = name.to_sym
+    type = type.to_sym
+    raise UnsupportedTypeError.new(type) unless SUPPORTED_TYPES.include?(type)
+
+    @attribute_names << name
+    @attribute_types[name] = type
+
+    self.class_eval(<<-CODE, __FILE__, __LINE__ + 1)
+      def #{name}=(value)
+        write_attribute(#{name.inspect}, value, #{type.inspect})
+      end
+
+      def #{name}
+        read_attribute(#{name.inspect})
+      end
+
+      def #{name}_changed?
+        !!changes[#{name.inspect}]
+      end
+    CODE
+
+    if type == :boolean
+      self.class_eval(<<-CODE, __FILE__, __LINE__ + 1)
+        def #{name}?
+          !!read_attribute(#{name.inspect})
+        end
+      CODE
+    end
+  end
+
+  def attributes
+    @attribute_names
+  end
+
+  module InstanceMethods
+    def write_attribute(name, value, type = nil)
+      name = name.to_sym
+
+      # Don't want to expose attribute types as a method on the class, so access
+      # via a back door.
+      type ||= self.class.instance_variable_get('@attribute_types')[name]
+      raise InvalidAttributeNameError.new(name) unless type
+
+      value = cast(value, type)
+      return if value == read_attribute(name)
+
+      if changes.has_key? name
+        original = changes[name].first
+      else
+        original = read_attribute(name)
+      end
+
+      if original == value
+        changes.delete(name)
+      else
+        changes[name] = [original, value]
+      end
+
+      instance_variable_set("@#{name}", value)
+    end
+
+    def read_attribute(name)
+      ivar_name = "@#{name}"
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      elsif !self.class.attributes.include?(name.to_sym)
+        raise InvalidAttributeNameError.new(name)
+      end
+    end
+
+    def attributes
+      self.class.attributes.each_with_object({}) do |name, attributes|
+        attributes[name] = read_attribute(name)
+      end
+    end
+
+    def set_attributes(attributes, can_set_private_attrs = false)
+      attributes.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=", can_set_private_attrs)
+      end
+    end
+
+    def ==(other)
+      return true if equal?(other)
+      if respond_to?(:id)
+        other.kind_of?(self.class) && id == other.id
+      else
+        other.kind_of?(self.class) && attributes == other.attributes
+      end
+    end
+    alias_method :eql?, :==
+
+    def changes
+      @changes ||= {} #HashWithIndifferentAccess.new
+    end
+
+    # Attributes suitable for serializing to a JSON string.
+    #
+    #  - Attribute keys are strings (for 'strict' JSON dumping).
+    #  - Attributes with a nil value are omitted to speed serialization.
+    #  - :time attributes are serialized as an Integer giving the number of
+    #    milliseconds since the epoch.
+    def attributes_for_json
+      self.class.attributes.each_with_object({}) do |name, attributes|
+        value = read_attribute(name)
+        unless value.nil?
+          value = (value.to_f * 1000).to_i if value.is_a? Time
+          attributes[name.to_s] = value
+        end
+      end
+    end
+
+    # Changed attributes suitable for serializing to a JSON string.  Returns a
+    # hash from attribute name (as a string) to the new value of that attribute,
+    # for attributes that have changed.
+    #
+    #  - :time attributes are serialized as an Integer giving the number of
+    #    milliseconds since the epoch.
+    #  - Unlike attributes_for_json, attributes that have changed to a nil value
+    #    *are* included.
+    def changes_for_json
+      hash = {}
+      changes.each do |attr_name, (_old_value, new_value)|
+        new_value = (new_value.to_f * 1000).to_i if new_value.is_a? Time
+        hash[attr_name.to_s] = new_value
+      end
+
+      hash
+    end
+
+    # Includes the class name and all the attributes and their values.  e.g.
+    # "#<User id: 1, paid: true, name: \"Fred\", created_at: 2014-12-25 08:00:00 +0000>"
+    def inspect
+      attribute_string = self.class.attributes.map do |key|
+        "#{key}: #{read_attribute(key).inspect}"
+      end.join(', ')
+      "#<#{self.class} #{attribute_string}>"
+    end
+
+    def cast(value, type)
+      return nil if value.nil?
+
+      case type
+      when :integer
+        int = Integer(value)
+        float = Float(value)
+        raise "Can't cast #{value.inspect} to an integer without loss of precision" unless int == float
+        int
+      when :boolean
+        if !!value == value
+          value
+        elsif value == 't'
+          true
+        elsif value == 'f'
+          false
+        else
+          raise "Can't cast #{value.inspect} to boolean"
+        end
+      when :time
+        case value
+        when Time
+          value
+        when Date, DateTime
+          value.to_time
+        when Integer
+          # Assume milliseconds since epoch.
+          Time.at(value / 1000.0)
+        when Numeric
+          # Numeric, but not an integer. Assume seconds since epoch.
+          Time.at(value)
+        else
+          Time.parse(value)
+        end
+      when :string
+        String(value)
+      when :json
+        if Json.valid?(value)
+          value
+        else
+          raise "JSON only supports nil, numeric, string, boolean and arrays and hashes of those."
+        end
+      else
+        raise UnsupportedTypeError.new(type)
+      end
+    end
+  end
 end