blueprinter 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 7305adc0699ba1c10026b7dbfc2de138d85b7e05f19de91d70fd10069bf274b1
-  data.tar.gz: a15a1d19a578a472c3cc91228070ff32441137e57b241571578e72ba89a5f892
+SHA1:
+  metadata.gz: 4f911f54c6fe83cbebf48847eee6b7b596931689
+  data.tar.gz: afe0b665b414c0b6fa9d86e853a2c94030318bed
 SHA512:
-  metadata.gz: f93a3442dd563f3f929e8d1964a320823819a2ef8bc4aa292751caa35bd33c2dfe74716e49f38bf856d594ebe12251fa4ca0f9ecde01ea7fe2a564f3c9e2a375
-  data.tar.gz: 3ffea695ddd219bd1ec1721853c9a519159d883c31259545440511b8700b82dddc1b9e55595cd886c808f2b09aacf9e47f41e6b65efd7f8034b512c3576d0061
+  metadata.gz: 8e41f7b0dccca6fd0640b2468edff7606d3afe23a08de4968f88e90ec6315eb8d99a89d756da5228330d2dc9f44e6c840adebf825d853fa94828e21e0521b345
+  data.tar.gz: 60e2e16868012f1e8956baf46ae7d9f5aba743c94fcde224d6d3d985f6ae355fca4a5512ebedf48e2226724a8ef0ee7338cfeb43c5715772b801e2b371c78a99

data/CHANGELOG.md

