jsonite 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49c0a11e4a44bd3ab0ad87f0cbf27debc56afd10
-  data.tar.gz: beeb10b2cc59a4e812c492cfba50bce34dfe5b4c
+  metadata.gz: 001f4ee4203a2a9ad449b3ce2be7bef23ba649dc
+  data.tar.gz: cf3d345ce6b1e7194edf8a009512b5a5873f3972
 SHA512:
-  metadata.gz: bee8032685d34443435ef821aaa94b8fe0b4170ecc6e0a1fb55b6ed1bb1ae95346f8b50dce5f22c57d3673f1f7027b881291c5e9199f08bd12fbcdd5797a4321
-  data.tar.gz: b3d8f45e00dd6164f2655988bbe6a5e2bc8880cde5ec1d9773087edc8518f047c07b2f8982e184d600c400d30ec847e0a2c05f29f3cb0fb54acfdf1fde65fe7b
+  metadata.gz: c819dffe0197681f90b17d6e86b5e219861538830c966d2b6f23e3497018c70e09d3070147a618684bb661ed8a42ee95d3c41f01d7e5a9c7bb8854ece3176746
+  data.tar.gz: 73ce6f0f49069b446b458347a3803d162b4bdd21d6ffd8ce74323d8e5e8a1f52b27a1a6d8b3c2a2e6d97c8496932d762dba5993bc332acf1fa1fc6b47e358b79

data/lib/jsonite/version.rb

@@ -1,5 +1,5 @@
 class Jsonite
 
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 
 end

data/lib/jsonite.rb

@@ -1,14 +1,33 @@
+require 'active_support/core_ext/object/blank'
+require 'active_support/json/encoding'
 require 'jsonite/helper'
 
-# A simple JSON presenter for hypermedia applications.
-# Loosely adheers to HAL: http://stateless.co/hal_specification.html
-
+# = Jsonite
+#
+# A tiny, HAL-compliant JSON presenter.
+#
+# http://tools.ietf.org/html/draft-kelly-json-hal-05
 class Jsonite
 
   class << self
 
+    # Presents a resource (or array of resources).
+    #
+    #   class UserPresenter < Jsonite
+    #     property :email
+    #   end
+    #   users = User.all
+    #   UserPresenter.present(users.first)
+    #   # => {"email"=>"stephen@example.com"}
+    #   UserPresenter.present(users)
+    #   # => [{"email"=>"stephen@example.com"}, ...]
+    #
+    # Configuration options:
+    # * <tt>:with</tt> - A specified presenter (defaults to `self`).
+    #
+    # All other options are passed along to <tt>#as_json</tt>.
     def present resource, options = {}
-      presenter = options.fetch :with, self
+      presenter = options.delete(:with) { self }
 
       case resource
       when Jsonite
@@ -29,8 +48,27 @@ class Jsonite
       end
     end
 
+    # Defines a property to be exposed during presentation.
+    #
+    #   class UserPresenter < Jsonite
+    #     property :email
+    #   end
+    #   # {
+    #   #   "email": "stephen@example.com"
+    #   # }
+    #
+    # Configuration options:
+    # * <tt>:with</tt> - A specified presenter. Ignored when a handler is
+    #   present. Useful when you want to embed a resource as a property (rather
+    #   than in the <tt>_embedded</tt> node).
     def property name, options = {}, &handler
-      properties[name] = handler || proc { send name }
+      handler ||= if options[:with]
+        proc { Jsonite.present send(name), with: options[:with] }
+      else
+        proc { send name }
+      end
+
+      properties[name] = handler
     end
 
     def properties *properties
@@ -39,44 +77,123 @@ class Jsonite
       @properties
     end
 
-    def embedded name, options = {}, &handler
-      unless options[:with].is_a?(Class) && options[:with] <= Jsonite
-        raise KeyError, ':with option must be a Jsonite'
-      end
-
-      property name, options do |context|
-        resource = handler ? instance_exec(context, &handler) : send(name)
-        present resource, { context: context, root: nil }.merge(options)
-      end
-    end
-
+    # Defines a link.
+    #
+    #   class UserPresenter < Jsonite
+    #     link do |context|
+    #       context.user_url self
+    #     end
+    #     link :todos do |context|
+    #       context.user_todos_url self
+    #     end
+    #   end
+    #   # {
+    #   #   "_links": {
+    #   #     "self": {
+    #   #       "href": "http://example.com/users/8oljbpyjetu8"
+    #   #     },
+    #   #     "todos": {
+    #   #       "href": "http://example.com/users/8oljbpyjetu8/todos"
+    #   #     }
+    #   #   }
+    #   # }
+    #
+    # Configuration options are displayed as additional properties on a link.
+    #
+    #   class UserPresenter < Jsonite
+    #     link :todos, title: 'To-dos', templated: true do |context|
+    #       "#{context.user_todos_url self}{?done}
+    #     end
+    #   end
+    #   # {
+    #   #   "_links": {
+    #   #     "todos": {
+    #   #       "href": "http://example.com/users/8oljbpyjetu8/todos{?done}",
+    #   #       "title": "To-dos",
+    #   #       "templated": true
+    #   #     }
+    #   #   }
+    #   # }
     def link rel = :self, options = {}, &handler
