norman 0.1.0

data/lib/norman/active_model.rb

@@ -0,0 +1,122 @@
+require "active_model"
+
+module Norman
+  # Extend this module if you want {Active Model}[http://github.com/rails/rails/tree/master/activemodel]
+  # support. Active Model is an API provided by Rails to make any Ruby object
+  # behave like an Active Record model instance. You can read an older writeup
+  # about it {here}[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/].
+  module ActiveModel
+    def self.extended(base)
+      base.instance_eval do
+        extend  ClassMethods
+        include InstanceMethods
+        extend  ::ActiveModel::Naming
+        extend  ::ActiveModel::Translation
+        include ::ActiveModel::Validations
+        include ::ActiveModel::Serializers::JSON
+        include ::ActiveModel::Serializers::Xml
+        extend  ::ActiveModel::Callbacks
+        define_model_callbacks :save, :destroy
+      end
+    end
+
+    # Custom validations.
+    module Validations
+      # A uniqueness validator, similar to the one provided by Active Record.
+      class Uniqueness< ::ActiveModel::EachValidator
+        def validate_each(record, attribute, value)
+          return if record.persisted?
+          if attribute.to_sym == record.class.id_method
+            begin
+              if record.class.mapper[value]
+                record.errors[attribute] << "must be unique"
+              end
+            rescue Norman::NotFoundError
+            end
+          else
+            if record.class.all.detect {|x| x.send(attribute) == value}
+              record.errors[attribute] << "must be unique"
+            end
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      # Create and save a model instance, raising an exception if any errors
+      # occur.
+      def create!(*args)
+        new(*args).save!
+      end
+
+      # Validate the uniqueness of a field's value in a model instance.
+      def validates_uniqueness_of(*attr_names)
+        validates_with Validations::Uniqueness, _merge_attributes(attr_names)
+      end
+
+      def model_name
+        @model_name ||= ::ActiveModel::Name.new(self)
+      end
+    end
+
+    module InstanceMethods
+      def initialize(*args)
+        @new_record = true
+        super
+      end
+
+      def attributes
+        hash = to_hash
+        hash.keys.each {|k| hash[k.to_s] = hash.delete(k)}
+        hash
+      end
+
+      def keys
+        self.class.attribute_names
+      end
+
+      def to_model
+        self
+      end
+
+      def new_record?
+        @new_record
+      end
+
+      def persisted?
+        !new_record?
+      end
+
+      def save
+        run_callbacks(:save) do
+          @new_record = false
+          super
+        end
+      end
+
+      def save!
+        if !valid?
+          raise Norman::NormanError, errors.to_a.join(", ")
+        else
+          save
+        end
+      end
+
+      def to_param
+        to_id if persisted?
+      end
+
+      def to_key
+        [to_param] if persisted?
+      end
+
+      def destroy
+        run_callbacks(:destroy) { delete }
+      end
+
+      def update_attributes
+        run_callbacks(:save) { update }
+      end
+    end
+  end
+end

data/lib/norman/adapter.rb

@@ -0,0 +1,53 @@
+module Norman
+
+  # Adapters are responsible for persisting the database. This base adapter
+  # offers no persistence, all IO operations are just stubs. Adapters must also
+  # present the full database as a Hash to the mapper, and provide a `key`
+  # method that returns an  array with all the keys for the specified model
+  # class.
+  class Adapter
+
+    attr_reader :name
+    attr_reader :db
+
+    # @option options [String] :name The adapter name. Defaults to {#Norman.default_adapter_name}.
+    def initialize(options = {})
+      @name = options[:name] || Norman.default_adapter_name
+      load_database
+      Norman.register_adapter(self)
+    end
+
+    # Get a hash of all the data for the specified model class.
+    # @param klass [#to_s] The model class whose data to return.
+    def db_for(klass)
+      @db[klass.to_s] ||= {}
+    end
+
+    # Loads the database. For this adapter, that means simply creating a new
+    # hash.
+    def load_database
+      @db = {}
+    end
+
+    # These are all just noops for this adapter, which uses an in-memory hash
+    # and offers no persistence.
+
+    # Inheriting adapters can overload this method to export the data to a
+    # String.
+    def export_data
+      true
+    end
+
+    # Inheriting adapters can overload this method to load the data from some
+    # kind of storage.
+    def import_data
+      true
+    end
+
+    # Inheriting adapters can overload this method to persist the data to some
+    # kind of storage.
+    def save_database
+      true
+    end
+  end
+end