@@ -1,24 +1,34 @@
-## 0.7.0  - 2018/10/17
+## 0.8.0  - 2018/11/19
+
+* [FEATURE] Extend Support for other JSON encoders like yajl-ruby. Please see pr [#118](https://github.com/procore/blueprinter/pull/118). Thanks to [@ritikesh](https://github.com/ritikesh).
+* [BUGFIX] Do not raise error on null date with `date_format` option. Please see pr [#117](https://github.com/procore/blueprinter/pull/117). Thanks to [@tpltn](https://github.com/tpltn).
+* [FEATURE] Add `default` option to `field`s which will be used as the serialized value instead of `null` when the field evaluates to null. Please see pr [#115](https://github.com/procore/blueprinter/pull/115). Thanks to [@mcclayton](https://github.com/mcclayton).
+* [BUGFIX] Made Base.associations completely private since they are not used outside of the Blueprinter base. Please see pr [#112](https://github.com/procore/blueprinter/pull/112). Thanks to [@philipqnguyen](https://github.com/philipqnguyen).
+* [BUGFIX] Fix issue where entire Blueprinter module was marked api private. Please see pr [#111](https://github.com/procore/blueprinter/pull/111). Thanks to [@philipqnguyen](https://github.com/philipqnguyen).
+* [FEATURE] Allow identifiers to be defined with a block. Please see pr [#110](https://github.com/procore/blueprinter/pull/110). Thanks to [@hugopeixoto](https://github.com/hugopeixoto).
+* [ENHANCEMENT] Update docs regarding the args yielded to blocks. Please see pr [#108](https://github.com/procore/blueprinter/pull/108). Thanks to [@philipqnguyen](https://github.com/philipqnguyen).
+* [ENHANCEMENT] Use `field` method in fields. Please see pr [#107](https://github.com/procore/blueprinter/pull/107). Thanks to [@hugopeixoto](https://github.com/hugopeixoto).
 
-* [FEATURE] Allow associations to be defined with a block. Please see pr #106. Thanks to @hugopeixoto.
-* [FEATURE] Inherit view definition when using inheritance. Please see pr #105. Thanks to @hugopeixoto.
+## 0.7.0  - 2018/10/17
 
+* [FEATURE] Allow associations to be defined with a block. Please see pr [#106](https://github.com/procore/blueprinter/pull/106). Thanks to [@hugopeixoto](https://github.com/hugopeixoto).
+* [FEATURE] Inherit view definition when using inheritance. Please see pr [#105](https://github.com/procore/blueprinter/pull/105). Thanks to [@hugopeixoto](https://github.com/hugopeixoto).
 
 ## 0.6.0  - 2018/06/05
 
-* [FEATURE] Add `date_time` format as an option to `field`. Please see pr #68. Thanks to @njbbaer.
-* [FEATURE] Add conditional field support `:unless` and `:if` as an option to `field`. Please see pr #86. Thanks to @ojab.
-* [BUGFIX] Fix case where miscellaneous options were not being passed through the `AutoExtractor`. See pr #83.
+* [FEATURE] Add `date_time` format as an option to `field`. Please see pr #68. Thanks to [@njbbaer](https://github.com/njbbaer).
+* [FEATURE] Add conditional field support `:unless` and `:if` as an option to `field`. Please see pr [#86](https://github.com/procore/blueprinter/pull/86). Thanks to [@ojab](https://github.com/ojab).
+* [BUGFIX] Fix case where miscellaneous options were not being passed through the `AutoExtractor`. See pr [#83](https://github.com/procore/blueprinter/pull/83).
 
 ## 0.5.0  - 2018/05/15
 
 * [FEATURE] Add `default` option to `association` which will be used as the serialized value instead of `null` when the association evaluates to null.
-See PR #78 by @vinaya-procore.
+See PR [#78](https://github.com/procore/blueprinter/pull/78) by [@vinaya-procore](https://github.com/vinaya-procore).
 
 ## 0.4.0  - 2018/05/02
 
 * [FEATURE] Add `render_as_hash` which will output a hash instead of
-a JSON String. See PR #76 by @amayer171 and Issue #73.
+a JSON String. See PR [#76](https://github.com/procore/blueprinter/pull/76) by [@amayer171](https://github.com/amayer171) and Issue [#73](https://github.com/procore/blueprinter/issues/73).
 
 ## 0.3.0  - 2018/04/05
 
@@ -35,7 +45,7 @@ field(:first_name, extractor: CustomExtractor)
 ```
 
 * [ENHANCEMENT] Renamed Serializer classes to Extractor. See #72.
-* [ENHANCEMENT] Updated README. See #66, #65
+* [ENHANCEMENT] Updated README. See pr [#66](https://github.com/procore/blueprinter/pull/66), [#65](https://github.com/procore/blueprinter/pull/65)
 
 ## 0.2.0  - 2018/01/22
 
@@ -44,8 +54,8 @@ Breaking Changes. To upgrade, ensure that any associated objects have a blueprin
 association :comments, blueprint: CommentsBlueprint
 ```
 
-* [BUGFIX] Remove Optimizer class. See #61.
-* [BUGFIX] Require associated objects to have a Blueprint, so that objects will always serialize properly. See #60.
+* [BUGFIX] Remove Optimizer class. See [#61](https://github.com/procore/blueprinter/pull/61).
+* [BUGFIX] Require associated objects to have a Blueprint, so that objects will always serialize properly. See [#60](https://github.com/procore/blueprinter/pull/60).
 
 ## 0.1.0  - 2018/01/17
 

data/README.md

@@ -144,15 +144,15 @@ Output:
 }
 ```
 
-#### Default option
-By default, an association that evaluates to `nil` is serialized as `nil`. A default serialized value can be
-specified as option on the association for cases when the association could potentially evaluate to `nil`.
+### Default Association/Field Option
+By default, an association or field that evaluates to `nil` is serialized as `nil`. A default serialized value can be
+specified as option on the association or field for cases when the association/field could potentially evaluate to `nil`.
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
 
   view :normal do
-    fields :first_name, :last_name
+    field :first_name, default: "N/A"
     association :company, blueprint: CompanyBlueprint, default: {}
   end
 end
@@ -160,13 +160,13 @@ end
 
 ### Defining a field directly in the Blueprint
 
-You can define a field directly in the Blueprint by passing it a block. This is especially useful if the object does not already have such an attribute or method defined, and you want to define it specifically for use with the Blueprint. For example:
+You can define a field directly in the Blueprint by passing it a block. This is especially useful if the object does not already have such an attribute or method defined, and you want to define it specifically for use with the Blueprint. This is done by passing `field` a block. The block also yields the object and any options that were passed from `render`. For example:
 
 ```ruby
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
-  field :full_name do |user|
-    "#{user.first_name} #{user.last_name}"
+  field :full_name do |user, options|
+    "#{options[:title_prefix]} #{user.first_name} #{user.last_name}"
   end
 end
 ```
@@ -174,7 +174,34 @@ end
 Usage:
 
 ```ruby
-puts UserBlueprint.render(user)
+puts UserBlueprint.render(user, title_prefix: "Mr")
+```
+
+Output:
+
+```json
+{
+  "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
+  "full_name": "Mr John Doe"
+}
+```
+
+#### Defining an identifier directly in the Blueprint
+
+You can also pass a block to an identifier:
+
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :uuid do |user, options|
+    options[:current_user].anonymize(user.uuid)
+  end
+end
+```
+
+Usage:
+
+```ruby
+puts UserBlueprint.render(user, current_user: current_user)
 ```
 
 Output:
@@ -182,7 +209,6 @@ Output:
 ```json
 {
   "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
-  "full_name": "John Doe"
 }
 ```
 
@@ -199,8 +225,8 @@ end
 class UserBlueprint < Blueprinter::Base
   identifier :uuid
 
-  association :projects, blueprint: ProjectBlueprint do |user|
-    user.projects + user.company.projects
+  association :projects, blueprint: ProjectBlueprint do |user, options|
+    user.projects + options[:draft_projects]
   end
 end
 ```
@@ -208,7 +234,7 @@ end
 Usage:
 
 ```ruby
-puts UserBlueprint.render(user)
+puts UserBlueprint.render(user, draft_projects: Project.where(draft: true))
 ```
 
 Output:
@@ -321,6 +347,21 @@ Ensure that you have the `Oj` gem installed in your Gemfile if you haven't alrea
 gem 'oj'
 ```
 
+## Yajl-ruby
+
+[yajl-ruby](https://github.com/brianmario/yajl-ruby) is a fast and powerful JSON generator/parser. To use `yajl-ruby` in place of `JSON / OJ`, use:
+
+```ruby
+require 'yajl' # you can skip this if OJ has already been required.
+
+Blueprinter.configure do |config|
+  config.generator = Yajl::Encoder # default is JSON
+  config.method = :encode # default is generate
+end
+```
+
+##### Note: You should be doing this only if you aren't using `yajl-ruby` through the JSON API by requiring `yajl/json_gem`. More details [here](https://github.com/brianmario/yajl-ruby#json-gem-compatibility-api). In this case, `JSON.generate` is patched to use `Yajl::Encoder.encode` internally.
+
 ## How to Document
 
 We use [Yard](https://yardoc.org/) for documentation. Here are the following

data/lib/blueprinter/base.rb

@@ -26,6 +26,9 @@ module Blueprinter
     # @param name [Symbol] to rename the identifier key in the JSON
     #   output. Defaults to method given.
     # @param extractor [AssociationExtractor,AutoExtractor,BlockExtractor,HashExtractor,PublicSendExtractor]
+    # @yield [object, options] The object and the options passed to render are
+    #   also yielded to the block.
+    #
     #   Kind of extractor to use.
     #   Either define your own or use Blueprinter's premade extractors.
     #   Defaults to AutoExtractor
@@ -36,13 +39,22 @@ module Blueprinter
     #     # other code
     #   end
     #
+    # @example Passing a block to be evaluated as the value.
+    #   class UserBlueprint < Blueprinter::Base
+    #     identifier :uuid do |user, options|
+    #       options[:current_user].anonymize(user.uuid)
+    #     end
+    #   end
+    #
     # @return [Field] A Field object
-    def self.identifier(method, name: method, extractor: AutoExtractor.new)
-      view_collection[:identifier] << Field.new(method, name, extractor, self)
-    end
-
-    def self.inherited(subclass)
-      subclass.send(:view_collection).inherit(view_collection)
+    def self.identifier(method, name: method, extractor: AutoExtractor.new, &block)
+      view_collection[:identifier] << Field.new(
+        method,
+        name,
+        extractor,
+        self,
+        block: block,
+      )
     end
 
     # Specify a field or method name to be included for serialization.
@@ -68,8 +80,8 @@ module Blueprinter
     #   to call to determine if the field should be included (e.g.
     #   `unless: :include_first_name?, or unless: Proc.new { |user, options| options[:current_user] != user }).
     #   The method, proc or string should return or evaluate to a true or false value.
-    # @yield [Object] The object passed to `render` is also passed to the
-    #   block.
+    # @yield [object, options] The object and the options passed to render are
+    #   also yielded to the block.
     #
     # @example Specifying a user's first_name to be serialized.
     #   class UserBlueprint < Blueprinter::Base
@@ -79,7 +91,9 @@ module Blueprinter
     #
     # @example Passing a block to be evaluated as the value.
     #   class UserBlueprint < Blueprinter::Base
-    #     field :full_name {|obj| "#{obj.first_name} #{obj.last_name}"}
+    #     field :full_name do |object, options|
+    #       "options[:title_prefix] #{object.first_name} #{object.last_name}"
+    #     end
     #     # other code
     #   end
     #
@@ -96,16 +110,13 @@ module Blueprinter
     #
     # @return [Field] A Field object
     def self.field(method, options = {}, &block)
-      options = if block_given?
-        {name: method, extractor: BlockExtractor.new, block: block}
-      else
-        {name: method, extractor: AutoExtractor.new}
-      end.merge(options)
-      current_view << Field.new(method,
-                                options[:name],
-                                options[:extractor],
-                                self,
-                                options)
+      current_view << Field.new(
+        method,
+        options.fetch(:name) { method },
+        options.fetch(:extractor) { AutoExtractor.new },
+        self,
+        options.merge(block: block),
+      )
     end
 
     # Specify an associated object to be included for serialization.
@@ -119,8 +130,8 @@ module Blueprinter
     #   JSON output.
     # @option options [Symbol] :view Specify the view to use or fall back to
     #   to the :default view.
-    # @yield [Object] The object passed to `render` is also passed to the
-    #   block.
+    # @yield [object, options] The object and the options passed to render are
+    #   also yielded to the block.
     #
     # @example Specifying an association
     #   class UserBlueprint < Blueprinter::Base
@@ -131,27 +142,20 @@ module Blueprinter
     #
     # @example Passing a block to be evaluated as the value.
     #   class UserBlueprint < Blueprinter::Base
-    #     association :vehicles, blueprint: VehiclesBlueprint do |user|
-    #       user.vehicles + user.company.vehicles
+    #     association :vehicles, blueprint: VehiclesBlueprint do |user, opts|
+    #       user.vehicles + opts[:additional_vehicles]
     #     end
     #   end
     #
     # @return [Field] A Field object
     def self.association(method, options = {}, &block)
       raise BlueprinterError, 'blueprint required' unless options[:blueprint]
-      name = options.delete(:name) || method
-
-      options = if block_given?
-        options.merge(extractor: BlockExtractor.new, block: block)
-      else
-        options.merge(extractor: AutoExtractor.new)
-      end
 
-      current_view << Field.new(method,
-                                name,
-                                AssociationExtractor.new,
-                                self,
-                                options.merge(association: true))
+      field(
+        method,
+        options.merge(association: true, extractor: AssociationExtractor.new),
+        &block
+      )
     end
 
     # Generates a JSON formatted String.
@@ -240,11 +244,6 @@ module Blueprinter
       end
     end
 
-    # @api private
-    def self.associations(view_name = :default)
-      view_collection.fields_for(view_name).select { |f| f.options[:association] }
-    end
-
     # Specify another view that should be mixed into the current view.
     #
     # @param view_name [Symbol] the view to mix into the current view.
@@ -311,6 +310,11 @@ module Blueprinter
 
     private
 
+    def self.inherited(subclass)
+      subclass.send(:view_collection).inherit(view_collection)
+    end
+    private_class_method :inherited
+
     def self.object_to_hash(object, view_name:, local_options:)
       view_collection.fields_for(view_name).each_with_object({}) do |field, hash|
         next if field.skip?(object, local_options)
@@ -338,7 +342,7 @@ module Blueprinter
     private_class_method :include_associations
 
     def self.jsonify(blob)
-      Blueprinter.configuration.generator.generate(blob)
+      Blueprinter.configuration.jsonify(blob)
     end
     private_class_method :jsonify
 
@@ -356,5 +360,10 @@ module Blueprinter
       object.is_a?(Array) || active_record_relation?(object)
     end
     private_class_method :array_like?
+
+    def self.associations(view_name = :default)
+      view_collection.fields_for(view_name).select { |f| f.options[:association] }
+    end
+    private_class_method :associations
   end
 end

data/lib/blueprinter/configuration.rb

@@ -1,9 +1,14 @@
 module Blueprinter
   class Configuration
-    attr_accessor :generator
+    attr_accessor :generator, :method
 
     def initialize
       @generator = JSON
+      @method = :generate
+    end
+
+    def jsonify(blob)
+      generator.public_send(method, blob)
     end
   end
 

data/lib/blueprinter/extractor.rb

@@ -1,5 +1,5 @@
-# @api private
 module Blueprinter
+  # @api private
   class Extractor
     def extract(field_name, object, local_options, options={})
       fail NotImplementedError, "An Extractor must implement #extract"

data/lib/blueprinter/extractors/association_extractor.rb

@@ -1,7 +1,11 @@
 module Blueprinter
   class AssociationExtractor < Extractor
+    def initialize
+      @extractor = AutoExtractor.new
+    end
+
     def extract(association_name, object, local_options, options={})
-      value = options[:extractor].extract(association_name, object, local_options, options)
+      value = @extractor.extract(association_name, object, local_options, options.except(:default))
       return options[:default] if value.nil?
       view = options[:view] || :default
       options[:blueprint].prepare(value, view_name: view, local_options: local_options)

data/lib/blueprinter/extractors/auto_extractor.rb

@@ -3,17 +3,29 @@ module Blueprinter
     def initialize
       @hash_extractor = HashExtractor.new
       @public_send_extractor = PublicSendExtractor.new
+      @block_extractor = BlockExtractor.new
     end
 
     def extract(field_name, object, local_options, options = {})
-      extractor = object.is_a?(Hash) ? @hash_extractor : @public_send_extractor
-      extraction = extractor.extract(field_name, object, local_options, options)
-      options.key?(:datetime_format) ? format_datetime(extraction, options[:datetime_format]) : extraction
+      extraction = extractor(object, options).extract(field_name, object, local_options, options)
+      value = options.key?(:datetime_format) ? format_datetime(extraction, options[:datetime_format]) : extraction
+      value.nil? ? options[:default] : value
     end
 
     private
 
+    def extractor(object, options)
+      if options[:block]
+        @block_extractor
+      elsif object.is_a?(Hash)
+        @hash_extractor
+      else
+        @public_send_extractor
+      end
+    end
+
     def format_datetime(datetime, format)
+      return nil if datetime.nil?
       datetime.strftime(format)
     rescue NoMethodError
       raise BlueprinterError, 'Cannot format invalid DateTime object'

data/lib/blueprinter/version.rb

@@ -1,3 +1,3 @@
 module Blueprinter
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Adam Hess
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-17 00:00:00.000000000 Z
+date: 2018-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: factory_bot
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.1
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -187,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Simple Fast Declarative Serialization Library