marble 0.1.0

data/.autotest

@@ -0,0 +1,9 @@
+require 'bundler/setup'
+
+Autotest.add_hook :initialize do |at|
+  at.testlib = 'minitest/unit'
+  
+  %w{test/rails}.each do |exception|
+    at.add_exception(exception)
+  end
+end

data/.gitignore

@@ -0,0 +1,19 @@
+coverage
+rdoc
+pkg
+test/tmp
+test/version_tmp
+tmp
+pkg
+*.gem
+*.rbc
+lib/bundler/man
+spec/reports
+.config
+InstalledFiles
+.bundle
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/.travis.yml

@@ -0,0 +1,6 @@
+script: 'rake test'
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - ree
+  - jruby

data/.yardopts

@@ -0,0 +1,3 @@
+--readme          README.md
+--markup          markdown
+--markup-provider maruku

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,93 @@
+PATH
+  remote: .
+  specs:
+    marble (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.5.0)
+    abstract (1.0.0)
+    actionmailer (3.0.5)
+      actionpack (= 3.0.5)
+      mail (~> 2.2.15)
+    actionpack (3.0.5)
+      activemodel (= 3.0.5)
+      activesupport (= 3.0.5)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.7)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.5)
+      activesupport (= 3.0.5)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.5)
+      activemodel (= 3.0.5)
+      activesupport (= 3.0.5)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.5)
+      activemodel (= 3.0.5)
+      activesupport (= 3.0.5)
+    activesupport (3.0.5)
+    arel (2.0.9)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    builder (2.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    i18n (0.5.0)
+    json (1.5.1)
+    mail (2.2.15)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    maruku (0.6.0)
+      syntax (>= 1.0.0)
+    mime-types (1.16)
+    minitest (2.1.0)
+    mocha (0.9.12)
+    polyglot (0.3.1)
+    rack (1.2.2)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rails (3.0.5)
+      actionmailer (= 3.0.5)
+      actionpack (= 3.0.5)
+      activerecord (= 3.0.5)
+      activeresource (= 3.0.5)
+      activesupport (= 3.0.5)
+      bundler (~> 1.0)
+      railties (= 3.0.5)
+    railties (3.0.5)
+      actionpack (= 3.0.5)
+      activesupport (= 3.0.5)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
+    rake (0.8.7)
+    syntax (1.0.0)
+    thor (0.14.6)
+    treetop (1.4.9)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.25)
+    yard (0.6.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  autotest (~> 4.4)
+  json (~> 1.5)
+  marble!
+  maruku (~> 0.6)
+  minitest (~> 2.0)
+  mocha (~> 0.9)
+  rails (= 3.0.5)
+  yard (~> 0.6)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Alexander Kern
+
+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,82 @@
+# marble [![StillMaintained Status](http://stillmaintained.com/CapnKernul/marble.png)](http://stillmaintained.com/CapnKernul/marble) [![Build Status](http://travis-ci.org/CapnKernul/marble.png)](http://travis-ci.org/CapnKernul/marble) #
+
+Marble is a Ruby object builder. It makes generating complex Ruby objects, and
+by extension JSON and YAML, much more readable. It's especially useful for Rails
+JSON API templates.
+
+## Installation ##
+
+Marble works both with and without Rails. Installation is as simple as adding
+this line to your `Gemfile`:
+
+    gem 'marble'
+
+If you'd like to use marble without bundler, you can also directly install the
+gem:
+
+    gem install marble
+
+## Usage ##
+
+First, require marble and create a builder.
+
+    require 'marble'
+    builder = Marble.new
+
+This builder can build any Ruby object using the `#build` method. The yielded
+value is the current builder:
+
+    builder.build do |m|
+      ['foo']
+    end # => ['foo']
+
+However, this isn't very useful. The `#array` and `#hash` methods are far more
+interesting. They allow you to build complex arrays and hashes in a minimal
+amount of lines:
+
+    builder.array do |m|
+      m.item 'foo'
+    end # => ['foo']
+    
+    builder.hash do |m|
+      m.foo 'bar'
+    end # => { 'foo' => 'bar' }
+
+The returned value can be converted to JSON and YAML, giving you a really
+concise way of creating JSON and YAML templates for API's.
+
+See the `Marble` documentation for more details.
+
+## Usage with Rails ##
+
+Marble provides a template handler for Rails. It supports object literal, JSON,
+and YAML output formats. Name your view template with the extension `marble`.
+The template creates a builder with the name `marble` for you to use. You can
+rename it using the block parameter. For example, in order to generate a JSON
+view:
+
+    # view_name.json.marble
+    marble.hash do |m|
+      m.foo 'bar'
+    end
+    
+    # Renders: {"foo": "bar"}
+
+See the `Marble::RailsTemplateHandler` documentation for more details.
+
+## Note on Patches/Pull Requests ##
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, but do not mess with the `Rakefile`. If you want to have your own version, that is fine but bump the version in a commit by itself in another branch so I can ignore it when I pull.
+* Send me a pull request. Bonus points for git flow feature branches.
+
+## Resources ##
+
+* [GitHub Repository](https://github.com/CapnKernul/marble)
+* [Documentation](http://rubydoc.info/github/CapnKernul/marble)
+
+## License ##
+
+Marble is licensed under the MIT License. See `LICENSE` for details.

data/Rakefile

@@ -0,0 +1,20 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task :default => 'test:unit'
+
+task :test => ['test:unit', 'test:rails']
+
+require 'rake/testtask'
+Rake::TestTask.new('test:unit') do |t|
+  t.ruby_opts += ['-rubygems']
+  t.libs << 'test'
+  t.pattern = 'test/test_*.rb'
+end
+
+task 'test:rails' do
+  sh <<-CMD
+    cd test/rails
+    rake
+  CMD
+end

data/lib/marble.rb

@@ -0,0 +1,274 @@
+# Builder for Ruby objects. Provides a convenient interface for generating
+# complex arrays and hashes.
+# 
+# First instantiate a builder:
+# 
+#     builder = Marble.new
+# 
+# Then, call either `#build`, `#array`, or `#hash` on the builder. You can use
+# the yielded block parameter to give the builder a shorter name. I suggest `m`.
+# 
+#     builder.hash do |m|
+#       m.zombies 'oh my!'
+#     end
+# 
+# The returned value is the built object.
+class Marble
+  # Builds an arbitrary value.
+  # 
+  # @example Build a simple value
+  #     builder = Marble.new
+  #     builder.build do |m|
+  #       true
+  #     end # => true
+  # 
+  # @example Build a more complex value
+  #     builder = Marble.new
+  #     builder.build do |m|
+  #       m.array do
+  #         m.item 'foo'
+  #       end
+  #     end # => ['foo']
+  # 
+  # @yield [builder] block to evaluate for the value
+  # @yieldparam builder [Marble] the current builder
+  # @return [Object] the built value
+  def build(&block)
+    value_structure(&block)
+  end
+  
+  # Builds a hash.
+  # 
+  # @example Build a simple hash
+  #     builder = Marble.new
+  #     builder.hash do |m|
+  #       m.foo 'bar'
+  #       m.baz 'quz'
+  #     end # => { 'foo' => 'bar', 'baz' => 'quz' }
+  # 
+  # @example Build nested hashes
+  #     builder = Marble.new
+  #     builder.hash do |m|
+  #       m.foo :hash do
+  #         m.bar 'baz'
+  #       end
+  #     end # => { 'foo' => { 'bar' => 'baz' } }
+  # 
+  # @yield [builder] block to evaluate within the hash's context
+  # @yieldparam builder [Marble] the current builder
+  # @return [Hash] the built hash
+  def hash(&block)
+    insert_structure({}, &block)
+  end
+  
+  # Builds an array.
+  # 
+  # @example Build a simple array
+  #     builder = Marble.new
+  #     builder.array do |m|
+  #       m.item 'foo'
+  #       m.item 'bar'
+  #     end # => ['foo', 'bar']
+  # 
+  # @example Build nested arrays
+  #     builder = Marble.new
+  #     builder.array do |m|
+  #       m.item :array do
+  #         m.item 'foo'
+  #       end
+  #     end # => [['foo']]
+  # 
+  # @yield [builder] block to evaluate within the array's context
+  # @yieldparam builder [Marble] the current builder
+  # @return [Array] the built array
+  def array(&block)
+    insert_structure([], &block)
+  end
+  
+  # Calls `#pair` or `#key` depending on the context.
+  # 
+  # When the current structure responds to `#push` (for example, in an array
+  # context), it calls `#item` ignoring the method name. This allows you to be
+  # more semantic when defining the items in an array. However, in most cases
+  # calling `#item` will suffice.
+  # 
+  # When the current structure responds to `#[]=` (for example, in a hash
+  # context), it calls `#pair` with the stringified method name as the key.
+  # This, in general, is a more concise and preferred way than explicitly
+  # calling `#pair`.
+  # 
+  # @example Build an array
+  #     builder = Marble.new
+  #     builder.array do |m|
+  #       m.milk 'toast'
+  #     end # => ['foo', 'bar']
+  # 
+  # @example Build a hash
+  #     builder = Marble.new
+  #     builder.hash do |m|
+  #       m.milk 'toast'
+  #     end # => { 'milk' => 'toast' }
+  def method_missing(method, *args, &block)
+    if @current.respond_to?(:push)
+      item(*args, &block)
+    elsif @current.respond_to?(:[]=)
+      pair(method.to_s, *args, &block)
+    else
+      super
+    end
+  end
+  
+  # Inserts an item into the current structure.
+  # 
+  # Arrays are the most common structure into which you insert an item (any
+  # value). Items are inserted using `#push`, so if you'd like to duck-type an
+  # array for whatever reason, go ahead.
+  # 
+  # You can provide values using either the second parameter or a block. If you
+  # provide a block, the block will be evaluated immediately.
+  # 
+  # Blocks by default insert the value of the block into the item. However, you
+  # can optionally specify the structure type of the block as either `:array` or
+  # `:hash` to insert an array or hash structure. That means that these are all
+  # equivalent:
+  # 
+  #     m.array do
+  #       m.item ['value']
+  #     end
+  #     
+  #     m.array do
+  #       m.item do
+  #         ['value']
+  #       end
+  #     end
+  #     
+  #     m.array do
+  #       m.item :hash do
+  #         m.pair 'key', 'value'
+  #       end
+  #     end
+  # 
+  # Choose the format that makes the most sense in a given context.
+  # 
+  # @overload item(value)
+  #   @param value [Object] the value to insert into the item
+  # @overload item()
+  #   @yield [builder] block to evaluate for the item's value
+  #   @yieldparam builder [Marble] the current builder
+  #   @yieldreturn [Object] the value to insert into the item
+  # @overload item(structure_type)
+  #   @param structure_type [:array, :hash] the block's structure type
+  #   @yield [builder] block to evaluate for the item's value
+  #   @yieldparam builder [Marble] the current builder
+  #   @yieldreturn [Object] the value to insert into the item
+  def item(value_or_structure_type = nil, &block)
+    if block_given?
+      @current.push evaluate_structure(value_or_structure_type, &block)
+    else
+      @current.push value_or_structure_type
+    end
+  end
+  
+  # Inserts a pair into the current structure.
+  # 
+  # Hashes are the most common structure into which you insert a pair (key and
+  # value). Pairs are inserted using `#[]=`, so if you'd like to duck-type a
+  # hash for whatever reason, go ahead.
+  # 
+  # You can provide values using either the second parameter or a block. If you
+  # provide a block, the block will be evaluated immediately.
+  # 
+  # Blocks by default insert the value of the block into the pair. However, you
+  # can optionally specify the structure type of the block as either `:array` or
+  # `:hash` to insert an array or hash structure. That means that these are all
+  # equivalent:
+  # 
+  #     m.hash do
+  #       m.pair 'key', ['value']
+  #     end
+  #     
+  #     m.hash do
+  #       m.pair 'key' do
+  #         ['value']
+  #       end
+  #     end
+  #     
+  #     m.hash do
+  #       m.pair 'key', :array do
+  #         m.item 'value'
+  #       end
+  #     end
+  # 
+  # Choose the format that makes the most sense in a given context.
+  # 
+  # @overload pair(key, value)
+  #   @param key [Object] the key to use for the pair
+  #   @param value [Object] the value to insert into the pair
+  # @overload pair(key)
+  #   @param key [Object] the key to use for the pair
+  #   @yield [builder] block to evaluate for the pair's value
+  #   @yieldparam builder [Marble] the current builder
+  #   @yieldreturn [Object] the value to insert into the pair
+  # @overload pair(key, structure_type)
+  #   @param key [Object] the key to use for the pair
+  #   @param structure_type [:array, :hash] the block's structure type
+  #   @yield [builder] block to evaluate for the pair's value
+  #   @yieldparam builder [Marble] the current builder
+  #   @yieldreturn [Object] the value to insert into the pair
+  def pair(key, value_or_structure_type = nil, &block)
+    if block_given?
+      @current[key] = evaluate_structure(value_or_structure_type, &block)
+    else
+      @current[key] = value_or_structure_type
+    end
+  end
+  
+  private
+  
+  # Inserts a value structure.
+  # 
+  # This is really only used as an easy way to insert into the current structure
+  # to whatever the block evaluates.
+  # 
+  # @yield [builder] block to evaluate for the value
+  # @yieldparam builder [Marble] the current builder
+  def value_structure(&block)
+    insert_structure(nil, &block)
+  end
+  
+  # Inserts a structure into the current structure.
+  # 
+  # @param structure [Object] the new structure to insert
+  # @yield [builder] block to evaluate for the value
+  # @yieldparam builder [Marble] the current builder
+  def insert_structure(structure)
+    if block_given?
+      parent = @current
+      @current = structure
+      value = yield(self)
+      @current = parent
+    end
+    
+    structure || value
+  end
+  
+  # Convenience method for inserting the correct structure type based on a
+  # symbol.
+  # 
+  # @param type [Symbol] the structure type
+  # @yield [builder] block to evaluate for the value
+  # @yieldparam builder [Marble] the current builder
+  def evaluate_structure(type, &block)
+    case type
+    when :hash then hash(&block)
+    when :array then array(&block)
+    else value_structure(&block)
+    end
+  end
+end
+
+require 'marble/version'
+
+if defined? ActionView::Template
+  require 'marble/rails_template_handler'
+end