shattered_support 0.3.1 → 0.3.2

data/lib/base.rb

@@ -2,10 +2,11 @@
 $:.unshift(File.dirname(__FILE__)) unless
 $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
   
+require 'active_support'
 require 'timer/timer'
 require 'vector'
 
-module ShatteredSupport
+module ShatteredSupport #:nodoc:
   
   BEFORE_INIT_CALL_VALUES = :before_init_call_values
   BEFORE_INIT_SET_VALUES = :before_init_set_values
@@ -16,30 +17,60 @@ module ShatteredSupport
     base.extend(ClassMethods)
   end
   module ClassMethods 
+    # In the pre_initialization phase (see #before_init_call), send an object a bunch of sets.
+    #
+    # This is used in actor, camera, mesh, and virtually everywhere to support the format of:
+    #   mesh "ruby", :position => v(1,0,0)
+    #
+    # becomes 
+    #   before_init_set( :ruby, {:position => v(1,0,0) } )
+    # becomes
+    #   ruby.position=v(1,0,0)
+    # when the obect is initialized.
     def before_init_set(variable, options={})
       self.write_inheritable_array(BEFORE_INIT_SET_VALUES, [[ variable, options ]] )
     end
     
+    # All shattered objects have a pre_initialization phase.  Use this to specify that
+    # a function should be called when the object is created.
+    #
+    # _Example_:
+    #   class BulletModel < ShatteredModel::Base
+    #     before_init_call(:calculate_trajectory, v(0,0,0), v(0,0,1))
+    #     def calculate_trajectory
+    #       #called before initialize is
+    #     end
+    #   end
+    #
     def before_init_call(function, *arguments)
       self.write_inheritable_array(BEFORE_INIT_CALL_VALUES, [[function, [*arguments]]])
     end
   end
   class Base
-    def self.new(*options)
+    
+    # This is overwritten to allow for a pre_initialize before initialize
+    def self.new(*options) #:nodoc
       new_base = allocate
       new_base.pre_initialize
       new_base.send(:initialize, *options)
       return new_base
     end
-    def state
+    
+    # Retrieve the current state
+    def state 
       Configuration.environment[:state]
     end
-    def pre_initialize
+    
+    # This function is called after an object is allocated, but before it's initialized.
+    #
+    # See ShatteredSupport::ClassMethods#before_init_call for usage.
+    def pre_initialize #:nodoc:
       pre_initialize_set
       pre_initialize_call
     end
     
-    def each_init_value(name)
+    # Used in pre_initialize
+    def each_init_value(name) #:nodoc:
       startup_attributes = self.class.read_inheritable_attribute( name ) || []
       startup_attributes.each do |actor, options|
         next if options.nil?
@@ -47,24 +78,23 @@ module ShatteredSupport
       end
     end
     
-    def pre_initialize_set
+    # Used in pre_initialize for before_init_set
+    def pre_initialize_set #:nodoc:
       each_init_value(BEFORE_INIT_SET_VALUES) do |variable, options|
         call_object_function_for_each_key( variable, options )  
       end
-#      self.class.write_inheritable_attribute(BEFORE_INIT_SET_VALUES, nil)
     end
     
-    def pre_initialize_call
+    # Used in pre_initialize for before_init_call
+    def pre_initialize_call #:nodoc:
         each_init_value(BEFORE_INIT_CALL_VALUES) do |function, args|
           call_object_function( :self, function, args )  
         end
-#      self.class.write_inheritable_attribute(BEFORE_INIT_CALL_VALUES, nil)
     end
 
     
-    # Overwrite this function to recieve an update event every frame, with the
-    # seconds elapsed since last update.
-    def update_event(time_elapsed)
+    # TODO - is this called anymore?
+    def update_event(time_elapsed) #:nodoc:
       actors.each do |actor|
         actor.update_actors(time_elapsed)
         actor.update(time_elapsed)
@@ -72,25 +102,25 @@ module ShatteredSupport
     end
     
     # remove_from_scene? should just be defined in model.
-    # Refactor?
-    def remove_from_scene?
+    # Refactor? TODO
+    def remove_from_scene? #:nodoc:
       return false
     end
     
-    def update_actors(time_elapsed)
+    # TODO outdated?
+    def update_actors(time_elapsed) #:nodoc:
       update_event time_elapsed
       remove_dead_actors
     end
     
-    def update(time_elapsed)
-    end
-  
-    def remove_dead_actors
+    # TODO outdated?
+    def remove_dead_actors #:nodoc:
       actors.each do |actor|
         remove_from_scene actor if actor.remove_from_scene?
       end
     end  
-
+    
+    # TODO outdated?
     def remove_from_scene(actor)
       actors.delete actor
       actor.unload!
@@ -103,6 +133,7 @@ module ShatteredSupport
         call_object_function actor, "#{action}=", params
       end
     end
