bbrowning-virtualbox 0.7.6.dev

data/lib/virtualbox/abstract_model/attributable.rb

@@ -0,0 +1,290 @@
+require 'virtualbox/abstract_model/version_matcher'
+
+module VirtualBox
+  class AbstractModel
+    # Module which can be included into any other class which allows
+    # that class to have attributes using the "attribute" class method.
+    # This creates the reader/writer for the attribute but also provides
+    # other useful options such as readonly attributes, default values,
+    # and more.
+    #
+    # Make sure to also see the {ClassMethods}.
+    #
+    # ## Defining a Basic Attribute
+    #
+    #     attribute :name
+    #
+    # The example above would put the "name" attribute on the class. This
+    # would give the class the following abilities
+    #
+    #     instance.name = "Harry!"
+    #     puts instance.name # => "Harry!"
+    #
+    # Basic attributes alone are not different than ruby's built-in
+    # `attr_*` methods.
+    #
+    # ## Defining a Readonly Attribute
+    #
+    #     attribute :age, :readonly => true
+    #
+    # The example above allows age to be read, but not written to via the
+    # `age=` method. The attribute is still able to written using
+    # {#write_attribute} but this is generally only for
+    # inter-class use, and not for users of it.
+    #
+    # ## Defining Default Values
+    #
+    #     attribute :format, :default => "VDI"
+    #
+    # The example above applies a default value to format. So if no value
+    # is ever given to it, `format` would return `VDI`.
+    #
+    # ## Attributes for a Specific VirtualBox Version
+    #
+    # Attributes change with different VirtualBox versions. One way to
+    # provide version-specific behavior is to specify the version
+    # which the attribute applies to.
+    #
+    #     attribute :name, :version => "3.2"
+    #     attribute :age, :version => "3.1"
+    #
+    # These versions only apply to major and minor releases of
+    # VirtualBox. Patch releases can't be specified (such as "3.2.4")
+    #
+    # ## Populating Multiple Attributes
+    #
+    # Attributes can be mass populated using {#populate_attributes}. Below
+    # is an example of the use.
+    #
+    #     class Person
+    #       include Attributable
+    #
+    #       attribute :name
+    #       attribute :age, :readonly => true
+    #
+    #       def initialize
+    #         populate_attributes({
+    #           :name => "Steven",
+    #           :age => 27
+    #         })
+    #       end
+    #     end
+    #
+    # **Note:** Populating attributes is not the same as mass-updating attributes.
+    # {#populate_attributes} is meant to do initial population only. There is
+    # currently no method for mass assignment for updating.
+    #
+    # ## Custom Populate Keys
+    #
+    # Sometimes the attribute names don't match the keys of the hash that will be
+    # used to populate it. For this purpose, you can define a custom
+    # `populate_key`. Example:
+    #
+    #     attribute :path, :populate_key => :location
+    #
+    #     def initialize
+    #       populate_attributes(:location => "Home")
+    #       puts path # => "Home"
+    #     end
+    #
+    # ## Lazy Loading Attributes
+    #
+    # While most attributes are fairly trivial to calculate and populate, sometimes
+    # attributes may have an expensive cost to populate, and are generally not worth
+    # populating unless a user of the class requests that attribute. This is known as
+    # _lazy loading_ the attributes. This is possibly by specifying the `:lazy` option
+    # on the attribute. In this case, the first time (and _only_ the first time) the
+    # attribute is requested, `load_attribute` will be called with the name of the
+    # attribute as the parameter. This method is then expected to call `write_attribute`
+    # on that attribute to give it a value.
+    #
+    #     class ExpensiveAttributeModel
+    #       include VirtualBox::AbstractModel::Attributable
+    #       attribute :expensive_attribute, :lazy => true
+    #
+    #       def load_attribute(name)
+    #         if name == :expensive_attribute
+    #           write_attribute(name, perform_expensive_calculation)
+    #         end
+    #       end
+    #     end
+    #
+    # Using the above definition, we could use the class like so:
+    #
+    #     # Initializing is fast, since no attribute population is done
+    #     model = ExpensiveAttributeModel.new
+    #
+    #     # But this is slow, since it has to calculate.
+    #     puts model.expensive_attribute
+    #
+    #     # But ONLY THE FIRST TIME. This time is FAST!
+    #     puts model.expensive_attribute
+    #
+    # In addition to calling `load_attribute` on initial read, `write_attribute`
+    # when performed on a lazy loaded attribute will mark it as "loaded" so there
+    # will be no load called on the first request. Example, using the above class
+    # once again:
+    #
+    #     model = ExpensiveAttributeModel.new
+    #     model.write_attribute(:expensive_attribute, 42)
+    #
+    #     # This is FAST, since "load_attribute" is not called
+    #     puts model.expensive_attribute # => 42
+    #
+    module Attributable
+      include VersionMatcher
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Defines the class methods for the {Attributable} module. For
+      # detailed overview documentation, see {Attributable}.
+      module ClassMethods
+        # Defines an attribute on the model.
+        #
+        # @param [Symbol] name The name of the attribute, which will also be
+        #   used to set the accessor methods.
+        # @option options [Boolean] :readonly (false) If true, attribute will be readonly.
+        #   More specifically, the `attribute=` method won't be defined for it.
+        # @option options [Object] :default (nil) Specifies a default value for the
+        #   attribute.
+        # @option options [Symbol] :populate_key (attribute name) Specifies
+        #   a custom populate key to use for {Attributable#populate_attributes}
+        def attribute(name, options = {})
+          name = name.to_sym
+          attributes[name] = defined?(@__attribute_scope) ? @__attribute_scope : {}
+          attributes[name].merge!(options)
+
+          # Create the method for reading this attribute
+          define_method("#{name}?") { read_attribute(name) } if options[:boolean]
+          define_method(name) { read_attribute(name) }
+
+          # Create the writer method for it unless the attribute is readonly,
+          # then remove the method if it exists
+          if !options[:readonly]
+            define_method("#{name}=") do |value|
+              write_attribute(name, value)
+            end
+          elsif method_defined?("#{name}=")
+            undef_method("#{name}=")
+          end
+        end
+
+        # Defines the specified scope for all attributes within the block.
+        # The scope is reset to the previous value once the block ends. Multiple
+        # scopes can be nested and they'll inherit from each other.
+        def attribute_scope(options, &block)
+          @__attribute_scope ||= {}
+          old_value = @__attribute_scope
+          @__attribute_scope = old_value.merge(options)
+
+          instance_eval(&block)
+
+          @__attribute_scope = old_value
+        end
+
+        # Returns the hash of attributes and their associated options.
+        def attributes
+          @attributes ||= {}
+        end
+
+        # Used to propagate attributes to subclasses. This method makes sure that
+        # subclasses of a class with {Attributable} included will inherit the
+        # attributes as well, which would be the expected behaviour.
+        def inherited(subclass)
+          super rescue NoMethodError
+
+          attributes.each do |name, option|
+            subclass.attribute(name, option)
+          end
+        end
+      end
+
+      # Does the initial population of the various attributes. It will
+      # ignore attributes which are not defined or have no value in the
+      # hash.
+      #
+      # Population uses the attributes `populate_key` if present to
+      # determine which value to take. Example:
+      #
+      #     attribute :name, :populate_key => :namae
+      #     attribute :age
+      #
+      #     def initialize
+      #       populate_attributes(:namae => "Henry", :age => 27)
+      #     end
+      #
+      # The above example would set `name` to `Henry` since that is
+      # the `populate_key`. If a `populate_key` is not present, the
+      # attribute name is used.
+      def populate_attributes(attribs)
+        self.class.attributes.each do |key, options|
+          value_key = options[:populate_key] || key
+          write_attribute(key, attribs[value_key]) if attribs.has_key?(value_key)
+        end
+      end
+
+      # Writes an attribute. This method ignores the `readonly` option
+      # on attribute definitions. This method is mostly meant for
+      # internal use on setting attributes (including readonly
+      # attributes), whereas users of a class which includes this
+      # module should use the accessor methods, such as `name=`.
+      def write_attribute(name, value)
+        attributes[name] = value
+      end
+
+      # Reads an attribute. This method will return `nil` if the
+      # attribute doesn't exist. If the attribute does exist but
+      # doesn't have a value set, it'll use the `default` value
+      # if specified.
+      def read_attribute(name)
+        if has_attribute?(name)
+          options = self.class.attributes[name]
+
+          assert_version_match(options[:version], VirtualBox.version) if options[:version]
+          if lazy_attribute?(name) && !loaded_attribute?(name)
+            # Load the lazy attribute
+            load_attribute(name.to_sym)
+          end
+
+          if attributes[name].nil?
+            options[:default]
+          else
+            attributes[name]
+          end
+        end
+      end
+
+      # Returns a hash of all attributes and their options.
+      def attributes
+        @attribute_values ||= {}
+      end
+
+      # Returns boolean value denoting if an attribute exists.
+      def has_attribute?(name)
+        self.class.attributes.has_key?(name.to_sym)
+      end
+
+      # Returns boolean value denoting if an attribute is "lazy loaded"
+      def lazy_attribute?(name)
+        has_attribute?(name) && self.class.attributes[name.to_sym][:lazy]
+      end
+
+      # Returns boolean value denoting if an attribute has been loaded
+      # yet.
+      def loaded_attribute?(name)
+        attributes.has_key?(name)
+      end
+
+      # Returns a boolean value denoting if an attribute is readonly.
+      # This method also returns false for **nonexistent attributes**
+      # so it should be used in conjunction with {#has_attribute?} if
+      # existence is important.
+      def readonly_attribute?(name)
+        name = name.to_sym
+        has_attribute?(name) && self.class.attributes[name][:readonly]
+      end
+    end
+  end
+end

