disposable 0.0.9 → 0.1.0

data/lib/disposable.rb

@@ -1,10 +1,9 @@
 require "disposable/version"
+require "disposable/twin"
 
 module Disposable
-  autoload :Twin,         'disposable/twin'
-  autoload :Composition,  'disposable/composition'
-end
-
-# if defined?(ActiveRecord)
-#   require 'disposable/facade/active_record'
-# end
+  class Twin
+    autoload :Composition,  "disposable/twin/composition"
+    autoload :Expose,       "disposable/twin/composition"
+  end
+end

data/lib/disposable/callback.rb

@@ -0,0 +1,174 @@
+# Callback is designed to work with twins under the hood since twins track events
+# like "adding" or "deleted". However, it could run with other model layers, too.
+# For example, when you manage to make ActiveRecord track those events, you won't need a
+# twin layer underneath.
+module Disposable::Callback
+  # Order matters.
+  #   on_change :change!
+  #   collection :songs do
+  #     on_add :notify_album!
+  #     on_add :reset_song!
+  #
+  # you can call collection :songs again, with :inherit. TODO: verify.
+
+  class Group
+    # TODO: make this easier via declarable.
+    extend Uber::InheritableAttr
+    inheritable_attr :representer_class
+
+    # class << self
+    #   include Representable::Cloneable
+    # end
+    self.representer_class = Class.new(Representable::Decorator) do
+      def self.default_inline_class
+        Group.extend Representable::Cloneable
+      end
+    end
+
+    def self.feature(*args)
+    end
+
+    def self.collection(name, options={}, &block)
+      property(name, options.merge(collection: true), &block)
+    end
+
+    def self.property(name, options={}, &block)
+      # NOTE: while the API will stay the same, it's very likely i'm gonna use Declarative::Config here instead
+      # of maintaining two stacks of callbacks.
+      # it should have a Definition per callback where the representer_module will be a nested Group or a Callback.
+      inherit = options[:inherit] # FIXME: this is deleted in ::property.
+
+      representer_class.property(name, options, &block).tap do |dfn|
+        return if inherit
+        hooks << ["property", dfn.name]
+      end
+    end
+
+    def self.remove!(event, callback)
+      hooks.delete hooks.find { |cfg| cfg[0] == event && cfg[1][0] == callback }
+    end
+
+
+    def initialize(twin)
+      @twin = twin
+      @invocations = []
+    end
+
+    attr_reader :invocations
+
+    inheritable_attr :hooks
+    self.hooks = []
+
+    class << self
+      %w(on_add on_delete on_destroy on_update on_create on_change).each do |event|
+        define_method event do |*args|
+          hooks << [event.to_sym, args]
+        end
+      end
+    end
+
+
+    def call(options={})
+      self.class.hooks.each do |cfg|
+        event, args = cfg
+
+        if event == "property" # FIXME: make nicer.
+          definition = self.class.representer_class.representable_attrs.get(args)
+          twin = @twin.send(definition.getter) # album.songs
+
+          @invocations += definition.representer_module.new(twin).(options).invocations # Group.new(twin).()
+          next
+        end
+
+        invocations << callback!(event, options, args)
+      end
+
+      self
+    end
+
+  private
+    # Runs one callback.
+    def callback!(event, options, args)
+      method      = args[0]
+      context     = options[:context] || self # TODO: test me.
+
+      options = args[1..-1]
+
+      # TODO: Use Option::Value here.
+      Dispatch.new(@twin).(event, method, *options) { |twin| context.send(method, twin) }
+    end
+  end
+
+
+  # Invokes callback for one event, e.g. on_add(:relax!).
+  # Implements the binding between the Callback API (on_change) and the underlying layer (twin/AR/etc.).
+  class Dispatch
+    def initialize(twins)
+      @twins = twins.is_a?(Array) ? twins : [twins] # TODO: find that out with Collection.
+      @invocations = []
+    end
+
+    def call(event, method, *args, &block) # FIXME: as long as we only support method, pass in here.
+      send(event, *args, &block)
+      [event, method, @invocations]
+    end
+
+    def on_add(state=nil, &block) # how to call it once, for "all"?
+      # @twins can only be Collection instance.
+      @twins.added.each do |item|
+        run!(item, &block) if state.nil?
+        run!(item, &block) if item.created? && state == :created # :created # DISCUSS: should we really keep that?
+      end
+    end
+
+    def on_delete(&block)
+      # @twins can only be Collection instance.
+      @twins.deleted.each do |item|
+        run!(item, &block)
+      end
+    end
+
+    def on_destroy(&block)
+      @twins.destroyed.each do |item|
+        run!(item, &block)
+      end
+    end
+
+    def on_update(&block)
+      @twins.each do |twin|
+        next if twin.created?
+        next unless twin.persisted? # only persisted can be updated.
+        next unless twin.changed?
+        run!(twin, &block)
+      end
+    end
+
+    def on_create(&block)
+      @twins.each do |twin|
+        next unless twin.created?
+        run!(twin, &block)
+      end
+    end
+
+    def on_change(options={}, &block)
+      name = options[:property]
+
+      @twins.each do |twin|
+        if name
+          run!(twin, &block) if twin.changed?(name)
+          next
+        end
+
+        next unless twin.changed?
+        run!(twin, &block)
+      end
+    end
+
+  private
+    def run!(twin, &block)
+      yield(twin).tap do |res|
+        @invocations << twin
+      end
+    end
+  end
+end

