rubyvis 0.2.0 → 0.2.1

data/examples/crimea/crimea_grouped_bar.rb

@@ -1,3 +1,5 @@
+# = Crimeam War deaths (Grouped bar)
+# Florence Nightingale used a coxcomb diagram to emphasize the number of deaths due to “preventible or mitigable zymotic diseases”. This graph shows data using a stacked bar chart.
 $:.unshift(File.dirname(__FILE__)+"/../../lib")
 require 'rubyvis'
 require 'ostruct'

data/examples/crimea/crimea_line.rb

@@ -1,3 +1,6 @@
+# = Crimeam War deaths (Grouped bar)
+# Florence Nightingale used a coxcomb diagram to emphasize the number of deaths due to “preventible or mitigable zymotic diseases”. This graph shows data using a line chart.
+
 $:.unshift(File.dirname(__FILE__)+"/../../lib")
 require 'rubyvis'
 require 'ostruct'

data/examples/first_protovis_api.rb

@@ -1,6 +1,6 @@
-# = First example
+# = First example (Protovis API)
 # This is the protovis API version of "Getting Started" example of Protovis introduction.
-# On this example we show you how can you build a bar chart using panel and bar marks.
+# On this example we  build a bar chart using panel and bar marks.
 # A mark represents a set of graphical elements that share data and visual encodings. Although marks are simple by themselves, you can combine them in interesting ways to make rich, interactive visualizations
 $:.unshift(File.dirname(__FILE__)+"/../lib")
 require 'rubyvis'

data/examples/first_rbp_api.rb

@@ -1,6 +1,6 @@
-# = First example
+# = First example (RBP API)
 # This is the RBP API version of "Getting Started" example of Protovis introduction.
-# On this example we show you how can you build a bar chart using panel and bar marks.
+# On this example we  build a bar chart using panel and bar marks.
 # A mark represents a set of graphical elements that share data and visual encodings. Although marks are simple by themselves, you can combine them in interesting ways to make rich, interactive visualizations
 $:.unshift(File.dirname(__FILE__)+"/../lib")
 require 'rubyvis'

data/lib/rubyvis.rb

@@ -22,11 +22,10 @@ require 'rubyvis/scene/svg_scene'
 require 'rubyvis/transform'
 
 
-
 module Rubyvis
   @document=nil
   # Rubyvis version
-  VERSION = '0.2.0' 
+  VERSION = '0.2.1' 
   # Protovis API on which current Rubyvis is based
   PROTOVIS_API_VERSION='3.3'
   # You actually can do it! http://snipplr.com/view/2137/uses-for-infinity-in-ruby/

data/lib/rubyvis/internals.rb

@@ -229,5 +229,34 @@ module Rubyvis
   def self.keys(map)
     map.keys
   end
-    
+  
+  # Returns a map constructed from the specified <tt>keys</tt>, using the
+  # function <tt>f</tt> to compute the value for each key. The single argument to
+  # the value function is the key. The callback is invoked only for indexes of
+  # the array which have assigned values; it is not invoked for indexes which
+  # have been deleted or which have never been assigned values.
+  #
+  # <p>For example, this expression creates a map from strings to string length:
+  #
+  # <pre>pv.dict(["one", "three", "seventeen"], function(s) s.length)</pre>
+  #
+  # The returned value is <tt>{one: 3, three: 5, seventeen: 9}</tt>. Accessor
+  # functions can refer to <tt>this.index</tt>.
+  #
+  # * @param {array} keys an array.
+  # * @param {function} f a value function.
+  # * @returns a map from keys to values.
+
+  
+  def self.dict(keys, f)
+    m = {}
+    keys.size.times do |i|
+      unless keys[i].nil?
+        k=keys[i] 
+        o=o_index(i)
+        m[k]=f.js_call(o,k)
+      end
+    end
+    m
+  end
 end

data/lib/rubyvis/javascript_behaviour.rb

@@ -57,7 +57,8 @@ class Proc
   def js_apply(obj,args)
     arguments=args.dup
     # Modify numbers of args to works with arity
