hal-interpretation 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ddd4f4d59ce42087dfde97336e8ff4c2cd32a99f
-  data.tar.gz: c922581f34ac914205b687a8bbabc7be87678377
+  metadata.gz: 7c73d5eadd5be34552f2a0b5d2677410b55da858
+  data.tar.gz: 8f612d0a43581eb0aa0293d1da2b91a0530d6db7
 SHA512:
-  metadata.gz: a52862249331ca2ebce1be637e8c44cf6d1d2073f95922b857e99400b4666a3356751849fb3a7b45d8967163b941c9be6256f679aa79488b826486177fd68319
-  data.tar.gz: 45c8213ca0346ea609bd3c57d767969b03590211c5396b44402ab3c09b241d6eb26db89900978768d13fec298dd7f1129e3453e5af8967f44ecc720fa75aeedd
+  metadata.gz: 257068790c8689c780904f9da8762bae1706e5adc32a2458c0873155b3d15feb32afeb63cbf5712c72ff5ae00ec1ffcc21227245b1be700a52493cc316e0ebaa
+  data.tar.gz: 991b7e1ff8582dc1341bbcdbf8821043518b3c9f3f4538f764917ed4087d56979c4bb8fc6546cb1f57d12e6e9549066ff804dad5fd2e444ca7876abcc5b54150

data/README.md

@@ -34,6 +34,8 @@ class UserHalInterpreter
 end
 ```
 
+#### Create
+
 To interpret a HAL document simply create a new interpreter from the
 JSON document to interpret and then call its `#items` method.
 
@@ -42,6 +44,8 @@ class Users < ApplicationController
   def create
     @users = UserHalInterpreter.new_from_json(request.raw_post).items
 
+    @users.each(&:save!)
+
   rescue HalInterpretation::InvalidRepresentationError => err
     render template: "shared/error", status: 422, locals: { problems: err.problems }
   end
@@ -50,6 +54,27 @@ end
 
 The `items` method returns an `Enumerable` of valid `item_class` objects.
 
+#### Update
+
+To update and existing record
+
+```ruby
+
+class Users < ApplicationController
+  def update
+    existing_user = User.find(params[:id])
+
+    @user = UserHalInterpreter.new_from_json(request.raw_post).only_update(existing_user)
+              .item
+
+    @user.save!
+
+  rescue HalInterpretation::InvalidRepresentationError => err
+    render template: "shared/error", status: 422, locals: { problems: err.problems }
+  end
+end
+```
+
 ### Errors
 
  If the JSON being interpreted is invalid or malformed

data/lib/hal_interpretation.rb

@@ -6,6 +6,11 @@ require "hal-client"
 # objects.
 module HalInterpretation
 
+  # Declares that this interpreter should only update `an_item`.
+  def only_update(an_item)
+    @item_to_update = an_item
+  end
+
   # Returns array of models created from the HAL representation we are
   # interpreting.
   #
@@ -14,7 +19,17 @@ module HalInterpretation
   def items
     (fail InvalidRepresentationError.new(problems)) if problems.any?
 
-    @observations ||= interpreters.flat_map(&:items)
+    @items ||= interpreters.flat_map(&:items)
+  end
+
+  # Returns the single item interpreted.
+  #
+  # Raises InvalidRepresentationError if more than one item was found.
+  def item
+    (fail InvalidRepresentationError, "More than one representation found") if
+      items.size > 1
+
+    items.first
   end
 
   # Returns array of problems messages, or empty array if there are
@@ -27,6 +42,17 @@ module HalInterpretation
   extend Forwardable
   def_delegators "self.class", :extractors, :extractor_for
 
+  # Internal: builds and returns items that should be use interpreted
+  # into.
+  def new_item(&blk)
+    if item_to_update
+      yield item_to_update
+      item_to_update
+    else
+      item_class.new(&blk)
+    end
+  end
+
   protected
 
   # opts
