friendly 0.3.5 → 0.4.0

data/.document

@@ -1,2 +1,2 @@
-README.rdoc
+README.md
 lib/**/*.rb

data/.gitignore

@@ -21,3 +21,6 @@ pkg
 ## PROJECT::SPECIFIC
 test.rb
 test_active_record.rb
+spec/config.yml
+.yardoc
+doc

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+Changelog
+=========
+
+### 0.4.0 (master)
+
+  * (jamesgolick) Add scope chaining. See the README and the docs for Friendly::Scope.
+  * (jamesgolick) Add has_many association.
+  * (jamesgolick) Add ad-hoc scopes. See the docs for Document.scope.
+  * (jamesgolick) Add named_scope functionality. See the docs for Document.named_scope.
+  * (jeffrafter + jamesgolick) DDL generation now supports custom types. Previously, it would only work with types that Sequel already supported. Now, if you want to register a custom type, use Friendly::Attribute.register_type(klass, sql_type, &conversion_method).
+

data/CONTRIBUTORS.md

@@ -0,0 +1,6 @@
+Contributors to Friendly
+========================
+
+  * James Golick     - http://jamesgolick.com (github: jamesgolick)
+  * Jonathan Palardy - http://technotales.wordpress.com (github: jpalardy)
+  * Jeff Rafter      - http://socialorange.com (github: jeffrafter)

data/README.md

@@ -1,5 +1,5 @@
 Friendly
-=======
+========
 
 ### Short Version
 
@@ -112,6 +112,98 @@ Currently, only caching by id is supported, but caching of arbitrary indexes is
 
 __We're seeing a 99.8% cache hit rate in production with this code.__
 
+Scopes
+======
+
+### Named Scopes
+
+It's possible to create a scope that you can refer to by name:
+
+    class Post
+      attribute :author, String
+
+      named_scope :by_james, :author => "James"
+    end
+
+Calling the scope will provide you with a Friendly:Scope object:
+
+    Post.by_james #=> #<Friendly::Scope>
+
+That scope object supports a variety of methods. Calling any of the methods is the equivalent of calling those methods directly on Document with the scope's parameters.
+
+  e.g.
+
+    Post.by_james.all == Post.all(:author => "James")
+    Post.by_james.first == Post.first(:author => "James")
+    Post.by_james.paginate # => #<WillPaginate::Collection>
+    Post.by_james.build.name == "James"
+    @post = Post.by_james.create
+    @post.new_record? # => false
+    @post.name # => "James"
+
+Each of the methods also accepts override parameters. The APIs are the same as on Document.
+
+    Post.by_james.all(:author => "Steve") == Post.all(:author => "Steve")
+
+You can also compose arbitrary combinations of scopes with simple chaining.
+    
+    class Post
+      # ... snip ...
+      named_scope :recent, :order! => :created_at.desc, :limit! => 4
+      indexes     :name, :created_at
+    end
+
+    Post.by_james.recent == Post.all(:name   => "James", 
+                                     :order! => :created_at.desc, 
+                                     :limit!  => 4)
+
+If two parameters conflict, the right-most scope takes precedence.
+
+### Ad-hoc Scopes
+
+You can also create a scope object on the fly:
+
+    Post.scope(:author => "Steve")
+    
+The object you get is identical to the one you get from a named_scope. So, see above for the API.
+
+Associations
+============
+
+Friendly currently only supports has\_many associations. 
+
+Creating a has\_many is as simple as setting up the necessary association and foreign key.
+
+_Note: Make sure that the target model is indexed on the foreign key. If it isn't, querying the association will raise Friendly::MissingIndex._
+
+e.g.
+
+    class Post
+      attribute :user_id, Friendly::UUID
+      indexes   :user_id
+    end
+     
+    class User
+      has_many :posts
+    end
+    
+    @user = User.create
+    @post = @user.posts.create
+    @user.posts.all == [@post] # => true
+
+Friendly defaults the foreign key to class_name_id just like ActiveRecord. It also converts the name of the association to the name of the target class just like ActiveRecord does.
+
+The biggest difference in semantics between Friendly's has\_many and active\_record's is that Friendly's just returns a Friendly::Scope object. If you want all the associated objects, you have to call #all to get them. 
+
+You can also use any other Friendly::Scope method like scope chaining.
+
+    # note: the Post.recent scope is defined in the above section
+    @user.posts.recent == Post.all(:user_id => @user.id,
+                                   :order!  => :created_at.desc, 
+                                   :limit!  => 4)
+
+See the section above or the Friendly::Scope docs for more details.
+
 Installation
 ============
 