-      links[rel] = options.merge handler: handler
+      links[rel] = options.merge handler: Proc.new # enforce handler presence
     end
 
     def links
       @links ||= {}
     end
 
+    # Defines an embedded resource.
+    #
+    #   class TodoPresenter < Jsonite
+    #     property :description
+    #   end
+    #   class UserPresenter < Jsonite
+    #     embed :todos, with: TodoPresenter
+    #   end
+    #   # {
+    #   #   "_embedded": {
+    #   #     "todos": [
+    #   #       {
+    #   #         "description": "Buy milk"
+    #   #       }
+    #   #     ]
+    #   #   }
+    #   # }
+    #
+    # Configuration options:
+    # * <tt>:with</tt> - A specified presenter. Required if a handler isn't
+    #   present.
+    def embed rel, options = {}, &handler
+      if handler.nil?
+        presenter = options.fetch :with
+        handler = proc do |context|
+          Jsonite.present send(rel), with: presenter, context: context
+        end
+      end
+
+      embedded[rel] = handler
+    end
+
+    def embedded
+      @embedded ||= {}
+    end
+
+    private
+
     def inherited presenter
       presenter.properties.update properties
       presenter.links.update links
+      presenter.embedded.update embedded
     end
 
   end
 
   attr_reader :resource, :defaults
 
+  # Initializes a new presenter instance with the given resource.
+  #
+  # Default options are passed to #as_json during presentation.
   def initialize resource, defaults = {}
     @resource, @defaults = resource, defaults
   end
 
+  # Returns a JSON representation (Hash) of the resource.
+  #
+  # Options:
+  # * <tt>:context</tt> - A context to pass a presenter instance while
+  #   rendering properties, links, and embedded resources.
   def as_json options = {}
     return resource.as_json options if instance_of? Jsonite
-    context, options = options.delete(:context), defaults.merge(options)
-    properties(context).merge(_links: links(context)).as_json options
+    options = defaults.merge options
+    context = options.delete :context
+    hash = properties context
+    hash.update _links: links(context) if self.class.links.present?
+    hash.update _embedded: embedded(context) if self.class.embedded.present?
+    hash.as_json options
   end
 
+  private
+
   def properties context = nil
     context ||= resource
     self.class.properties.each_with_object({}) do |(name, handler), props|
@@ -88,10 +205,19 @@ class Jsonite
 
   def links context = nil
     context ||= resource
-    self.class.links.each_with_object({}) do |(name, link), props|
+    self.class.links.each_with_object({}) do |(rel, link), links|
       catch :ignore do
         href = resource.instance_exec context, &link[:handler]
-        props[name] = { href: href }.merge link.except :handler
+        links[rel] = { href: href }.merge link.except :handler
+      end
+    end
+  end
+
+  def embedded context = nil
+    context ||= resource
+    self.class.embedded.each_with_object({}) do |(name, handler), embedded|
+      catch :ignore do
+        embedded[name] = resource.instance_exec context, &handler
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonite
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Stephen Celis
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-31 00:00:00.000000000 Z
+date: 2013-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -25,7 +25,35 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: 3.1.0
-description: Tiny JSON presenter
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+description: Jsonite provides a very simple DSL to build HAL-compliant JSON presenters.
 email:
 - stephen@stephencelis.com
 - kainosnoema@gmail.com
@@ -37,7 +65,8 @@ files:
 - lib/jsonite/version.rb
 - lib/jsonite.rb
 homepage: https://github.com/barrelage/jsonite
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -58,5 +87,5 @@ rubyforge_project:
 rubygems_version: 2.0.2
 signing_key: 
 specification_version: 4
-summary: Tiny JSON presenter
+summary: A tiny, HAL-compliant JSON presenter
 test_files: []