ork 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d614293fd63e1d8d2a8de96cfb92ad40c09ebdc5
-  data.tar.gz: f487220a7969011adfe79399feb8ddcecc0d7187
+  metadata.gz: 609ee14359a522c9a80be687981cf6280fb2f2ea
+  data.tar.gz: d2b93d067769324259a9d48daebaff978a6e32c6
 SHA512:
-  metadata.gz: 39953ee12661946b11f55e278253d8726871ff9b8d3eb3c389e9d2ba447460f8c959048c99b9d6ade5a7992974297bc7bc78d8b55ba0e7c9366c82b6492fb9ba
-  data.tar.gz: 7b565b3a8ff7901cc7457464a335a54b0c5c1a1f53cf159f87815e4402a250d168bbd275da6f7a4a12a8621c59be86e53e08cf5066e10c9eb5428ea632a6cc03
+  metadata.gz: beb105369966731ad130fb658f7586defa8d8d2c64f12e1438a3c6fad6946e75cf181a836d4c197f308020d1178733559ff76494f85e812691bfd35c096c71fe
+  data.tar.gz: caa7d2aff4293bc60f84cc9b85b228389447aa76ecac6ac291b85ff0ac23d059d2ec552eb4f7b00025fb4402d2b3db82a2eee27a67b26402c6f6c37fe9b219e6

data/README.md