data/lib/disposable/composition.rb

@@ -1,78 +1,41 @@
-require 'forwardable'
-
 module Disposable
-  # Composition delegates accessors to models as per configuration.
-  #
-  # Composition doesn't know anything but methods (readers and writers) to expose and the mappings to
-  # the internal models. Optionally, it knows about renamings such as mapping `#song_id` to `song.id`.
-  #
-  #   class Album
-  #     include Disposable::Composition
+  # Composition allows renaming properties and combining one or more objects
+  # in order to expose a different API.
+  # It can be configured from any Representable schema.
   #
-  #     map( {cd: [[:id], [:name]], band: [[:id, :band_id], [:title]]} )
+  #   class AlbumTwin < Disposable::Twin
+  #     property :name, on: :artist
   #   end
   #
-  # Composition adds #initialize to the includer.
-  #
-  #   album = Album.new(cd: CD.find(1), band: Band.new)
-  #   album.id #=> 1
-  #   album.title = "Ten Foot Pole"
-  #   album.band_id #=> nil
+  #   class AlbumExpose < Disposable::Composition
+  #     from AlbumTwin
+  #   end
   #
-  # It allows accessing the contained models using the `#[]` reader.
-  module Composition
-    def self.included(base)
-      base.extend(Forwardable)
-      base.extend(ClassMethods)
-    end
-
-
-    module ClassMethods
-      def map(options)
-         @map = {}
-
-        options.each do |mdl, meths|
-          meths.each do |mtd| # [[:title], [:id, :song_id]]
-            create_accessors(mdl, mtd)
-            add_to_map(mdl, mtd)
-          end
-        end
-      end
-
-    private
-      def create_accessors(model, methods)
-        def_instance_delegator "@#{model}", *methods # reader
-        def_instance_delegator "@#{model}", *methods.map { |m| "#{m}=" } # writer
-      end
-
-      def add_to_map(model, methods)
-        name, public_name = methods
-        public_name     ||= name
-
-        @map[public_name.to_sym] = {:method => name.to_sym, :model => model.to_sym}
-      end
-    end
-
-
+  #   AlbumExpose.new(artist: OpenStruct.new(name: "AFI")).name #=> "AFI"
+  class Composition < Expose
     def initialize(models)
-      models.each do |name, obj|
-        instance_variable_set(:"@#{name}", obj)
+      models.each do |name, model|
+        instance_variable_set(:"@#{name}", model)
       end
 
-      @_models = models.values
+      @_models = models
     end
 
     # Allows accessing the contained models.
     def [](name)
-      instance_variable_get(:"@#{name}")
+      instance_variable_get("@#{name}")
     end
 
-    # Allows multiplexing method calls to all composed models.
     def each(&block)
-      _models.each(&block)
+      # TODO: test me.
+      @_models.values.each(&block)
     end
 
   private
-    attr_reader :_models
+    def self.accessors!(public_name, private_name, definition)
+      model = definition[:on]
+      define_method("#{public_name}")  { self[model].send("#{private_name}") }
+      define_method("#{public_name}=") { |*args| self[model].send("#{private_name}=", *args) }
+    end
   end
 end

data/lib/disposable/expose.rb

@@ -0,0 +1,49 @@
+module Disposable
+  # Expose allows renaming properties in order to expose a different API.
+  # It can be configured from any Representable schema.
+  #
+  #   class AlbumTwin < Disposable::Twin
+  #     property :name, from: :title
+  #   end
+  #
+  #   class AlbumExpose < Disposable::Expose
+  #     from AlbumTwin
+  #   end
+  #
+  #   AlbumExpose.new(OpenStruct.new(title: "AFI")).name #=> "AFI"
+  class Expose
+    class << self
+      def from(representer)
+        representer.representable_attrs.each do |definition|
+          process_definition!(definition)
+        end
+        self
+      end
+
+    private
+      def process_definition!(definition)
+        public_name  = definition.name
+        private_name = definition[:private_name] || public_name
+
+        accessors!(public_name, private_name, definition)
+      end
+
+      def accessors!(public_name, private_name, definition)
+        define_method("#{public_name}")  { @model.send("#{private_name}") }
+        define_method("#{public_name}=") { |*args| @model.send("#{private_name}=", *args) }
+      end
+    end
+
+
+    def initialize(model)
+      @model = model
+    end
+
+    module Save
+      def save
+        @model.save # FIXME: block?
+      end
+    end
+    include Save
+  end
+end

data/lib/disposable/twin.rb

