robust_excel_ole 1.2 → 1.3

data/docs/README_save_close.rdoc

@@ -6,7 +6,7 @@
 
 Imagine, you have opened a workbook with
 
-  book = Workbook.open('workbook.xls', :visible => true)
+  book = Workbook.open('spec/data/workbook.xls', :visible => true)
 
 and have modified it.
 
@@ -37,8 +37,8 @@ For example, you want to save a workbook and overwrite the file if it exists bef
 
 If a workbook blocks the workbook that should be saved, then the former one can be saved and closed before.
 
-  book = Workbook.open('workbook.xls')
-  book2 = Workbook.open('another_workbook.xls')
+  book = Workbook.open('spec/data/workbook.xls')
+  book2 = Workbook.open('spec/data/another_workbook.xls')
   book2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)  
 
 === Closing a workbook.
@@ -62,7 +62,7 @@ The option specifies: If the workbook is unsaved, then
 
 You can open a workbook with given file name.
 
-  book = Workbook.open('workbook.xls')
+  book = Workbook.open('spec/data/workbook.xls')
 
 You can save a workbook with given file name, if it is open.
 
@@ -70,8 +70,8 @@ You can save a workbook with given file name, if it is open.
 
 The workbook can be saved under a new file name, if it is open.
 
-  Workbook.save_as('workbook.xls', 'new_workbook.xls')
+  Workbook.save_as('spec/data/workbook.xls', 'new_workbook.xls')
 
 Finally the workbook can be closed with a given filename.
 
-  Workbook.close('workbook.xls')
+  Workbook.close('spec/data/workbook.xls')

data/docs/README_sheet.rdoc

@@ -6,7 +6,7 @@ Worksheets are represented by Sheet objects.
 
 Assume you have opened a workbook
 
-  book = Workbook.open('workbook.xls', :visible => true)
+  book = Workbook.open('spec/data/workbook.xls', :visible => true)
 
 === Accessing a worksheet.
 
@@ -32,6 +32,10 @@ You can access all Sheet objects by using the methods Workbook#each.
     # do something with sheet
   end
 
