serial 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8606568eae4354b244eee0133b643b70b83a8d46
-  data.tar.gz: 14c06a5dbbc592f84e08f29b4de5394f5b3eb23f
+  metadata.gz: 29eb0ebd62982d93650098a3f2f4f54f11879bf3
+  data.tar.gz: 6d516f85165f6a46f767925a48c4d40d5a0cb1c9
 SHA512:
-  metadata.gz: cac05055fd052f2b838043014f540b697b38e7ee0a7340cf2f48a71e4ff8358cd253c6a0db6986bcd54a9c53c4f9da19177e7b948369bb58a722a87f2ca61af6
-  data.tar.gz: 49d8597da55ed54ac1b492f000efd29d8e4b3852716f05d158499825e890901bd66abece7c5ff753755cf46784a8905055c8843a2f0f423c56c70895e6f236c0
+  metadata.gz: 60d63e4986fc120337231c0ad4e0f1145947d6975e856fe61924c6760f3bb29c60218aafef65899015c19fb1a23241bf83558d81ca6b398a0b10fe7f5123d657
+  data.tar.gz: 6922159d7d31c6e77abc2c9e1cc3f4b7b3fc3f1990afc8c6d5c11303e9364ef940ee21f3428a4be577764a476fd5c931b8507be74e673abd9f7b94e3b504f588

data/.rspec

@@ -1,3 +1,4 @@
 --require spec_helper
 --format documentation
 --color
+--tty

data/.travis.yml

@@ -1,4 +1,11 @@
 language: ruby
 rvm:
-  - 2.2.2
+  - 2.1
+  - 2.2
+  - ruby-head
+  - jruby
+  - rbx-2
 before_install: gem install bundler -v 1.10.6
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/.yardopts

@@ -0,0 +1 @@
+--asset elabs-logo.png

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# CHANGELOG
+
+## 0.2.0
+
+- Raise an error if serializer is not given a block.
+- Add RailsHelpers.
+- Fix ArrayBuilder#collection taking a key parameter.
+
+## 0.1.0
+
+- Initial release.

data/Gemfile

@@ -1,4 +1,14 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-# Specify your gem's dependencies in serial.gemspec
 gemspec
+
+group :development do
+  platform :ruby do
+    gem "sqlite3"
+  end
+
+  platform :jruby do
+    gem "jdbc-sqlite3"
+    gem "activerecord-jdbcsqlite3-adapter"
+  end
+end

data/README.md

@@ -1,64 +1,148 @@
 # Serial
 