@@ -1,9 +1,17 @@
-require 'uber/inheritable_attr'
-require 'representable/decorator'
-require 'representable/hash'
-require 'disposable/twin/representer'
-require 'disposable/twin/option'
-require 'disposable/twin/builder'
+# DISCUSS: sync via @fields, not reader? allows overriding a la reform 1.
+
+require "uber/inheritable_attr"
+
+require "disposable/twin/representer"
+require "disposable/twin/collection"
+require "disposable/twin/setup"
+require "disposable/twin/sync"
+require "disposable/twin/save"
+require "disposable/twin/option"
+require "disposable/twin/builder"
+require "disposable/twin/changed"
+require "disposable/twin/property_processor"
+require "disposable/twin/persisted"
 
 # Twin.new(model/composition hash/hash, options)
 #   assign hash to @fields
@@ -13,71 +21,110 @@ require 'disposable/twin/builder'
 module Disposable
   class Twin
     extend Uber::InheritableAttr
+
     inheritable_attr :representer_class
     self.representer_class = Class.new(Decorator)
 
+    # Returns an each'able array of all properties defined in this twin.
+    # Allows to filter using
+    #   * collection: true
+    #   * twin:       true
+    #   * scalar:     true
+    #   * exclude:    ["title", "email"]
+    def schema
+      self.class.representer_class
+    end
+
+
+    extend Representable::Feature # imports ::feature, which calls ::register_feature.
+    def self.register_feature(mod)
+      representer_class.representable_attrs[:features][mod] = true
+    end
 
+
+    # TODO: move to Declarative, as in Representable and Reform.
     def self.property(name, options={}, &block)
-      deprecate_as!(options) # TODO: remove me in 0.1.0
       options[:private_name] = options.delete(:from) || name
       options[:pass_options] = true
 
       representer_class.property(name, options, &block).tap do |definition|
         mod = Module.new do
-          define_method(name)       { read_property(name, options[:private_name]) }
-          define_method("#{name}=") { |value| write_property(name, options[:private_name], value) } # TODO: this is more like prototyping.
+          define_method(name)       { @fields[name.to_s] }
+          # define_method(name)       { read_property(name) }
+          define_method("#{name}=") { |value| write_property(name, value, definition) } # TODO: this is more like prototyping.
         end
         include mod
+
+        # property -> build_inline(representable_attrs.features)
+        if definition[:extend]
+          nested_twin = definition[:extend].evaluate(nil)
+          process_inline!(nested_twin, definition)
+          # DISCUSS: could we use build_inline's api here to inject the name feature?
+
+          definition.merge!(:twin => nested_twin)
+        end
       end
     end
 
     def self.collection(name, options={}, &block)
-      property(name, options.merge(:collection => true), &block)
+      property(name, options.merge(collection: true), &block)
     end
 
+    include Setup
+
 
-    module Initialize
-      def initialize(model, options={})
-        @fields = {}
-        @model  = model
+    module Accessors
+    private
+      # assumption: collections are always initialized from Setup since we assume an empty [] for "nil"/uninitialized collections.
+      def write_property(name, value, dfn)
+        return if dfn[:twin] and value.nil? # TODO: test me (model.composer => nil)
+        value = dfn.array? ? wrap_collection(dfn, value) : wrap_scalar(dfn, value) if dfn[:twin]
 
-        from_hash(options) # assigns known properties from options.
+        @fields[name.to_s] = value
       end
-    end
-    include Initialize
 
+      def wrap_scalar(dfn, value)
+        Twinner.new(dfn).(value)
+      end
 
-    # read/write to twin using twin's API (e.g. #record= not #album=).
-    def self.write_representer
-      representer = Class.new(representer_class) # inherit configuration
+      def wrap_collection(dfn, value)
+        Collection.for_models(Twinner.new(dfn), value)
+      end
     end
+    include Accessors
 
-  private
-    def read_property(name, private_name)
-      return @fields[name.to_s] if @fields.has_key?(name.to_s)
-      @fields[name.to_s] = read_from_model(private_name)
+    # DISCUSS: this method might disappear or change pretty soon.
+    def self.process_inline!(mod, definition)
     end
 
-    def read_from_model(getter)
-      model.send(getter)
+    # FIXME: this is experimental.
+    module ToS
+      def to_s
+        return super if self.class.name
+        "#<Twin (inline):#{object_id}>"
+      end
     end
+    include ToS
 
-    def write_property(name, private_name, value)
-       @fields[name.to_s] = value
-    end
 
-    def from_hash(options)
-      self.class.write_representer.new(self).from_hash(options)
-    end
+    class Twinner
+      def initialize(dfn)
+        @dfn = dfn
+      end
 
-    attr_reader :model # TODO: test
+      def call(value)
+        @dfn.twin_class.new(value)
+      end
+    end
 
-    include Option
 
-    def self.deprecate_as!(options) # TODO: remove me in 0.1.0
-      return unless as = options.delete(:as)
-      options[:from] = as
-      warn "[Disposable] The :as options got renamed to :from."
+  private
+    module ModelReaders
+      attr_reader :model # #model is a private concept.
+      attr_reader :mapper
     end
+    include ModelReaders
+
+    include Option
   end
 end