-    min_args=self.arity>0 ? self.arity : (-self.arity)-1
+    min_args=self.arity > 0 ? self.arity : (-self.arity)-1
+    
     if args.size > min_args and self.arity>0
       arguments=arguments[0,self.arity]
     elsif args.size < min_args
@@ -65,7 +66,12 @@ class Proc
     end
     #puts "#{args}->#{arguments} (#{self.arity})"
     if self.arity==0
-      obj.instance_eval(&self)
+      if RUBY_VERSION <="1.9.2" # CHECK THIS
+        obj.instance_eval(&self)
+      else
+        obj.instance_exec(&self)
+        
+      end
     else
       obj.instance_exec(*arguments,&self)
     end

data/lib/rubyvis/layout.rb

@@ -3,7 +3,13 @@ module Rubyvis
     Rubyvis::Layout
   end
   class Layout < Rubyvis::Panel
-    @properties=Mark.properties.dup    
+    @properties=Panel.properties.dup
+    def layout_build_properties(s,properties)
+      mark_build_properties(s,properties)
+    end
+    def layout_build_implied(s)
+      panel_build_implied(s)
+    end
     def self.attr_accessor_dsl(*attr)
       attr.each  do |sym|
         if sym.is_a? Array

data/lib/rubyvis/layout/stack.rb

@@ -74,10 +74,10 @@ module Rubyvis
     # <tt>crimea</tt>); the second argument is the layer data (a string in
     # <tt>causes</tt>). Additional arguments specify the data of enclosing panels, if any.
     class Stack < Rubyvis::Layout
-      @properties=Panel.properties.dup    
-      
-      attr_accessor :_x, :_y, :_values, :prop
+      @properties=Layout.properties.dup
       attr_accessor_dsl :orient,:offset, :order, :layers
+      attr_accessor :_x, :_y, :_values, :prop
+
       def self.defaults
         Stack.new.extend(Layout.defaults).orient("bottom-left").offset("zero").layers([[]])
       end

data/lib/rubyvis/mark.rb

@@ -1,62 +1,117 @@
 
 module Rubyvis