data/Rakefile

@@ -13,6 +13,7 @@ begin
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "cucumber", ">= 0"
     gem.add_development_dependency "jferris-mocha"
+    gem.add_development_dependency "memcached"
     gem.add_dependency "sequel", ">= 3.7.0"
     gem.add_dependency "json"
     gem.add_dependency "activesupport"

data/VERSION

@@ -1 +1 @@
-0.3.5
+0.4.0

data/friendly.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{friendly}
-  s.version = "0.3.5"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["James Golick"]
-  s.date = %q{2009-12-17}
+  s.date = %q{2009-12-22}
   s.description = %q{}
   s.email = %q{jamesgolick@gmail.com}
   s.extra_rdoc_files = [
@@ -20,6 +20,8 @@ Gem::Specification.new do |s|
     ".document",
      ".gitignore",
      "APACHE-LICENSE",
+     "CHANGELOG.md",
+     "CONTRIBUTORS.md",
      "LICENSE",
      "README.md",
      "Rakefile",
@@ -27,6 +29,9 @@ Gem::Specification.new do |s|
      "examples/friendly.yml",
      "friendly.gemspec",
      "lib/friendly.rb",
+     "lib/friendly/associations.rb",
+     "lib/friendly/associations/association.rb",
+     "lib/friendly/associations/set.rb",
      "lib/friendly/attribute.rb",
      "lib/friendly/boolean.rb",
      "lib/friendly/cache.rb",
@@ -37,8 +42,11 @@ Gem::Specification.new do |s|
      "lib/friendly/document_table.rb",
      "lib/friendly/index.rb",
      "lib/friendly/memcached.rb",
+     "lib/friendly/named_scope.rb",
      "lib/friendly/newrelic.rb",
      "lib/friendly/query.rb",
+     "lib/friendly/scope.rb",
+     "lib/friendly/scope_proxy.rb",
      "lib/friendly/sequel_monkey_patches.rb",
      "lib/friendly/storage.rb",
      "lib/friendly/storage_factory.rb",
@@ -49,12 +57,14 @@ Gem::Specification.new do |s|
      "lib/friendly/translator.rb",
      "lib/friendly/uuid.rb",
      "rails/init.rb",
+     "spec/config.yml.example",
      "spec/fakes/data_store_fake.rb",
      "spec/fakes/database_fake.rb",
      "spec/fakes/dataset_fake.rb",
      "spec/fakes/document.rb",
      "spec/fakes/serializer_fake.rb",
      "spec/fakes/time_fake.rb",
+     "spec/integration/ad_hoc_scopes_spec.rb",
      "spec/integration/basic_object_lifecycle_spec.rb",
      "spec/integration/batch_insertion_spec.rb",
      "spec/integration/convenience_api_spec.rb",
@@ -62,12 +72,17 @@ Gem::Specification.new do |s|
      "spec/integration/default_value_spec.rb",
      "spec/integration/find_via_cache_spec.rb",
      "spec/integration/finder_spec.rb",
+     "spec/integration/has_many_spec.rb",
      "spec/integration/index_spec.rb",
+     "spec/integration/named_scope_spec.rb",
      "spec/integration/pagination_spec.rb",
+     "spec/integration/scope_chaining_spec.rb",
      "spec/integration/table_creator_spec.rb",
      "spec/integration/write_through_cache_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb",
+     "spec/unit/associations/association_spec.rb",
+     "spec/unit/associations/set_spec.rb",
      "spec/unit/attribute_spec.rb",
      "spec/unit/cache_by_id_spec.rb",
      "spec/unit/cache_spec.rb",
@@ -78,7 +93,10 @@ Gem::Specification.new do |s|
      "spec/unit/friendly_spec.rb",
      "spec/unit/index_spec.rb",
      "spec/unit/memcached_spec.rb",
+     "spec/unit/named_scope_spec.rb",
      "spec/unit/query_spec.rb",
+     "spec/unit/scope_proxy_spec.rb",
+     "spec/unit/scope_spec.rb",
      "spec/unit/storage_factory_spec.rb",
      "spec/unit/storage_proxy_spec.rb",
      "spec/unit/translator_spec.rb",
@@ -139,6 +157,7 @@ Gem::Specification.new do |s|
      "spec/fakes/document.rb",
      "spec/fakes/serializer_fake.rb",
      "spec/fakes/time_fake.rb",
+     "spec/integration/ad_hoc_scopes_spec.rb",
      "spec/integration/basic_object_lifecycle_spec.rb",
      "spec/integration/batch_insertion_spec.rb",
      "spec/integration/convenience_api_spec.rb",
@@ -146,11 +165,16 @@ Gem::Specification.new do |s|
      "spec/integration/default_value_spec.rb",
      "spec/integration/find_via_cache_spec.rb",
      "spec/integration/finder_spec.rb",
+     "spec/integration/has_many_spec.rb",
      "spec/integration/index_spec.rb",
+     "spec/integration/named_scope_spec.rb",
      "spec/integration/pagination_spec.rb",
+     "spec/integration/scope_chaining_spec.rb",
      "spec/integration/table_creator_spec.rb",
      "spec/integration/write_through_cache_spec.rb",
      "spec/spec_helper.rb",
+     "spec/unit/associations/association_spec.rb",
+     "spec/unit/associations/set_spec.rb",
      "spec/unit/attribute_spec.rb",
      "spec/unit/cache_by_id_spec.rb",
      "spec/unit/cache_spec.rb",
@@ -161,7 +185,10 @@ Gem::Specification.new do |s|
      "spec/unit/friendly_spec.rb",
      "spec/unit/index_spec.rb",
      "spec/unit/memcached_spec.rb",
+     "spec/unit/named_scope_spec.rb",
      "spec/unit/query_spec.rb",
+     "spec/unit/scope_proxy_spec.rb",
+     "spec/unit/scope_spec.rb",
      "spec/unit/storage_factory_spec.rb",
      "spec/unit/storage_proxy_spec.rb",
      "spec/unit/translator_spec.rb"
@@ -175,6 +202,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<cucumber>, [">= 0"])
       s.add_development_dependency(%q<jferris-mocha>, [">= 0"])