+    
     def call_object_function(actor, action, params)
       begin
         if params.is_a? Symbol #|| (params.length == 1 && params[0].is_a?(Symbol)) this will allow substitution in before_init_call. This may not be intended behavior.
@@ -121,40 +152,62 @@ module ShatteredSupport
         raise bang
       end
     end
-    def unload!
-    end
     
     public
     
-    # attr helpers.  This defines instance level attr_* functions.
+    # attr helpers.  These are instance level attr_* functions.
     def attr_reader(*args)
       name, value = args
       attr_define(:reader, name, value)
     end
-    
+
+    # attr helpers.  These are instance level attr_* functions.    
+    # attr_writer accepts a value as the second argument
     def attr_writer(*args)
       name, value = args
       attr_define(:writer, name, value)
     end
     
+    # attr helpers.  These are instance level attr_* functions.    
+    # attr_accessor accepts a value as the second argument
     def attr_accessor(*args)
       name, value = args
       attr_define(:accessor, name, value)
     end
     
+    # Define a block to execute when an object is unloaded.
+    def when_unloaded(&block)
+      @unloaded_events ||= []
+      @unloaded_events << block
+    end
+    
     protected
     
     def attr_define(accessor_level, name, value)
-      self.class.send(:"attr_#{accessor_level}", :"#{name}")
-      instance_variable_set(:"@#{name}", value) if !value.nil?
+      self.class.send("attr_#{accessor_level}".to_sym, "#{name}".to_sym)
+      instance_variable_set("@#{name}".to_sym, value) if !value.nil?
+    end
+
+    private
+    
+    def disabled?
+      @unloaded_events == nil
+    end
+    
+    def unload!
+      return if disabled?
+      @unloaded_events.each do |event|
+        event.call
+      end
+      @unloaded_events = nil
     end
     
   end
   
-  class Error < StandardError
+  class Error < StandardError # :nodoc:
   end
   
-  class RetossError < StandardError
+  class RetossError < StandardError # :nodoc:
     attr_accessor :message 
     def initialize(error, message)
       self.message = message

data/lib/runner.rb

@@ -1,11 +1,8 @@
 module ShatteredSupport
-  class Configuration
+  class Configuration #:nodoc:
     def self.environment
-      begin
-        return @@environment
-      rescue NameError
-        return {}
-      end
+      @@environment={} unless defined? @@environment
+      return @@environment 
     end
     def self.environment=(environment)
       @@environment=environment

data/lib/shattered_support.rb

@@ -1,17 +1,19 @@
 require 'rubygems'
-require 'active_support'
 
 class Object
   def method_defined?(method)
     return self.class.method_defined?(method)
   end
   
+  # This is a shorthand to define vector object coordinates.
+  #
+  # Creates a vector object at coordinates x,y,z
   def v(x, y, z) 
     Vector.new(x, y, z) 
   end
 end
 
-class File
+class File #:nodoc:
   # File.each_in_path will recursively look for all files, starting at the given path.
   # It will yield with each result.
   def self.each_in_path(path)
@@ -46,7 +48,7 @@ class File
   end
 end
 
-class Dir
+class Dir #:nodoc:
   # Dir.each_in_path will recursively yield all non-hidden directories from the given path.
   def self.each_in_path(path, &block)
     return unless File.directory? path

data/lib/timer/timed_event.rb

@@ -1,5 +1,5 @@
 module ShatteredSupport
-  module Timer
+  module Timer #:nodoc:all
     
     class Timer
       attr_reader :events_remaining

data/lib/timer/timer.rb

@@ -1,7 +1,7 @@
 require File.dirname(__FILE__)+'/timed_event'
 
 module ShatteredSupport
-  module Timer
+  module Timer #:nodoc:
     def self.append_features(base)
       super
       base.extend(ClassMethods)

data/lib/vector.rb

@@ -1,5 +1,5 @@
 
-class Array
+class Array #:nodoc:
   # Vector extensions for array.  Allows for coersion of a 3 element Array into a vector.
   
   # Randomize the order of an array
@@ -26,26 +26,33 @@ class Array
   end
 end
   
-module ShatteredSupport
+module ShatteredSupport #:nodoc:
+  # Vector is a three dimensional array, that allows for various operations on itself.
+  # To create a vector, use the shorthand:
+  #   v(0,0,0) # Creates a zero vector
   class Vector
     
     attr_reader :x, :y, :z
     
-    # Create a new Vector object.  It requires exactly 3 arguments: x, y and z.
+    # Create a new Vector object.  It requires exactly 3 arguments: x, y and z.  Any value that
+    # can be converted to a float is acceptable.
+    #
+    # *NOTE:* The recomended way to create Vector objects is to use the <tt>v(1,2,3)</tt> shorthand.
     def initialize(x_val, y_val, z_val)