@@ -54,6 +80,8 @@ module HalInterpretation
           [ItemInterpreter.new(repr, location: location, interpreter: self)]
         end
       end
+      .tap {|is| raise(HalInterpretation::InvalidRepresentationError,
+                       "Too many representations") if item_to_update && is.size > 1 }
   end
 
   # Back stop method to be overridden by individual interpreters.
@@ -61,6 +89,8 @@ module HalInterpretation
     fail NotImplementedError, "interpreter classes must call `item_class <model class>` in the class defintion"
   end
 
+  attr_reader :item_to_update
+
   module ClassMethods
     # Returns new interpreter for the provided JSON document.
     #

data/lib/hal_interpretation/item_interpreter.rb

@@ -28,7 +28,7 @@ module HalInterpretation
 
     extend Forwardable
 
-    def_delegators :interpreter, :extractors, :extractor_for, :item_class
+    def_delegators :interpreter, :extractors, :extractor_for
 
     attr_reader :repr, :location, :interpreter
 
@@ -37,7 +37,7 @@ module HalInterpretation
     end
 
     def interpret
-      new_item = item_class.new do |it|
+      new_item = interpreter.new_item do |it|
         e = extractors
         e.each do |an_extractor|
           @problems += an_extractor.extract(from: repr, to: it, context: interpreter)

data/lib/hal_interpretation/version.rb

@@ -1,3 +1,3 @@
 module HalInterpretation
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/spec/hal_interpretation_spec.rb

@@ -39,12 +39,29 @@ describe HalInterpretation do
     JSON
 
     specify { expect(interpreter.items).to have(1).item }
-    specify { expect(interpreter.items.first.name).to eq "foo" }
-    specify { expect(interpreter.items.first.latitude).to eq 39.1 }
-    specify { expect(interpreter.items.first.up).to eq "/foo" }
-    specify { expect(interpreter.items.first.bday).to eq Time.utc(2013,12,11,10,9,8) }
-    specify { expect(interpreter.items.first.seq).to eq 1 }
+    specify { expect(interpreter.item).to be interpreter.items.first }
+    specify { expect(interpreter.item.name).to eq "foo" }
+    specify { expect(interpreter.item.latitude).to eq 39.1 }
+    specify { expect(interpreter.item.up).to eq "/foo" }
+    specify { expect(interpreter.item.bday).to eq Time.utc(2013,12,11,10,9,8) }
+    specify { expect(interpreter.item.seq).to eq 1 }
     specify { expect(interpreter.problems).to be_empty }
+
+    context "for update" do
+      let(:existing) { test_item_class.new do |it|
+                         it.name = "foo"
+                         it.latitude = 40
+                       end }
+
+      before do interpreter.only_update(existing) end
+
+      specify { expect(interpreter.items).to have(1).item }
+      specify { expect(interpreter.item).to be interpreter.items.first }
+      specify { expect(interpreter.item).to eq existing }
+      specify { expect(interpreter.item.name).to eq "foo" }
+      specify { expect(interpreter.item.latitude).to eq 39.1 }
+      specify { expect(interpreter.item.bday).to eq Time.utc(2013,12,11,10,9,8) }
+    end
   end
 
   context "valid collection" do
@@ -75,6 +92,9 @@ describe HalInterpretation do
     specify { expect(interpreter.items[0].seq).to eq 1 }
     specify { expect(interpreter.items[1].seq).to eq 2 }
 
+    specify { expect{interpreter.item}
+              .to raise_error HalInterpretation::InvalidRepresentationError }
+
     matcher :item_named do |expected_name|
       match do |obj|
         obj.name == expected_name

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hal-interpretation
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-30 00:00:00.000000000 Z
+date: 2014-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hal-client
@@ -188,3 +188,4 @@ test_files:
 - spec/hal_interpretation/extractor_spec.rb
 - spec/hal_interpretation_spec.rb
 - spec/spec_helper.rb
+has_rdoc: