RubyGems - rep - Versions diffs - 0.0.1 → 0.0.2 - Mend

rep 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

data/docs/rep/version.html ADDED

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>version.rb</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+          <a class="source" href="../rep.html">rep.rb</a>
+          <a class="source" href="version.html">version.rb</a>
+      </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>version.rb</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-1">&#182;</a>
+        </div>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="k">module</span> <span class="nn">Rep</span>
+  <span class="no">VERSION</span> <span class="o">=</span> <span class="s2">&quot;0.0.1&quot;</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+  </table>
+</div>
+</body>

data/lib/rep.rb CHANGED

@@ -1,13 +1,51 @@
-require "rep/version"
+# **Rep** is a small module to endow any class to make json quickly. It solves four problems:
+#
+# 1. Enumerating top level keys for a json structure
+# 2. Providing a convention for the value of those keys
+# 3. Defining `attr_accessor`'s that are prefilled from an options hash given to `#initialize`
+# 4. Sharing instances to help GC
+#
+# The code is available on [github](http://github.com/myobie/rep).
+# `Forwardable` is in the stdlib and allows ruby objects to delegate methods off to other objects. An example:
+#
+#     class A
+#       extend Forwardable
+#       delegate [:length, :first] => :@array
+#       def initialize(array = [])
+#         @array = array
+#       end
+#     end
+#
+#     A.new([1,2,3]).length # => 3
+#     A.new([1,2,3]).first  # => 1
 require 'forwardable'
+# `JSON::generate` and `JSON::decode` are much safer to use than `Object#to_json`.
 require 'json'
+require 'rep/version'
 module Rep
+  # All classes that `include Rep` are extended with `Forwardable`,
+  # given some aliases, endowned with `HashieSupport` if Hashie is loaded,
+  # and given a delegate method if it doesn't already have one.
   def self.included(klass)
     klass.extend Forwardable
     klass.extend ClassMethods
     klass.instance_eval {
       class << self
+        unless defined?(delegate)
+          def delegate(opts = {})
+            methods, object_name = opts.to_a.first
+            args = [object_name, methods].flatten
+            def_delegators *args
+          end
+        end
         alias forward delegate
         unless defined?(fields)
@@ -18,21 +56,29 @@ module Rep
           include HashieSupport
         end
       end
-      unless defined?(parse_opts)
-        def parse_opts(opts = {})
-          # NOOP
-        end
-      end
     }
   end
+  # Since a goal is to be able to share instances, we need an easy way to reset a
+  # shared instance back to factory defaults. If you memoize any methods that are
+  # not declared as json fields, then overried this method and set any memoized
+  # variables to nil, then super.
   def reset_for_json!
     self.class.all_json_methods.each do |method_name|
       instance_variable_set(:"@#{method_name}", nil)
     end
   end
+  # All the work of generating a hash from an instance is packaged up in one method. Since
+  # fields can be aliases in the format `{ :json_key_name => :method_name }`, there
+  # is some fancy logic to determine the `field_name` and `method_name` variables.
+  #
+  #     { :one => :foo }.to_a # => [[:one, :foo]]
+  #
+  # Right now it will raise if either a field doesn't have a method to provide it's value or
+  # if there are no json fields setup for the particular set (which defaults to `:default`).
   def to_hash(name = :default)
     if fields = self.class.json_fields(name)
       fields.reduce({}) do |memo, field|
@@ -55,6 +101,15 @@ module Rep
   end
   module ClassMethods
+    # Defines an attr_accessor with a default value. The default for default is nil. Example:
+    #
+    #     class A
+    #       register_accessor :name => "No Name"
+    #     end
+    #
+    #     A.new.name # => "No Name"
     def register_accessor(acc)
       name, default = acc.is_a?(Hash) ? acc.to_a.first : [acc, nil]
       attr_accessor name
@@ -66,19 +121,38 @@ module Rep
       end
     end
+    # Defines an `#initialize` method that accepts a Hash argument and copies some keys out into `attr_accessors`.
+    # If your class already has an `#iniatialize` method then this will overwrite it (so don't use it). `#initialize_with`
+    # does not have to be used to use any other parts of Rep.
     def initialize_with(*args)
       @initializiation_args = args
-      define_singleton_method :initializiation_args do
-        @initializiation_args
+      # Remember what args we normally initialize with so we can refer to them when building shared instances.
+      if defined?(define_singleton_method)
+        define_singleton_method :initializiation_args do
+          @initializiation_args
+        end
+      else
+        singleton = class << self; self end
+        singleton.send :define_method, :initializiation_args, lambda { @initializiation_args }
       end
+      # Create an `attr_accessor` for each one. Defaults can be provided using the Hash version { :arg => :default_value }
       args.each { |a| register_accessor(a) }