data/lib/norman/adapters/cookie.rb

@@ -0,0 +1,55 @@
+require "active_support"
+require "active_support/message_verifier"
+require "zlib"
+
+module Norman
+  module Adapters
+
+    # Norman's cookie adapter allows you to store a Norman database inside
+    # a zipped and signed string suitable for setting as a cookie. This can be
+    # useful for modelling things like basic shopping carts or form wizards.
+    # Keep in mind the data is signed, so it can't be tampered with. However,
+    # the data is not *encrypted*, so somebody that wanted to could unzip and
+    # load the cookie data to see what's inside. So don't send this data
+    # client-side if it's at all sensitive.
+    class Cookie < Adapter
+
+      attr :verifier
+      attr_accessor :data
+
+      MAX_DATA_LENGTH = 4096
+
+      def self.max_data_length
+        MAX_DATA_LENGTH
+      end
+
+      def initialize(options)
+        @data     = options[:data]
+        @verifier = ActiveSupport::MessageVerifier.new(options[:secret])
+        super
+      end
+
+      def export_data
+        cookie = verifier.generate(Zlib::Deflate.deflate(Marshal.dump(db)))
+        length = cookie.bytesize
+        if length > Cookie.max_data_length
+          raise(NormanError, "Data is %s bytes, cannot exceed %s" % [length, Cookie.max_data_length])
+        end
+        cookie
+      end
+
+      def import_data
+        data.blank? ? {} : Marshal.load(Zlib::Inflate.inflate(verifier.verify(data)))
+      end
+
+      def load_database
+        @db = import_data
+        @db.map(&:freeze)
+      end
+
+      def save_database
+        @data = export_data
+      end
+    end
+  end
+end

data/lib/norman/adapters/file.rb

@@ -0,0 +1,38 @@
+module Norman
+  module Adapters
+    # Loads and saves hash database from a Marshal.dump file.
+    class File < Adapter
+
+      attr_reader :file_path
+      attr :lock
+
+      def initialize(options)
+        @file_path = options[:file]
+        @lock      = Mutex.new
+        super
+      end
+
+      def load_database
+        @db = import_data
+        @db.blank? ? @db = {} : @db.map(&:freeze)
+      rescue Errno::ENOENT
+        # @TODO warn via logger when file doesn't exist
+        @db = {}
+      end
+
+      def export_data
+        Marshal.dump(db)
+      end
+
+      def import_data
+        Marshal.load(::File.read(file_path))
+      end
+
+      def save_database
+        @lock.synchronize do
+          ::File.open(file_path, "w") {|f| f.write(export_data)}
+        end
+      end
+    end
+  end
+end

data/lib/norman/adapters/yaml.rb

@@ -0,0 +1,17 @@
+require "yaml"
+
+module Norman
+  module Adapters
+    # An Adapter that uses YAML for its storage.
+    class YAML < File
+
+      def import_data
+        data = ::YAML.load(::File.read(file_path))
+      end
+
+      def export_data
+        db.to_yaml
+      end
+    end
+  end
+end

data/lib/norman/hash_proxy.rb

