cistern 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 654c51d23fb889c16d378ffd6b0517dd8a9bea01
-  data.tar.gz: bb865084d2e05d0f07647ca6cfc193aae4ba277a
+  metadata.gz: e00bac7d299cc0636b1ac4b5ca42958de6f96f41
+  data.tar.gz: 0f83891e9e0bc7f9cdcbdb8ad9c0280dfb969ae3
 SHA512:
-  metadata.gz: 2686e1a240fc0bbca101c446c09a5bd06eed8dd76e15c62243be044afa0316f84d8b5eadefcc8b22b092e3024d155da155a0db176776ab75ca3d4a3391641fa6
-  data.tar.gz: 9743c3688790d9b67ba0c24528dced11f0559126eb821103f1eb5d56c13fd1cdb7494b6f0e0d4956fddd3415291f99aac199f1356f733c9d6251494ae08dfe77
+  metadata.gz: d8e0baa62cd55e6f8cafc7ef6401d1c8a6f8a8bcfafd4fb19cb850ae6e06ba76eacdc55912c6780eddc53729b162db855db6d8986ae7ac25463937eac96c7fb3
+  data.tar.gz: 4ec77508143ddad1788aff2159711eaa49301bafb765eecdfda0c498d02c0e4969449646eb6990daf1b6e7f899374043dd176869261867f4105302238242a1f5

data/README.md

@@ -15,154 +15,177 @@ This represents the remote service that you are wrapping. If the service name is
 
 Requests are enumerated using the `request` method and required immediately via the relative path specified via `request_path`.
 
-    class Foo::Client < Cistern::Service
-      request_path "my-foo/requests"
+```ruby
+class Foo::Client < Cistern::Service
+  request_path "my-foo/requests"
 
-      request :get_bar  # require my-foo/requests/get_bar.rb
-      request :get_bars # require my-foo/requests/get_bars.rb
+  request :get_bar  # require my-foo/requests/get_bar.rb
+  request :get_bars # require my-foo/requests/get_bars.rb
 
-      class Real
-        def request(url)
-          Net::HTTP.get(url)
-        end
-      end
+  class Real
+    def request(url)
+      Net::HTTP.get(url)
     end
+  end
+end
+```
 
 
 <!--todo move to a request section-->
 A request is method defined within the context of service and mode (Real or Mock).  Defining requests within the service mock class is optional.
 
-    # my-foo/requests/get_bar.rb
-    class Foo::Client
-      class Real
-        def get_bar(bar_id)
-          request("http://example.org/bar/#{bar_id}")
-        end
-      end # Real
-
-      # optional, but encouraged
-      class Mock
-        def get_bars
-          # do some mock things
-        end
-      end # Mock
-    end # Foo::client
+```ruby
+# my-foo/requests/get_bar.rb
+class Foo::Client
+  class Real
+    def get_bar(bar_id)
+      request("http://example.org/bar/#{bar_id}")
+    end
+  end # Real
+
+  # optional, but encouraged
+  class Mock
+    def get_bars
+      # do some mock things
+    end
+  end # Mock
+end # Foo::client
+```
 
 All declared requests can be listed via `Cistern::Service#requests`.
 
-    Foo::Client.requests # => [:get_bar, :get_bars]
+```ruby
+Foo::Client.requests # => [:get_bar, :get_bars]
+```
 
 #### Models and Collections
 
 Models and collections have declaration semantics similar to requests.  Models and collections are enumerated via `model` and `collection` respectively.
 
-    class Foo::Client < Cistern::Service
-      model_path "my-foo/models"
+```ruby
+class Foo::Client < Cistern::Service
+  model_path "my-foo/models"
 
-      model :bar       # require my-foo/models/bar.rb
-      collection :bars # require my-foo/models/bars.rb
-    end
+  model :bar       # require my-foo/models/bar.rb
+  collection :bars # require my-foo/models/bars.rb
+end
+```
 
 #### Initialization
 
 Service initialization parameters are enumerated by `requires` and `recognizes`.  `recognizes` parameters are optional.
 