-Serial is a serialization library. Its primary purpose is to generate simple
-datastructures from object graphs.
+[![Build Status](https://travis-ci.org/elabs/serial.svg?branch=master)](http://travis-ci.org/elabs/serial)
+[![Dependency Status](https://gemnasium.com/elabs/serial.svg)](https://gemnasium.com/elabs/serial)
+[![Code Climate](https://codeclimate.com/github/elabs/serial/badges/gpa.svg)](https://codeclimate.com/github/elabs/serial)
+[![Gem Version](https://badge.fury.io/rb/serial.svg)](http://badge.fury.io/rb/serial)
+[![Inline docs](http://inch-ci.org/github/elabs/serial.svg?branch=master&style=shields)](http://inch-ci.org/github/elabs/serial)
 
+*Psst, full documentation can be found at [rubydoc.info/gems/serial](http://www.rubydoc.info/gems/serial)*
+
+Serial is a light-weight and simple serialization library. Its primary purpose is to generate primitive
+datastructures from object graphs, in other words to help you serialize your data.
+
+Serial is sponsored by [Elabs][].
+
+[![elabs logo][]][Elabs]
+
+[Elabs]: http://www.elabs.se/
+[elabs logo]: ./elabs-logo.png?raw=true
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'serial'
+gem "serial"
 ```
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## The DSL
 
-    $ gem install serial
+*Full reference: [Serial::HashBuilder](http://www.rubydoc.info/gems/serial/Serial/HashBuilder), [Serial::ArrayBuilder](http://www.rubydoc.info/gems/serial/Serial/ArrayBuilder).*
 
-## Usage
+- All keys are turned into strings.
+- There is no automatic camel-casing. You name your keys the way you want them.
 
-You can set up your serializers like this:
+### Simple attributes
 
 ``` ruby
-# app/serializers/person_serializer.rb
-PersonSerializer = Serializer.new do |h, person|
-  h.attribute(:id, person.id)
-  h.attribute(:name, person.name)
-end
-
-# app/serializers/project_serializer.rb
-ProjectSerializer = Serializer.new do |h, project|
+ProjectSerializer = Serial::Serializer.new do |h, project|
   h.attribute(:id, project.id)
-  h.attribute(:projectName, project.name)
-  h.attribute(:description, project.description)
+  h.attribute(:displayName, project.display_name)
+end # => { "id" => …, "displayName" => … }
+```
+
+### Nested attributes
 
-  h.attribute(:client, project.client) do |h, client|
-    h.attribute(:id, client.id)
-    h.attribute(:name, client.name)
+``` ruby
+ProjectSerializer = Serial::Serializer.new do |h, project|
+  h.attribute(:owner, project.owner) do |h, owner|
+    h.attribute(:name, owner.name)
   end
+end # => { "owner" => { "name" => … } }
+```
 
+### Collections
+
+`#map` is a convenient method for serializing lists of items.
+
+``` ruby
+ProjectSerializer = Serial::Serializer.new do |h, project|
   h.map(:assignments, project.assignments) do |h, assignment|
     h.attribute(:id, assignment.id)
     h.attribute(:duration, assignment.duration)
+  end
+end # => { "assignments" => [{ "id" => …, "duration" => … }, …] }
+```
 
-    # This is how you compose serializers.
-    h.attribute(:person, assignment.person, &PersonSerializer)
+The low-level interface powering `#map` is `#collection`.
+
+``` ruby
+ProjectSerializer = Serial::Serializer.new do |h, project|
+  h.collection(:indices) do |l|
+    l.element { |h| h.attribute(…)  }
+    l.element { |h| h.attribute(…)  }
+
+    l.collection do |l|
+      l.element { … }
+      l.element { … }
+    end
   end
+end # => { "indices" => [{…}, {…}, [{…}, {…}]] }
+```
+
+### Composition
+
+You can compose serializers by passing them as blocks to the DSL methods.
 
+``` ruby
+PersonSerializer = Serial::Serializer.new do |h, person|
+  h.attribute(:name, person.name)
+end # => { "name" => … }
+
+ProjectSerializer = Serial::Serializer.new do |h, project|
+  h.attribute(:owner, project.owner, &PersonSerializer)
   h.map(:people, project.people, &PersonSerializer)
-end
+end # { "owner" => { "name" => … }, "people" => [{ "name" => … }, …] }
+```
+
+## Using your serializers
+
+*Full reference: [Serial::Serializer](http://www.rubydoc.info/gems/serial/Serial/Serializer).*
+
+- The context parameter in the below examples (when using `#call` and `#map`) is optional, if not provided regular block scoping rules apply.
+- Tip: include [Serial::RailsHelpers](http://www.rubydoc.info/gems/serial/Serial/RailsHelpers) in ApplicationController for a convenient `#serialize` method.
+
+### Serializing a single object
+
+``` ruby
+project = Project.find(…)
+context = self
+ProjectSerializer.call(context, project) # => { … }
 ```
 
-Whenever you need to use them you invoke them like this:
+### Serializing a list of objects
 
 ``` ruby
-person = Person.find(1)
-render json: PersonSerializer.call(self, person)
+projects = Project.all
+context = self
+ProjectSerializer.map(context, projects) # => [{ … }, …]
+```
+
+### Using with Rails
+
+``` ruby
+# app/controllers/project_controller.rb
+class ProjectController < ApplicationController
+  include Serial::RailsHelpers
+
+  def show
+    project = Project.find(…)
+
+    # 1. Using helper from RailsHelpers.
+    render json: serialize(project)
+
+    # 2. Explicitly mentioning serializer using helper method.
+    render json: serialize(project, &ProjectSerializer)
+
+    # 3. Explicitly mentioning serializer.
+    render json: ProjectSerializer.call(self, project)
+  end
+end
 ```
 
 ## Development

data/Rakefile

@@ -1,6 +1,11 @@
+task :release => :spec # BEFORE bundler gem tasks.
+
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
+require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
+require "yard"
+YARD::Rake::YardocTask.new(:doc)
+
 task :default => :spec

data/bin/console

@@ -6,9 +6,5 @@ require "serial"
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start
+require "pry"
+Pry.start

data/lib/serial.rb

@@ -3,6 +3,8 @@ require "serial/serializer"
 require "serial/builder"
 require "serial/hash_builder"
 require "serial/array_builder"
+require "serial/rails_helpers"
 
+# Serial namespace. See {Serial::Serializer} for reference.
 module Serial
 end

data/lib/serial/array_builder.rb

@@ -1,18 +1,43 @@
 module Serial
-  # @api private
+  # A builder for building arrays. You most likely just want to look at the
+  # public API methods in this class.
   class ArrayBuilder < Builder
-    def initialize(context, &block)
+    # @api private
+    def initialize(context)
       @context = context
       @data = []
-      yield self
     end
 
+    # @api public
+    # Serializes a hash item in a collection.
+    #
+    # @example
+    #   h.collection(…) do |l|
+    #     l.element do |h|
+    #       h.attribute(…)
+    #     end
+    #   end
+    #
+    # @yield [builder]
+    # @yieldparam builder [HashBuilder]
     def element(&block)
-      @data << build(HashBuilder, &block)
+      @data << HashBuilder.build(@context, &block)
     end
 
-    def collection(key, &block)
-      @data << build(ArrayBuilder, &block)
+    # @api public
+    # Serializes a collection in a collection.
+    #
+    # @example
+    #   h.collection(…) do |l|
+    #     l.collection do |l|
+    #       l.element { … }
+    #     end
+    #   end
+    #
+    # @yield [builder]
+    # @yieldparam builder [ArrayBuilder]
+    def collection(&block)
+      @data << ArrayBuilder.build(@context, &block)
     end
   end
 end

data/lib/serial/builder.rb

@@ -1,12 +1,32 @@
 module Serial
   # @api private
+  #
+  # Builder contains common methods to the serializer DSL.
   class Builder
-    def self.build(context, &block)
-      new(context, &block).data
+    # Create the builder, execute the block inside it, and return its' data.
+    # Any superflous arguments are given to {#exec}.
+    #
+    # @param context [#instance_exec, nil] the context to execute block inside
+    # @yield (see #exec)
+    # @yieldparam (see #exec)
+    # @return [#data]
+    def self.build(context, *args, &block)
+      builder = new(context)
+      builder.exec(*args, &block)
+      builder.data
     end
 
+    # Builder data, depends on what kind of builder it is.
+    #
+    # @return [Array, Hash]
     attr_reader :data
 
+    # Executes a block in the configured context, if there is one, otherwise using regular closure scoping.
+    #
+    #
+    # @yield [self, *args]
+    # @yieldparam self [Builder] passes in self as the first parameter.
+    # @yieldparam *args superflous arguments are passed to the block.
     def exec(*args, &block)
       if @context
         @context.instance_exec(self, *args, &block)
@@ -14,11 +34,5 @@ module Serial
         block.call(self, *args)
       end
     end
-
-    def build(builder_klass, *args, &block)
-      builder_klass.build(@context) do |builder|
-        builder.exec(*args, &block)
-      end
-    end
   end
 end

data/lib/serial/hash_builder.rb

@@ -1,26 +1,79 @@
 module Serial
-  # @api private
+  # A builder for building hashes. You most likely just want to look at the
+  # public API methods in this class.
   class HashBuilder < Builder
-    def initialize(context, &block)
+    # @api private
+    def initialize(context)
       @context = context
       @data = {}
-      yield self
     end
 
+    # @api public
+    # Declare an attribute.
+    #
+    # @example without block
+    #   h.attribute(:id, 5) # => { "id" => 5 }
+    #
+    # @example nested attribute, with block
+    #   h.attribute(:project, project) do |h, project|
+    #     h.attribute(:name, project.name)
+    #   end # => { "project" => { "name" => … } }
+    #
+    # @param key [#to_s]
+    # @param value
+    # @yield [builder, value] declare nested attribute if block is given
+    # @yieldparam builder [HashBuilder] (keep in mind the examples shadow the outer `h` variable)
+    # @yieldparam value
     def attribute(key, value = nil, &block)
-      value = build(HashBuilder, value, &block) if block
+      value = HashBuilder.build(@context, value, &block) if block
       @data[key.to_s] = value
     end
 
+    # @api public
+    # Declare a collection attribute. This is a low-level method, see {#map} instead.
+    #
+    # @example
+    #   h.collection(:people) do |l|
+    #     l.element do |h|
+    #       h.attribute(…)
+    #     end
+    #     l.element do |h|
+    #       h.attribute(…)
+    #     end
+    #     l.collection do |l|
+    #       l.element do |h|
+    #         h.attribute(…)
+    #       end
+    #     end
+    #   end # => { "people" => [{…}, {…}, [{…}]] }
+    #
+    # @see ArrayBuilder
+    # @param key [#to_s]
+    # @yieldparam builder [ArrayBuilder]
     def collection(key, &block)
-      list = build(ArrayBuilder, &block)
-      attribute(key, list)
+      attribute(key, ArrayBuilder.build(@context, &block))
     end
 
+    # @api public
+    # Declare a collection attribute from a list of values.
+    #
+    # @example
+    #   h.map(:people, project.people) do |h, person|
+    #     h.attribute(:name, person.name)
+    #   end # => { "people" => [{ "name" => … }] }
+    #
+    # @see #collection
+    # @param key [#to_s]
+    # @param list [#each]
+    # @yield [builder, value] yields each value from list to build an array of hashes
+    # @yieldparam builder [HashBuilder]
+    # @yieldparam value
     def map(key, list, &block)
       collection(key) do |builder|
         list.each do |item|
-          builder.element { |element| element.exec(item, &block) }
+          builder.element do |element|
+            element.exec(item, &block)
+          end
         end
       end
     end

data/lib/serial/rails_helpers.rb

@@ -0,0 +1,31 @@
+module Serial
+  # Helpers for using Serial with Rails.
+  module RailsHelpers
+    # Find the serializer for `model` and serialize it in the context of self.
+    #
+    # @example serializing a single object
+    #   render json: { person: serialize(Person.first) }
+    #
+    # @example serializing multiple objects
+    #   render json: { people: serialize(Person.all) }
+    #
+    # @example serializing with explicit context
+    #   render json: { people: serialize(presenter, Person.all) }
+    #
+    # @example serializing with explicit serializer
+    #   render json: { people: serialize(Person.all, &my_serializer) }
+    #
+    # @param context [#instance_exec]
+    # @param model [#model_name, #each?]
+    def serialize(context = self, model, &serializer)
+      serializer &&= Serializer.new(&serializer)
+      serializer ||= "#{model.model_name}Serializer".constantize
+
+      if model.respond_to?(:map)
+        serializer.map(context, model)
+      else
+        serializer.call(context, model)
+      end
+    end
+  end
+end

data/lib/serial/serializer.rb

@@ -1,23 +1,111 @@
 module Serial
+  # Using this class you build serializers.
   class Serializer
+    # Create a new Serializer, using the block as instructions.
+    #
+    # @example
+    #   # app/serializers/person_serializer.rb
+    #   PersonSerializer = Serial::Serializer.new do |h, person|
+    #     h.attribute(:name, person.name)
+    #   end
+    #
+    # @yield [builder, value]
+    # @yieldparam builder [HashBuilder]
+    # @yieldparam value from {#call} or {#map}
     def initialize(&block)
+      unless block_given?
+        raise ArgumentError, "instructions (block) is required"
+      end
+
       @block = block
+      @to_proc = method(:to_proc_implementation).to_proc
+    end
+
+    # Serialize an object with this serializer, optionally within a context.
+    #
+    # @example with context, the serializer block is evaluated inside the context
+    #   # app/serializers/person_serializer.rb
+    #   PersonSerializer = Serial::Serializer.new do |h, person|
+    #     h.attribute(:id, person.id)
+    #     h.attribute(:url, people_url(person))
+    #   end
+    #
+    #   # app/controllers/person_controller.rb
+    #   def show
+    #     person = Person.find(…)
+    #     render json: PersonSerializer.call(self, person)
+    #   end
+    #
+    # @example without context, the serializer block is evaluated using normal closure rules
+    #   # app/models/person.rb
+    #   class Person
+    #     Serializer = Serial::Serializer.new do |h, person|
+    #       h.attribute(:id, person.id)
+    #       h.attribute(:available_roles, available_roles)
+    #     end
+    #
+    #     def self.available_roles
+    #       …
+    #     end
+    #   end
+    #
+    #   # app/controllers/person_controller.rb
+    #   def show
+    #     person = Person.find(…)
+    #     render json: Person::Serializer.call(person)
+    #   end
+    #
+    # @param context [#instance_exec, nil] context to execute serializer in, or nil to use regular block closure rules.
+    # @param value
+    # @return [Hash]
+    def call(context = nil, value)
+      HashBuilder.build(context, value, &@block)
     end
 
+    # Serialize a list of objects with this serializer, optionally within a context.
+    #
+    # @example
+    #   # app/serializers/person_serializer.rb
+    #   PersonSerializer = Serial::Serializer.new do |h, person|
+    #     h.attribute(:id, person.id)
+    #     h.attribute(:url, people_url(person))
+    #   end
+    #
+    #   # app/controllers/person_controller.rb
+    #   def index
+    #     people = Person.all
+    #     render json: PersonSerializer.map(self, people)
+    #   end
+    #
+    # @see #call see #call for an explanation of the context parameter
+    # @param context (see #call)
+    # @param list [#map]
+    # @return [Array<Hash>]
     def map(context = nil, list)
       list.map { |item| call(context, item) }
     end
 
-    def call(context = nil, value)
-      block = @block
-      HashBuilder.build(context) do |builder|
-        builder.exec(value, &block)
-      end
-    end
+    # Serializer composition!
+    #
+    # @example
+    #   # app/serializers/person_serializer.rb
+    #   PersonSerializer = Serial::Serializer.new do |h, person|
+    #     h.attribute(:name, person.name)
+    #   end
+    #
+    #   # app/serializers/project_serializer.rb
+    #   ProjectSerializer = Serial::Serializer.new do |h, project|
+    #     h.attribute(:owner, project.owner, &PersonSerializer)
+    #     h.map(:people, project.people, &PersonSerializer)
+    #   end
+    #
+    # @return [Proc]
+    attr_reader :to_proc
+
+    private
 
-    def to_proc
-      block = @block
-      proc { |builder, value| builder.exec(value, &block) }
+    def to_proc_implementation(builder, *args)
+      builder.exec(*args, &@block)
     end
   end
 end

data/lib/serial/version.rb

@@ -1,3 +1,4 @@
 module Serial
-  VERSION = "0.1.1"
+  # Gem version, uses SemVer.
+  VERSION = "0.2.0"
 end

data/serial.gemspec

@@ -6,11 +6,11 @@ require 'serial/version'
 Gem::Specification.new do |spec|
   spec.name          = "serial"
   spec.version       = Serial::VERSION
-  spec.authors       = ["Jonas Nicklas", "Kim Burgestrand"]
-  spec.email         = ["jonas@elabs.se", "kim@elabs.se"]
+  spec.authors       = ["Elabs", "Jonas Nicklas", "Kim Burgestrand"]
+  spec.email         = ["dev@elabs.se", "jonas@elabs.se", "kim@elabs.se"]
   spec.license       = "MIT"
 
-  spec.summary       = %q{Plain old Ruby for generating simple data structures from object graphs.}
+  spec.summary       = %q{Plain old Ruby for generating primitive data structures from object graphs.}
   spec.homepage      = "https://github.com/elabs/serial"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -19,7 +19,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "pry", "~> 0.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.2"
   spec.add_development_dependency "yard", "~> 0.8"
+  spec.add_development_dependency "activerecord", "~> 4.0"
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: serial
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
+- Elabs
 - Jonas Nicklas
 - Kim Burgestrand
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-01 00:00:00.000000000 Z
+date: 2015-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -25,6 +26,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -67,8 +82,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: 
 email:
+- dev@elabs.se
 - jonas@elabs.se
 - kim@elabs.se
 executables: []
@@ -78,15 +108,19 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
+- elabs-logo.png
 - lib/serial.rb
 - lib/serial/array_builder.rb
 - lib/serial/builder.rb
 - lib/serial/hash_builder.rb
+- lib/serial/rails_helpers.rb
 - lib/serial/serializer.rb
 - lib/serial/version.rb
 - serial.gemspec
@@ -113,6 +147,6 @@ rubyforge_project:
 rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
-summary: Plain old Ruby for generating simple data structures from object graphs.
+summary: Plain old Ruby for generating primitive data structures from object graphs.
 test_files: []
 has_rdoc: