pragma-decorator 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7fbddf33eb638f9dc7cc36f989bc22ffea969ee5
-  data.tar.gz: 363a2780b6a8316b3330eb7756f1cda1e5a768cf
+  metadata.gz: 1ff48d9c11a4d5a07d7a11f0b8c90005a06ff998
+  data.tar.gz: 53f69d42826745d481a7dc0317e28e90be17904e
 SHA512:
-  metadata.gz: 34b21171d3f3961379083f634e2178d6b6166d7c75b0d5c50ddb6a5a6ac75390728988beaeb4a31a7ca1a9c45f0436ea32809d84ab13fd015a3866c9323054b6
-  data.tar.gz: 1f5a2172ef77a3261676d119deb273bd9b75962db264a3787fa0f3feb600390ac3fb9d280d226e2bc83919075f66eb82ce1ab9ce03f5ef38db044bd195a62aeb
+  metadata.gz: cf5197a94d5f7664b8ed594687c5d549abf3c01a9f61166a68c8a93dbd89bf4ade857efd1568b0e6645f9ec3f2396434eb56045805b977cdb9a38d8f4783f58e
+  data.tar.gz: 37bea54b8e417195fccfb37cfda43635bd625570f8569afa5cb68fc7de70b5652e7d1834f0e30f480a7709fdf2e6c430b13d214699391bf8137364bdce140769

data/.gitignore

@@ -3,7 +3,6 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/README.md

@@ -32,216 +32,7 @@ $ gem install pragma-decorator
 
 ## Usage
 
