jsonity 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7837ec79aa7e71a84da9f8fda957c0217bd2691b
-  data.tar.gz: 26ad97f8e6d9b9dcd3dad8c0155eab31a80c8d6b
+  metadata.gz: b5e0cbbf0655194ed77a8e96424d290e700cc6a6
+  data.tar.gz: c26576875dc473fd201e7f8ccd21940a642da05f
 SHA512:
-  metadata.gz: e7535b1ce03cb5c6cb877aaf91fa0676f93eda13bc706db8ddeb5169bc443853f0112893dcd2cc20d5a60264d2226231a9b83dca599e86815cb75f37c5e64208
-  data.tar.gz: 7b7cff2ba3ece3d3a5be9a9eb002ce8ebdc9c534537120cbc74736be1079b999621a9b90893c5c231fe5b0c999c33eb435196fa2a849bf8b9f604651059ca268
+  metadata.gz: 305a32a835c2695991915d9e35899c5080ec3c624dffd63eb54c4760d9107b0390c8c6fd43b10cf86e5135cf0ceca19b1996ac763dfc11d250c34c77af3a6c0b
+  data.tar.gz: 4ef7f0f1a7c647255cff9f469ef35f0a7027510f5bdb1e9764fe8e6964ab6b20d142d4d7bd0db4fb792ea4c8c7b7dabe56ed87058c1e7d57c0b16d088765b712

data/README.md

@@ -1,24 +1,45 @@
 Jsonity
 =======
 
-**The most natural language for building JSON in Ruby**
+**The most sexy language for building JSON in Ruby**
+
+I'd been writing JSON API with [Jbuilder](https://github.com/rails/jbuilder), [RABL](https://github.com/nesquena/rabl) and [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers), but nothing of them meet my requirement and use case.
+
+- Jbuilder is very verbose in syntax, and its functonalities of partial and mixin are actually weak
+- RABL has simple syntax, but writing complex data structure with it is not very readable
+- ActiveModel::Serializer is persuasive role in Rails architecture, but can get very useless when you need to fully control from controller what attributes of nested (associated) object to be included
+
+So I chose to create new one -- Jsonity, which is simple and powerful JSON builder especially for JSON API representations.
+
+- Simple and readable syntax even if it gets complex
+- Flexible and arbitrary nodes
+- Includable mixin
+- Declarative attributes inclusion
+
+
+Installation
+------------
+
+Make sure to add the gem to your Gemfile.
+
+```ruby
+gem 'jsonity'
+```
 
 
 Overview
 --------
 
 ```ruby
-@meta_pagination = ->(t) {
-  t.meta!(inherit: true) { |meta|
+@meta_pagination_mixin = ->(t) {
+  t.meta! { |meta|
     meta.total_pages
     meta.current_page
   }
 }
 
 Jsonity.build { |t|
-  t <= @users
-
-  t[].users!(inherit: true) { |user|
+  t[].users!(@users) { |user|
     user.id
     user.age
     user.full_name { |u| [u.first_name, u.last_name].join ' ' }
@@ -28,115 +49,113 @@ Jsonity.build { |t|
     }
   }
 
-  t.(&@meta_pagination)
-}
-#=> {
-#     "users": [
-#       {
-#         "id": 1,
-#         "age": 21,
-#         "full_name": "John Smith",
-#         "avatar": {
-#           "image_url": "http://example.com/john.png"
-#         }
-#       },
-#       {
-#         "id": 2,
-#         "age": 37,
-#         "full_name": "William Northington",
-#         "avatar": {
-#           "image_url": "http://example.com/william.png"
-#         }
-#       },
-#       {
-#         "id": 3,
-#         "age": 29,
-#         "full_name": "Samuel Miller",
-#         "avatar": {
-#           "image_url": "http://example.com/samuel.png"
-#         }
-#       }
-#     ],
-#     "meta": {
-#       "total_pages": 1,
-#       "current_page": 1
-#     }
-#   }
+  t.(@users, &@meta_pagination_mixin)
+}
+=begin
+{
+  "users": [
+    {
+      "id": 1,
+      "age": 21,
+      "full_name": "John Smith",
+      "avatar": {
+        "image_url": "http://example.com/john.png"
+      }
+    },
+    {
+      "id": 2,
+      "age": 37,
+      "full_name": "William Northington",
+      "avatar": null
+    }
+  ],
+  "meta": {
+    "total_pages": 1,
+    "current_page": 1
+  }
+}
+=end
 ```
 
 
 Usage
 -----
 