-    class Foo::Client < Cistern::Service
-      requires :hmac_id, :hmac_secret
-      recognizes :url
-    end
+```ruby
+class Foo::Client < Cistern::Service
+  requires :hmac_id, :hmac_secret
+  recognizes :url
+end
 
-    # Acceptable
-    Foo::Client.new(hmac_id: "1", hmac_secret: "2")                            # Foo::Client::Real
-    Foo::Client.new(hmac_id: "1", hmac_secret: "2", url: "http://example.org") # Foo::Client::Real
+# Acceptable
+Foo::Client.new(hmac_id: "1", hmac_secret: "2")                            # Foo::Client::Real
+Foo::Client.new(hmac_id: "1", hmac_secret: "2", url: "http://example.org") # Foo::Client::Real
 
-    # ArgumentError
-    Foo::Client.new(hmac_id: "1", url: "http://example.org")
-    Foo::Client.new(hmac_id: "1")
+# ArgumentError
+Foo::Client.new(hmac_id: "1", url: "http://example.org")
+Foo::Client.new(hmac_id: "1")
+```
 
 
 ### Mocking
 
 Cistern strongly encourages you to generate mock support for service. Mocking can be enabled using `mock!`.
 
-    Foo::Client.mocking?          # falsey
-    real = Foo::Client.new        # Foo::Client::Real
-    Foo::Client.mock!
-    Foo::Client.mocking?          # true
-    fake = Foo::Client.new        # Foo::Client::Mock
-    Foo::Client.unmock!
-    Foo::Client.mocking?          # false
-    real.is_a?(Foo::Client::Real) # true
-    fake.is_a?(Foo::Client::Mock) # true
+```ruby
+Foo::Client.mocking?          # falsey
+real = Foo::Client.new        # Foo::Client::Real
+Foo::Client.mock!
+Foo::Client.mocking?          # true
+fake = Foo::Client.new        # Foo::Client::Mock
+Foo::Client.unmock!
+Foo::Client.mocking?          # false
+real.is_a?(Foo::Client::Real) # true
+fake.is_a?(Foo::Client::Mock) # true
+```
 
 #### Data
 
 A uniform interface for mock data is mixed into the `Mock` class by default.
 
-    Foo::Client.mock!
-    client = Foo::Client.new     # Foo::Client::Mock
-    client.data                  # Cistern::Data::Hash
-    client.data["bars"] += ["x"] # ["x"]
+```ruby
+Foo::Client.mock!
+client = Foo::Client.new     # Foo::Client::Mock
+client.data                  # Cistern::Data::Hash
+client.data["bars"] += ["x"] # ["x"]
+```
 
 Mock data is class-level by default
 
-    Foo::Client::Mock.data["bars"] # ["x"]
+```ruby
+Foo::Client::Mock.data["bars"] # ["x"]
+```
 
 `reset!` dimisses the `data` object.
 
-    client.data.object_id # 70199868585600
-    client.reset!
-    client.data["bars"]   # []
-    client.data.object_id # 70199868566840
+```ruby
+client.data.object_id # 70199868585600
+client.reset!
+client.data["bars"]   # []
+client.data.object_id # 70199868566840
+```
 
 `clear` removes existing keys and values but keeps the same object.
 
-    client.data["bars"] += ["y"] # ["y"]
-    client.data.object_id        # 70199868378300
-    client.clear
-    client.data["bars"]          # []
+```ruby
+client.data["bars"] += ["y"] # ["y"]
+client.data.object_id        # 70199868378300
+client.clear
+client.data["bars"]          # []
 
-    client.data.object_id        # 70199868566840
+client.data.object_id        # 70199868566840
+```
 
 * `store` and `[]=` write
 * `fetch` and `[]` read
 
 You can make the service bypass Cistern's mock data structures by simply creating a `self.data` function in your service `Mock` declaration.
 
