letterpress 0.0.1 → 0.0.3

data/README.md

@@ -1,6 +1,7 @@
-# Letterpress
+# Letterpress [![Build Status](http://travis-ci.org/unders/letterpress.png)](http://travis-ci.org/unders/letterpress)
+
+Letterpress is a _lightweight_ model generator that replaces fixture files.
 
-TODO: Write a gem description
 
 ## Installation
 
@@ -18,7 +19,271 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Rails, ActiveRecord and minitest
+
+
+1. Update Gemfile
+
+    ``` ruby
+    group :development, :test do
+      gem 'letterpress', :require => 'letterpress/rails'
+    end
+    ```
+
+2. Install the gem
+
+        $ bundle install
+
+3. Generate (test|spec)/blueprint.rb file
+
+
+        $ rails generate letterpress:install
+        
+
+4. Update config/application.rb
+
+    ``` ruby
+    config.generators do |g|
+      g.test_framework :mini_test, :spec => true, :fixture_replacement => :letterpress
+    end
+    ```
+
+5. Generate a model object with its factory
+
+        $ rails generate model Comment post_id:integer body:text
+
+6. It adds to the end of file (test|spec)/blueprint.rb
+
+    ``` ruby
+    class Comment < Blueprint(ProxyMethods)
+      default do
+        post_id { 1 }
+        body { "MyText" }
+      end
+    end
+    ```
+
+7. Modify the generated blueprint according to your preferences
+
+    ``` ruby
+    class Comment < Blueprint(ProxyMethods)
+      default do
+        post { Post.make.new }
+        body { "MyText" }
+      end
+    end
+    ```
+
+8. Write tests in test/comment_test.rb
+
+    ``` ruby
+    require "minitest_helper"
+
+    class CommentTest < MiniTest::Rails::Model
+      before do
+        @comment = Comment.make.new
+      end
+
+      it "must be valid" do
+        @comment.valid?.must_equal true
+      end
+    end
+    ```
+
+
+## Blueprint Class
+A blueprint for a model is defined inside the Letterpress module; the class name of the blueprint
+__must__ be the same as the models class name. 
+
+Below is an example of a Letterpress User class. Letterpress has two methods for 
+defining blueprints: `default` and `define`; `default` can be used once in each 
+class but `define` can be used as many time as you like. In this example 
+the `admin` attribute is overridden by the admin block. The admin block will inherit 
+the other attributes defined inside the default block. 
+
+
+```ruby
+module Letterpress
+  class User < Blueprint(ProxyMethods)
+    default do
+      email { "user@example.com" }
+      admin { false }
+    end
+
+    define(:admin) do
+      admin { true }
+    end
+  end
+end
+
+user = User.make # => returns a proxy object (an instance of Letterpress::User)
+user.admin # => false; itdelegates to an instance of the User class
+user.email # => "user@example.com"
+
+user = User.make(:admin)
+user.admin # => true
+user.email # => "user@example.com"
+
+user = User.make(:admin, admin: false)
+user.admin # => false
+user.email # => "user@example.com"
+```
+
+#### Unique Attributes
+For attributes that must be unique, you can call the `sn` method within the 
+attribute block to get a unique serial number for the object.
+
+```ruby
+email { "user-#{sn}@example.com" } # Each email gets a unique serial number.
+
+user1 = User.make
+user2 = User.make
+
+user1.email # => "user1@example.com"
+user2.email # => "user2@example.com"
+```
+
+#### Associations
+When you create associations you don't have to persist them inside the blueprint.
+
+* has_many
+
+```ruby
+# When defining a has_many association, you define it with an array.
+# These 2 comments will only be persisted in the database when Post.make.save 
+# is called, and not when Post.make or Post.make.new is called. 
+comments { [ Comment.make.new, Comment.make.new ] }
+```
+
+* belongs_to
+
+```ruby
+# Post.make.new defines a non persisted post instance.
+# The post instance will only be saved to the database if
+# Comment.make.save is called.
+post { Post.make.new }
+```
+
+#### What you must know to create a blueprint class:
+* The class methods `default` and `define` is used for defining default attribute values.
+* An attribute values __must__ be defined inside a block: `{}`. 
+* The `sn` method is used inside an attribute block to create unique attribute values, e.g if 
+  each user instance must have a unique email address.
+
+## Creating Object
+Letterpress ads [`make`](https://github.com/unders/letterpress/blob/master/lib/letterpress.rb#L12) 
+to each ActiveRecord class; When `make` is called on an ActiveRecord class, it returns a proxy object 
+that will [delegate](https://github.com/unders/letterpress/blob/master/lib/letterpress/blueprint.rb#L73) 
+its received messages to the ActiveRecord instance.
+
+The [proxy object](https://github.com/unders/letterpress/blob/master/lib/letterpress.rb#L18) implements these methods:
+* [`new`](https://github.com/unders/letterpress/blob/master/spec/letterpress/rails_spec.rb#L86) - returns the object under test or raises an exception if the object isn't valid.
+* [`new!`](https://github.com/unders/letterpress/blob/master/spec/letterpress/rails_spec.rb#L108) - returns the object under test, even if not valid.
+* [`save`](https://github.com/unders/letterpress/blob/master/spec/letterpress/rails_spec.rb#L128) - returns the persisted object under test or raises an exception if the object isn't valid.
+
+
+```ruby
+User.make # Returns instance of Letterpress::User
+User.make(:admin) # Returns instance of Letterpress::User
+User.make(:admin, email: "foo@bar.com") # Returns instance of Letterpress::User
+
+
+User.make.new # Returns a new User instance
+User.make(:admin).save # Returns a persisted User instance
+User.make(:admin, email: "foo@bar.com").new! # Returns a new User instance
+```
+
+## Creating global ProxyMethods
+Since each Letterpress class inherits from 
+[ProxyMethods](https://github.com/unders/letterpress/blob/master/lib/letterpress.rb#L18), 
+we can define methods in that module and they will be added to each proxy object.
+
+In the code snippet below I have added a `save_and_relod` method that will be 
+available on every proxy object.
+
+```ruby
+module Letterpress
+  module ProxyMethods
+    def save_and_reload
+      record = save
+      @object = @object.class.find(record.id)
+    end
+  end
+end
+
+user = User.make.save_and_reload
+```
+
+## Creating ProxyMethods on a class
+If you want to add a method to only one proxy object, see code below.
+
+```ruby
+module Letterpress
+  class User < Blueprint(ProxyMethods)
+    default do
+      #...
+    end
+
+    def password(password)
+      @object.password = "#{password} - in proxy" 
+      @object
+    end
+  end
+end
+
+user = User.make.password("secret").save
+user.password # => "secret - in proxy"
+```
+
+## Overriding .make
+If you for some reason want to do something with the proxy object before returning it, you can 
+do that, see code below.
+
+```ruby
+module Letterpress
+  class User < Blueprint(ProxyMethods)
+    default do
+      #...
+    end
+
+    def self.make
+     user = super
+     # do something with the proxy object before returning it
+     user.password =  "I always have this value"
+     user
+    end
+  end
+end
+
+user = User.make.new
+user.password # => "I always have this value"
+```
+
+Compatibility
+-------------
+
+Ruby version 1.9.2 and 1.9.3 and Rails version 3.1
+
+[GemTesters](http://test.rubygems.org/gems/letterpress) has
+ more information on which platforms Letterpress is tested.
+ 
+
+Test
+-------------------------
+
+    gem install rubygems-test
+    gem test letterpress
+
+
+For more info see: [GemTesters](http://test.rubygems.org/)
+
+Where
+-----
+* [Letterpress @ Github](http://github.com/unders/letterpress)
+* [Letterpress @ GemTesters](http://test.rubygems.org/gems/letterpress)
+* [Letterpress @ Rubygems](http://rubygems.org/gems/letterpress)
+* [Letterpress @ Rubydoc](http://rubydoc.info/gems/letterpress)
+* [Letterpress @ Travis](http://travis-ci.org/#!/unders/letterpress)
 
 ## Contributing
 

data/lib/letterpress/blueprint.rb

@@ -33,7 +33,7 @@ module Letterpress
         end
 
         default = ghosts.fetch(:default, {})
-        (default.keys - blueprint_keys).each do |key|
+        (default.keys - blueprint_keys - options.keys).each do |key|
           hash[key] = default.send(key)
         end
 

data/lib/letterpress/version.rb

@@ -1,3 +1,3 @@
 module Letterpress
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letterpress
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-13 00:00:00.000000000 Z
+date: 2012-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord