boxer 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Brad Fults, Gowalla Incorporated
+
+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,106 @@
+# Boxer
+
+Boxer is a template engine for creating nested and multi-view JSON objects
+from Ruby hashes.
+
+## The Problem
+
+Say you have a couple ActiveRecord models in your Rails app and you want to
+render an API response in JSON, but the view of each of those model objects
+may change based on the API action that's being requested.
+
+ * User
+ * Place
+
+For instance, the API for `GET /users/:id` should render a full representation
+of the User object in question, including all relevant attributes.
+
+But in your `GET /places/:id/users` API call, you only need short-form
+representations of the users at that place, without every single attribute
+being included in the response.
+
+## The Solution
+
+Boxer allows you to define a box for each type of object you'd like to display
+(or for each amalgamation of objects you want to display—it's up to you).
+
+    Boxer.box(:user) do |box, user|
+      {
+        :name => user.name,
+        :age  => user.age,
+      }
+    end
+
+To display different views on the same object, you can use Boxer's views:
+
+    Boxer.box(:user) do |box, user|
+      box.view(:base) do
+        {
+          :name => user.name,
+          :age  => user.age,
+        }
+      end
+
+      box.view(:full, :extends => :base) do
+        {
+          :email      => user.email,
+          :is_private => user.private?,
+        }
+      end
+    end
+
+As you might guess, the `:full` view includes all attributes in the `:base`
+view by virtue of the `:extends` option.
+
+Now, in order to render a User with the `:base` view, simple call `Boxer.ship`:
+
+    Boxer.ship(:user, User.first)
+
+Boxer assumes that you want the `:base` view if no view is specified to
+`ship`—it's the only specially-named view.
+
+To render the full view for the same user:
+
+    Boxer.ship(:user, User.first, :view => :full)
+
+Which will give you back a Ruby hash on which you can call `#to_json`, to render
+your JSON response<sup>1</sup>:
+
+    >> Boxer.ship(:user, User.first, :view => :full).to_json
+    => "{"name": "Bo Jim", "age": 17, "email": "b@a.com", "is_private": false}"
+
+Composing different boxes together is as simple as calling `Boxer.ship` from
+within a box&mdash;it's just Ruby:
+
+    Boxer.box(:place) do |box, place|
+      {
+        :name     => place.name,
+        :address  => place.address,
+        :top_user => Boxer.ship(:user, place.users.order(:visits).first),
+      }
+    end
+
+ 1. `Hash#to_json` requires the [`json` library](http://rubygems.org/gems/json)
+
+## More Features
+
+See [the wiki](/h3h/boxer/wiki) for more features of Boxer, including:
+
+ * [Extra Arguments](/h3h/boxer/wiki/Extra-Arguments)
+ * [Preconditions](/h3h/boxer/wiki/Preconditions)
+ * [Helper Methods in Boxes](/h3h/boxer/wiki/Helper-Methods-in-Boxes)
+ * [Box Includes](/h3h/boxer/wiki/Box-Includes)
+ * [Multiple Inheritance](/h3h/boxer/wiki/Multiple-Inheritance)
+
+## Installation
+
+Install the [boxer gem](http://rubygems.org/gems/boxer).
+
+## Original Author
+
+ * [Brad Fults](http://h3h.net/), Gowalla Incorporated
+
+## Inspiration
+
+Boxer was inspired by [rabl](https://github.com/nesquena/rabl),
+by Nathan Esquenazi.

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/boxer.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "boxer/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'boxer'
+  s.version     = Boxer::VERSION
+  s.authors     = ['Brad Fults']
+  s.email       = ['bfults@gmail.com']
+  s.homepage    = 'http://github.com/h3h/boxer'
+  s.license     = 'MIT'
+  s.summary     = %q{
+    Easy custom-defined templates for JSON generation of objects in Ruby.
+  }
+  s.description = %q{
+    A composable templating system for generating JSON via Ruby hashes, with
+    different possible views on each object and runtime data passing.
+  }
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'rspec', '>= 2.0.0'
+  s.add_runtime_dependency 'activesupport', '>= 3.0.0'
+end

data/lib/boxer.rb

@@ -0,0 +1,101 @@
+require 'boxer/version'
+require 'active_support/core_ext/class/attribute_accessors'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/core_ext/hash/deep_merge'
+require 'ostruct'
+
+class Boxer
+  cattr_accessor :config
+
+  self.config = OpenStruct.new({
+    :box_includes => [],
+  })
+
+  class ViewMissingError < StandardError; end
+
+  def initialize(name, options={}, &block)
+    @name = name
+    @block = block
+    @fallback = []
+    @views = {}
+    @views_chain = {}
+    @options = options
+  end
+
+  ## class methods
+
+  def self.box(name, options={}, &block)
+    (@boxes ||= {})[name] = self.new(name, options, &block)
+  end
+
+  def self.boxes
+    @boxes
+  end
+
+  def self.clear!
+    @boxes = {}
+  end
+
+  def self.configure
+    yield config
+  end
+
+  def self.ship(name, *args)
+    fail "Unknown box: #{name.inspect}" unless @boxes.has_key?(name)
+    @boxes[name].ship(*args)
+  end
+
+  ## instance methods
+
+  def emit(val)
+    @fallback = [val]
+  end
+
+  def ship(*args)
+    args = args.dup
+    if args.last.is_a?(Hash)
+      args[-1] = args.last.dup
+      view = args.last.delete(:view)
+      args.slice!(-1) if args.last.empty?
+    end
+    view ||= :base
+
+    modules = self.class.config.box_includes
+    black_box = Class.new do
+      modules.each do |mod|
+        include mod
+      end
+    end
+    block_result = black_box.new.instance_exec(self, *args, &@block)
+
+    if @fallback.length > 0
+      return @fallback.pop
+    elsif @views_chain.any?
+      unless @views_chain.has_key?(view)
+        fail ViewMissingError.new([@name, view].map(&:inspect).join('/'))
+      end
+      return @views_chain[view].inject({}) do |res, view_name|
+        res.deep_merge(@views[view_name].call(*args))
+      end
+    else
+      return block_result
+    end
+  end
+
+  def precondition
+    yield self
+  end
+
+  def view(name, opts={}, &block)
+    @views_chain[name] = []
+    if opts.has_key?(:extends)
+      ancestors = Array(opts[:extends]).map do |parent|
+        (@views_chain[parent] || []) + [parent]
+      end.flatten.uniq
+      @views_chain[name] += ancestors
+    end
+    @views_chain[name] << name
+
+    @views[name] = block
+  end
+end

data/lib/boxer/version.rb

@@ -0,0 +1,3 @@
+class Boxer
+  VERSION = "1.0.0"
+end

data/spec/boxer_spec.rb

@@ -0,0 +1,206 @@
+require 'spec_helper'
+require 'boxer'
+
+module MyTestModule
+  def my_test_method; 42 end
+end
+
+module MySecondTestModule
+  def my_second_test_method; 43 end
+end
+
+describe Boxer do
+
+  describe ".box" do
+    it "can create a box based on a simple hash" do
+      Boxer.box(:foo) do
+        {:working => true}
+      end
+
+      Boxer.ship(:foo).should eq({:working => true})
+    end
+
+    it "defaults to shipping the base view, when it exists" do
+      Boxer.box(:foo) do |box|
+        box.view(:base) { {:working => true} }
+      end
+
+      Boxer.ship(:foo).should eq({:working => true})
+    end
+
+    it "fails if views are specified, but :base is missing" do
+      Boxer.box(:foo) do |box|
+        box.view(:face) { {:working => true} }
+      end
+
+      expect {
+        Boxer.ship(:foo).should eq({:working => true})
+      }.to raise_exception(Boxer::ViewMissingError)
+    end
+
+    it "executes its block in a sandbox context, not a global one" do
+      Boxer.box(:foo) do |box|
+        self
+      end
+
+      context_obj = Boxer.ship(:foo)
+      context_obj.inspect.should_not include('RSpec')
+      context_obj.inspect.should include('Class')
+    end
+
+    it "raises a ViewMissing error if given a non-existent view" do
+      Boxer.box(:foo) do |box|
+        box.view(:face) { {:working => true} }
+      end
+
+      expect {
+        Boxer.ship(:foo).should eq({:working => true})
+      }.to raise_exception(Boxer::ViewMissingError)
+    end
+  end
+
+  describe ".clear!" do
+    it "clears all boxes" do
+      Boxer.box(:foo) { {:working => true} }
+      Boxer.clear!
+      Boxer.boxes.should be_empty
+    end
+  end
+
+  describe ".configure" do
+    it "sets config.box_includes via its supplied block" do
+      Boxer.config.box_includes = []
+      Boxer.configure {|config| config.box_includes = [MyTestModule] }
+      Boxer.config.box_includes.should include(MyTestModule)
+    end
+  end
+
+  describe ".ship" do
+    it "accepts arguments and passes them to a box for shipping" do
+      Boxer.box(:bar) do |box, x, y, z|
+        box.view(:base) { {:working => true, :stuff => [x, y, z]} }
+      end
+
+      Boxer.ship(:bar, 1, 2, 3).should eq(
+        {:working => true, :stuff => [1, 2, 3]}
+      )
+    end
+
+    it "allows a hash as the final argument" do
+      Boxer.box(:bar) do |box, x, y, z|
+        box.view(:base) { {:working => true, :stuff => [x, y, z]} }
+      end
+
+      Boxer.ship(:bar, 1, 2, :banana => true).should eq(
+        {:working => true, :stuff => [1, 2, {:banana => true}]}
+      )
+    end
+
+    it "includes modules from config.box_includes in shipping boxes" do
+      Boxer.config.box_includes = [MyTestModule, MySecondTestModule]
+      Boxer.box(:bar) do |box|
+        box.view(:base) { {:a => my_test_method, :b => my_second_test_method} }
+      end
+
+      Boxer.ship(:bar).should eq({:a => 42, :b => 43})
+    end
+
+    it "does not mutate passed in arguments" do
+      Boxer.box(:bar) do |box, num, opts|
+        box.view(:base) { {} }
+      end
+
+      hash = {:view => :base}.freeze
+      orig_hash = hash.dup
+      Boxer.ship(:bar, 1, hash)
+      hash.should eq(orig_hash)
+    end
+  end
+
+  describe "#precondition" do
+    it "ships the value emitted in the precondition" do
+      Boxer.box(:foo) do |box, obj|
+        box.precondition {|resp| resp.emit({}) if obj.nil? }
+        box.view(:base) { {:working => true} }
+      end
+
+      Boxer.ship(:foo, nil).should eq({})
+    end
+
+    it "disregards the precondition if no value is emitted" do
+      Boxer.box(:foo) do |box, obj|
+        box.precondition {|resp| resp.emit({}) if obj.nil? }
+        box.view(:base) { {:working => true} }
+      end
+
+      Boxer.ship(:foo, Object.new).should eq({:working => true})
+    end
+
+    it "can handle nil as an emitted precondition value" do
+      Boxer.box(:foo) do |box, obj|
+        box.precondition {|resp| resp.emit(nil) if obj.nil? }
+        box.view(:base) { {:working => true} }
+      end
+
+      Boxer.ship(:foo, nil).should eq(nil)
+    end
+
+    it "doesn't remember a fallback value from a previous shipping" do
+      Boxer.box(:foo) do |box, obj|
+        box.precondition {|resp| resp.emit({}) if obj.nil? }
+        box.view(:base) { {:working => true} }
+      end
+
+      Boxer.ship(:foo, nil).should eq({})
+      Boxer.ship(:foo, Object.new).should eq({:working => true})
+    end
+  end
+
+  describe "#view" do
+    it "allow extending of other views" do
+      Boxer.box(:foo) do |box|
+        box.view(:base) { {:working => true} }
+        box.view(:face, :extends => :base) { {:awesome => true} }
+      end
+
+      Boxer.ship(:foo, :view => :face).should eq(
+        {:working => true, :awesome => true}
+      )
+    end
+
+    it "extends by smashing lesser (extended) views" do
+      Boxer.box(:foo) do |box|
+        box.view(:base) { {:working => true} }
+        box.view(:face, :extends => :base) { {:working => :awesome} }
+      end
+
+      Boxer.ship(:foo, :view => :face).should eq(
+        {:working => :awesome}
+      )
+    end
+
+    it "extends by merging nested keys without overriding" do
+      Boxer.box(:foo) do |box|
+        box.view(:base) { {:working => {:a => 1}} }
+        box.view(:face, :extends => :base) { {:working => {:b => 2}} }
+      end
+
+      Boxer.ship(:foo, :view => :face).should eq(
+        {:working => {:a => 1, :b => 2}}
+      )
+    end
+
+    it "allows extending in a chain of more than two views" do
+      Boxer.box(:foo) do |box|
+        box.view(:base) { {:working => {:a => 1}} }
+        box.view(:face, :extends => :base) { {:working => {:b => 2}} }
+        box.view(:race, :extends => :face) { {:working => {:c => 3}} }
+      end
+
+      Boxer.ship(:foo, :view => :race).should eq(
+        {:working => {:a => 1, :b => 2, :c => 3}}
+      )
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$:.push File.expand_path("../../lib", __FILE__)
+
+RSpec.configure do |config|
+  # ...
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: boxer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Brad Fults
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-18 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70290064287800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *70290064287800
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70290064287300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70290064287300
+description: ! "\n    A composable templating system for generating JSON via Ruby
+  hashes, with\n    different possible views on each object and runtime data passing.\n
+  \ "
+email:
+- bfults@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- boxer.gemspec
+- lib/boxer.rb
+- lib/boxer/version.rb
+- spec/boxer_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/h3h/boxer
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Easy custom-defined templates for JSON generation of objects in Ruby.
+test_files:
+- spec/boxer_spec.rb
+- spec/spec_helper.rb