@@ -0,0 +1,55 @@
+module Norman
+  # Wrapper around hash instances that allows values to be accessed as symbols,
+  # strings or method invocations. It behaves similary to OpenStruct, with the
+  # fundamental difference being that you instantiate *one* HashProxy instance
+  # and reassign its Hash during a loop in order to avoid creating garbage.
+  class HashProxy
+    attr :hash
+
+    # Allows accessing a hash attribute as a method.
+    def method_missing(symbol)
+      hash[symbol] or raise NoMethodError
+    end
+
+    # Allows accessing a hash attribute as hash key, either a string or symbol.
+    def [](value)
+      hash[value || value.to_sym || value.to_s]
+    end
+
+    # Remove the hash.
+    def clear
+      @hash = nil
+    end
+
+    # Assign the value to hash and return self.
+    def using(hash)
+      @hash = hash ; self
+    end
+
+    # Set the hash to use while calling the block. When the block ends, the
+    # hash is unset.
+    def with(hash, &block)
+      yield using hash ensure clear
+    end
+  end
+
+  # Like HashProxy, but proxies access to two or more Hash instances.
+  class HashProxySet
+
+    attr :proxies
+
+    def initialize
+      @proxies = []
+    end
+
+    def using(*args)
+      args.size.times { proxies.push HashProxy.new } if proxies.empty?
+      proxies.each_with_index {|proxy, index| proxy.using args[index] }
+    end
+
+    def clear
+      proxies.map(&:clear)
+    end
+  end
+
+end

data/lib/norman/mapper.rb

@@ -0,0 +1,66 @@
+module Norman
+
+  # Mappers provide the middle ground between models and adapters. Mappers are
+  # responsible for performing finds and moving objects in and out of the
+  # hash.
+  class Mapper
+    extend Forwardable
+    attr :hash
+    attr_accessor :adapter_name, :klass, :indexes, :options
+    def_delegators :hash, :clear, :delete
+    def_delegators :key_set, :all, :count, :find, :find_by_key, :first, :keys
+
+    def initialize(klass, adapter_name = nil, options = {})
+      @klass        = klass
+      @adapter_name = adapter_name || Norman.default_adapter_name
+      @indexes      = {}
+      @lock         = Mutex.new
+      @options      = options
+      @hash         = adapter.db_for(klass)
+    end
+
+    # Returns a hash or model attributes corresponding to the provided key.
+    def [](key)
+      hash[key] or raise NotFoundError.new(klass, key)
+    end
+
+    # Sets a hash by key.
+    def []=(key, value)
+      @lock.synchronize do
+        @indexes = {}
+        if value.id_changed?
+          hash.delete value.to_id(true)
+        end
+        saved = hash[key] = value.to_hash.freeze
+        adapter.save_database if @options[:sync]
+        saved
+      end
+    end
+
+    # Memoize the output of a find in a threadsafe manner.
+    def add_index(name, indexable)
+      @lock.synchronize do
+        @indexes[name] = indexable
+      end
+    end
+
+    # Get the adapter.
+    def adapter
+      Norman.adapters[adapter_name]
+    end
+
+    # Get an instance by key
+    def get(key)
+      klass.send :from_hash, self[key]
+    end
+
+    def key_set
+      klass.key_class.new(hash.keys.freeze, self)
+    end
+
+    # Sets an instance, invoking its to_id method
+    def put(instance)
+      self[instance.to_id] = instance
+    end
+  end
+end

data/lib/norman/model.rb

@@ -0,0 +1,164 @@
+module Norman
+
+  module Model
+    def self.extended(base)
+      base.instance_eval do
+        @lock            = Mutex.new
+        @attribute_names = []
+        @key_class       = Class.new(Norman::AbstractKeySet)
+        extend  ClassMethods
+        include InstanceMethods
+        include Comparable
+      end
+    end
+
+    module ClassMethods
+      extend Forwardable
+      attr_accessor :attribute_names, :id_method, :mapper
+      attr_reader :key_class
+      def_delegators(*[:find, Enumerable.public_instance_methods(false)].flatten)
+      def_delegators(:mapper, :[], :all, :delete, :first, :get, :count, :find, :find_by_key, :keys)
+      alias id_field id_method=
+
+      def field(*names)
+        names.each do |name|
+          # First attribute added is the default id
+          id_field name if attribute_names.empty?
+          attribute_names << name.to_sym
+          class_eval(<<-EOM, __FILE__, __LINE__ + 1)
+            def #{name}
+              @#{name} or (@attributes[:#{name}] if @attributes)
+            end
+
+            def #{name}=(value)
+              @#{name} = value
+            end
+          EOM
+        end
+      end
+
+      def use(adapter_name, options = {})
+        @mapper         = nil
+        @adapter_name   = adapter_name
+        @mapper_options = options
+      end
+
+      # Memoize the output of the method call invoked in the block.
+      # @param [#to_s] name If not given, the name of the method calling with_index will be used.
+      def with_index(name = nil, &block)
+        name ||= caller(1)[0].match(/in `(.*)'\z/)[1]
+        mapper.indexes[name.to_s] or begin
+          indexable = yield
+          mapper.add_index(name, indexable)
+        end
+      end
+
+      def create(hash)
+        new(hash).save
+      end
+
+      # The point of this method is to provide a fast way to get model instances
+      # based on the hash attributes managed by the mapper and adapter.
+      #
+      # The hash arg gets frozen, which can be a nasty side-effect, but helps
+      # avoid hard-to-track-down bugs if the hash is updated somewhere outside
+      # the model. This should only be used internally to Norman, which is why
+      # it's private.
+      def from_hash(hash)
+        instance = allocate
+        instance.instance_variable_set :@attributes, hash.freeze
+        instance
+      end
+      private :from_hash
+
+      def filters(&block)
+        key_class.class_eval(&block)
+        key_class.instance_methods(false).each do |name|
+        instance_eval(<<-EOM, __FILE__, __LINE__ + 1)
+          def #{name}(*args)
+            mapper.key_set.#{name}(*args)
+          end
+        EOM
+        end
+      end
+
+      def mapper
+        @mapper or @lock.synchronize do
+          name      = @adapter_name || Norman.default_adapter_name
+          options   = @mapper_options || {}
+          @mapper ||= Mapper.new(self, name, options)
+        end
+      end
+    end
+
+    module InstanceMethods
+
+      # Norman models can be instantiated with a hash of attribures, a block,
+      # or both. If both a hash and block are given, then the values set inside
+      # the block will take precedence over those set in the hash.
+      #
+      # @example
+      #   Person.new :name => "Joe"
+      #   Person.new {|p| p.name = "Joe"}
+      #   Person.new(params[:person]) {|p| p.age = 38}
+      #
+      def initialize(attributes = nil, &block)
+        @attributes = {}.freeze
+        return unless attributes || block_given?
+        if attributes
+          self.class.attribute_names.each do |name|
+            value = attributes[name] || attributes[name.to_s]
+            send("#{name}=", value) if value
+          end
+        end
+        yield self if block_given?
+      end
+
+      # Norman models implement the <=> method and mix in Comparable to provide
+      # sorting methods. This default implementation compares the result of
+      # #to_id. If the items being compared are not of the same kind.
+      def <=>(instance)
+        to_id <=> instance.to_id if instance.kind_of? self.class
+      end
+
+      # Get a hash of the instance's model attributes.
+      def to_hash
+        self.class.attribute_names.inject({}) do |hash, key|
+          hash[key] = self.send(key); hash
+        end
+      end
+
+      # Returns true is the model's id field has been updated.
+      def id_changed?
+        to_id != @attributes[self.class.id_method]
+      end
+
+      # Invoke the model's id method to return this instance's unique key. If
+      # true is passed, then the id will be read from the attributes hash rather
+      # than from an instance variable. This allows you to retrieve the old id,
+      # in the event that the id has been changed.
+      def to_id(use_old = false)
+        use_old ? @attributes[self.class.id_method] : send(self.class.id_method)
+      end
+
+      # Tell the mapper to save the data for this model instance.
+      def save
+        self.class.mapper.put(self)
+      end
+
+      # Update this instance's attributes and invoke #save.
+      def update(attributes)
+        self.class.attribute_names.each do |name|
+          value = attributes[name] || attributes[name.to_s]
+          send("#{name}=", value) if value
+        end
+        save
+      end
+
+      # Tell the mapper to delete the data for this instance.
+      def delete
+        self.class.delete(self.to_id)
+      end
+    end
+  end
+end