-      define_method(:initialize) { |opts = {}| parse_opts(opts) }
+      define_method(:initialize) { |*args|
+        opts = args.first || {}
+        parse_opts(opts)
+      }
+      # `#parse_opts` is responsable for getting the `attr_accessor` values prefilled. Since defaults can be specified, it
+      # must negotiate Hashes and use the first key of the hash for the `attr_accessor`'s name.
       define_method :parse_opts do |opts|
-        @presidential_options = opts
+        @rep_options = opts
         self.class.initializiation_args.each do |field|
           name = field.is_a?(Hash) ? field.to_a.first.first : field
           instance_variable_set(:"@#{name}", opts[name])
@@ -86,6 +160,32 @@ module Rep
       end
     end
+    # `#json_fields` setups up some class instance variables to remember sets of top level keys for json structures. Example:
+    #
+    #     class A
+    #       json_fields [:one, :two, :three] => :default
+    #     end
+    #
+    #     A.json_fields(:default) # => [:one, :two, :three]
+    #
+    # There is a general assumption that each top level key's value is provided by a method of the same name on an instance
+    # of the class. If this is not true, a Hash syntax can be used to alias to a different method name. Example:
+    #
+    #     class A
+    #       json_fields [{ :one => :the_real_one_method }, :two, { :three => :some_other_three }] => :default
+    #     end
+    #
+    # Once can also set multiple sets of fields. Example:
+    #
+    #     class A
+    #       json_fields [:one, :two, :three] => :default
+    #       json_fields [:five, :two, :six] => :other
+    #     end
+    #
+    # And all fields are returned by calling `#json_fields` with no args. Example:
+    #
+    #     A.json_fields # => { :default => [:one, :two, :three], :other => [:five, :two, :six] }
     def json_fields(arg = nil)
       if arg.is_a?(Hash)
         fields, name = arg.to_a.first
@@ -102,6 +202,9 @@ module Rep
       end
     end
+    # `#flat_json_fields` is just a utility method to DRY up the next two methods, because their code is almost exactly the same,
+    # it is not intended for use directly and might be confusing.
     def flat_json_fields(side = :right)
       side_number = side == :right ? 1 : 0
@@ -116,22 +219,83 @@ module Rep
       end.uniq
     end
+    # We need a way to get a flat, uniq'ed list of all the fields accross all field sets. This is that.
     def all_json_fields
       flat_json_fields(:left)
     end
+    # We need a wya to get a flat, uniq'ed list of all the method names accross all field sets. This is that.
     def all_json_methods
       flat_json_fields(:right)
     end
-    # TODO: thread safety
+    # An easy way to save on GC is to use the same instance to turn an array of objects into hashes instead
+    # of instantiating a new object for every object in the array. Here is an example of it's usage:
+    #
+    #     class BookRep
+    #       initialize_with :book_model
+    #       fields :title => :default
+    #       forward :title => :book_model
+    #     end
+    #
+    #     BookRep.shared(:book_model => Book.first).to_hash # => { :title => "Moby Dick" }
+    #     BookRep.shared(:book_model => Book.last).to_hash  # => { :title => "Lost Horizon" }
+    #
+    # This should terrify you. If it doesn't, then this example will:
+    #
+    #     book1 = BookRep.shared(:book_model => Book.first)
+    #     book2 = BookRep.shared(:book_model => Book.last)
+    #
+    #     boo1.object_id === book2.object_id # => true
+    #
+    # **It really is a shared object.**
+    #
+    # You really shouldn't use this method directly for anything.
     def shared(opts = {})
-      @instance ||= new
-      @instance.reset_for_json!
-      @instance.parse_opts(opts)
-      @instance
+      @pointer = (Thread.current[:rep_shared_instances] ||= {})
+      @pointer[object_id] ||= new
+      @pointer[object_id].reset_for_json!
+      @pointer[object_id].parse_opts(opts)
+      @pointer[object_id]
     end
+    # The fanciest thing in this entire library is this `#to_proc` method. Here is an example of it's usage:
+    #
+    #     class BookRep
+    #       initialize_with :book_model
+    #       fields :title => :default
+    #       forward :title => :book_model
+    #     end
+    #
+    #     Book.all.map(&BookRep) # => [{ :title => "Moby Dick" }, { :title => "Lost Horizon " }]
+    #
+    # And now I will explain how it works. Any object can have a to_proc method and when you call `#map` on an
+    # array and hand it a proc it will in turn hand each object as an argument to that proc. What I've decided
+    # to do with this object is use it the options for a shared instance to make a hash.
+    #
+    # Since I know the different initialization argumants from a call to `initialize_with`, I can infer by order
+    # which object is which option. Then I can create a Hash to give to `parse_opts` through the `shared` method.
+    # I hope that makes sense.
+    #
+    # It allows for extremely clean Rails controllers like this:
+    #
+    #     class PhotosController < ApplicationController
+    #       respond_to :json, :html
+    #
+    #       def index
+    #         @photos = Photo.paginate(page: params[:page], per_page: 20)
+    #         respond_with @photos.map(&PhotoRep)
+    #       end
+    #
+    #       def show
+    #         @photo = Photo.find(params[:id])
+    #         respond_with PhotoRep.new(photo: @photo)
+    #       end
+    #     end
     def to_proc
       proc { |obj|
         arr = [obj].flatten

data/lib/rep/version.rb CHANGED

@@ -1,3 +1,3 @@
 module Rep
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/rep.gemspec CHANGED

@@ -17,4 +17,8 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
   gem.add_dependency 'json'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rocco'
+  gem.add_development_dependency 'rdiscount'
 end

data/test/lib/rep_test.rb CHANGED

@@ -23,10 +23,6 @@ describe Rep do
     new_rep_class.must_respond_to :fields
   end
-  it "has a parse_opts method" do
-    new_rep_class.must_respond_to :parse_opts
-  end
   it "can have fields" do
     klass = new_rep_class do
       fields [:foo, :bar] => :default
@@ -38,24 +34,24 @@ describe Rep do
     klass = new_rep_class do
       initialize_with :foo, :bar
     end
-    inst = klass.new(foo: 'foo123')
+    inst = klass.new(:foo => 'foo123')
     inst.foo.must_equal 'foo123'
     inst.bar.must_be_nil
   end
   it "can have default initialization options" do
     klass = new_rep_class do
-      initialize_with :foo, { bar: "barbar" }
+      initialize_with :foo, { :bar => "barbar" }
     end
-    inst = klass.new(foo: 'foofoo')
+    inst = klass.new(:foo => 'foofoo')
     inst.bar.must_equal 'barbar'
   end
   it "can overried default initialization options" do
     klass = new_rep_class do
-      initialize_with :foo, { bar: "barbar" }
+      initialize_with :foo, { :bar => "barbar" }
     end
-    inst = klass.new(bar: 'notbar')
+    inst = klass.new(:bar => 'notbar')
     inst.bar.must_equal 'notbar'
     inst.foo.must_be_nil
   end
@@ -84,7 +80,7 @@ describe Rep do
       def two; 2; end
       def three; 3; end
     end
-    klass.new.to_hash.must_equal one: 1, two: 2, three: 3
+    klass.new.to_hash.must_equal :one => 1, :two => 2, :three => 3
   end
   it "should send fields to instance to make json" do
@@ -133,10 +129,48 @@ describe Rep do
       fields :keys => :default
       forward :keys => :hash
     end
-    hashes = [{ one: 1, two: 2 },
-              { three: 3, four: 4 },
-              { one: 1, five: 5 }]
+    hashes = [{ :one => 1, :two => 2 },
+              { :three => 3, :four => 4 },
+              { :one => 1, :five => 5 }]
     hashes.map(&klass).to_json.must_equal '[{"keys":["one","two"]},{"keys":["three","four"]},{"keys":["one","five"]}]'
   end
+  describe "shared" do
+    User = Struct.new(:name, :age)
+    def users
+      @users ||= %w(Nathan 28 Jason 31 Justin 23).each_slice(2).
+                   map { |name, age| User.new(name, age.to_i) }
+    end
+    class UserRep
+      include Rep
+      initialize_with :user
+      fields [:name, :age, :random_number] => :default
+      forward fields(:default) => :user
+      def random_number
+        @random_number ||= rand(100)
+      end
+    end
+    it "should memoize random_number" do
+      rep = UserRep.new(:user => users.first)
+      rep.random_number.must_equal rep.random_number
+    end
+    it "should get a clean instance each time" do
+      num1 = UserRep.shared(:user => users.first).random_number
+      num2 = UserRep.shared(:user => users.first).random_number
+      num1.wont_equal num2
+    end
+    it "should be really really shared" do
+      rep1 = UserRep.shared(:user => users.first)
+      rep2 = UserRep.shared(:user => users.last)
+      rep1.must_equal rep2
+      rep1.name.must_equal rep2.name
+    end
+  end
 end

data/test/test_helper.rb CHANGED

@@ -1,9 +1,3 @@
 require 'minitest/autorun'
 require 'minitest/pride'
 require 'rep'
-class User < Struct.new(:name, :email, :location)
-end
-class Photo < Struct.new(:name, :location, :exif)
-end

metadata CHANGED

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rep
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease:
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2012-11-10 00:00:00.000000000 Z
+date: 2012-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -27,6 +27,70 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rocco
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdiscount
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A library for writing authoritative representations of objects for pages
   and apis.
 email:
@@ -36,10 +100,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/index.html
+- docs/lib/rep.html
+- docs/lib/rep/version.html
+- docs/rep.html
+- docs/rep/version.html
 - lib/rep.rb
 - lib/rep/version.rb
 - rep.gemspec