-      @x, @y, @z = x_val.to_f, y_val.to_f, z_val.to_f
+      @x, @y, @z = [x_val, y_val, z_val].collect(&:to_f)
     end
     
-    # Iterate through x, y and z with a black.  The passed value is the value of the component.
+    # Iterate through x, y and z with a block.  The passed value is the value of each component of 
+    # the vector.
     def each(&block)
-      self.to_a.each do |item|
-        yield item
+      self.to_a.each do |component|
+        yield component
       end
     end
     
     # Returns this Vector as an Ogre vector object: Vector3.  Should only be used internally by
     # Shattered to communicate with the Ogre engine.
-    def to_v3
+    def to_v3 # :nodoc:
       ShatteredOgre::Vector3.new @x, @y, @z
     end
     
@@ -54,14 +61,14 @@ module ShatteredSupport
       self
     end
     
-    # Returns an array with x, y and z dumped into its elements
-    #
-    #   Vector.new(1, 2, 3).to_a #=> [1, 2, 3]
+    # Returns an array with x, y and z dumped into its elements.
+    #   v(1, 2, 3).to_a #=> [1.0, 2.0, 3.0]
     def to_a
       [@x, @y, @z]
     end
     
     # Add 2 Vectors together.
+    #   v(1,1,1) + v(1,2,3) #=> v(2,3,4)
     def +(*args)
       vector = convert_args_to_vector(args)
       Vector.new(
@@ -71,7 +78,8 @@ module ShatteredSupport
       )
     end
     
-    # Subtract one Vector form another.
+    # Subtract one Vector from another.
+    #   v(1,2,3) - v(1,1,1) #=> v(0,1,2)
     def -(args)
       vector = convert_args_to_vector(args)
       Vector.new(
@@ -82,6 +90,7 @@ module ShatteredSupport
     end
     
     # Multiply all components of a vector by a scalar amount.
+    #   v(1,2,3) * 3 #=> v(3,6,9)
     def *(value)
       result = []
       each do |i|
@@ -91,6 +100,7 @@ module ShatteredSupport
     end
     
     # Divide all components of a vector by a scalar amount
+    #   v(5,10,15) / 5 #=> v(1,2,3)
     def /(value)
       result = Array.new
       self.each do |i|
@@ -100,18 +110,25 @@ module ShatteredSupport
     end
     
     # Returns this Vector but normalized to a length of 1.
+    #   v(9, 0, 0).normalize #=> v(1,0,0)
     def normalize
       self * (1 / length)
     end
     alias_method :normalise, :normalize
     
-    # Same as #normalize but is destructive.
+    # Same as #normalize but modifies the receiver in place.
     def normalize!
       @x, @y, @z = normalize.to_a
     end
     alias_method :normalise!, :normalize!
     
-    # Return the value specified by bracket notation.
+    # Return the value specified by bracket notation.  Integers, Symbols or Strings
+    # are accepted as keys.
+    #   
+    #   vector = v(1,2,3)
+    #   vector[:x]  #=> 1
+    #   vector['y'] #=> 2
+    #   vector[2]   #=> 3
     def [](index)
       case
         when index == 0 || index == :x || index == 'x'
@@ -123,7 +140,8 @@ module ShatteredSupport
       end
     end
     
-    # Set the value specified by bracket notation.
+    # Set the value specified by bracket notation.  Accepts the same keys as the #[] 
+    # method.
     def []=(index, value)
       case
         when index == 0 || index == :x || index == 'x'
@@ -135,28 +153,44 @@ module ShatteredSupport
       end
     end
     
+    # Set the value of the X component.
     def x=(value)
       @x = value.to_f
     end
     
+    # Set the value of the Y component.
     def y=(value)
       @y = value.to_f
     end
     
+    # Set the value of the Z component.
     def z=(value)
       @z = value.to_f
     end
     
     
     # Returns the length of this vector.
+    #   v(0,0,7).length #=> 7
     def length
       Math.sqrt(x**2 + y**2 + z**2)
     end
     
+    # Converts the vector into an easily identifiable form.  Mostly used for debugging
+    # and console output.
+    #   v(1,2,3).to_s #=> "#<Vector [1.0, 2.0, 3.0]>"
     def to_s
       "#<Vector [#@x, #@y, #@z]>"
     end
     
+    # Equality test.  This method will return true if all components of both vectors are
+    # indentical.
+    def ==(vector)
+      vector.kind_of?(Vector) && 
+      x == vector.x           && 
+      y == vector.y           &&
+      z == vector.z
+    end
+    
   private
     
     def convert_args_to_vector(*args)

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.10
 specification_version: 1
 name: shattered_support
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
-date: 2006-05-16
+  version: 0.3.2
+date: 2006-06-04
 summary: "Shattered Support:  Allows a common derivation point for shattered MVC."
 require_paths: 
   - lib