-    class Foo::Client < Cistern::Service
-      class Mock
-        def self.data
-          @data ||= {}
-        end
-      end
+```ruby
+class Foo::Client < Cistern::Service
+  class Mock
+    def self.data
+      @data ||= {}
     end
+  end
+end
+```
 
 
 #### Requests
 
 Mock requests should be defined within the contextual `Mock` module and interact with the `data` object directly.
 
-    # lib/foo/requests/create_bar.rb
-    class Foo::Client
-      class Mock
-        def create_bar(options={})
-          id = Foo.random_hex(6)
+```ruby
+# lib/foo/requests/create_bar.rb
+class Foo::Client
+  class Mock
+    def create_bar(options={})
+      id = Foo.random_hex(6)
 
-          bar = {
-            "id" => id
-          }.merge(options)
+      bar = {
+        "id" => id
+      }.merge(options)
 
-          self.data[:bars][id] = bar
-
-          response(
-            :body   => {"bar" => bar},
-            :status => 201,
-            :path => '/bar',
-          )
-        end
-      end # Mock
-    end # Foo::Client
+      self.data[:bars][id] = bar
 
+      response(
+        :body   => {"bar" => bar},
+        :status => 201,
+        :path => '/bar',
+      )
+    end
+  end # Mock
+end # Foo::Client
+```
 
 #### Storage
 
@@ -174,12 +197,14 @@ Currently supported storage backends are:
 
 Backends can be switched by using `store_in`.
 