@@ -1,45 +1,173 @@
-# `ork`
+# Ork
 [![Gem Version](https://badge.fury.io/rb/ork.png)](http://badge.fury.io/rb/ork)
-[![Build Status](https://secure.travis-ci.org/eMancu/ork.png)](http://travis-ci.org/eMancu/ork)
-[![Code Climate](https://codeclimate.com/github/eMancu/ork.png)](https://codeclimate.com/github/eMancu/ork)
-[![Coverage Status](https://coveralls.io/repos/eMancu/ork/badge.png)](https://coveralls.io/r/eMancu/ork)
-[![Dependency Status](https://gemnasium.com/eMancu/ork.png)](https://gemnasium.com/eMancu/ork)
+[![Build Status](https://secure.travis-ci.org/emancu/ork.png)](http://travis-ci.org/emancu/ork)
+[![Code Climate](https://codeclimate.com/github/emancu/ork.png)](https://codeclimate.com/github/emancu/ork)
+[![Coverage Status](https://coveralls.io/repos/emancu/ork/badge.png)](https://coveralls.io/r/emancu/ork)
+[![Dependency Status](https://gemnasium.com/emancu/ork.png)](https://gemnasium.com/emancu/ork)
 
-`ork` is a small Ruby modeling layer for **Riak**, Basho's distributed database inspired by [Ohm](http://ohm.keyvalue.org).
+Ork is a small Ruby modeling layer for **Riak** database, inspired by [Ohm](http://ohm.keyvalue.org).
 
 ## Dependencies
 
 `ork` requires Ruby 1.9 or later and the `riak-client` gem to connect to **Riak**.
 
+Install dependencies using `dep` is easy as run:
+
+    dep install
+
+## Installation
+
+Install [Riak](http://basho.com/riak/) with your package manager:
+
+    $ brew install riak
+
+Or download it from [Riak's download page](http://docs.basho.com/riak/latest/downloads/)
+
+Once you have it installed, you can execute `riak start` and it will run on `localhost:8098` by default.
+
+If you don't have Ork, try this:
+
+    $ gem install ork
+
 ## Getting started
 
-## Attributes
+Ork helps you to focus your energy on modeling and designing the object collaborations without worry about how Riak works.
+Take a look at the example below:
+
+### Example
+
+```ruby
+class Post
+  include Ork::Document
+
+  attribute :name
+  attribute :age, default: 18
+
+  index :age
+  unique :name
+end
+
+class Comment
+  include Ork::Document
+
+  attribute :text
+  reference :post, :Post
+end
+```
+
+It also gives you some helpful **class methods**:
+
+
+| Class Method | Description                                      | Example (ruby)           |
+|:-------------|:-------------------------------------------------|:-------------------------|
+| bucket       | `Riak::Bucket` The bucket assigned to this class | `#<Riak::Bucket {post}>` |
+| bucket_name  | `String` The bucket name                         | `"post"`                 |
+| attributes   | `Array` Attributes declared                      | `[:name, :age]`          |
+| indices      | `Array` Indices declared                         | `[:age]`                 |
+| uniques      | `Array` Unique indices declared                  | `[:name]`                |
+| embedding    | `Array` Embedded attributes declared             | `[:post]`                |
+| defaults     | `Hash` Defaults for attributes                   | `{:age=>18}`             |
+
+
+And for **instance methods** it defines:
+
+| Instance Method                    | Description                                       |
+|:-----------------------------------|:--------------------------------------------------|
+| new?                               | `Bool` Answer if its a new instance or not.       |
+| embeddable?                        | `Bool` Answer if its an embeddable object or not. |
+| update(_attr_)                     | `Bool` Update model attributes and save it.       |
+| update_attributes(_attr_)          | `Array` Update model attributes.                  |
+| update_embedded_attributes(_attr_) | `Array` Update embedded model attributes.         |
+| reload                             | `<class>` Preload all the attributes from Riak.   |
+| save                               | `Bool` Persist document.                          |
+| delete                             | `Bool` Delete the document from Riak.             |
 
-Ork::Model provides one attribute type:
 
-- Ork::Model.attribute attribute
 
-And three meta types:
+# Modeling
+> Embeddable objects are those with `include Ork::Embeddable` and they can not be saved
+> without a parent.
 
-- Ork::Model.reference  reference
-- Ork::Model.referenced referenced
-- Ork::Model.collection collection
 
-### attribute
+Core behaviour of `Ork::Model`.
 
-An `attribute` is just any value that can be stored.
+## attribute
 
-### reference
+An `attribute` is just any value that can be stored. It is composed of a `:name` and an optional `hash`.
+
+```ruby
+attribute :age, default: 18
+```
+
+#### Options
+
+- `default: nil` set to the attribute a _value_ by default.
+
+- `accessors: [:reader, :writer]` defines which accessors will be defined
+  * `:reader` a.k.a **attr_reader**, create a method to read the value.
+  * `:writer` a.k.a **attr_writer**, create a method to write the value.
+  * `:question` create a question method. Perfect for **bool** attributes.
+
+
+## reference
 
 It's a special kind of attribute that references another model.
 Internally, Ork will keep a pointer to the model (its ID), but you get
 accessors that give you real instances. You can think of it as the model
 containing the foreign key to another model.
 
-### referenced
+```ruby
+reference :user, :User
+```
+
+## referenced
 
 Provides an accessor to search for _one_ model that `reference` the current model.
 
-### collection
+```ruby
+referenced :comment, :Comment
+```
+
+## collection
 
 Provides an accessor to search for _all_ models that `reference` the current model.
+
+```ruby
+collection :comments, :Comment
+```
+
+## embed
+> Only accepts embeddable objects.
+
+It's a special kind of attribute that embeds another model.
+Internally, Ork will keep the object as an attribute, but you get
+accessors that give you real instances.
+
+```ruby
+embed :comment, :Comment
+```
+
+## embed_collection
+> Only accepts embeddable objects.
+
+Provides an accessor for _all_ models that are `embedded` into the current model.
+It also provides a method for _adding_ objects to this collection.
+
+```ruby
+embed_collection :comments, :Comment
+
+# It provides
+def add_comments(a_comment)
+  # code
+end
+```
+
+
+## embedded
+> Only for embeddable objects.
+
+Provides an accessor to the object that `embeds` the current model.
+
+```ruby
+embedded :post, :Post
+```

data/lib/ork/embedded.rb

@@ -0,0 +1,48 @@
+require_relative 'model'
+
+module Ork
+  module Embeddable
+
+    def self.included(klass)
+      klass.send(:include, Ork::Model)
+      klass.extend(Ork::Model::Embedded::ClassMethods)
+    end
+
+    def embeddable?
+      true
+    end
+
+    def __parent
+      @attributes[model.__parent_key] or raise Ork::ParentMissing
+    end
+
+    def __parent=(object)
+      @attributes[model.__parent_key] = object
+    end
+
+    # Check for equality by doing the following assertions:
+    #
+    # 1. That the passed model is of the same type.
+    # 2. That they have the same attributes.
+    #
+    # How it was developed, 2 implies 1.
+    #
+    def ==(other)
+      other.kind_of?(model) &&
+        __persist_attributes == other.__persist_attributes &&
+        other.attributes[model.__parent_key] == @attributes[model.__parent_key]
+    end
+    alias :eql? :==
+
+    # Pretty print for the model
+    #
+    #  Example:
+    #
+    #    User.new(name: 'John').inspect
+    #    # => #<User {:name=>"John"}>
+    #
+    def inspect
+      "#<#{model} #{attributes.inspect}>"
+    end
+  end
+end

data/lib/ork/errors.rb

@@ -0,0 +1,8 @@
+module Ork
+  class Error < StandardError; end
+  class IndexNotFound < RuntimeError; end
+  class UniqueIndexViolation < RuntimeError; end
+
+  class NotAnEmbeddableObject < RuntimeError; end
+  class ParentMissing < RuntimeError; end
+end

data/lib/ork/model/associations.rb

@@ -6,7 +6,7 @@ module Ork::Model
     # Example:
     #
     #   class Post
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     reference :user, :User
     #   end
@@ -14,7 +14,7 @@ module Ork::Model
     #   # It's the same as:
     #
     #   class Post
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     attribute :user_id
     #     index :user_id
@@ -50,8 +50,8 @@ module Ork::Model
       end
 
       define_method(:"#{name}=") do |value|
-        @_memo.delete(name)
         send(writer, value ? value.id : nil)
+        @_memo[name] = value
       end
 
       define_method(name) do
@@ -66,13 +66,13 @@ module Ork::Model
     #
     # Example:
     #   class Post
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     reference :user, :User
     #   end
     #
     #   class User
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     referenced :post, :Post
     #   end
@@ -80,7 +80,7 @@ module Ork::Model
     #   # is the same as
     #
     #   class User
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     def post
     #       Post.find(:user_id => self.id)
@@ -89,8 +89,11 @@ module Ork::Model
     #
     def referenced(name, model, reference = to_reference)
       define_method name do
-        model = Ork::Utils.const(self.class, model)
-        model.find(:"#{reference}_id" => id).first
+        return nil if self.id.nil?
+        @_memo[name] ||= begin
+                           model = Ork::Utils.const(self.class, model)
+                           model.find(:"#{reference}_id", self.id).first
+                         end
       end
     end
 
@@ -98,13 +101,13 @@ module Ork::Model
     #
     # Example:
     #   class Post
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     reference :user, :User
     #   end
     #
     #   class User
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     collection :posts, :Post
     #   end
@@ -112,7 +115,7 @@ module Ork::Model
     #   # is the same as
     #
     #   class User
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     def posts
     #       Post.find(:user_id => self.id)
@@ -121,8 +124,106 @@ module Ork::Model
     #
     def collection(name, model, reference = to_reference)
       define_method name do
-        model = Ork::Utils.const(self.class, model)
-        model.find(:"#{reference}_id" => id)
+        return [] if self.id.nil?
+        @_memo[name] ||= begin
+                           model = Ork::Utils.const(self.class, model)
+                           model.find(:"#{reference}_id", self.id)
+                         end
+      end
+    end
+
+    # A macro for defining an attribute, and the accessors
+    # for a given model.
+    #
+    # Example:
+    #
+    #   class Post
+    #     include Ork::Document
+    #
+    #     embed :author, :Author
+    #   end
+    #
+    #   # It's the same as:
+    #
+    #   class Post
+    #     include Ork::Document
+    #
+    #     def author
+    #       @embedding[:author]
+    #     end
+    #
+    #     def author=(author)
+    #       @embedding[:author] = author
+    #       author.__parent = self
+    #     end
+    #   end
+    #
+    def embed(name, model)
+      embedding << name unless embedding.include?(name)
+
+      define_method(name) do
+        return nil unless @embedding.has_key? name
+        @_memo[name] ||= begin
+                           model = Ork::Utils.const(self.class, model)
+                           model.new(@embedding[name])
+                         end
+      end
+
+      define_method(:"#{name}=") do |object|
+        unless object.respond_to?(:embeddable?) && object.embeddable?
+          raise Ork::NotAnEmbeddableObject.new(object)
+        end
+
+        @embedding[name] = object.attributes
+        object.__parent = self
+
+        @_memo[name] = object
+      end
+    end
+
+    # A macro for find embedded objects of the same type, massive assign and
+    # syntactic sugar for add an object to the collection.
+    #
+    # Example:
+    #
+    #   class Post
+    #     include Ork::Document
+    #
+    #     embed_collection :authors, :Author
+    #   end
+    #
+    #   # It's the same as:
+    #
+    #   class Post
+    #     include Ork::Document
+    #
+    #     def authors
+    #       # An array of authors
+    #     end
+    #
+    #     def add_author(author)
+    #       # Add an author to the embed collection
+    #     end
+    #   end
+    #
+    def embed_collection(name, model)
+      embedding << name unless embedding.include?(name)
+
+      define_method(name) do
+        return [] unless @embedding.has_key? name
+
+        @_memo[name] ||= begin
+                           model = Ork::Utils.const(self.class, model)
+                           @embedding[name].map{|atts| model.new atts}
+                         end
+      end
+
+      define_method(:"add_#{name}") do |object|
+        raise Ork::NotAnEmbeddableObject.new(object) unless object.embeddable?
+
+        object.__parent = self
+        @_memo[name] << object unless @_memo[name].nil?
+        @embedding[name] = Array(@embedding[name]) << object.attributes
       end
     end
 

data/lib/ork/model/class_methods.rb

@@ -1,8 +1,11 @@
+require_relative 'index'
+
 module Ork::Model
   module ClassMethods
     attr_writer :bucket_name
 
     # Syntactic sugar for Model.new(atts).save
+    #
     def create(atts = {})
       new(atts).save
     end
@@ -19,14 +22,22 @@ module Ork::Model
       @bucket_name ||= self.to_s.downcase
     end
 
+    def embedding
+      @embedding ||= []
+    end
+
     def indices
-      @indices ||= []
+      @indices ||= {}
     end
 
     def uniques
       @uniques ||= []
     end
 
+    def defaults
+      @defaults ||= {}
+    end
+
     protected
 
     # Declares persisted attributes.
@@ -34,7 +45,7 @@ module Ork::Model
     #
     # Example:
     #   class User
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     attribute :name
     #   end
@@ -42,7 +53,7 @@ module Ork::Model
     #   # It's the same as:
     #
     #   class User
-    #     include Ork::Model
+    #     include Ork::Document
     #
     #     def name
     #       @attributes[:name]
@@ -53,37 +64,112 @@ module Ork::Model
     #     end
     #   end
     #
-    def attribute(name, cast = nil)
+    def attribute(name, options = {})
       attributes << name unless attributes.include?(name)
+      defaults[name] = options[:default] if options.has_key?(:default)
 
-      if cast
-        define_method(name) do
-          cast[@attributes[name]]
-        end
-      else
-        define_method(name) do
-          @attributes[name]
-        end
+      if options.has_key?(:accessors)
+        to_define = Array(options[:accessors]) & accessor_options
+      else # Default methods
+        to_define = [:reader, :writer]
       end
 
-      define_method(:"#{name}=") do |value|
-        @attributes[name] = value
-      end
+      to_define.each{|m| send("#{m}_for", name) }
     end
 
-    # Index any method on your model. Once you index a method, you can
-    # use it in `find` statements.
-    def index(attribute)
-      indices << attribute unless indices.include?(attribute)
+    # Index any attribute on your model. Once you index an attribute,
+    # you can use it in `find` statements.
+    #
+    def index(name)
+      indices[name] = Index.new(name) unless indices.include?(name)
     end
 
-    # Create a unique index for any method on your model.
+    # Create a 'unique index' for any method on your model.
+    # Actually it creates a regular index, but it checks if
+    # it's repeated just before persist the new values.
     #
     # Note: if there is a conflict while saving, an
     # `Ork::UniqueIndexViolation` violation is raised.
     #
     def unique(attribute)
       uniques << attribute unless uniques.include?(attribute)
+      index(attribute)
+    end
+
+    private
+
+    # Valid options for attribute accessor value
+    #
+    def accessor_options
+      [:reader, :writer, :question]
+    end
+
+    # Create reader method
+    #
+    def reader_for(name)
+      define_method(name) do
+        @attributes[name]
+      end
+    end
+
+    # Create writer method
+    #
+    def writer_for(name)
+      define_method(:"#{name}=") do |value|
+        @attributes[name] = value
+      end
+    end
+
+    # Create question method
+    #
+    def question_for(name)
+      define_method(:"#{name}?") do
+        !!@attributes[name]
+      end
     end
   end
+
+  module Embedded
+    module ClassMethods
+      attr_accessor :__parent_key
+
+      # Declares parent accessors for embedded objects and set the parent key
+      #
+      # Example:
+      #   class Comment
+      #     include Ork::Embeddable
+      #
+      #     embedded :post, :Post
+      #   end
+      #
+      #   # It's the same as:
+      #
+      #   class Comment
+      #     include Ork::Embeddable
+      #
+      #     def post
+      #       @attributes[:post]
+      #     end
+      #
+      #     def post=(post)
+      #       @attributes[:post] = post
+      #     end
+      #   end
+      #
+      def embedded(name, model)
+        @__parent_key = name
+
+        define_method(name) do
+          @attributes[name]
+        end
+
+        define_method(:"#{name}=") do |object|
+          raise Ork::ParentMissing if object.nil?
+
+          @attributes[name] = object
+        end
+      end
+    end
+  end
+
 end