-Make sure to add the gem to your Gemfile.
-
-```ruby
-gem 'neo_json'
-```
+### Object assignment
 
-Start writing object:
+To declare the data object for use:
 
 ```ruby
 Jsonity.build { |t|
+  t <= @user
   # ...
 }
 ```
 
-### Object assignment
-
-To declare the data object for use:
+Or pass as an argument:
 
 ```ruby
-t <= @user
+Jsonity.build(@user) { |user|
+  # ...
+}
 ```
 
+
 ### Attribute nodes
 
 Basic usage of defining simple attributes:
 
 ```ruby
-t.id   # @user.id
-t.age  # @user.age
+Jsonity.build(@user) { |user|
+  user.id   # @user.id
+  user.age  # @user.age
+}
+=begin
+{
+  "id": 123,
+  "age": 27
+}
+=end
 ```
  
 Or you can use custom attributes in flexible ways:
 
 ```ruby
-t.full_name { |u| [u.first_name, u.last_name].join ' ' }  # u = @user
-t.russian_roulette { rand(1..10) }                        # block parameter isn't required
-t.with_object(Time) { |t| t.now }                         # now, t = Time
-t.seventeen 17                                            # block can be omitted
-```
+Jsonity.build(@user) { |user|
+  # create full_name from @user.first_name and @user.last_name
+  user.full_name { |u| [u.first_name, u.last_name].join ' ' }
 
-Aliased attributes works well as you expected:
- 
-```ruby
-# show `id` as `my_id`
-t.my_id &:id
-```
+  # block parameter isn't required
+  user.russian_roulette { rand(1..10) }
 
-### Automatic attributes inclusion
+  # or with specified object
+  user.feature_time(Time.now) { |now| now + 1.years }
 
-If you set `attr_json` in any class, the specified attributes will automatically be included:
+  # block can be omitted if the value is constant
+  user.seventeen 17
+}
+=begin
+{
+  "full_name": "John Smith",
+  "russian_roulette": 4,
+  "feature_time": "2015-09-13 12:32:39 +0900",
+  "seventeen": 17
+}
+=end
+```
 
+Aliased attributes works well as you expected:
+ 
 ```ruby