-    # use redis with defaults
-    Patient::Mock.store_in(:redis)
-    # use redis with a specific client
-    Patient::Mock.store_in(:redis, client: Redis::Namespace.new("cistern", redis: Redis.new(host: "10.1.0.1"))
-    # use a hash
-    Patient::Mock.store_in(:hash)
+```ruby
+# use redis with defaults
+Patient::Mock.store_in(:redis)
+# use redis with a specific client
+Patient::Mock.store_in(:redis, client: Redis::Namespace.new("cistern", redis: Redis.new(host: "10.1.0.1"))
+# use a hash
+Patient::Mock.store_in(:hash)
+```
 
 ### Model
 
@@ -188,108 +213,141 @@ Backends can be switched by using `store_in`.
 
 Example
 
-    class Foo::Client::Bar < Cistern::Model
-      identity :id
+```ruby
+class Foo::Client::Bar < Cistern::Model
+  identity :id
+
+  attribute :flavor
+  attribute :keypair_id, aliases: "keypair",  squash: "id"
+  attribute :private_ips, type: :array
+
+  def destroy
+    params  = {
+      "id" => self.identity
+    }
+    self.connection.destroy_bar(params).body["request"]
+  end
+
+  def save
+    requires :keypair_id
+
+    params = {
+      "keypair" => self.keypair_id,
+      "bar"     => {
+        "flavor" => self.flavor,
+      },
+    }
+
+    if new_record?
+      merge_attributes(connection.create_bar(params).body["bar"])
+    else
+      requires :identity
+
+      merge_attributes(connection.update_bar(params).body["bar"])
+    end
+  end
+end
+```
 
-      attribute :flavor
-      attribute :keypair_id, aliases: "keypair",  squash: "id"
-      attribute :private_ips, type: :array
+#### Dirty
 
-      def destroy
-        params  = {
-          "id" => self.identity
-        }
-        self.connection.destroy_bar(params).body["request"]
-      end
+Dirty attributes are tracked and cleared when `merge_attributes` is called.
 
-      def save
-        requires :keypair_id
+* `changed` returns a Hash of changed attributes mapped to there initial value and current value
+* `dirty_attributes` returns Hash of changed attributes with there current value.  This should be used in the model `save` function.
 
-        params = {
-          "keypair" => self.keypair_id,
-          "bar"     => {
-            "flavor" => self.flavor,
-          },
-        }
 
-        if new_record?
-          merge_attributes(connection.create_bar(params).body["bar"])
-        else
-          requires :identity
+```ruby
+bar = Foo::Client::Bar.new(id: 1, flavor: "x") # => <#Foo::Client::Bar>
 
-          merge_attributes(connection.update_bar(params).body["bar"])
-        end
-      end
-    end
+bar.dirty?           # => false
+bar.changed          # => {}
+bar.dirty_attributes # => {}
+
+bar.flavor = "y"
+
+bar.dirty?           # => true
+bar.changed          # => {flavor: ["x", "y"]}
+bar.dirty_attributes # => {flavor: "y"}
+
+bar.save
+bar.dirty?           # => false
+bar.changed          # => {}
+bar.dirty_attributes # => {}
+```
 
 ### Collection
 
 `model` tells Cistern which class is contained within the collection.  `Cistern::Collection` inherits from `Array` and lazy loads where applicable.
 
-    class Foo::Client::Bars < Cistern::Collection
+```ruby
+class Foo::Client::Bars < Cistern::Collection
 
-      model Foo::Client::Bar
+  model Foo::Client::Bar
 
-      def all(params = {})
-        response = connection.get_bars(params)
+  def all(params = {})
+    response = connection.get_bars(params)
 
-        data = response.body
+    data = response.body
 
-        self.load(data["bars"])     # store bar records in collection
-        self.merge_attributes(data) # store any other attributes of the response on the collection
-      end
+    self.load(data["bars"])     # store bar records in collection
+    self.merge_attributes(data) # store any other attributes of the response on the collection
+  end
 
-      def discover(provisioned_id, options={})
-        params = {
-          "provisioned_id" => provisioned_id,
-        }
-        params.merge!("location" => options[:location]) if options.key?(:location)
+  def discover(provisioned_id, options={})
+    params = {
+      "provisioned_id" => provisioned_id,
+    }
+    params.merge!("location" => options[:location]) if options.key?(:location)
 
-        connection.requests.new(connection.discover_bar(params).body["request"])
-      end
+    connection.requests.new(connection.discover_bar(params).body["request"])
+  end
 
-      def get(id)
-        if data = connection.get_bar("id" => id).body["bar"]
-          new(data)
-        else
-          nil
-        end
-      end
+  def get(id)
+    if data = connection.get_bar("id" => id).body["bar"]
+      new(data)
+    else
+      nil
     end
+  end
+end
+```
 
 ### Request
 
-    module Foo
-      class Client
-        class Real
-          def create_bar(options={})
-            request(
-              :body     => {"bar" => options},
-              :method   => :post,
-              :path     => '/bar'
-            )
-          end
-        end # Real
-
-        class Mock
-          def create_bar(options={})
-            id = Foo.random_hex(6)
-
-            bar = {
-              "id" => id
-            }.merge(options)
-
-            self.data[:bars][id]= bar
-
-            response(
-              :body   => {"bar" => bar},
-              :status => 201,
-              :path => '/bar',
-            )
-          end
-        end # Mock
-      end # Client
-    end # Foo
+```ruby
+module Foo
+  class Client
+    class Real
+      def create_bar(options={})
+        request(
+          :body     => {"bar" => options},
+          :method   => :post,
+          :path     => '/bar'
+        )
+      end
+    end # Real
+
+    class Mock
+      def create_bar(options={})
+        id = Foo.random_hex(6)
+
+        bar = {
+          "id" => id
+        }.merge(options)
+
+        self.data[:bars][id]= bar
+
+        response(
+          :body   => {"bar" => bar},
+          :status => 201,
+          :path => '/bar',
+        )
+      end
+    end # Mock
+  end # Client
+end # Foo
+```
 
 ## Examples
 

data/lib/cistern/attributes.rb

@@ -123,13 +123,26 @@ module Cistern::Attributes
 
     def write_attribute(name, value)
       options = self.class.attributes[name] || {}
+
       transform = Cistern::Attributes.transforms[options[:squash] ? :squash : :none] ||
         Cistern::Attributes.default_transform
+
       parser = Cistern::Attributes.parsers[options[:type]] ||
         options[:parser] ||
         Cistern::Attributes.default_parser
+
       transformed = transform.call(name, value, options)
-      attributes[name.to_s.to_sym]= parser.call(transformed, options)
+
+      new_value = parser.call(transformed, options)
+      attribute = name.to_s.to_sym
+
+      previous_value = attributes[attribute]
+
+      attributes[attribute] = new_value
+
+      changed!(attribute, previous_value, new_value)
+
+      new_value
     end
 
     def attributes
@@ -174,6 +187,7 @@ module Cistern::Attributes
           end
         end
       end
+      changed.clear
       self
     end
 
@@ -198,10 +212,30 @@ module Cistern::Attributes
       end
     end
 
+    def dirty?
+      changed.any?
+    end
+
+    def dirty_attributes
+      changed.inject({}) { |r,(k,(_,v))| r.merge(k => v) }
+    end
+
+    def changed
+      @changes ||= {}
+    end
+
     protected
 
     def missing_attributes(args)
       ([:connection] | args).select{|arg| send("#{arg}").nil?}
     end
+
+    def changed!(attribute, from, to)
+      changed[attribute] = if existing = changed[attribute]
+                             [existing.first, to]
+                           else
+                             [from, to]
+                           end
+    end
   end
 end

data/lib/cistern/formatter.rb

@@ -1,7 +1,6 @@
 module Cistern::Formatter
   autoload :AwesomePrint, 'cistern/formatter/awesome_print'
-  autoload :Default, 'cistern/formatter/default'
-  autoload :Formatador, 'cistern/formatter/formatador'
+  autoload :Formatador,   'cistern/formatter/formatador'
 
   def self.default
     if defined?(::AwesomePrint)

data/lib/cistern/version.rb

@@ -1,3 +1,3 @@
 module Cistern
-  VERSION = "0.10.2"
+  VERSION = "0.11.0"
 end

data/spec/dirty_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe "Cistern::Model#dirty" do
+  class DirtySpec < Cistern::Model
+    identity :id
+
+    attribute :name
+    attribute :properties, type: :array
+
+    def save
+      merge_attributes(attributes)
+    end
+  end
+
+  it "should mark a existing record as dirty" do
+    model = DirtySpec.new(id: 1, name: "steve")
+    expect(model.changed).to be_empty
+
+    expect {
+      model.properties = [1]
+    }.to change { model.dirty? }.to(true)
+
+    expect(model.changed).to eq(properties: [nil, [1]])
+    expect(model.dirty_attributes).to eq(properties: [1])
+
+    expect {
+      model.properties = [2]
+    }.to change { model.changed }.to(properties: [nil, [2]])
+    expect(model.dirty_attributes).to eq(properties: [2])
+
+    expect {
+      model.save
+    }.to change { model.dirty? }.to(false)
+
+    expect(model.changed).to eq({})
+    expect(model.dirty_attributes).to eq({})
+  end
+end

data/spec/model_spec.rb

@@ -1,7 +1,6 @@
 require 'spec_helper'
 
 describe "Cistern::Model" do
-
   describe "#update" do
     class UpdateSpec < Cistern::Model
       identity :id

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cistern
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Josh Lane
@@ -45,6 +45,7 @@ files:
 - lib/cistern/version.rb
 - lib/cistern/wait_for.rb
 - spec/collection_spec.rb
+- spec/dirty_spec.rb
 - spec/formatter_spec.rb
 - spec/hash_spec.rb
 - spec/mock_data_spec.rb
@@ -78,6 +79,7 @@ specification_version: 4
 summary: API client framework
 test_files:
 - spec/collection_spec.rb
+- spec/dirty_spec.rb
 - spec/formatter_spec.rb
 - spec/hash_spec.rb
 - spec/mock_data_spec.rb