+Once you have got a Sheet object (in RobustExcelOle), you can apply all VBA methods that you would apply to a VBA Worksheet object
+(see https://docs.microsoft.com/en-us/office/vba/api/excel.worksheet#methods).
+For some common and complex tasks you can apply methods of RobustExcelOle.
+
 === Reading and changing the worksheet name
 
 You can read and change the worksheet name.

data/examples/edit_sheets/example_concating.rb

@@ -24,7 +24,7 @@ begin
         name = cell.Name.Name rescue nil
         if name
           cell.Value = cell.Value.to_s + cell.Offset(0,1).Value.to_s
-          sheet.set_name(name, cell.Row, cell.Column)
+          sheet.add_name(name, cell.Row, cell.Column)
         end
       end
     end

data/examples/edit_sheets/example_copying.rb

@@ -33,7 +33,7 @@ begin
           cell_name = short_name ? short_name : sheet_name
           contains_named_cells = true
           new_sheet[cell.Row, cell.Column].Value = cell.Value
-          new_sheet.set_name(cell_name, cell.Row,cell.Column)
+          new_sheet.add_name(cell_name, cell.Row,cell.Column)
         end
       end
       new_sheet.Delete() unless contains_named_cells

data/examples/edit_sheets/example_expanding.rb

@@ -36,7 +36,7 @@ begin
       rescue REOError => msg
         sheet_new.name = sheet_name + sheet.name if msg.message == "sheet name already exists" 
       end
-      sheet_new.set_name("name", 2, 2)
+      sheet_new.add_name("name",2,2)
       sheet_new["name"] = sheet_name   
     end
     

data/examples/edit_sheets/example_naming.rb

@@ -29,7 +29,7 @@ begin
     book.each do |sheet|
       sheet.each do |cell_orig|
         contents = cell_orig.Value
-        sheet.set_name(contents, cell_orig.Row, cell_orig.Column) if contents && contents.is_a?(String)
+        sheet.add_name(contents, cell_orig.Row, cell_orig.Column) if contents && contents.is_a?(String)
       end
     end
   end

data/examples/open_save_close/example_rename_cells.rb

@@ -17,7 +17,7 @@ begin
   workbook = book.ole_workbook
   fullname = workbook.Fullname
   puts "fullname: #{fullname}"  
-  sheet.set_name("a_name",1,1)   # rename cell A1 to "a_name"
+  sheet.add_name("a_name",1,1)   # rename cell A1 to "a_name"
   number = workbook.Names.Count
   puts "number of name objects :#{number}"
   name_object = workbook.Names("a_name")

data/lib/robust_excel_ole/book.rb

@@ -77,7 +77,7 @@ module RobustExcelOle
       def open(file, opts={ }, &block)
         options = @options = process_options(opts)
         book = nil
-        if (not (options[:force][:excel] == :new))
+        if (not (options[:force][:excel] == :new) and not (options[:force][:excel] == :reserved_new))
           # if readonly is true, then prefer a book that is given in force_excel if this option is set
           forced_excel = if options[:force][:excel]
             options[:force][:excel] == :current ? excel_class.new(:reuse => true) : excel_of(options[:force][:excel])
@@ -238,7 +238,8 @@ module RobustExcelOle
         return
       end
       excel_option = (options[:force].nil? or options[:force][:excel].nil?) ? options[:default][:excel] : options[:force][:excel]
-      @excel = self.class.excel_of(excel_option) unless (excel_option == :current || excel_option == :new)
+      @excel = self.class.excel_of(excel_option) unless (excel_option == :current || excel_option == :new || excel_option == :reserved_new)
+      excel_class.new(:reuse => false) if excel_option == :reserved_new and Excel.known_excel_instances.empty?
       @excel = excel_class.new(:reuse => (excel_option == :current)) unless (@excel && @excel.alive?)
       @excel
     end    
@@ -772,30 +773,14 @@ module RobustExcelOle
     # @param [String] name the name of a range
     # @returns [Variant] the value of the range
     def [] name
-      nameval(name)
+      namevalue_glob(name)
     end
 
     # sets the value of a range
     # @param [String]  name  the name of the range
     # @param [Variant] value the contents of the range
     def []= (name, value)
-      set_nameval(name,value, :color => 42)   # 42 - aqua-marin, 4-green
-    end
-
-    # renames a range
-    # @param [String] name     the previous range name
-    # @param [String] new_name the new range name
-    def rename_range(name, new_name)
-      begin
-        item = self.Names.Item(name)
-      rescue WIN32OLERuntimeError
-        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
-      end
-      begin
-        item.Name = new_name
-      rescue WIN32OLERuntimeError
-        raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"      
-      end
+      set_namevalue_glob(name,value, :color => 42)   # 42 - aqua-marin, 4-green
     end
 
     # sets options

data/lib/robust_excel_ole/excel.rb

@@ -604,14 +604,14 @@ module RobustExcelOle
     # @param [String] name the name of a range
     # @returns [Variant] the value of the range
     def [] name
-      nameval(name)
+      namevalue_glob(name)
     end
 
     # sets the value of a range
     # @param [String]  name  the name of the range
     # @param [Variant] value the contents of the range
     def []= (name, value)
-      set_nameval(name,value, :color => 42) # 42 - aqua-marin, 7-green
+      set_namevalue_glob(name,value, :color => 42) # 42 - aqua-marin, 7-green
     end
 
     def to_s              # :nodoc: #
@@ -657,8 +657,13 @@ module RobustExcelOle
     end
 
   end
+
+  public
+
+    Application = Excel
+
 end
 
 class WIN32OLE
   include Enumerable
-end  
+end

data/lib/robust_excel_ole/range.rb

@@ -1,22 +1,27 @@
 # -*- coding: utf-8 -*-
 module RobustExcelOle
+  
   class Range < REOCommon
     include Enumerable
+    attr_reader :ole_range
+    attr_reader :worksheet
 
     def initialize(win32_range)
-      @range = win32_range
+      @ole_range = win32_range
+      @worksheet = sheet_class.new(self.Parent)
     end
 
     def each
-      @range.each do |row_or_column|
+      @ole_range.each do |row_or_column|
         yield RobustExcelOle::Cell.new(row_or_column)
       end
     end
 
+    # returns flat array of the values of a given range
+    # @params [Range] a range
+    # @returns [Array] the values
     def values(range = nil)
-#+#      result = self.map(&:value).flatten
       result = self.map{|x| x.value}.flatten
-#+#      range ? result.each_with_index.select{ |row_or_column, i| range.include?(i) }.map{ |i| i[0] } : result
       if range 
         relevant_result = []
         result.each_with_index{ |row_or_column, i| relevant_result << row_or_column if range.include?(i) }
@@ -28,11 +33,48 @@ module RobustExcelOle
 
     def [] index
       @cells = []
-      @cells[index + 1] = RobustExcelOle::Cell.new(@range.Cells.Item(index + 1))
+      @cells[index + 1] = RobustExcelOle::Cell.new(@ole_range.Cells.Item(index + 1))
     end
 
+    # copies a range
+    # @params [Fixnum,Range] row or range of the rows 
+    # @params [Fixnum,Range] column or range of columns 
+    # @options [Sheet] the worksheet in which to copy      
+    def copy(int_range1, int_range2, sheet = :__not_provided)
+      int_range1 = int_range1 .. int_range1 if int_range1.is_a?(Fixnum)
+      int_range2 = int_range2 .. int_range2 if int_range2.is_a?(Fixnum)
+      sheet = @worksheet if sheet == :__not_provided
+      if sheet.workbook.excel == @worksheet.workbook.excel 
+        begin
+          self.Copy(:destination => sheet.range(int_range1.min..int_range1.max,
+                                                int_range2.min..int_range2.max).ole_range)
+        rescue WIN32OLERuntimeError
+          raise RangeNotCopied, "cannot copy range"
+        end
+      else
+        self.Select
+        self.Copy
+        sheet.Paste(sheet.range(int_range1.min..int_range1.max,int_range2.min..int_range2.max).ole_range)
+      end
+    end
+
+    def self.sheet_class    # :nodoc: #
+      @sheet_class ||= begin
+        module_name = self.parent_name
+        "#{module_name}::Sheet".constantize
+      rescue NameError => e
+        Sheet
+      end
+    end
+
+    def sheet_class        # :nodoc: #
+      self.class.sheet_class
+    end
+
+  private
+
     def method_missing(id, *args)  # :nodoc: #
-      @range.send(id, *args)
+      @ole_range.send(id, *args)
     end
   end
 end

data/lib/robust_excel_ole/reo_common.rb

@@ -65,6 +65,12 @@ module RobustExcelOle
   class RangeNotEvaluatable < MiscREOError         # :nodoc: #
   end
 
+  class RangeNotCreated < MiscREOError             # :nodoc: #
+  end
+
+  class RangeNotCopied < MiscREOError              # :nodoc: #
+  end
+
   class OptionInvalid < MiscREOError               # :nodoc: #
   end
 
@@ -77,6 +83,9 @@ module RobustExcelOle
   class TimeOut < REOError                         # :nodoc: #
   end  
 
+  class AddressInvalid < REOError                  # :nodoc: #
+  end
+
   class UnexpectedREOError < REOError              # :nodoc: #
   end
 
@@ -129,6 +138,42 @@ module RobustExcelOle
 
   end
 
+  class Address < REOCommon
+
+    attr_reader :rows
+    attr_reader :columns
+    attr_reader :a1_format
+
+    def initialize(address_comp1, address_comp2 = __not_provided)
+      begin
+        if address_comp2 == __not_provided                  
+          row_comp = address_comp1.gsub(/[0-9]/,'')
+          column_comp = address_comp1.gsub(/[A-Z]/,'')
+          if address_comp1 != column_comp+row_comp
+            raise AddressInvalid, "address #{address_comp1.inspect} not in A1-format"
+          end             
+          address_comp1, address_comp2 = column_comp, row_comp
+        end
+        address_comp1 = address_comp1 .. address_comp1 unless address_comp1.is_a?(Range)
+        address_comp2 = address_comp2 .. address_comp2 unless address_comp2.is_a?(Range)
+        if address_comp1.min.is_a?(String)
+          raise AddressInvalid, "address (#{address_comp1.inspect}, #{address_comp2.inspect}) not in A1-format" if address_comp2.min.is_a?(String)
+          @columns = address_comp1
+          @rows = address_comp2
+          @a1_format = true
+        else
+          @columns = address_comp2
+          @rows = address_comp1
+          @a1_format = false
+        end
+      rescue  
+        address_string = (address_comp2 == __not_provided) ? 
+          "#{address_comp1.inspect}" : "#{address_comp1.inspect}, #{address_comp2.inspect}"
+        raise AddressInvalid, "address (#{address_string}) not in A1- or R1C1-format"
+      end
+    end
+  end
+
   class RangeOwners < REOCommon
 
     # returns the contents of a range with given name
@@ -141,7 +186,7 @@ module RobustExcelOle
     # @param  [Hash]        opts      the options
     # @option opts [Symbol] :default  the default value that is provided if no contents could be returned
     # @return [Variant] the contents of a range with given name
-    def nameval(name, opts = {:default => :__not_provided})
+    def namevalue_glob(name, opts = {:default => :__not_provided})
       name_obj = begin
         name_object(name)
       rescue NameNotFound => msg
@@ -175,7 +220,7 @@ module RobustExcelOle
     # @param [Variant] value the contents of the range
     # @param [FixNum]  color the color when setting a value
     # @param [Hash]    opts :color [FixNum]  the color when setting the contents
-    def set_nameval(name, value, opts = {:color => 0})
+    def set_namevalue_glob(name, value, opts = {:color => 0})
       begin
         cell = name_object(name).RefersToRange
         cell.Interior.ColorIndex = opts[:color] 
@@ -194,8 +239,8 @@ module RobustExcelOle
     # @param  [Hash]        opts      the options
     # @option opts [Symbol] :default  the default value that is provided if no contents could be returned
     # @return [Variant] the contents of a range with given name   
-    def rangeval(name, opts = {:default => :__not_provided})
-      return nameval(name, opts) if self.is_a?(Book)
+    def namevalue(name, opts = {:default => :__not_provided})
+      return namevalue_glob(name, opts) if self.is_a?(Book)
       begin
         range = self.Range(name)
       rescue WIN32OLERuntimeError
@@ -214,17 +259,15 @@ module RobustExcelOle
       end 
       return opts[:default] unless opts[:default] == :__not_provided or value.nil?
       value      
-      #return opts[:default] unless opts[:default] == :__not_provided
-      #raise RangeNotEvaluatable, "cannot evaluate range named #{name.inspect}" if value == -2146828288 + RobustExcelOle::XlErrName
     end
 
     # assigns a value to a range given a locally defined name
     # @param [String]  name   the name of a range
     # @param [Variant] value  the assigned value
     # @param [Hash]    opts :color [FixNum]  the color when setting the contents
-    def set_rangeval(name,value, opts = {:color => 0})
+    def set_namevalue(name, value, opts = {:color => 0})
       begin
-        return set_nameval(name, value, opts) if self.is_a?(Book)
+        return set_namevalue_glob(name, value, opts) if self.is_a?(Book)
         range = self.Range(name)
       rescue WIN32OLERuntimeError
         raise NameNotFound, "name #{name.inspect} not in #{self.inspect}"
@@ -238,14 +281,85 @@ module RobustExcelOle
       end
     end
 
+    def nameval(name, opts = {:default => :__not_provided})   # :deprecated: #
+      namevalue_glob(name, opts)
+    end
+
+    def set_nameval(name, value, opts = {:color => 0})        # :deprecated: #
+      set_namevalue_glob(name, value, opts)
+    end
+
+    def rangeval(name, opts = {:default => :__not_provided})  # :deprecated: #
+      namevalue(name, opts)
+    end
+
+    def set_rangeval(name, value, opts = {:color => 0})       # :deprecated: #
+      set_namevalue(name, value, opts)
+    end
+
+    # adds a name referring to a range given by the row and column
+    # @param [String] name   the range name
+    # @params [Fixnum,Range] row or range of the rows 
+    # @params [Fixnum,Range] column or range of columns 
+    def add_name(name, int_range1, int_range2)
+      int_range1 = int_range1 .. int_range1 if int_range1.is_a?(Fixnum)
+      int_range2 = int_range2 .. int_range2 if int_range2.is_a?(Fixnum)
+      address = "Z" + int_range1.min.to_s + "S" + int_range2.min.to_s + 
+                ":Z" + int_range1.max.to_s + "S" + int_range2.max.to_s
+      begin
+        self.Names.Add("Name" => name, "RefersToR1C1" => "=" + address)
+      rescue WIN32OLERuntimeError => msg
+        #trace "WIN32OLERuntimeError: #{msg.message}"
+        raise RangeNotEvaluatable, "cannot add name #{name.inspect} to cell with row #{row.inspect} and column #{column.inspect}"
+      end
+      name
+    end 
+
+    def set_name(name,row,column)     # :deprecated :#
+      add_name(name,row,column)
+    end
+
+    # renames a range
+    # @param [String] name     the previous range name
+    # @param [String] new_name the new range name
+    def rename_range(name, new_name)
+      begin
+        item = self.Names.Item(name)
+      rescue WIN32OLERuntimeError
+        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
+      end
+      begin
+        item.Name = new_name
+      rescue WIN32OLERuntimeError
+        raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"      
+      end
+    end
+
+    # deletes a name of a range
+    # @param [String] name     the previous range name
+    # @param [String] new_name the new range name
+    def delete_name(name)
+      begin
+        item = self.Names.Item(name)
+      rescue WIN32OLERuntimeError
+        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
+      end
+      begin
+        item.Delete
+      rescue WIN32OLERuntimeError
+        raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"      
+      end
+    end
+
+
   private  
 
     def name_object(name)
       begin
-        self.Parent.Names.Item(name)
+        self.Names.Item(name)        
       rescue WIN32OLERuntimeError
         begin
-          self.Names.Item(name)
+          self.Parent.Names.Item(name)
         rescue WIN32OLERuntimeError
           raise RobustExcelOle::NameNotFound, "name #{name.inspect} not in #{self.inspect}"  
         end