hal-interpretation 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a2e12f276257a0cbc1b66f5777f5dee67570f6e7
-  data.tar.gz: 1fd1c93f8399581deb75ac6b2c8566b7179b9c20
+  metadata.gz: ba7860074fdcec96c7e93e4de881bc2acbf2654f
+  data.tar.gz: 99d106bfe6ec85f33979309d5c4983e21fd450ff
 SHA512:
-  metadata.gz: 41c74b5b41ae43af541941fab2ef38a02b5d9905551d95b1b303a2cfdd0b23946ea689448c59c77ba36e5e72f45d0f8a12650703a49042ce23803a2d466b26f2
-  data.tar.gz: 576ff03799bbeaaf6939eb649848a990085ae86df21e14cace8af6ad75a0cc0ef89ab83583b26c07b959f17de31548c8198771658f8ca6f6b517a8571a41090d
+  metadata.gz: d550101e729d0997a634ca46e9141d19d8cd9023c3b9c156172205e764031674ab235ecb2061ab78d90e403b36b9b3d7e6984d51f09b956bc8d5a219441a5eb4
+  data.tar.gz: b1e21c3e017494d6532adf460fea15edb442d4dbab9f2c55c07689b379ac8bc51785b88bf123e9d9a268a5f5a69b7546d94607a8f8dc09c50b9f94ecce0e7b47

data/README.md

@@ -17,10 +17,31 @@ class UserHalInterpreter
 
   item_class User
 
+  # Extract value of the name member of the JSON object and assign it to
+  # the `name` attribute of the model.
   extract :name
+
+  # Extract the value of the line1 member of the address member of the JSON
+  # object and assign it to the `address_line` attribute of the model.
   extract :address_line, from: "address/line1"
+
+  # Assign the `seq` attribute of the model a newly generated sequence number.
   extract :seq, with: ->(_hal_repr) { next_seq_num }
-  extract :birthday, coercion: ->(date_str) { Date.iso8601(date_str) } 
+
+  # Extract the birthday member of the JSON object, convert it to a ruby date
+  # and assign it to the `birthday` attribute of the model.
+  extract :birthday, coercion: ->(date_str) { Date.iso8601(date_str) }
+
+  # Extract the targets of the .../knows links, extract the ids from each and
+  # assign those ids to the `friend_ids` attribute of the model.
+  extract_links :friend_ids, coercion: ->(urls) { urls.map{|u| u.split("/").last} },
+    rel: "http://xmlns.com/foaf/0.1/knows"
+
+  # Extract the target of the up link and assign the full url to the up
+  # attribute of the model. Reports a problem if more than one link of this
+  # type is present.
+  extract_link  :up
+
 
   def initialize
     @cur_seq_num = 0
@@ -34,6 +55,61 @@ class UserHalInterpreter
 end
 ```
 
+This interpreter will work for documents that look like the following
+
+```json
+{ "name": "Bob",
+  "address": {
+    "line1": "123 Main St",
+    "city":  "Denver"
+  },
+  "birthday": "1980-08-31",
+  "_links": {
+    "http://xmlns.com/foaf/0.1/knows": [
+      { "href": "http://example.com/alice" },
+      { "href": "http://example.com/mallory" }
+    ],
+    "up": { "href": "http://example.com/vips" }
+} }
+```
+
+or
+
+```json
+{ "_embedded": {
+    "item": [
+      { "name": "Bob",
+        "address": {
+          "line1": "123 Main St",
+          "city":  "Denver"
+        },
+        "birthday": "1980-08-31",
+        "_links": {
+          "http://xmlns.com/foaf/0.1/knows": [
+            { "href": "http://example.com/alice" },
+            { "href": "http://example.com/mallory" }
+          ],
+          "up": { "href": "http://example.com/vips" }
+      } },
+
+      { "name": "Alice",
+        "address": {
+          "line1": "123 Main St",
+          "city":  "Denver"
+        },
+        "birthday": "1979-02-16",
+        "_links": {
+          "http://xmlns.com/foaf/0.1/knows": [
+            { "href": "http://example.com/bob" },
+            { "href": "http://example.com/mallory" }
+          ],
+          "up": { "href": "http://example.com/vips" }
+      } }
+    ]
+} }
+
+```
+
 #### Create
 
 To interpret a HAL document simply create a new interpreter from the
@@ -56,7 +132,7 @@ The `items` method returns an `Enumerable` of valid `item_class` objects.
 
 #### Update
 
-To update and existing record
+To update an existing record
 
 ```ruby
 