data/lib/virtualbox/abstract_model/dirty.rb

@@ -0,0 +1,177 @@
+module VirtualBox
+  class AbstractModel
+    # Tracks "dirtiness" of values for a class. Its not tied to AbstractModel
+    # in any way other than the namespace.
+    #
+    # # Checking if a Value was Changed
+    #
+    # Dynamic methods allow functionality for checking if values changed:
+    #
+    #     obj.foo_changed?
+    #
+    # # Previous Value
+    #
+    # Can also view the previous value of an attribute:
+    #
+    #     obj.foo # => "foo" initially
+    #     obj.foo = "bar"
+    #     obj.foo_was # => "foo"
+    #
+    # # Previous and Current Value
+    #
+    # Using the `_change` dynamic method, can view the changes of a field.
+    #
+    #     obj.foo # => "foo" initially
+    #     obj.foo = "bar"
+    #     obj.foo_change # => ["foo", "bar"]
+    #
+    # # All Changes
+    #
+    # Can also view all changes for a class with the `changes` method.
+    #
+    #     obj.foo # => "foo" initially
+    #     obj.bar # => "bar" initially
+    #     obj.foo = "far"
+    #     obj.bar = "baz"
+    #     obj.changes # => { :foo => ["foo", "far"], :bar => ["bar", "baz"]}
+    #
+    # # Setting Dirty
+    #
+    # Dirtiness tracking only occurs for values which the implementor
+    # explicitly sets as dirty. This is done with the {#set_dirty!}
+    # method. Example implementation below:
+    #
+    #     class Person
+    #       include VirtualBox::AbstractModel::Dirty
+    #
+    #       attr_reader :name
+    #
+    #       def name=(value)
+    #         set_dirty!(:name, @name, value)
+    #         @name = value
+    #       end
+    #     end
+    #
+    # The above example has all the changes necessary to track changes
+    # on an attribute.
+    #
+    # # Ignoring Dirtiness Tracking
+    #
+    # Sometimes, for features such as mass assignment, dirtiness tracking
+    # should be disabled. This can be done with the `ignore_dirty` method.
+    #
+    #     ignore_dirty do |obj|
+    #       obj.name = "Foo"
+    #     end
+    #
+    #     obj.changed? # => false
+    #
+    # # Clearing Dirty State
+    #
+    # Sometimes, such as after saving a model, dirty states should be cleared.
+    # This can be done with the `clear_dirty!` method.
+    #
+    #     obj.clear_dirty!(:name)
+    #     obj.name_changed? # => false
+    #
+    # If no specific field is speciied, `clear_dirty!` will clear the dirty
+    # status on the entire model.
+    #
+    #     obj.changed? # => assume true
+    #     obj.clear_dirty!
+    #     obj.changed? # => false
+    #
+    module Dirty
+      # Manages dirty state for an attribute. This method will handle
+      # setting the dirty state of an attribute (or even clearing it
+      # if the old value is reset). Any implementors of this mixin should
+      # call this for any fields they want tracked.
+      #
+      # @param [Symbol] name Name of field
+      # @param [Object] current Current value (not necessarilly the
+      #   original value, but the **current** value)
+      # @param [Object] value The new value being set
+      def set_dirty!(name, current, value)
+        if current != value
+          name = name.to_sym
+
+          # If its the first time this attribute has changed, store the
+          # original value in the first field
+          changes[name] ||= [current, nil]
+
+          # Then store the changed value
+          changes[name][1] = value
+
+          # If the value changed back to the original value, remove from the
+          # dirty hash
+          if changes[name][0] == changes[name][1]
+            changes.delete(name)
+          end
+        end
+      end
+
+      # Clears dirty state for a field.
+      #
+      # @param [Symbol] key The field to clear dirty state.
+      def clear_dirty!(key=nil)
+        if key.nil?
+          @changed_attributes = {}
+        else
+          changes.delete(key)
+        end
+      end
+
+      # Ignores any dirty changes during the duration of the block.
+      # Guarantees the dirty state will be the same before and after
+      # the method call, but not within the block itself.
+      def ignore_dirty(&block)
+        current_changes = changes.dup
+        yield self
+        @changed_attributes = current_changes
+      end
+
+      # Returns boolean denoting if field changed or not. If no attribute
+      # is specified, returns true of false showing whether the model
+      # changed at all.
+      #
+      # @param [Symbol] attribute The attribute to check, or if nil,
+      #   all fields checked.
+      def changed?(attribute = nil)
+        if attribute.nil?
+          !changes.empty?
+        else
+          changes.has_key?(attribute)
+        end
+      end
+
+      # Returns hash of changes. Keys are fields, values are an
+      # array of the original value and the current value.
+      #
+      # @return [Hash]
+      def changes
+        @changed_attributes ||= {}
+      end
+
+      # Method missing is used to implement the "magic" methods of
+      # `field_changed`, `field_change`, and `field_was`.
+      def method_missing(meth, *args)
+        meth_string = meth.to_s
+
+        if meth_string =~ /^(.+?)_changed\?$/
+          changed?($1.to_sym)
+        elsif meth_string =~ /^(.+?)_change$/
+          changes[$1.to_sym]
+        elsif meth_string =~ /^(.+?)_was$/
+          change = changes[$1.to_sym]
+          if change.nil?
+            nil
+          else
+            change[0]
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end