- # Constructs a new mark with default properties. Marks, with the exception of
- # the root panel, are not typically constructed directly; instead, they are
- # added to a panel or an existing mark via Mark#add
- #
- # Represents a data-driven graphical mark. The +Mark+ class is
- # the base class for all graphical marks in Protovis; it does not provide any
- # specific rendering functionality, but together with Panel establishes
- # the core framework.
- #
- # Concrete mark types include familiar visual elements such as bars, lines
- # and labels. Although a bar mark may be used to construct a bar chart, marks
- # know nothing about charts; it is only through their specification and
- # composition that charts are produced. These building blocks permit many
- # combinatorial possibilities.
- #
- # Marks are associated with <b>data</b>: a mark is generated once per
- # associated datum, mapping the datum to visual <b>properties</b> such as
- # position and color. Thus, a single mark specification represents a set of
- # visual elements that share the same data and visual encoding. The type of
- # mark defines the names of properties and their meaning. A property may be
- # static, ignoring the associated datum and returning a constant; or, it may be
- # dynamic, derived from the associated datum or index. Such dynamic encodings
- # can be specified succinctly using anonymous functions. Special properties
- # called event handlers can be registered to add interactivity.
- #
- # Protovis uses <b>inheritance</b> to simplify the specification of related
- # marks: a new mark can be derived from an existing mark, inheriting its
- # properties. The new mark can then override properties to specify new
- # behavior, potentially in terms of the old behavior. In this way, the old mark
- # serves as the <b>prototype</b> for the new mark. Most mark types share the
- # same basic properties for consistency and to facilitate inheritance.
- #
- # The prioritization of redundant properties is as follows:<ol>
- #
- # <li>If the <tt>width</tt> property is not specified (i.e., null), its value
- # is the width of the parent panel, minus this mark's left and right margins;
- # the left and right margins are zero if not specified.
- #
- # <li>Otherwise, if the <tt>right</tt> margin is not specified, its value is
- # the width of the parent panel, minus this mark's width and left margin; the
- # left margin is zero if not specified.
- #
- # <li>Otherwise, if the <tt>left</tt> property is not specified, its value is
- # the width of the parent panel, minus this mark's width and the right margin.
- #
- # </ol>This prioritization is then duplicated for the <tt>height</tt>,
- # <tt>bottom</tt> and <tt>top</tt> properties, respectively.
- #
- # While most properties are <i>variable</i>, some mark types, such as lines
- # and areas, generate a single visual element rather than a distinct visual
- # element per datum. With these marks, some properties may be <b>fixed</b>.
- # Fixed properties can vary per mark, but not <i>per datum</i>! These
- # properties are evaluated solely for the first (0-index) datum, and typically
- # are specified as a constant. However, it is valid to use a function if the
- # property varies between panels or is dynamically generated.
- #
+  # Constructs a new mark with default properties. Marks, with the exception of
+  # the root panel, are not typically constructed directly; instead, they are
+  # added to a panel or an existing mark via Mark#add
+  #
+  # Represents a data-driven graphical mark. The +Mark+ class is
+  # the base class for all graphical marks in Protovis; it does not provide any
+  # specific rendering functionality, but together with Panel establishes
+  # the core framework.
+  #
+  # Concrete mark types include familiar visual elements such as bars, lines
+  # and labels. Although a bar mark may be used to construct a bar chart, marks
+  # know nothing about charts; it is only through their specification and
+  # composition that charts are produced. These building blocks permit many
+  # combinatorial possibilities.
+  #
+  # Marks are associated with <b>data</b>: a mark is generated once per
+  # associated datum, mapping the datum to visual <b>properties</b> such as
+  # position and color. Thus, a single mark specification represents a set of
+  # visual elements that share the same data and visual encoding. The type of
+  # mark defines the names of properties and their meaning. A property may be
+  # static, ignoring the associated datum and returning a constant; or, it may be
+  # dynamic, derived from the associated datum or index. Such dynamic encodings
+  # can be specified succinctly using anonymous functions. Special properties
+  # called event handlers can be registered to add interactivity.
+  #
+  # Protovis uses <b>inheritance</b> to simplify the specification of related
+  # marks: a new mark can be derived from an existing mark, inheriting its
+  # properties. The new mark can then override properties to specify new
+  # behavior, potentially in terms of the old behavior. In this way, the old mark
+  # serves as the <b>prototype</b> for the new mark. Most mark types share the
+  # same basic properties for consistency and to facilitate inheritance.
+  #
+  # The prioritization of redundant properties is as follows:<ol>
+  #
+  # <li>If the <tt>width</tt> property is not specified (i.e., null), its value
+  # is the width of the parent panel, minus this mark's left and right margins;
+  # the left and right margins are zero if not specified.
+  #
+  # <li>Otherwise, if the <tt>right</tt> margin is not specified, its value is
+  # the width of the parent panel, minus this mark's width and left margin; the
+  # left margin is zero if not specified.
+  #
+  # <li>Otherwise, if the <tt>left</tt> property is not specified, its value is
+  # the width of the parent panel, minus this mark's width and the right margin.
+  #
+  # </ol>This prioritization is then duplicated for the <tt>height</tt>,
+  # <tt>bottom</tt> and <tt>top</tt> properties, respectively.
+  #
+  # While most properties are <i>variable</i>, some mark types, such as lines
+  # and areas, generate a single visual element rather than a distinct visual
+  # element per datum. With these marks, some properties may be <b>fixed</b>.
+  # Fixed properties can vary per mark, but not <i>per datum</i>! These
+  # properties are evaluated solely for the first (0-index) datum, and typically
+  # are specified as a constant. However, it is valid to use a function if the
+  # property varies between panels or is dynamically generated.
+  #
+  # == 'RBP' API
+  # 
+  # Since version 0.2.0, you could use a new API to use marks
+  # , similar to one described on Brown's "Ruby Best Practices".
+  # === Set properties using blocks 
+  # You could use a block to set a property, without using explicitly
+  # lambda statement. So
+  #   area.width {|d| d*20}
+  # is the same as
+  #   area.width lambda {|d| d*20}
+  # === Shortcuts methods
+  # The protovis API uses the chain method aproach. Every method which
+  # set a value on a object returns the same object. I maintain
+  # this approach, and you can do
+  #
+  #   area.width(10).height(20).top(lambda {|d| d*10})
+  #
+  # To add a mark to another, you need to use +add+ method. This methods
+  # returns the new mark, so you can still use the chain methods API,
+  #
+  #   area.width(10).height(20). # object is 'area'
+  #   add(Rubyvis::Label).       # object changed to new label
+  #     text('hi')               # text refers to new label
+  # 
+  # In the spirit of RBP, I created several methods as shortcut for +add+:
+  # area(), bar(), dot(), image(), label(), line(), panel(), rule() and wedge().
+  # If you provide a block, it will be executed inside the context of current of new mark depending on block's parameter.
+  # * Without parameter: block executed inside context of new mark
+  # * With paramenter: block executed inside context of current mark. 
+  #   Parameter references the new mark
+  # 
+  # ==Example
+  #
+  # *Without parameter*
+  #  vis=Rubyvis::Panel.new do
+  #    area do
+  #      width 10 # width changed for area
+  #      height 10 # height changed for area
+  #    end
+  #  end
+  # 
+  # *Without parameter*
+  #  vis=Rubyvis::Panel.new do
+  #    area do |a|
+  #      width 10 # width changed for panel
+  #      a.height 10 # height changed for area
+  #    end
+  #  end
+  #
   class Mark
