collection_json_serializer 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f682b562eebc07619c02953ffa74bc78cbe6bd20
+  data.tar.gz: 9a23b69d8605c95f7faec47e86d2e14752dcb26d
+SHA512:
+  metadata.gz: f48bbd38d5c5b65b6cf3592d583379a3e8b67414468fa13ca1c5369179a225f6ecb9267556feded7fa9dc8fad4f50259457f683f44ebbd4be0f9982be9ce75f2
+  data.tar.gz: 4b2fe8dbb795bf652085a3d6f5c82bb76fdf839c97c8bd5580e42ee0b7f26b60d23bfc8f59b23745959623a1c4de20b86199ce938b5cec15c32ac855f92275de

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.1.5
+  - 2.1.3
+  - 2.1.0
+before_install:
+  - gem install bundler

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in collection_json_serializer.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Carles Jove i Buxeda
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# CollectionJson::Serializer
+
+[![Build Status](https://travis-ci.org/carlesjove/collection_json_serializer.svg?branch=master)](https://travis-ci.org/carlesjove/collection_json_serializer)
+
+| :warning: ** This is _not finished_ yet, so you better do not use it ** |
+---------------------------------------------------------------------------
+
+A Ruby gem to respond with Collection+JSON.
+
+CollectionJson::Serializer formats JSON responses following the Collection+JSON media type by Mike Amudsen. It also handles input data templates.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'collection_json_serializer'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install collection_json_serializer
+
+## Usage
+
+As this gem user, you will be mainly writing/generating and mantaining serializers for your models. A serializer goes like:
+
+```ruby
+class UserSerializer < CollectionJson::Serializer
+  href self: "http://example.com/users/1",
+       collection: "http://example.com/users"
+
+  attributes :id, name: { prompt: "Your full name" }, :email
+
+  template :name, email: { prompt: "My email" }
+
+  # Please note that links can only be passed as hashes
+  links dashboard: { href: "http://example.com/my-dashboard" }
+end
+```
+
+Then, you pass your objects to the serializer:
+
+```ruby
+# Create your object as you wish
+@user = User.new(name: "Carles Jove", email: "hola@carlus.cat")
+
+# You can also pass an array of objects
+# user_serializer = UserSerializer.new([@user1, @user2, etc])
+
+# Pass it to the serializer
+user_serializer = UserSerializer.new(@user)
+
+# Pass the serializer to the builder, and pack it as a hash
+builder = Builder.new(user_serializer)
+builder.pack
+# => { collection: { version: "1.0" } }
+
+# Get it as JSON
+builder.to_json
+```
+
+This will generate this Collection+JSON response:
+
+```javascript
+{ "collection": 
+  {
+    "version" : "1.0",
+    "href" : "http://example.com/users",
+    "items" : [{
+      "href": "http://example.com/users/1",
+      "data": [
+        { "name": "id", "value": "1" },
+        { "name": "name", "value": "Carles Jove", "prompt": "Your full name" },
+        { "name": "email", "value": "email@example.com" },
+      ],
+      "links": [
+        { "name": "dashboard", "href": "http://example.com/my-dashboard" }
+      ]
+    }],
+    "template" : {
+      "data": [
+        { "name": "name", "value": "" },
+        { "name": "email", "value": "", "prompt": "My email" }
+      ]
+    }
+  }
+}
+```
+
+#### URL placeholders
+
+URLs can be generated dinamically with placeholder. A placeholder is a URL segment wrapped in curly braces. A placeholder can be any method that can be called on the object that the serializer takes (i.e. `id`, `username`, etc.).
+
+```ruby
+class UserSerializer < CollectionJson::Serializer
+  href self: "http://example.com/users/{id}"
+end
+```
+
+All placeholders will be called, so you can use more than one if necessary, but you may use only one placeholer per segment.
+
+```ruby
+class UserSerializer < CollectionJson::Serializer
+  # This is ok
+  href self: "http://example.com/users/{id}/{username}"
+
+  # This is not ok
+  href self: "http://example.com/users/{id}-{username}"
+end
+```
+
+#### Open Attributes Policy
+
+Collection+JSON serializer has an __open attributes policy__, which means that objects' attributes can be extended at will. That is good if you want to use many of the [extensions available](https://github.com/collection-json/extensions), and also if you need to add custom extensions to suit your particular needs. Be aware that, [as the specs say](https://github.com/collection-json/spec#7-extensibility), you must only extend attributes in a way that won't break clients that are not aware of them.
+
+```ruby
+class UserSerializer < CollectionJson::Serializer
+  attributes :id, name: { css_class: "people" }
+
+  template name: { regex: "/\A[a-zA-Z0-9_]*\z/" }
+
+  links profile: { css_class: "button" }
+end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/collection_json_serializer/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test
+

data/collection_json_serializer.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'collection_json_serializer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "collection_json_serializer"
+  spec.version       = CollectionJson::Serializer::VERSION
+  spec.authors       = ["Carles Jove i Buxeda"]
+  spec.email         = ["hola@carlus.cat"]
+  spec.summary       = %q{Serialize objects as Collection+JSON.}
+  spec.description   = %q{CollectionJson::Serializer makes it easy to serialize objects into the Collection+JSON hypermedia type.}
+  spec.homepage      = "https://github.com/carlesjove/collection_json_serializer"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", "~> 4.1"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.4"
+end

data/lib/collection_json_serializer/builder.rb

@@ -0,0 +1,56 @@
+module CollectionJson
+  class Serializer
+    class Builder
+      def initialize(serializer)
+        @serializer = serializer
+        @collection = { version: "1.0" }
+      end
+
+      def pack
+        if @serializer.errors.any?
+          error = "The #{@serializer.class} has errors: "
+          @serializer.errors.each_value { |v| error << v.join(", ") }
+          raise Exception, error
+        else
+          build
+          { collection: @collection }
+        end
+      end
+
+      def to_json
+        pack.to_json
+      end
+
+      private
+
+      def build
+        # There might be a more elegant way to do it, yes
+        add_href if @serializer.href.respond_to? :key
+        add_items if @serializer.attributes.present?
+        add_template if @serializer.template.present?
+      end
+
+      def add_href
+        if @serializer.href.key? :collection
+          @collection.store :href, @serializer.href[:collection]
+        end
+      end
+
+      def add_items
+        @collection.store :items, Array.new
+        @serializer.resources.each_index do |i|
+          item = CollectionJson::Serializer::Objects::Item.
+            new(@serializer, item: i)
+          @collection[:items] << item.create
+        end
+      end
+
+      def add_template
+        @collection.store :template, Hash.new
+        template = CollectionJson::Serializer::Objects::Template.
+          new(@serializer)
+        @collection[:template].store :data, template.create
+      end
+    end
+  end
+end

data/lib/collection_json_serializer/core_ext/hash.rb

@@ -0,0 +1,9 @@
+class Hash
+  def extract_params
+    params = {}
+    params[:name] = keys.first
+    params[:properties] = self[keys.first]
+
+    params
+  end
+end

data/lib/collection_json_serializer/core_ext/symbol.rb

@@ -0,0 +1,8 @@
+class Symbol
+  def extract_params
+    params = {}
+    params[:name] = self
+
+    params
+  end
+end

data/lib/collection_json_serializer/objects/item.rb

@@ -0,0 +1,70 @@
+module CollectionJson
+  class Serializer
+    class Objects
+      class Item
+        include CollectionJson::Serializer::Support
+
+        def initialize(serializer, item: 0)
+          @serializer = serializer
+          @index = item >= 0 ? item : 0
+          @resource = @serializer.resources[@index]
+          @item = Hash.new
+        end
+
+        def create
+          add_href  if @serializer.href.present?
+          add_data  if @serializer.attributes.present?
+          add_links if @serializer.links.present?
+
+          @item
+        end
+
+        private
+
+        def add_href
+          if @serializer.href.present?
+            @item.store :href, set_href
+          end
+        end
+
+        def add_data
+          @serializer.attributes.each do |attr|
+            params = attr.extract_params
+            value = extract_value_from(@resource, params[:name])
+
+            next unless value
+
+            c = { name: params[:name], value: value }
+            c.merge!(params[:properties]) if params[:properties]
+
+            start_object :data, Array.new
+            @item[:data] << c
+          end if @serializer.attributes.present?
+        end
+
+        def add_links
+          @serializer.links.each do |attr|
+            params = attr.extract_params
+
+            next unless params.key? :properties
+
+            start_object :links, Array.new
+            @item[:links] << {
+              name: params[:name].to_s,
+              href: params[:properties][:href]
+            }.merge!(params[:properties])
+          end if @serializer.links.present?
+        end
+
+        def start_object(name, type)
+          @item.store(name.to_sym, type) unless @item.key? name.to_sym
+        end
+
+        def set_href
+          url = @serializer.href[:self] || @serializer.href
+          parse_url(url, @resource)
+        end
+      end
+    end
+  end
+end

data/lib/collection_json_serializer/objects/template.rb

@@ -0,0 +1,25 @@
+module CollectionJson
+  class Serializer
+    class Objects
+      class Template
+        def initialize(serializer)
+          @serializer = serializer
+          @data = Array.new
+        end
+
+        def create
+          @serializer.template.each do |attr|
+            params = attr.extract_params
+
+            c = { name: params[:name], value: nil.to_s }
+            c.merge!(params[:properties]) if params[:properties]
+
+            @data << c
+          end if @serializer.template.present?
+
+          @data
+        end
+      end
+    end
+  end
+end

data/lib/collection_json_serializer/serializer.rb

@@ -0,0 +1,71 @@
+module CollectionJson
+  class Serializer
+    class << self
+      attr_accessor :href
+      attr_accessor :attributes
+      attr_accessor :template
+      attr_accessor :links
+    end
+
+    def self.inherited(base)
+      base.href = []
+      base.attributes = []
+      base.template = []
+      base.links = []
+    end
+
+    def self.href(*attrs)
+      @href.concat attrs
+    end
+
+    def self.attributes(*attrs)
+      @attributes.concat attrs
+    end
+
+    def self.template(*attrs)
+      @template.concat attrs
+    end
+
+    def self.links(*attrs)
+      @links.concat attrs
+    end
+
+    attr_accessor :resources
+
+    def initialize(resource)
+      @resources = if resource.respond_to? :to_ary
+                     resource
+                   else
+                     [resource]
+                   end
+    end
+
+    def href
+      self.class.href.first
+    end
+
+    def attributes
+      self.class.attributes
+    end
+
+    def template
+      self.class.template
+    end
+
+    def links
+      self.class.links
+    end
+
+    def invalid?
+      Validator.new(self).invalid?
+    end
+
+    def valid?
+      Validator.new(self).valid?
+    end
+
+    def errors
+      Validator.new(self).errors
+    end
+  end
+end