-class Sample < Struct.new(:id, :foo)
-  attr_json :id, :foo
-end
-
-@sample = Sample.new 123, 'foo!'
-
-Jsonity.build { |t|
-  t.sample!(@sample) { |t|
-    # leave empty inside
-  }
+Jsonity.build(@user) { |user|
+  # show `id` as `my_id`
+  user.my_id &:id
 }
-#=> {
-#     "sample": {
-#       "id": 123,
-#       "foo": "foo!"
-#     }
-#   }
+=begin
+{
+  "my_id": 123
+}
+=end
 ```
 
 ### Hash nodes
@@ -144,7 +163,7 @@ Jsonity.build { |t|
 With name suffixed with `!`, nested object can be included:
 
 ```ruby
-t.user! { |user|
+Jsonity.build(@user) { |user|
   user.name  # @user.name
 
   user.avatar! { |avatar|
@@ -153,89 +172,152 @@ t.user! { |user|
     avatar.height     # @user.avatar.height
   }
 }
-```
-
-If `@user.avatar = nil`, the output will be like this:
+=begin
+Assume that `@user.avatar` is `nil`,
 
-```javascipt
 {
-  "user": {
-    "name": "John Smith",
-    "avatar": {
-      "image_url": null,
-      "width": null,
-      "height": null
-    }
+  "name": "John Smith",
+  "avatar": {
+    "image_url": null,
+    "width": null,
+    "height": null
   }
 }
+=end
 ```
 
 On the other hand, use `?` as suffix, the whole object become `null`:
 
 ```ruby
-t.user! { |user|
+Jsonity.build(@user) { |user|
   user.name
 
-  user.avatar? { |avatar|
+  user.avatar? { |avatar|  # <-- look, prefix is `?`
     avatar.image_url
     avatar.width
     avatar.height
   }
 }
+=begin
+Assume that `@user.avatar` is `nil`,
+
+{
+  "name": "John Smith",
+  "avatar": null
+}
+=end
+```
+
+Explicitly specify an object to use inside a block:
+
+```ruby
+Jsonity.build { |t|
+  t.home!(@user.hometown_address) { |home|
+    home.street  # @user.hometown_address.street
+    home.zip
+    home.city
+    home.state
+  }
+}
+=begin
+{
+  "home": {
+    "street": "4611 Armbrester Drive",
+    "zip": "90017",
+    "city": "Los Angeles",
+    "state": "CA"
+  }
+}
+=end
 ```
 
-and the output will be:
+Or a block can inherit the parent object:
 
-```javascipt
+```ruby
+Jsonity.build { |t|
+  t.user!(@user) { |user|
+    t.profile!(inherit: true) { |profile|
+      profile.name  # @user.name
+    }
+  }
+}
+=begin
 {
   "user": {
-    "name": "John Smith",
-    "avatar": null
+    "profile": {
+      "name": "John Smith"
+    }
   }
 }
+=end
 ```
 
-Explicitly set an object to use inside a block:
+### Automatic attributes inclusion
+
+If you set `attr_json` in any class, **the specified attributes will automatically be included**:
 
 ```ruby
-t.home?(@user.hometown_address) { |home|
-  home.street  # @user.hometown_address.street
-  home.zip
-  home.city
-  home.state
-}
+class Sample < Struct.new(:id, :foo, :bar)
+  attr_json :id, :foo
+end
+
+@sample = Sample.new 123, 'foo!', 'bar!!'
 ```
 
-Or blocks can inherit the parent object:
+and then,
 
 ```ruby
-t.user! { |user|
-  t.my!(inherit: true) { |my|
-    my.name  # @user.name
+Jsonity.build { |t|
+  t.sample! @sample
+}
+=begin
+{
+  "sample": {
+    "id": 123,
+    "foo": "foo!"
   }
 }
+=end
 ```
 
-### Array nodes
-
-Including a collection of objects, just use `t[]` and write the same syntax of hash node:
+Still you can create any kinds of nodes with a block:
 
 ```ruby
-t[].friends! { |friend|
-  friend.name
+Jsonity.build { |t|
+  t.sample!(@sample) { |sample|
+    sample.bar { |bar| "this is #{bar}" }
+  }
+}
+=begin
+{
+  "sample": {
+    "id": 123,
+    "foo": "foo!",
+    "bar": "this is bar!!"
+  }
 }
+=end
 ```
 
-and the output JSON will be:
 
-```javascipt
+### Array nodes
+
+Including a collection of objects, just use `[]` and write the same syntax of hash node:
+
+```ruby
+Jsonity.build(@user) { |user|
+  user[].friends! { |friend|
+    friend.name  # @user.friends[i].name
+  }
+}
+=begin
 {
   "friends": [
-    {
-      name: "John Smith"
-    }
+    { "name": "John Smith" },
+    { "name": "William Northington" }
   ]
 }
+=end
 ```
 
 Similar to hash nodes in naming convention,  
@@ -246,10 +328,10 @@ Also passing the object or inheritance can be done in the same way as hash nodes
 
 ### Mixin / Scope
 
-Since Jsonity aim to be simple and light, use plain `Proc` to fullfill functonality of mixin.
+Since Jsonity aim to be simple and light, **use plain `Proc`** to fullfill functonality of mixin.
 
 ```ruby
-timestamp_mixin = ->(t) {
+@timestamps_mixin = ->(t) {
   t.created_at
   t.updated_at
 }
@@ -258,29 +340,54 @@ timestamp_mixin = ->(t) {
 and then,
 
 ```ruby
-t.user! { |user|
-  user.(&timestamp_mixin)
+Jsonity.build { |t|
+  t.user!(@user) { |user|
+    user.(&@timestamps_mixin)
+  }
 }
+=begin
+{
+  "user": {
+    "created_at": "2014-09-10 10:41:07 +0900",
+    "updated_at": "2014-09-13 12:55:56 +0900"
+  }
+}
+=end
 ```
 
-In case you might use different object in mixin, you can pass the object in the first argument:
+In case you might explicitly **specify an object to use** in mixin, you can do by passing it in the first argument:
 
 ```ruby
-t.(@other_user, &timestamps)
+Jsonity.build { |t|
+  t.(@user, &@timestamps_mixin)
+}
+=begin
+{
+  "created_at": "2014-09-10 10:41:07 +0900",
+  "updated_at": "2014-09-13 12:55:56 +0900"
+}
+=end
 ```
 
-So you take this functonality for scope:
+So you take this functonality for **scope**:
 
 ```ruby
-t.(@other_user) { |other_user|
-  other_user.name
+Jsonity.build { |t|
+  t.(@user) { |user|
+    user.name
+  }
 }
+=begin
+{
+  "name": "John Smith"
+}
+=end
 ```
 
 #### Mixining nested object and merging
 
 ```ruby
-meta_pagination_mixin = ->(t) {
+@meta_pagination_mixin = ->(t) {
   t.meta! { |meta|
     meta.total_pages
     meta.current_page
@@ -291,46 +398,41 @@ meta_pagination_mixin = ->(t) {
 and use this mixin like:
 
 ```ruby
-t[].people!(@people) { |person|
-  # ...
-}
-
-t.(@people, &meta_pagination_mixin)
+Jsonity.build { |t|
+  t.(@people, &@meta_pagination_mixin)
 
-t.meta! { |meta|
-  meta.total_count @people.count
+  t.meta! { |meta|
+    meta.total_count @people.count
+  }
 }
-```
-
-the output become:
+=begin
+Notice that two objects `meta!` got merged.
 
-```javascript
 {
-  "people": [
-    // ...
-  ],
   "meta": {
     "total_pages": 5,
     "current_page": 1,
     "total_count": 123
   }
 }
+=end
 ```
 
-Notice that two objects `meta!` got merged.
 
-### Conditions
+### Using object
 
-Simply you can use `if` or `unless` statement inside the block:
+You can get the current object as a second block parameter.
 
-```
-t[].people! { |person|
-  unless person.private_member?
-    person.name
-    person.age
-  end
+```ruby
+Jsonity.build { |t|
+  t[].people!(@people) { |person, person_obj|
+    unless person_obj.private_member?
+      person.name
+      person.age
+    end
 
-  person.cv if person.looking_for_job?
+    person.cv if person_obj.looking_for_job?
+  }
 }
 ```
 
@@ -338,7 +440,7 @@ t[].people! { |person|
 With Rails
 ----------
 
-Helper method is available for rendering with Jsonity:
+Helper method is available in controller for rendering with Jsonity:
 
 ```ruby
 render_json(status: :ok) { |t|

data/jsonity.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Jsonity::VERSION
   spec.authors       = ['Yuki Iwanaga']
   spec.email         = ['yuki@creasty.com']
-  spec.summary       = 'The most natural language for building JSON in Ruby'
-  spec.description   = 'The most natural language for building JSON in Ruby'
+  spec.summary       = 'The most sexy language for building JSON in Ruby'
+  spec.description   = 'The most sexy language for building JSON in Ruby'
   spec.homepage      = 'https://github.com/creasty/jsonity'
   spec.license       = 'MIT'
 

data/lib/jsonity/version.rb

@@ -1,3 +1,3 @@
 module Jsonity
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonity
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Yuki Iwanaga
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-12 00:00:00.000000000 Z
+date: 2014-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,7 +38,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.3'
-description: The most natural language for building JSON in Ruby
+description: The most sexy language for building JSON in Ruby
 email:
 - yuki@creasty.com
 executables: []
@@ -80,5 +80,5 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: The most natural language for building JSON in Ruby
+summary: The most sexy language for building JSON in Ruby
 test_files: []