hal-interpretation 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ee39c1fec5913e271d4fab7531f9ff40b6623dc9
-  data.tar.gz: 5c21413e4a4be9e30d16eb3cc8e6a00644154731
+  metadata.gz: f58aa8729b4937c393264c78c95d632709da9466
+  data.tar.gz: 56ba264b40ef29039d9e43b036f294686e7355ca
 SHA512:
-  metadata.gz: 7cbe1d536193dd6f563c43823b7828ebe5975ba039201b5189960b033f12dfb72c04b767a95e8765c21736e661aee117b64fb95f769afc4f38fa7f626255ee01
-  data.tar.gz: eb3d579ce01aea81b727c59df2457c509765759ef0bc884492afe3adf57d746de99a43a639c2c44f0b95c6fcf5c998020189f8e0cb62552065c5ab4754ac5f8f
+  metadata.gz: f837c0d54a4761ad9b0cee0f62c7ab01217daefe2533dea6afac51a5f82b66bb5e9b82ce4f385a72ef00dd6efff364c7e30e02268bb6f226c6f75381c27be740
+  data.tar.gz: 01f37e998c2e7cd8740065c0e664806b4c7710765c8ff6af89737896609dfb87297775510087aa4628ccd79dfccd281a2cb9a6581b746c85260e145b5297e39a

data/README.md

@@ -42,6 +42,19 @@ class UserHalInterpreter
   # type is present.
   extract_link  :up
 
+  # Extract the target of the rel link and assign a HAL representation to the person
+  # attribute of the model. Reports a problem if more than one link of this
+  # type is present.
+  extract_related  :profile, rel: "http://xmlns.com/foaf/0.1/Person",
+    coercion: ->(profile_repr) { CustomInterpretation.new(profile_repr) }
+
+  # Extract the target of the rel link and assign a HAL representation
+  # set to the cohorts attribute of the model. Reports a problem if
+  # more than one link of this type is present.
+  extract_relateds  :cohorts, rel: "http://xmlns.com/foaf/0.1/knows",
+    coercion: ->(cohort_repr_set) {
+      cohort_repr_set.map {|repr| CustomInterpretation.new(repr) }
+    }
 
   def initialize
     @cur_seq_num = 0
@@ -65,6 +78,7 @@ This interpreter will work for documents that look like the following
   },
   "birthday": "1980-08-31",
   "_links": {
+    "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/bob" },
     "http://xmlns.com/foaf/0.1/knows": [
       { "href": "http://example.com/alice" },
       { "href": "http://example.com/mallory" }
@@ -85,6 +99,7 @@ or
         },
         "birthday": "1980-08-31",
         "_links": {
+          "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/bob" },
           "http://xmlns.com/foaf/0.1/knows": [
             { "href": "http://example.com/alice" },
             { "href": "http://example.com/mallory" }
@@ -99,6 +114,7 @@ or
         },
         "birthday": "1979-02-16",
         "_links": {
+          "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/alice },
           "http://xmlns.com/foaf/0.1/knows": [
             { "href": "http://example.com/bob" },
             { "href": "http://example.com/mallory" }
@@ -197,4 +213,4 @@ Or install it yourself as:
 
 [semver]: http://semver.org/
 [json pointer]: http://tools.ietf.org/html/rfc6901
-[collections]: https://tools.ietf.org/html/rfc6573
+[collections]: https://tools.ietf.org/html/rfc6573

data/lib/hal_interpretation/dsl.rb

@@ -119,9 +119,86 @@ module HalInterpretation
               coercion: opts[:coercion]
     end
 
+    # Declare that an attribute should be extracted from the HAL
+    # document's links (or embeddeds) as a representation.
+    #
+    # attr_name - name of the attribute on the model to extract to as
+    # a representation
+    #
+    # 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_repr :author,
+    #                   rel: "http://xmlns.com/foaf/0.1/Person"
+    #
+    # extracts the targets of the `.../Person` link and stores the
+    # corresponding HAL representation object in the `author`
+    # attribute of the model.
+    #
+    #     extract_repr :author, rel: "http://xmlns.com/foaf/0.1/Person",
+    #                   coercion: ->(person_repr) {
+    #                     MyInterpretation.new(person_repr)
+    #                   }
+    #
+    # looks up the author pointed to by the rel and uses coercion to
+    # initialize a custom object stored on the model that uses the
+    # representation
+    def extract_related(attr_name, opts={})
+      extract_related_with_blk(attr_name, opts) {|r, rel| r.related(rel){[]}.first }
+    end
+
+    # Declare that an attribute should be extracted from the HAL
+    # document's links (or embeddeds) as a representation set.
+    #
+    # attr_name - name of the attribute on the model to extract to as
+    # a representation set
+    #
+    # 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_reprs :authors,
+    #                    rel: "http://exampe.com/authors"
+    #
+    # extracts the targets of the `.../authors` link and stores the
+    # corresponding HAL representation set object in the `authors`
+    # attribute of the model.
+    #
+    #     extract_reprs :authors, rel: "http://example.com/authors",
+    #       coercion: ->(person_repr_set) {
+    #         person_repr_set.map {|repr| MyInterpretation.new(repr)}
+    #       }
+    #
+    # looks up the authors pointed to by the rel and uses coercion to
+    # initialize an array of custom objects stored on the model that
+    # uses the representation set
+    def extract_relateds(attr_name, opts={})
+      extract_related_with_blk(attr_name, opts) {|r, rel| r.related(rel){[]} }
+    end
+
 
     protected
 
+    def extract_related_with_blk(attr_name, opts={}, &blk)
+      rel = opts.fetch(:rel) { attr_name }.to_s
+      path = "/_links/" + json_path_escape(rel)
+
+      extract attr_name, from: path,
+                         with: ->(r) { blk.call(r, rel) },
+                         coercion: opts[:coercion]
+    end
+
     def json_path_escape(rel)
       rel.gsub('~', '~0').gsub('/', '~1')
     end

data/lib/hal_interpretation/version.rb

@@ -1,3 +1,3 @@
 module HalInterpretation
-  VERSION = "1.7.0"
+  VERSION = "1.8.0"
 end

data/spec/hal_interpretation_spec.rb

@@ -6,6 +6,7 @@ require "rspec/collection_matchers"
 describe HalInterpretation do
   subject(:interpreter_class) {
     test_item_class = self.test_item_class
+
     Class.new do
       include HalInterpretation
       item_class test_item_class
@@ -17,6 +18,8 @@ describe HalInterpretation do
       extract_links :friend_ids, rel: "http://xmlns.com/foaf/0.1/knows",
                     coercion: ->(urls) { urls.map{|u| u.split("/").last } }
       extract_link :archives_url_tmpl, rel: "archives"
+      extract_related :profile, rel: "http://xmlns.com/foaf/0.1/Person"
+      extract_relateds :cohorts, rel: "http://xmlns.com/foaf/0.1/knows"
 
       def initialize(*args)
         @cur_seq_num = 0
@@ -26,7 +29,8 @@ describe HalInterpretation do
       def next_seq_num
         @cur_seq_num += 1
       end
-    end }
+    end
+  }
 
   let(:interpreter) { interpreter_class.new_from_json(json_doc) }
 
@@ -41,6 +45,7 @@ describe HalInterpretation do
         }
         ,"_links": {
           "up": { "href": "/foo" },
+          "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/foo" },
           "http://xmlns.com/foaf/0.1/knows": [
             { "href": "http://example.com/bob" },
             { "href": "http://example.com/alice" }
@@ -60,6 +65,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.profile).to be_kind_of HalClient::Representation }
+    specify { expect(interpreter.item.cohorts).to be_kind_of HalClient::RepresentationSet }
     specify { expect(interpreter.item.friend_ids).to eq ["bob", "alice"] }
     specify { expect(interpreter.item.archives_url_tmpl)
               .to eq "http://example.com/old{?since,until}" }
