serial 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29eb0ebd62982d93650098a3f2f4f54f11879bf3
-  data.tar.gz: 6d516f85165f6a46f767925a48c4d40d5a0cb1c9
+  metadata.gz: bfac09f4727b81d0b72935e00e38a5584f1203cf
+  data.tar.gz: aab5f90c21fa6356fda1c115b9e2a93cb71d694a
 SHA512:
-  metadata.gz: 60d63e4986fc120337231c0ad4e0f1145947d6975e856fe61924c6760f3bb29c60218aafef65899015c19fb1a23241bf83558d81ca6b398a0b10fe7f5123d657
-  data.tar.gz: 6922159d7d31c6e77abc2c9e1cc3f4b7b3fc3f1990afc8c6d5c11303e9364ef940ee21f3428a4be577764a476fd5c931b8507be74e673abd9f7b94e3b504f588
+  metadata.gz: 6e675f5cb4da83f143bec4fd7706e05a1267e35039e01192ed9268a44a7298dfe7807b3ef60047178b54079be4b92c252a71607ea8045f907d9b5dc2edd86eba
+  data.tar.gz: 8916083402ec5d799da188484c999bdaaf496def62156362f12b06c824f66c05e75ef1e857bd9cfac0e398220139b2293d06309c8d7523f520f4a4e75c6746f0

data/.yardopts

@@ -1 +1,2 @@
 --asset elabs-logo.png
+--files CODE_OF_CONDUCT.md,CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 1.0.0
+
+- Add HashBuilder#merge. [cb11a3c5]
+- Raise an error by default if a key already exists in HashBuilder. [4b46db57]
+
 ## 0.2.0
 
 - Raise an error if serializer is not given a block.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all