+    # On ruby 1.8, we must delete #id method
+    # Is deprecated, so any good developer should'nt use it....
+    if RUBY_VERSION<"1.9"
+      undef_method :id
+    end
+
     # Hash storing properties names for current Mark type. 
     @properties={}
     
@@ -130,7 +185,6 @@ module Rubyvis
     def self.property_method(name, _def, func=nil, klass=nil)
       return if klass.method_defined? name
       klass.send(:define_method, name) do |*arguments,&block|
-        
         v,dummy = arguments
         if block
           v=block
@@ -200,7 +254,11 @@ module Rubyvis
     # the index is set to the instance that triggered the event.
     # @return [Integer]
     def index
-      @index
+      if @index.nil?
+        Mark.index
+      else
+        @index
+      end
     end
     # Returns true if index attribute is set and not deleted
     def index_defined?
@@ -234,8 +292,8 @@ module Rubyvis
     end
     
     
-    # @private Returns the current instance of this mark in the scene graph.
-    # This is typically equivalent to <tt>this.scene[this.index]</tt>, however if the scene or index is unset, the default instance of the mark is returned. If no default is set, the default is the last instance. 
+    # Returns the current instance of this mark in the scene graph.
+    # This is typically equivalent to +self.scene[self.index]+, however if the scene or index is unset, the default instance of the mark is returned. If no default is set, the default is the last instance. 
     # Similarly, if the scene or index of the parent panel is unset, the default instance of this mark in the last instance of the enclosing panel is returned, and so on.
     #
     # @return a node in the scene graph.
@@ -243,9 +301,10 @@ module Rubyvis
       scene=self.scene
       scene||=self.parent.instance(-1).children[self.child_index]
       
-      index = index_defined? ? self.index : default_index
-      # "defined?: #{index_defined?} : type: #{type}, self.index: #{self.index}, index:#{index}"
-      scene[index<0 ? scene.size-1: index]
+      index = !self.index.nil? ? self.index : default_index
+      
+      #puts "defined?: #{index_defined?} : type: #{type}, self.index: #{self.index}, default_index: #{default_index}, index:#{index}"
+      scene[index < 0 ? scene.size-1: index]
     end
 
     ##
@@ -397,17 +456,15 @@ module Rubyvis
       @scale=1
       @scene=nil
       if block
-        block.arity<1 ? self.instance_eval(&block) : block.call(self)
+        execute(&block)
+        #block.arity<1 ? self.instance_eval(&block) : block.call(self)
       end
     end
-    
-    
-    
-    
-
+    # Execute a block using this mark as a reference
+    def execute(&block)
       
-    
-    
+      block.arity<1 ? self.instance_eval(&block) : block.call(self)      
+    end
     # The mark type; a lower name. The type name controls rendering
     # behavior, and unless the rendering engine is extended, must be one of the
     # built-in concrete mark types: area, bar, dot, image, label, line, panel,
