lib/rspreadsheet/row.rb in rspreadsheet-0.2.3 vs lib/rspreadsheet/row.rb in rspreadsheet-0.2.4

@@ -1,47 +1,59 @@
 require 'rspreadsheet/cell'
 require 'rspreadsheet/xml_tied'
 
-# Currently this is only syntax sugar for cells and contains no functionality
 
 module Rspreadsheet
 
+# Represents a row in a spreadsheet which has coordinates, contains value, formula and can be formated.
+# You can get this object like this (suppose that @worksheet contains {Rspreadsheet::Worksheet} object)
+#
+#     @row = @worksheet.rows(5)
+#
+# Mostly you will this object to access row cells
+#
+#     @row.cells(2)     # identical to @worksheet.rows(5).cells(2)
+#     @row[2]           # identical to @worksheet[5,2] or @row.cells(2)
+#
+# or manipulate rows
+#
+#     @row.add_row_above   # adds empty row above
+#     @row.delete          # deletes row
+#
+# and shifts all other rows down/up appropriatelly.
+
 class Row < XMLTiedItem
   include XMLTiedArray
-  attr_reader :worksheet, :rowi
-  def xml_repeated_attribute; 'number-rows-repeated' end
-  def xml_items_node_name; 'table-row' end
-  def xml_options; {:xml_items_node_name => xml_items_node_name, :xml_repeated_attribute => xml_repeated_attribute} end
-  def subitem_xml_options; {:xml_items_node_name => 'table-cell', :xml_repeated_attribute => 'number-columns-repeated'} end
+  ## @return [Worksheet] worksheet which contains the row
+  # @!attribute [r] worksheet
+  attr_reader :worksheet
+  ## @return [Integer] row index of the row
+  # @!attribute [r] rowi
+  attr_reader :rowi 
     
   def initialize(aworksheet,arowi)
     @worksheet = aworksheet
     @rowi = arowi
     @itemcache = Hash.new  #TODO: move to module XMLTiedArray
   end
+  
   def xmlnode; parent.find_my_subnode_respect_repeated(index, xml_options)  end
     
-  # XMLTiedItem things and extensions
-  def parent; @worksheet end
-  def index; @rowi end
-  def set_index(value); @rowi=value end
-    
-  # XMLTiedArray rozšíření 
-  def prepare_subitem(coli); Cell.new(@worksheet,@rowi,coli) end
-  def cells(*params)
-    raise 'Invalid row reference' if invalid_reference?
-    case params.length 
-      when 0 then subitems_array
-      when 1 then subitem(params[0]) 
-      else raise Exception.new('Wrong number of arguments.')
-    end
-  end
-  # syntactis sugar to cells and its values
+ # @!group Syntactic sugar
+  def cells(*params); subitems(*params) end
+  
+  ## @return [String or Float or Date] value of the cell
+  # @param coli [Integer] colum index of the cell 
+  # returns value of the cell at column `coli`
   def [](coli); cells(coli).value end
+  ## @param coli [Integer] colum index of the cell 
+  # @param avalue [String or Float or Date] colum index of the cell  
+  # sets value of the cell at column `coli`
   def []=(coli,avalue); cells(coli).value=avalue end
-    
-  # další
+ # @!endgroup
+  
+ # @!group Other methods
   def style_name=(value); 
     detach_if_needed
     Tools.set_ns_attribute(xmlnode,'table','style-name',value)
   end
   def nonemptycells
@@ -54,13 +66,35 @@
     else
       @worksheet.find_nonempty_subnode_indexes(myxmlnode, {:xml_items_node_name => 'table-cell', :xml_repeated_attribute => 'number-columns-repeated'})
     end
   end
   alias :used_range :range
-  def shift_by(diff)
+  # Inserts row above itself (and shifts itself and all following rows down)
+  def add_row_above
+    parent.add_row_above(rowi)
+  end
+  def cellvalues
+    cells.collect{|c| c.value}
+  end
+  
+ # @!group Private methods, which should not be called directly
+  # @private
+  # shifts internal represetation of row by diff. This should not be called directly
+  # by user, it is only used by XMLTiedArray as hook when shifting around rows
+  def _shift_by(diff)
     super
     @itemcache.each_value{ |cell| cell.set_rowi(@rowi) }
   end
+  
+ private
+  # @!group XMLTiedArray related methods
+  def subitem_xml_options; {:xml_items_node_name => 'table-cell', :xml_repeated_attribute => 'number-columns-repeated'} end
+  def prepare_subitem(coli); Cell.new(@worksheet,@rowi,coli) end
+  # @!group XMLTiedItem related methods and extensions
+  def xml_options; {:xml_items_node_name => 'table-row', :xml_repeated_attribute => 'number-rows-repeated'} end
+  def parent; @worksheet end                
+  def index; @rowi end                       
+  def set_index(value); @rowi=value end      
 end
 
 # class Row
 #   def initialize
 #     @readonly = :unknown
\ No newline at end of file