@@ -75,6 +151,9 @@ class Users < ApplicationController
 end
 ```
 
+This approach with produce an error if the JSON contains more than one
+representation.
+
 ### Errors
 
  If the JSON being interpreted is invalid or malformed

data/lib/hal_interpretation/dsl.rb

@@ -27,10 +27,97 @@ module HalInterpretation
         attr: attr_name,
         location: opts.fetch(:from) { "/#{attr_name}" }
       }
-      extractor_opts[:extraction_proc] = opts.fetch(:with) if opts.key? :with
-      extractor_opts[:coercion] = opts[:coercion] if opts.key? :coercion
+      extractor_opts[:extraction_proc] = opts.fetch(:with) if opts[:with]
+      extractor_opts[:coercion] = opts[:coercion] if opts[:coercion]
 
       extractors << Extractor.new(extractor_opts)
     end
+
+    # Declare that an attribute should be extracted the HAL document's
+    # links (or embeddeds) where only one instance of that link type
+    # is legal.
+    #
+    # attr_name - name of the attribute on the model to extract
+    #
+    # opts - hash of named arguments
+    #
+    #  :rel - rel of link to extract. Default: attr_name
+    #
+    #  :coercion - callable with which the raw URL should transformed
+    #  before being stored in the model
+    #
+    # Examples
+    #
+    #     extract_link :author_website,
+    #                  rel: "http://xmlns.com/foaf/0.1/homepage"
+    #
+    # extracts the target of the `.../homepage` link and stores in the
+    # `author_website` attribute of the model.
+    #
+    #     extract_link :parent, rel: "up",
+    #                   coercion: ->(url) {
+    #                     Blog.find id_from_url(u)
+    #                   }
+    #
+    # looks up the blog pointed to by the `up` link and stores that
+    # model instance in the `parent` association of the model we are
+    # interpreting.
+    def extract_link(attr_name, opts={})
+      orig_coercion = opts[:coercion] || IDENTITY
+      adjusted_opts = opts.merge coercion: ->(urls) {
+        fail "Too many instances (expected exactly 1, found #{urls.count})" if
+          urls.count > 1
+
+        instance_exec urls.first, &orig_coercion
+      }
+
+      extract_links attr_name, adjusted_opts
+    end
+
+    # Declare that an attribute should be extracted the HAL document's
+    # links (or embeddeds).
+    #
+    # attr_name - name of the attribute on the model to extract
+    #
+    # opts - hash of named arguments
+    #
+    #  :rel - rel of link to extract. Default: attr_name
+    #
+    #  :coercion - callable with which the raw URL should transformed
+    #  before being stored in the model
+    #
+    # Examples
+    #
+    #     extract_links :author_websites,
+    #                   rel: "http://xmlns.com/foaf/0.1/homepage"
+    #
+    # extracts the targets of the `.../homepage` link and stores in the
+    # `author_websites` attribute of the model.
+    #
+    #     extract_links :parents, rel: "up",
+    #                   coercion: ->(urls) {
+    #                     urls.map { |u| Blog.find id_from_url(u) }
+    #                   }
+    #
+    # looks up the blogs pointed to by the `up` links and stores that
+    # collection of model instances in the `parents` association of
+    # the model we are interpreting.
+    def extract_links(attr_name, opts={})
+      rel = opts.fetch(:rel) { attr_name }.to_s
+      path = "/_links/" + json_path_escape(rel)
+
+      extract attr_name, from: path,
+              with: ->(r){ r.related_hrefs(rel){[]} },
+              coercion: opts[:coercion]
+    end
+
+
+    protected
+
+    def json_path_escape(rel)
+      rel.gsub('~', '~0').gsub('/', '~1')
+    end
+
+    IDENTITY = ->(o) { o }
   end
-end
+end

data/lib/hal_interpretation/version.rb

@@ -1,3 +1,3 @@
 module HalInterpretation
-  VERSION = "1.4.1"
+  VERSION = "1.5.0"
 end

data/spec/hal_interpretation_spec.rb

@@ -11,7 +11,9 @@ describe HalInterpretation do
       item_class test_item_class
       extract :name
       extract :latitude, from: "/geo/latitude"
-      extract :up, with: ->(hal_repr){hal_repr.related_hrefs("up").first}, from: "/_links/up"
+      extract_link  :up
+      extract_links :friend_ids, rel: "http://xmlns.com/foaf/0.1/knows",
+                    coercion: ->(urls) { urls.map{|u| u.split("/").last } }
       extract :bday, coercion: ->(val){ Time.parse(val) }
       extract :seq, with: ->(_) { next_seq_num }
 
@@ -37,7 +39,11 @@ describe HalInterpretation do
           "latitude": 39.1
         }
         ,"_links": {
-          "up": {"href": "/foo"}
+          "up": { "href": "/foo" },
+          "http://xmlns.com/foaf/0.1/knows": [
+            { "href": "http://example.com/bob" },
+            { "href": "http://example.com/alice" }
+          ]
         }
       }
     JSON
@@ -49,6 +55,8 @@ describe HalInterpretation do
     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.item.friend_ids).to eq ["bob", "alice"] }
+
     specify { expect(interpreter.problems).to be_empty }
 
     context "for update" do
@@ -66,6 +74,27 @@ describe HalInterpretation do
       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
+
+    context "with embedded links" do
+      let(:json_doc) { <<-JSON }
+          { "name": "foo"
+            ,"bday": "2013-12-11T10:09:08Z"
+            ,"geo": {
+              "latitude": 39.1
+            }
+            ,"_embedded": {
+              "up": { "_links": { "self": { "href": "/foo" } } },
+              "http://xmlns.com/foaf/0.1/knows": [
+                { "_links": { "self":{ "href": "http://example.com/bob" } } },
+                { "_links": { "self":{ "href": "http://example.com/alice" } } }
+              ]
+            }
+          }
+        JSON
+
+      specify { expect(interpreter.item.up).to eq "/foo" }
+      specify { expect(interpreter.item.friend_ids).to eq ["bob", "alice"] }
+    end
   end
 
   context "valid collection" do
@@ -115,22 +144,35 @@ describe HalInterpretation do
       }
     JSON
 
+    before do
+      test_item_class.class_eval do
+        validates :up, presence: true
+        validates :friend_ids, presence: { message: "only popular people allowed" }
+      end
+    end
+
     specify { expect{interpreter.items}
         .to raise_exception HalInterpretation::InvalidRepresentationError }
     context "raised error" do
       subject(:error) { interpreter.items rescue $! }
 
       specify { expect(error.problems)
-          .to include matching matching(%r(/geo/latitude\b)).and(match(/\binvalid value\b/i)) }
+          .to include matching(%r(/geo/latitude\b)).and(match(/\binvalid value\b/i)) }
       specify { expect(error.problems)
           .to include matching(%r(/name\b)).and(match(/\bblank\b/i))  }
     end
+
     specify { expect(interpreter.problems)
         .to include matching(%r(/name\b)).and(match(/\bblank\b/i))  }
     specify { expect(interpreter.problems)
         .to include matching(%r(/geo/latitude\b)).and(match(/\binvalid value\b/i))  }
     specify { expect(interpreter.problems)
         .to include matching(%r(/bday\b)).and(match(/\bno time\b/i))  }
+    specify { expect(interpreter.problems)
+              .to include matching(%r(/_links/up\b)).and(match(/\bblank\b/i)) }
+    specify { expect(interpreter.problems)
+              .to include matching(%r(/_links/http:~1~1xmlns.com~1foaf~10.1~1knows\b))
+                           .and(match(/\bpopular\b/i)) }
   end
 
   context "collection w/ invalid attributes" do
@@ -225,7 +267,7 @@ describe HalInterpretation do
   let(:test_item_class) { Class.new do
       include ActiveModel::Validations
 
-      attr_accessor :name, :latitude, :up, :bday, :seq, :hair
+      attr_accessor :name, :latitude, :up, :bday, :seq, :hair, :friend_ids
 
       def initialize
         yield self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hal-interpretation
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-05 00:00:00.000000000 Z
+date: 2014-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hal-client