+      s.add_development_dependency(%q<memcached>, [">= 0"])
       s.add_runtime_dependency(%q<sequel>, [">= 3.7.0"])
       s.add_runtime_dependency(%q<json>, [">= 0"])
       s.add_runtime_dependency(%q<activesupport>, [">= 0"])
@@ -183,6 +211,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<cucumber>, [">= 0"])
       s.add_dependency(%q<jferris-mocha>, [">= 0"])
+      s.add_dependency(%q<memcached>, [">= 0"])
       s.add_dependency(%q<sequel>, [">= 3.7.0"])
       s.add_dependency(%q<json>, [">= 0"])
       s.add_dependency(%q<activesupport>, [">= 0"])
@@ -192,6 +221,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<cucumber>, [">= 0"])
     s.add_dependency(%q<jferris-mocha>, [">= 0"])
+    s.add_dependency(%q<memcached>, [">= 0"])
     s.add_dependency(%q<sequel>, [">= 3.7.0"])
     s.add_dependency(%q<json>, [">= 0"])
     s.add_dependency(%q<activesupport>, [">= 0"])

data/lib/friendly.rb

@@ -1,3 +1,4 @@
+require 'friendly/associations'
 require 'friendly/attribute'
 require 'friendly/boolean'
 require 'friendly/cache'
@@ -8,8 +9,11 @@ require 'friendly/document'
 require 'friendly/document_table'
 require 'friendly/index'
 require 'friendly/memcached'
+require 'friendly/named_scope'
 require 'friendly/query'
 require 'friendly/sequel_monkey_patches'