-Creating a decorator is as simple as inheriting from `Pragma::Decorator::Base`:
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          property :id
-          property :email
-          property :full_name
-        end
-      end
-    end
-  end
-end
-```
-
-Just instantiate the decorator by passing it an object to decorate, then call `#to_hash` or
-`#to_json`:
-
-```ruby
-decorator = API::V1::User::Decorator::Resource.new(user)
-decorator.to_json
-```
-
-This will produce the following JSON:
-
-```json
-{
-  "id": 1,
-  "email": "jdoe@example.com",
-  "full_name": "John Doe"
-}
-```
-
-Since Pragma::Decorator is built on top of [ROAR](https://github.com/apotonick/roar) (which, in
-turn, is built on top of [Representable](https://github.com/apotonick/representable)), you should
-consult their documentation for the basic usage of decorators; the rest of this section only covers
-the features provided specifically by Pragma::Decorator.
-
-### Object types
-
-It is recommended that decorators expose the type of the decorated object. You can achieve this
-with the `Type` mixin:
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Type
-        end
-      end
-    end
-  end
-end
-```
-
-This would result in the following representation:
-
-```json
-{
-  "type": "user",
-  "...": "...""
-}
-```
-
-You can also set a custom type name (just make sure to use it consistently!):
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          def type
-            :custom_type
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-Note: `array` is already overridden with the more language-agnostic `list`.
-
-### Associations
-
-`Pragma::Decorator::Association` allows you to define associations in your decorator (currently,
-only `belongs_to`/`has_one` associations are supported):
-
-```ruby
-module API
-  module V1
-    module Invoice
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Association
-
-          belongs_to :customer
-        end
-      end
-    end
-  end
-end
-```
-
-Rendering an invoice will now create the following representation:
-
-```json
-{
-  "customer": {
-    "id": 19
-  }
-}
-```
-
-Not impressed? Just wait.
-
-We also support association expansion through an interface similar to the one provided by the
-[Stripe API](https://stripe.com/docs/api/curl#expanding_objects). You can define which associations
-are expandable in the decorator:
-
-```ruby
-module API
-  module V1
-    module Invoice
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Association
-
-          belongs_to :customer, expandable: true
-        end
-      end
-    end
-  end
-end
-```
-
-You can now pass `expand[]=customer` as a request parameter and have the `customer` property
-expanded into a full object!
-
-```json
-{
-  "customer": {
-    "id": 19,
-    "...": "..."
-  }
-}
-```
-
-This also works for nested associations. For instance, if the customer has a `company` association
-marked as expandable, you can pass `expand[]=customer&expand[]=customer.company` to get that
-association expanded too.
-
-In order for association expansion to work, you will have to pass the associations to expand to the
-representer as a user option:
-
-```ruby
-decorator = API::V1::Invoice::Decorator::Resource.new(invoice)
-decorator.to_json(user_options: {
-  expand: ['customer', 'customer.company', 'customer.company.contact']
-})
-```
-
-Here's a list of options accepted when defining an association:
-
-Name | Type | Default | Meaning
----- | ---- | ------- | -------
-`expandable` | Boolean | `false` | Whether this association is expandable by consumers. Attempting to expand a non-expandable association will raise a `UnexpandableError`.
-`decorator` | Class | - | If provided, decorates the expanded object with this decorator. Otherwise, simply calls `#to_hash` on the object to get a representable hash.
-`render_nil` | Boolean | `false` | Whether the property should be rendered at all when it is `nil`.
-`exec_context` | Symbol | `:decorated` | Whether to call the getter on the decorator (`:decorator`) or the decorated object (`:decorated`).
-
-### Timestamps
-
-[UNIX time](https://en.wikipedia.org/wiki/Unix_time) is your safest bet when rendering/parsing
-timestamps in your API, as it doesn't require a timezone indicator (the timezone is always UTC).
-
-You can use the `Timestamp` mixin for converting `Time` instances to UNIX times:
-
-```ruby
-module API
-  module V1
-    module User
-      module Decorator
-        class Resource < Pragma::Decorator::Base
-          feature Pragma::Decorator::Timestamp
-
-          timestamp :created_at
-        end
-      end
-    end
-  end
-end
-```
-
-This will render a user like this:
-
-```json
-{
-  "type": "user",
-  "created_at": 1480287994
-}
-```
-
-The `#timestamp` method supports all the options supported by `#property` (except for `:as`).
+All documentation is in the [doc](https://github.com/pragmarb/pragma-decorator/tree/master/doc) folder.
 
 ## Contributing
 

data/doc/01-basic-usage.md

@@ -0,0 +1,42 @@
+# Basic usage
+
+Creating a decorator is as simple as inheriting from `Pragma::Decorator::Base`:
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Resource < Pragma::Decorator::Base
+          property :id
+          property :email
+          property :full_name
+        end
+      end
+    end
+  end
+end
+```
+
+Just instantiate the decorator by passing it an object to decorate, then call `#to_hash` or
+`#to_json`:
+
+```ruby
+decorator = API::V1::User::Decorator::Resource.new(user)
+decorator.to_json
+```
+
+This will produce the following JSON:
+
+```json
+{
+  "id": 1,
+  "email": "jdoe@example.com",
+  "full_name": "John Doe"
+}
+```
+
+Since Pragma::Decorator is built on top of [ROAR](https://github.com/apotonick/roar) (which, in
+turn, is built on top of [Representable](https://github.com/apotonick/representable)), you should
+consult their documentation for the basic usage of decorators; the rest of this section only covers
+the features provided specifically by Pragma::Decorator.

data/doc/02-object-types.md

@@ -0,0 +1,47 @@
+# Object types
+
+It is recommended that decorators expose the type of the decorated object. You can achieve this
+with the `Type` mixin:
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Resource < Pragma::Decorator::Base
+          feature Pragma::Decorator::Type
+        end
+      end
+    end
+  end
+end
+```
+
+This would result in the following representation:
+
+```json
+{
+  "type": "user",
+  "...": "...""
+}
+```
+
+You can also set a custom type name (just make sure to use it consistently!):
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Resource < Pragma::Decorator::Base
+          def type
+            :custom_type
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Note: `array` is already overridden with the more language-agnostic `list`.

data/doc/03-associations.md

@@ -0,0 +1,91 @@
+# Associations
+
+`Pragma::Decorator::Association` allows you to define associations in your decorator (currently,
+only `belongs_to`/`has_one` associations are supported):
+
+```ruby
+module API
+  module V1
+    module Invoice
+      module Decorator
+        class Resource < Pragma::Decorator::Base
+          feature Pragma::Decorator::Association
+
+          belongs_to :customer
+        end
+      end
+    end
+  end
+end
+```
+
+Rendering an invoice will now create the following representation:
+
+```json
+{
+  "customer": 19
+}
+```
+
+Not impressed? Just wait.
+
+## Expanding associations
+
+We also support association expansion through an interface similar to the one provided by the
+[Stripe API](https://stripe.com/docs/api/curl#expanding_objects). You can define which associations
+are expandable in the decorator:
+
+```ruby
+module API
+  module V1
+    module Invoice
+      module Decorator
+        class Resource < Pragma::Decorator::Base
+          feature Pragma::Decorator::Association
+
+          belongs_to :customer, expandable: true
+        end
+      end
+    end
+  end
+end
+```
+
+You can now pass `expand[]=customer` as a request parameter and have the `customer` property
+expanded into a full object!
+
+```json
+{
+  "customer": {
+    "id": 19,
+    "...": "..."
+  }
+}
+```
+
+## Nested associations
+
+This also works for nested associations. For instance, if the customer has a `company` association
+marked as expandable, you can pass `expand[]=customer&expand[]=customer.company` to get that
+association expanded too.
+
+In order for association expansion to work, you will have to pass the associations to expand to the
+representer as a user option:
+
+```ruby
+decorator = API::V1::Invoice::Decorator::Resource.new(invoice)
+decorator.to_json(user_options: {
+  expand: ['customer', 'customer.company', 'customer.company.contact']
+})
+```
+
+## Accepted options
+
+Here's a list of options accepted when defining an association:
+
+Name | Type | Default | Meaning
+---- | ---- | ------- | -------
+`expandable` | Boolean | `false` | Whether this association is expandable by consumers. Attempting to expand a non-expandable association will raise a `UnexpandableError`.
+`decorator` | Class | - | If provided, decorates the expanded object with this decorator. Otherwise, simply calls `#to_hash` on the object to get a representable hash.
+`render_nil` | Boolean | `false` | Whether the property should be rendered at all when it is `nil`.
+`exec_context` | Symbol | `:decorated` | Whether to call the getter on the decorator (`:decorator`) or the decorated object (`:decorated`).

data/doc/04-timestamps.md

@@ -0,0 +1,33 @@
+# Timestamps
+
+[UNIX time](https://en.wikipedia.org/wiki/Unix_time) is your safest bet when rendering/parsing
+timestamps in your API, as it doesn't require a timezone indicator (the timezone is always UTC).
+
+You can use the `Timestamp` mixin for converting `Time` instances to UNIX times:
+
+```ruby
+module API
+  module V1
+    module User
+      module Decorator
+        class Resource < Pragma::Decorator::Base
+          feature Pragma::Decorator::Timestamp
+
+          timestamp :created_at
+        end
+      end
+    end
+  end
+end
+```
+
+This will render a user like this:
+
+```json
+{
+  "type": "user",
+  "created_at": 1480287994
+}
+```
+
+The `#timestamp` method supports all the options supported by `#property` (except for `:as`).

data/lib/pragma/decorator/association/binding.rb

@@ -34,19 +34,15 @@ module Pragma
           end
         end
 
-        # Returns the unexpanded hash for the associated object (i.e. a hash with only the +id+
-        # property).
+        # Returns the unexpanded value for the associated object (i.e. its +id+ property).
         #
-        # @return [Hash]
-        def unexpanded_hash
+        # @return [String]
+        def unexpanded_value
           return unless associated_object
-
-          {
-            id: associated_object.id
-          }
+          associated_object.id
         end
 
-        # Returns the expanded hash for the associated object.
+        # Returns the expanded value for the associated object.
         #
         # If a decorator was specified for the association, first decorates the associated object,
         # then calls +#to_hash+ to render it as a hash.
@@ -61,7 +57,7 @@ module Pragma
         # @return [Hash]
         #
         # @raise [UnexpandableError] if the association is not expandable
-        def expanded_hash(expand)
+        def expanded_value(expand)
           fail UnexpandableError, reflection unless reflection.expandable?
 
           return unless associated_object
@@ -91,9 +87,9 @@ module Pragma
           expand ||= []
 
           if expand.any? { |value| value.to_s == reflection.property.to_s }
-            expanded_hash(expand)
+            expanded_value(expand)
           else
-            unexpanded_hash
+            unexpanded_value
           end
         end
 

data/lib/pragma/decorator/association/reflection.rb

@@ -56,12 +56,12 @@ module Pragma
         end
 
         def validate_options
-          unless [:decorator, :decorated].include?(options[:exec_context])
-            fail(
-              ArgumentError,
-              "'#{options[:exec_context]}' is not a valid value for :exec_context."
-            )
-          end
+          return if [:decorator, :decorated].include?(options[:exec_context])
+
+          fail(
+            ArgumentError,
+            "'#{options[:exec_context]}' is not a valid value for :exec_context."
+          )
         end
       end
     end

data/lib/pragma/decorator/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 module Pragma
   module Decorator
-    VERSION = '0.1.0'
+    VERSION = '1.0.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pragma-decorator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-26 00:00:00.000000000 Z
+date: 2017-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roar
@@ -139,6 +139,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- doc/01-basic-usage.md
+- doc/02-object-types.md
+- doc/03-associations.md
+- doc/04-timestamps.md
 - lib/pragma/decorator.rb
 - lib/pragma/decorator/association.rb
 - lib/pragma/decorator/association/binding.rb
@@ -169,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Convert your API resources into JSON with minimum hassle.