+people who contribute through reporting issues, posting feature requests,
+updating documentation, submitting pull requests or patches, and other
+activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual
+language or imagery, derogatory comments or personal attacks, trolling, public
+or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct. Project maintainers who do not
+follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting one or more of the project
+maintainers.
+
+This Code of Conduct is adapted from the [Contributor
+Covenant](http:contributor-covenant.org), version 1.0.0, available at
+[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/README.md

@@ -36,9 +36,13 @@ And then execute:
 
 - All keys are turned into strings.
 - There is no automatic camel-casing. You name your keys the way you want them.
+- Using the same key twice will raise an error by default.
+- To override the value for an existing key, use the respective !-method DSL, i.e. `#attribute!`, `#collection!`, `#map!`, or `#merge!`.
 
 ### Simple attributes
 
+`#attribute` creates a simple attribute with a value.
+
 ``` ruby
 ProjectSerializer = Serial::Serializer.new do |h, project|
   h.attribute(:id, project.id)
@@ -48,6 +52,8 @@ end # => { "id" => …, "displayName" => … }
 
 ### Nested attributes
 
+`#attribute` supports nesting by giving it a block.
+
 ``` ruby
 ProjectSerializer = Serial::Serializer.new do |h, project|
   h.attribute(:owner, project.owner) do |h, owner|
@@ -85,6 +91,21 @@ ProjectSerializer = Serial::Serializer.new do |h, project|
 end # => { "indices" => [{…}, {…}, [{…}, {…}]] }
 ```
 
+### Merging
+
+`#merge` will let you merge another serializer without introducing a new nesting level.
+
+``` ruby
+ProjectSerializer = Serial::Serializer.new do |h, project|
+  h.attribute(:name, project.name)
+end # => { "name" => … }
+
+FullProjectSerializer = Serial::Serializer.new do |h, project|
+  h.merge(project, &ProjectSerializer)
+  h.attribute(:description, project.description)
+end # { "name" => …, "description" => … }
+```
+
 ### Composition
 
 You can compose serializers by passing them as blocks to the DSL methods.
@@ -125,6 +146,13 @@ ProjectSerializer.map(context, projects) # => [{ … }, …]
 
 ### Using with Rails
 
+```ruby
+# app/serializers/project_serializer.rb
+ProjectSerializer = Serial::Serializer.new do |h, project|
+  …
+end
+```
+
 ``` ruby
 # app/controllers/project_controller.rb
 class ProjectController < ApplicationController
@@ -161,7 +189,7 @@ git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygem
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/elabs/serial. This project is intended to be a safe,
 welcoming space for collaboration, and contributors are expected to adhere to
-the [Contributor Covenant](contributor-covenant.org) code of conduct.
+the [Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct.
 
 ## License
 

data/lib/serial.rb

@@ -7,4 +7,11 @@ require "serial/rails_helpers"
 
 # Serial namespace. See {Serial::Serializer} for reference.
 module Serial
+  # All serial-specific errors inherit from this error.
+  class Error < StandardError
+  end
+
+  # Raised when an already-defined key is defined again.
+  class DuplicateKeyError < StandardError
+  end
 end

data/lib/serial/builder.rb

@@ -30,8 +30,10 @@ module Serial
     def exec(*args, &block)
       if @context
         @context.instance_exec(self, *args, &block)
-      else
+      elsif block
         block.call(self, *args)
+      else
+        raise ArgumentError, "no serializer block given"
       end
     end
   end

data/lib/serial/hash_builder.rb

@@ -24,7 +24,20 @@ module Serial
     # @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
+    # @raise [DuplicateKeyError] if the same key has already been defined.
     def attribute(key, value = nil, &block)
+      check_duplicate_key!(key)
+      attribute!(key, value, &block)
+    end
+
+    # @api public
+    # Same as {#attribute}, but will not raise an error on duplicate keys.
+    #
+    # @see #attribute
+    # @param (see #attribute)
+    # @yield (see #attribute)
+    # @yieldparam (see #attribute)
+    def attribute!(key, value = nil, &block)
       value = HashBuilder.build(@context, value, &block) if block
       @data[key.to_s] = value
     end
@@ -49,9 +62,22 @@ module Serial
     #
     # @see ArrayBuilder
     # @param key [#to_s]
+    # @yield [builder]
     # @yieldparam builder [ArrayBuilder]
     def collection(key, &block)
-      attribute(key, ArrayBuilder.build(@context, &block))
+      check_duplicate_key!(key)
+      collection!(key, &block)
+    end
+
+    # @api public
+    # Same as {#collection}, but will not raise an error on duplicate keys.
+    #
+    # @see #collection
+    # @param (see #collection)
+    # @yield (see #collection)
+    # @yieldparam (see #collection)
+    def collection!(key, &block)
+      attribute!(key, ArrayBuilder.build(@context, &block))
     end
 
     # @api public
@@ -69,7 +95,19 @@ module Serial
     # @yieldparam builder [HashBuilder]
     # @yieldparam value
     def map(key, list, &block)
-      collection(key) do |builder|
+      check_duplicate_key!(key)
+      map!(key, list, &block)
+    end
+
+    # @api public
+    # Same as {#map}, but will not raise an error on duplicate keys.
+    #
+    # @see #map
+    # @param (see #map)
+    # @yield (see #map)
+    # @yieldparam (see #map)
+    def map!(key, list, &block)
+      collection!(key) do |builder|
         list.each do |item|
           builder.element do |element|
             element.exec(item, &block)
@@ -77,5 +115,48 @@ module Serial
         end
       end
     end
+
+    # @api public
+    # Merge another serializer into the current serialization.
+    #
+    # @example
+    #   ExtendedProjectSerializer = Serial::Serializer.new do |h, project|
+    #     h.merge(project, &ProjectSerializer)
+    #     h.attribute(:extra, project.extra_info)
+    #   end # => { "name" => …, …, "extra" => … }
+    #
+    # @param value
+    # @yield [builder, value] to another serializer
+    # @yieldparam builder [HashBuilder]
+    # @yieldparam value
+    # @raise [DuplicateKeyError] if a key to be merged is already defined.
+    def merge(value, &serializer)
+      hash = HashBuilder.build(@context, value, &serializer)
+      hash.keys.each { |key| check_duplicate_key!(key) }
+      @data.merge!(hash)
+    end
+
+    # @api public
+    # Same as {#merge}, but will not raise an error on duplicate keys.
+    #
+    # @see #merge
+    # @param (see #merge)
+    # @yield (see #merge)
+    # @yieldparam (see #merge)
+    def merge!(value, &serializer)
+      hash = HashBuilder.build(@context, value, &serializer)
+      @data.merge!(hash)
+    end
+
+    private
+
+    # @param key [#to_s]
+    # @raise [DuplicateKeyError] if key is defined
+    # @return [nil]
+    def check_duplicate_key!(key)
+      if @data.has_key?(key.to_s)
+        raise DuplicateKeyError, "'#{key}' is already defined"
+      end
+    end
   end
 end

data/lib/serial/rails_helpers.rb

@@ -1,6 +1,7 @@
 module Serial
   # Helpers for using Serial with Rails.
   module RailsHelpers
+    # @api public
     # Find the serializer for `model` and serialize it in the context of self.
     #
     # @example serializing a single object
@@ -17,6 +18,8 @@ module Serial
     #
     # @param context [#instance_exec]
     # @param model [#model_name, #each?]
+    # @yield [builder, model] yields if a block is given to use a custom serializer
+    # @yieldparam builder [HashBuilder]
     def serialize(context = self, model, &serializer)
       serializer &&= Serializer.new(&serializer)
       serializer ||= "#{model.model_name}Serializer".constantize

data/lib/serial/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serial
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Elabs
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-18 00:00:00.000000000 Z
+date: 2015-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,6 +110,7 @@ files:
 - ".travis.yml"
 - ".yardopts"
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - Gemfile
 - README.md
 - Rakefile