@@ -467,8 +524,28 @@ module Rubyvis
       scene
     end
     
+
+    # Returns the first instance of this mark in the scene graph. This
+    # method can only be called when the mark is bound to the scene graph (for
+    # example, from an event handler, or within a property function).
+    #
+    # * @returns a node in the scene graph.
+    def first 
+      scene[0]
+    end
+    # Returns the last instance of this mark in the scene graph. This
+    # method can only be called when the mark is bound to the scene graph (for
+    # example, from an event handler, or within a property function). In addition,
+    # note that mark instances are built sequentially, so the last instance of this
+    # mark may not yet be constructed.
+    #
+    # * @returns a node in the scene graph.
+    def last 
+      scene[scene.size - 1]
+    end
     
-    #Returns the previous instance of this mark in the scene graph, or
+        
+    # Returns the previous instance of this mark in the scene graph, or
     # nil if this is the first instance.
     #
     # @return a node in the scene graph, or nil.
@@ -487,6 +564,15 @@ module Rubyvis
       s= par ? par.sibling : nil
       (s and s.children) ? s.children[self.child_index][self.index] : nil
     end
+    
+    # Adds a new mark of the specified type to the enclosing parent panel,
+    # whilst simultaneously setting the prototype of the new mark 
+    # to be this mark.
+    #
+    # * @param {function} type the type of mark to add; a constructor, such as
+    # +Rubyvis::Bar+
+    # * @returns {Mark} the new mark.
+    # * @see #extend
     def add(type)
       parent.add(type).extend(self)
     end
@@ -526,13 +612,13 @@ module Rubyvis
           a=self.scene.target.map {|s| puts "s:#{s.data}" if $DEBUG; s.data}
           p a if $DEBUG
           a 
+        }).visible(lambda {
+          self.scene.target[index].visible
+        }).id(lambda {
+            self.scene.target[index].id
         }).
-        visible(lambda {
-          self.scene.target[self.index].visible
-        }).
-        id(lambda {self.scene.target[self.index].id}).
         left(lambda {
-          s = self.scene.target[self.index]
+          s = self.scene.target[index]
           w = s.width
           w||=0
           if ['bottom','top','center'].include?(self.name)
@@ -577,7 +663,7 @@ module Rubyvis
           'bottom'
         end
       })
-      return anchor
+      anchor
     end
 
 
@@ -685,7 +771,10 @@ module Rubyvis
         parent=parent.parent
       end
 
-      self.context( parent ? parent.scene : nil, parent ? parent.index : -1, lambda {render_render(self.root, 0,1)})
+      self.context( parent ? parent.scene : nil,
+        parent ? parent.index : -1,
+        lambda { render_render(root, 0,1) }
+        )
 
     end
 
@@ -786,7 +875,7 @@ module Rubyvis
     end
 
 
-    def context_apply(scene,index)
+    def context_apply(scene,index) # :nodoc:
       Mark.scene=scene
       Mark.index=index
       return if(!scene)
@@ -819,7 +908,7 @@ module Rubyvis
       end
 
     end
-    def context_clear(scene,index)
+    def context_clear(scene,index) # :nodoc:
       return if !scene
       that=scene.mark
       mark=nil
@@ -841,7 +930,7 @@ module Rubyvis
         mark.index=nil
       end while(mark=mark.parent)
     end
-    def context(scene,index,f)
+    def context(scene,index,f) # :nodoc:
       proto=Mark
       stack=Mark.stack
       oscene=Mark.scene
@@ -954,7 +1043,7 @@ module Rubyvis
     #
     # @param s a node in the scene graph; the instance of the mark to build.
     # @param properties an array of properties.
-    def build_properties(ss, props)
+    def build_properties(ss, props) # :nodoc:
       #p props
       props.each do |prop|
         v=prop.value
@@ -967,7 +1056,7 @@ module Rubyvis
       end
     end
     # @todo implement
-    def event(type,handler)
+    def event(type,handler) # :nodoc:
       #@_handlers[type]=handler
       self
     end