@@ -93,6 +100,7 @@ describe HalInterpretation do
             }
             ,"_embedded": {
               "up": { "_links": { "self": { "href": "/foo" } } },
+              "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/foo" },
               "http://xmlns.com/foaf/0.1/knows": [
                 { "_links": { "self":{ "href": "http://example.com/bob" } } },
                 { "_links": { "self":{ "href": "http://example.com/alice" } } }
@@ -103,6 +111,8 @@ describe HalInterpretation do
 
       specify { expect(interpreter.item.up).to eq "/foo" }
       specify { expect(interpreter.item.friend_ids).to eq ["bob", "alice"] }
+      specify { expect(interpreter.item.profile).to be_kind_of HalClient::Representation }
+      specify { expect(interpreter.item.cohorts).to be_kind_of HalClient::RepresentationSet }
     end
   end
 
@@ -114,14 +124,20 @@ describe HalInterpretation do
                       ,"geo": {
                         "latitude": 39.1
                       }
-                      ,"_links": { "up": {"href": "/foo"} }
+                      ,"_links": {
+                        "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/foo" },
+                        "up": {"href": "/foo"}
+                      }
                     }
                     ,{ "name": "bar"
                       ,"bday": "2013-12-11T10:09:08Z"
                       ,"geo": {
                         "latitude": 39.2
                       }
-                      ,"_links": { "up": {"href": "/bar"} }
+                      ,"_links": {
+                         "http://xmlns.com/foaf/0.1/Person": { "href": "http://example.com/bar" },
+                         "up": {"href": "/bar"}
+                      }
                     }]
         }
       }
@@ -133,6 +149,8 @@ describe HalInterpretation do
     specify { expect(interpreter.items).to include item_named "bar" }
     specify { expect(interpreter.items[0].seq).to eq 1 }
     specify { expect(interpreter.items[1].seq).to eq 2 }
+    specify { expect(interpreter.items[0].profile).to be_kind_of HalClient::Representation }
+    specify { expect(interpreter.items[1].profile).to be_kind_of HalClient::Representation }
 
     specify { expect{interpreter.item}
               .to raise_error HalInterpretation::InvalidRepresentationError }
@@ -279,7 +297,7 @@ describe HalInterpretation do
       include ActiveModel::Validations
 
       attr_accessor :name, :latitude, :up, :bday, :seq, :hair, :friend_ids,
-                    :archives_url_tmpl
+                    :archives_url_tmpl, :profile, :cohorts
 
       def initialize
         yield self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hal-interpretation
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-12 00:00:00.000000000 Z
+date: 2015-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hal-client