gom 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Philipp Brüll
+
+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.rdoc

@@ -0,0 +1,111 @@
+
+= Generic Object Mapper
+
+The Generic Object Mapper maps ruby objects to different storage engines and vice versa. The interface is designed to
+be small and try to avoid any unnecessary dependencies between GOM and your code. On the other side, the storage engine
+is plugged-in via an adapter interface. Currently, the following adapters are provided.
+
+* filesystem - http://github.com/phifty/gom-filesystem-adapter
+* couchdb - http://github.com/phifty/gom-couchdb-adapter
+
+== Configuration
+
+At the beginning of your program the configuration should be read with the following command.
+
+  GOM::Storage::Configuration.read filename
+
+The configuration file should be written in the YML format and look like...
+
+  storage_name:
+    adapter: filesystem
+    directory: /var/project-name/data
+
+Look at the adapter pages to see the adapter-specific configuration values.
+
+== How to use
+
+=== Storing an object
+
+To store an object just pass it to <tt>GOM::Storage.store</tt>.
+
+  class Book
+
+    attr_accessor :author_name
+    attr_accessor :pages
+
+  end
+
+  book = Book.new
+  book.author_name = "Mr. Storyteller"
+  book.pages = 1253
+
+  GOM::Storage.store book, :storage_name
+
+The storage name doesn't have to be specified. If it's missing, the object's previously use storage or the default
+storage is used.
+
+There is no base class needed for your model class. GOM inspects your object, reads all the instance variables and
+passes the values to specified store adapter. The first time an object is stored, an id is generated and assigned to
+the object. This id an be determined by calling <tt>GOM::Object.id</tt>.
+
+  book_id = GOM::Object.id book
+  # book_id => "storage_name:1234..."
+
+=== Fetching an object
+
+Once an object is stored, it can be easily brought back to life by using it's id to fetch it from the storage.
+
+  book = GOM::Storage.fetch book_id
+
+The storage name is encoded (prefixed) in the id and don't have to be specified. The classname of the object was also
+saved during the storage and the fetch instantiate a new object using the constructor. If the constructor requires
+arguments, <tt>nil</tt> will be passed for each of them. The internal state (the instance variables) will be
+overwritten anyway.
+
+=== Removing an object
+
+To remove an object from the storage, simply pass it to <tt>GOM::Storage.remove</tt>.
+
+  GOM::Storage.remove book
+
+It's also possible to use just the id to remove the assigned object.
+
+  GOM::Storage.remove book_id
+
+== Relations
+
+GOM does make a distinction between object properties and object relations. The properties are more atomic values that
+can be stored in a key/value-way and relations are links to more complex objects. Since in Ruby everything is an object,
+it's necessary to mark the relations. This is done by the following way.
+
+  class Book
+
+    attr_accessor :author
+
+  end
+
+  class Author
+
+    attr_accessor :name
+
+  end
+
+  author = Author.new
+  author.name = "Mr. Storyteller"
+
+  book = Book.new
+  book.author = GOM::Object.reference author
+
+The <tt>GOM::Object.reference</tt> call creates a proxy to the referenced object, that passes every call to it. For
+example, the call
+
+  book.author.name
+
+will return the instance variable <tt>@name</tt> ("Mr. Storyteller") from the author object.
+
+== Development
+
+Development has been done test-driven and the code follows at most the Clean Code paradigms. Code smells has been
+removed by using the reek[http://github.com/kevinrutherford/reek] code smell detector.
+
+This project is still experimental and under development. Any bug report and contribution is welcome!

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+gem 'rspec'
+gem 'reek'
+require 'rspec'
+require 'rake/rdoctask'
+require 'rspec/core/rake_task'
+require 'reek/rake/task'
+
+task :default => :spec
+
+namespace :gem do
+
+  desc "Builds the gem"
+  task :build do
+    system "gem build *.gemspec && mkdir -p pkg/ && mv *.gem pkg/"
+  end
+
+  desc "Builds and installs the gem"
+  task :install => :build do
+    system "gem install pkg/"
+  end
+
+end
+
+Reek::Rake::Task.new do |task|
+  task.fail_on_error = true
+end
+
+desc "Generate the rdoc"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.add [ "README.rdoc", "lib/**/*.rb" ]
+  rdoc.main = "README.rdoc"
+  rdoc.title = ""
+end
+
+desc "Run all specs in spec directory"
+RSpec::Core::RakeTask.new do |task|
+  task.pattern = "spec/gom/**/*_spec.rb"
+end
+
+namespace :spec do
+
+  desc "Run all integration specs in spec/acceptance directory"
+  RSpec::Core::RakeTask.new(:acceptance) do |task|
+    task.pattern = "spec/acceptance/**/*_spec.rb"
+  end
+
+end

data/lib/gom.rb

@@ -0,0 +1,7 @@
+
+module GOM
+
+  autoload :Object, File.join(File.dirname(__FILE__), "gom", "object")
+  autoload :Storage, File.join(File.dirname(__FILE__), "gom", "storage")
+
+end

data/lib/gom/object.rb

@@ -0,0 +1,23 @@
+
+module GOM
+
+  module Object
+
+    autoload :Id, File.join(File.dirname(__FILE__), "object", "id")
+    autoload :Injector, File.join(File.dirname(__FILE__), "object", "injector")
+    autoload :Inspector, File.join(File.dirname(__FILE__), "object", "inspector")
+    autoload :Mapping, File.join(File.dirname(__FILE__), "object", "mapping")
+    autoload :Proxy, File.join(File.dirname(__FILE__), "object", "proxy")
+
+    def self.id(object)
+      id = Mapping.id_by_object object
+      id ? id.to_s : nil
+    end
+
+    def self.reference(object)
+      Proxy.new object
+    end
+
+  end
+
+end

data/lib/gom/object/id.rb

@@ -0,0 +1,30 @@
+
+module GOM
+
+  module Object
+
+    # Value class for object ids.
+    class Id
+
+      attr_accessor :storage_name
+      attr_accessor :object_id
+
+      def initialize(id_or_storage_name = nil, object_id = nil)
+        @storage_name, @object_id = id_or_storage_name.is_a?(String) ?
+          (object_id.is_a?(String) ? [ id_or_storage_name, object_id ] : id_or_storage_name.split(":")) :
+          [ nil, nil ]
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && @storage_name == other.storage_name && @object_id == other.object_id
+      end
+
+      def to_s
+        "#{@storage_name}:#{@object_id}"
+      end
+
+    end
+
+  end
+
+end

data/lib/gom/object/injector.rb

@@ -0,0 +1,45 @@
+
+module GOM
+
+  module Object
+
+    # Injects the given properties into the given object.s
+    class Injector
+
+      attr_reader :object
+
+      def initialize(object, object_hash)
+        @object, @object_hash = object, object_hash
+      end
+
+      def perform
+        clear_instance_variables
+        write_properties
+        write_relations
+      end
+
+      private
+
+      def clear_instance_variables
+        @object.instance_variables.each do |name|
+          @object.send :remove_instance_variable, name
+        end
+      end
+
+      def write_properties
+        (@object_hash[:properties] || { }).each do |name, value|
+          @object.instance_variable_set :"@#{name}", value
+        end
+      end
+
+      def write_relations
+        (@object_hash[:relations] || { }).each do |name, value|
+          @object.instance_variable_set :"@#{name}", value
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/gom/object/inspector.rb

@@ -0,0 +1,55 @@
+
+module GOM
+
+  module Object
+
+    # Inspect an object and returns it's class and it's properties
+    class Inspector
+
+      attr_reader :object
+      attr_reader :object_hash
+
+      def initialize(object)
+        @object = object
+        @object_hash = { }
+      end
+
+      def perform
+        read_class
+        read_properties
+        read_relations
+      end
+
+      private
+
+      def read_class
+        @object_hash[:class] = @object.class.to_s
+      end
+
+      def read_properties
+        @object_hash[:properties] = { }
+        read_instance_variables do |key, value|
+          @object_hash[:properties][key] = value unless value.is_a?(GOM::Object::Proxy)
+        end
+      end
+
+      def read_relations
+        @object_hash[:relations] = { }
+        read_instance_variables do |key, value|
+          @object_hash[:relations][key] = value if value.is_a?(GOM::Object::Proxy)
+        end
+      end
+
+      def read_instance_variables
+        @object.instance_variables.each do |name|
+          key = name.to_s.sub(/^@/, "").to_sym
+          value = @object.instance_variable_get name
+          yield key, value
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/gom/object/mapping.rb

@@ -0,0 +1,61 @@
+
+module GOM
+
+  module Object
+
+    # Provides a mapping between objects and ids
+    class Mapping
+
+      def initialize
+        @map = { }
+      end
+
+      def put(object, id)
+        @map[object] = id
+      end
+
+      def object_by_id(id)
+        @map.respond_to?(:key) ? @map.key(id) : @map.index(id)
+      end
+
+      def id_by_object(object)
+        @map[object]
+      end
+
+      def remove_by_id(id)
+        @map.delete object_by_id(id)
+      end
+
+      def remove_by_object(object)
+        @map.delete object
+      end
+
+      def self.singleton
+        @mapping ||= self.new
+      end
+
+      def self.put(object, id)
+        self.singleton.put object, id
+      end
+
+      def self.object_by_id(id)
+        self.singleton.object_by_id id
+      end
+
+      def self.id_by_object(object)
+        self.singleton.id_by_object object
+      end
+
+      def self.remove_by_id(id)
+        self.singleton.remove_by_id id
+      end
+
+      def self.remove_by_object(object)
+        self.singleton.remove_by_object object
+      end
+
+    end
+
+  end
+
+end

data/lib/gom/object/proxy.rb

@@ -0,0 +1,44 @@
+
+module GOM
+
+  module Object
+
+    # The proxy that fetches an object if it's needed and simply passes method calls to it.
+    class Proxy
+
+      def initialize(object_or_id)
+        @object, @id = object_or_id.is_a?(GOM::Object::Id) ?
+          [ nil, object_or_id ] :
+          [ object_or_id, nil ]
+      end
+
+      def object
+        fetch_object unless @object
+        @object
+      end
+
+      def id
+        fetch_id unless @id
+        @id
+      end
+
+      def method_missing(method_name, *arguments, &block)
+        fetch_object unless @object
+        @object.send method_name, *arguments, &block
+      end
+
+      private
+
+      def fetch_object
+        @object = GOM::Storage::Fetcher.new(@id).object
+      end
+
+      def fetch_id
+        @id = GOM::Object::Mapping.id_by_object @object
+      end
+
+    end
+
+  end
+
+end