+require 'friendly/scope'
+require 'friendly/scope_proxy'
 require 'friendly/storage_factory'
 require 'friendly/storage_proxy'
 require 'friendly/translator'

data/lib/friendly/associations.rb

@@ -0,0 +1,7 @@
+require 'friendly/associations/association'
+require 'friendly/associations/set'
+
+module Friendly
+  module Associations
+  end
+end

data/lib/friendly/associations/association.rb

@@ -0,0 +1,34 @@
+module Friendly
+  module Associations
+    class Association
+      attr_reader :owner_klass, :name
+
+      def initialize(owner_klass, name, options = {})
+        @owner_klass = owner_klass
+        @name        = name
+        @class_name  = options[:class_name]
+        @foreign_key = options[:foreign_key]
+      end
+
+      def klass
+        @klass ||= class_name.constantize
+      end
+
+      def foreign_key
+        @foreign_key ||= [owner_klass_name, :id].join("_").to_sym
+      end
+
+      def class_name
+        @class_name ||= name.to_s.classify
+      end
+
+      def owner_klass_name
+        owner_klass.name.to_s.underscore.singularize
+      end
+
+      def scope(document)
+        klass.scope(foreign_key => document.id)
+      end
+    end
+  end
+end

data/lib/friendly/associations/set.rb

@@ -0,0 +1,37 @@
+module Friendly
+  module Associations
+    class Set
+      attr_reader :klass, :association_klass, :associations
+
+      def initialize(klass, association_klass = Association)
+        @klass             = klass
+        @association_klass = association_klass
+        @associations      = {}
+      end
+
+      def add(name, options = {})
+        associations[name] = association_klass.new(klass, name, options)
+        add_association_accessor(name)
+      end
+
+      def get_scope(name, document)
+        get(name).scope(document)
+      end
+
+      def get(name)
+        associations[name]
+      end
+
+      protected
+        def add_association_accessor(name)
+          klass.class_eval do
+            eval <<-__END__
+            def #{name}
+              self.class.association_set.get_scope(:#{name}, self)
+            end
+            __END__
+          end
+        end
+    end
+  end
+end

data/lib/friendly/attribute.rb

@@ -1,14 +1,36 @@
-require 'friendly/boolean'
-require 'friendly/uuid'
-
 module Friendly
   class Attribute
-    CONVERTERS = {}
-    CONVERTERS[UUID]    = lambda { |s| UUID.new(s) }
-    CONVERTERS[Integer] = lambda { |s| s.to_i }
-    CONVERTERS[String]  = lambda { |s| s.to_s }
-    CONVERTERS[Boolean] = lambda { |s| s }
+    class << self
+      def register_type(type, sql_type, &block)
+        sql_types[type.name] = sql_type
+        converters[type]     = block
+      end
+
+      def deregister_type(type)
+        sql_types.delete(type.name)
+        converters.delete(type)
+      end
+        
+      def sql_type(type)
+        sql_types[type.name]
+      end
+
+      def sql_types
+        @sql_types ||= {}
+      end
 
+      def converters
+        @converters ||= {}
+      end
+
+      def custom_type?(klass)
+        !sql_type(klass).nil?
+      end
+    end
+
+    converters[Integer] = lambda { |s| s.to_i }
+    converters[String]  = lambda { |s| s.to_s }
+    
     attr_reader :klass, :name, :type, :default_value
 
     def initialize(klass, name, type, options = {})
@@ -25,7 +47,7 @@ module Friendly
 
     def convert(value)
       assert_converter_exists(value)
-      CONVERTERS[type].call(value)
+      converters[type].call(value)
     end
 
     def default
@@ -37,7 +59,7 @@ module Friendly
         nil
       end
     end
-
+      
     protected
       def build_accessors
         n = name
@@ -55,11 +77,15 @@ module Friendly
       end
 
       def assert_converter_exists(value)
-        unless CONVERTERS.has_key?(type)
+        unless converters.has_key?(type)
           msg = "Can't convert #{value} to #{type}. 
                  Add a custom converter to Friendly::Attribute::CONVERTERS."
           raise NoConverterExists, msg
         end
       end
+
+      def converters
+        self.class.converters
+      end
   end
 end