robust_excel_ole 1.3 → 1.4

data/lib/robust_excel_ole/reo_common.rb

@@ -95,7 +95,7 @@ module RobustExcelOle
   class REOCommon
 
     def excel
-      raise TypeREOError, "receiver instance is neither an Excel nor a Book"
+      raise TypeREOError, "receiver instance is neither an Excel nor a Workbook"
     end
 
     def own_methods
@@ -142,36 +142,53 @@ module RobustExcelOle
 
     attr_reader :rows
     attr_reader :columns
-    attr_reader :a1_format
 
-    def initialize(address_comp1, address_comp2 = __not_provided)
+    def initialize(address)
+      address = [address] unless address.is_a?(Array)
+      raise AddressInvalid, "more than two components" if address.size > 2
       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
+        if address.size == 1
+          comp1, comp2 = address[0].split(':')          
+          address_comp1 = comp1.gsub(/[A-Z]/,'')
+          address_comp2 = comp1.gsub(/[0-9]/,'')
+          if comp1 != address_comp2+address_comp1
+            raise AddressInvalid, "address #{comp1.inspect} not in A1-format"
+          end
+          unless comp2.nil?
+            address_comp3 = comp2.gsub(/[A-Z]/,'')
+            address_comp4 = comp2.gsub(/[0-9]/,'')  
+            if comp2 != address_comp4+address_comp3
+              raise AddressInvalid, "address #{comp2.inspect} not in A1-format"
+            end
+            address_comp1 = address_comp1..address_comp3
+            address_comp2 = address_comp2..address_comp4
+          end
+        else
+          address_comp1, address_comp2 = address
         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
+        address_comp1 = address_comp1 .. address_comp1 unless address_comp1.is_a?(Object::Range)
+        address_comp2 = address_comp2 .. address_comp2 unless address_comp2.is_a?(Object::Range)
+        @rows = address_comp1.min.to_i .. address_comp1.max.to_i
+        if address_comp2.min.to_i == 0
+          raise AddressInvalid, "address (#{address_comp1.inspect}, #{address_comp2.inspect}) not in A1-format" if address_comp1.min.to_i == 0                    
+          @columns = str2num(address_comp2.min) .. str2num(address_comp2.max)
         else
-          @columns = address_comp2
-          @rows = address_comp1
-          @a1_format = false
+          @columns = address_comp2.min.to_i .. address_comp2.max.to_i
         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"
+        raise AddressInvalid, "address (#{address.inspect}) not in A1- or R1C1-format"
       end
     end
+
+  private
+
+    def str2num(str)
+      str = str.upcase
+      sum = 0
+      (1..str.length).each { |i| sum += (str[i-1].ord-64) * 26 ** (str.length - i) }
+      sum
+    end
+
   end
 
   class RangeOwners < REOCommon
@@ -196,8 +213,8 @@ module RobustExcelOle
       value = begin
         name_obj.RefersToRange.Value
       rescue WIN32OLERuntimeError
-        sheet = if self.is_a?(Sheet) then self
-        elsif self.is_a?(Book) then self.sheet(1)
+        sheet = if self.is_a?(Worksheet) then self
+        elsif self.is_a?(Workbook) then self.sheet(1)
         elsif self.is_a?(Excel) then self.workbook.sheet(1)
         end
         begin
@@ -240,7 +257,7 @@ module RobustExcelOle
     # @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 namevalue(name, opts = {:default => :__not_provided})
-      return namevalue_glob(name, opts) if self.is_a?(Book)
+      return namevalue_glob(name, opts) if self.is_a?(Workbook)
       begin
         range = self.Range(name)
       rescue WIN32OLERuntimeError
@@ -267,7 +284,7 @@ module RobustExcelOle
     # @param [Hash]    opts :color [FixNum]  the color when setting the contents
     def set_namevalue(name, value, opts = {:color => 0})
       begin
-        return set_namevalue_glob(name, value, opts) if self.is_a?(Book)
+        return set_namevalue_glob(name, value, opts) if self.is_a?(Workbook)
         range = self.Range(name)
       rescue WIN32OLERuntimeError
         raise NameNotFound, "name #{name.inspect} not in #{self.inspect}"
@@ -297,23 +314,32 @@ module RobustExcelOle
       set_namevalue(name, value, opts)
     end
 
+    # @params [String] name  defined range name
+    # @returns [Range] a Range object
+    def name2range(name)
+      begin
+        RobustExcelOle::Range.new(name_object(name).RefersToRange)
+      rescue WIN32OLERuntimeError
+        raise RangeNotCreated, "range could not be created from the defined name"
+      end
+    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
+    # @params [Address] address of the range 
+    def add_name(name, addr, addr_deprecated = :__not_provided)
+      addr = [addr,addr_deprecated] unless addr_deprecated == :__not_provided
+      address = Address.new(addr)
+      address_string = "Z" + address.rows.min.to_s + "S" + address.columns.min.to_s + 
+                ":Z" + address.rows.max.to_s + "S" + address.columns.max.to_s
       begin
-        self.Names.Add("Name" => name, "RefersToR1C1" => "=" + address)
+        self.Names.Add("Name" => name, "RefersToR1C1" => "=" + address_string)
       rescue WIN32OLERuntimeError => msg
         #trace "WIN32OLERuntimeError: #{msg.message}"
-        raise RangeNotEvaluatable, "cannot add name #{name.inspect} to cell with row #{row.inspect} and column #{column.inspect}"
+        raise RangeNotEvaluatable, "cannot add name #{name.inspect} to range #{addr.inspect}"
       end
       name
-    end 
+    end
 
     def set_name(name,row,column)     # :deprecated :#
       add_name(name,row,column)

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "1.3"
+  VERSION = "1.4"
 end

data/lib/robust_excel_ole/{book.rb → workbook.rb}

@@ -4,7 +4,9 @@ require 'weakref'
 
 module RobustExcelOle
 
-  class Book < RangeOwners
+  # see https://docs.microsoft.com/en-us/office/vba/api/excel.workbook#methods
+
+  class Workbook < RangeOwners
 
     attr_accessor :excel
     attr_accessor :ole_workbook
@@ -73,7 +75,7 @@ module RobustExcelOle
       # :visible              true -> makes the workbook visible
       # :check_compatibility  true -> check compatibility when saving
       # :update_links         true -> user is being asked how to update links, false -> links are never updated
-      # @return [Book] a representation of a workbook
+      # @return [Workbook] a representation of a workbook
       def open(file, opts={ }, &block)
         options = @options = process_options(opts)
         book = nil
@@ -111,12 +113,12 @@ module RobustExcelOle
       end
     end    
 
-    # creates a Book object by opening an Excel file given its filename workbook or 
-    # by lifting a Win32OLE object representing an Excel file
+    # creates a Workbook object by opening an Excel file given its filename workbook
+    # or by promoting a Win32OLE object representing an Excel file
     # @param [WIN32OLE] workbook a workbook
     # @param [Hash] opts the options
     # @option opts [Symbol] see above
-    # @return [Book] a workbook
+    # @return [Workbook] a workbook
     def self.new(workbook, opts={ }, &block)
       opts = process_options(opts)
       if workbook && (workbook.is_a? WIN32OLE)
@@ -136,12 +138,12 @@ module RobustExcelOle
       end
     end
 
-    # creates a new Book object, if a file name is given
-    # Promotes the workbook to a Book object, if a win32ole-workbook is given    
+    # creates a new Workbook object, if a file name is given
+    # Promotes the win32ole workbook to a Workbook object, if a win32ole-workbook is given    
     # @param [Variant] file_or_workbook  file name or workbook
     # @param [Hash]    opts              the options
     # @option opts [Symbol] see above
-    # @return [Book] a workbook
+    # @return [Workbook] a workbook
     def initialize(file_or_workbook, options={ }, &block)
       #options = @options = self.class.process_options(options) if options.empty?
       if file_or_workbook.is_a? WIN32OLE        
@@ -210,7 +212,7 @@ module RobustExcelOle
       opts
     end
 
-    # returns an Excel object when given Excel, Book or Win32ole object representing a Workbook or an Excel
+    # returns an Excel object when given Excel, Workbook or Win32ole object representing a Workbook or an Excel
     def self.excel_of(object)  # :nodoc: #
       if object.is_a? WIN32OLE
         case object.ole_obj_help.name
@@ -478,7 +480,7 @@ module RobustExcelOle
     # @option opts [Boolean] :rw_change_excel Excel instance in which the workbook with the new
     #                         write permissions shall be opened  :current (default), :new or an Excel instance                   
     # @option opts [Boolean] :keep_open whether the workbook shall be kept open after unobtrusively opening 
-    # @return [Book] a workbook
+    # @return [Workbook] a workbook
     def self.unobtrusively(file, opts = { }, &block) 
       opts = {:if_closed => :current,
               :rw_change_excel => :current,
@@ -577,7 +579,7 @@ module RobustExcelOle
     #                  :close_if_saved      -> closes the blocking workbook, if it is saved, 
     #                                          otherwise raises an exception
     # :discoloring     states, whether colored ranges shall be discolored
-    # @return [Book], the book itself, if successfully saved, raises an exception otherwise
+    # @return [Workbook], the book itself, if successfully saved, raises an exception otherwise
     def save_as(file, opts = { } )
       raise FileNameNotGiven, "filename is nil" if file.nil?
       raise ObjectNotAlive, "workbook is not alive" unless alive?
@@ -682,10 +684,10 @@ module RobustExcelOle
 
     # returns a sheet, if a sheet name or a number is given
     # @param [String] or [Number]
-    # @returns [Sheet]
+    # @returns [Worksheet]
     def sheet(name)
       begin
-        sheet_class.new(@ole_workbook.Worksheets.Item(name))
+        worksheet_class.new(@ole_workbook.Worksheets.Item(name))
       rescue WIN32OLERuntimeError => msg
         raise NameNotFound, "could not return a sheet with name #{name.inspect}"
       end
@@ -693,32 +695,32 @@ module RobustExcelOle
 
     def each
       @ole_workbook.Worksheets.each do |sheet|
-        yield sheet_class.new(sheet)
+        yield worksheet_class.new(sheet)
       end
     end
 
     def each_with_index(offset = 0)
       i = offset
       @ole_workbook.Worksheets.each do |sheet|
-        yield sheet_class.new(sheet), i
+        yield worksheet_class.new(sheet), i
         i += 1
       end
     end
   
     # copies a sheet to another position
     # default: copied sheet is appended
-    # @param [Sheet] sheet a sheet that shall be copied
+    # @param [Worksheet] sheet a sheet that shall be copied
     # @param [Hash]  opts  the options
     # @option opts [Symbol] :as     new name of the copied sheet
     # @option opts [Symbol] :before a sheet before which the sheet shall be inserted
     # @option opts [Symbol] :after  a sheet after which the sheet shall be inserted
     # @raise  NameAlreadyExists if the sheet name already exists
-    # @return [Sheet] the copied sheet
+    # @return [Worksheet] the copied sheet
     def copy_sheet(sheet, opts = { })
       new_sheet_name = opts.delete(:as)
       after_or_before, base_sheet = opts.to_a.first || [:after, last_sheet]
       sheet.Copy({ after_or_before.to_s => base_sheet.ole_worksheet })
-      new_sheet = sheet_class.new(@excel.Activesheet)
+      new_sheet = worksheet_class.new(@excel.Activesheet)
       new_sheet.name = new_sheet_name if new_sheet_name
       new_sheet
     end      
@@ -730,24 +732,24 @@ module RobustExcelOle
     # @option opts [Symbol] :before a sheet before which the sheet shall be inserted
     # @option opts [Symbol] :after  a sheet after which the sheet shall be inserted
     # @raise  NameAlreadyExists if the sheet name already exists
-    # @return [Sheet] the added sheet
+    # @return [Worksheet] the added sheet
     def add_empty_sheet(opts = { })
       new_sheet_name = opts.delete(:as)
       after_or_before, base_sheet = opts.to_a.first || [:after, last_sheet]
       @ole_workbook.Worksheets.Add({ after_or_before.to_s => base_sheet.ole_worksheet })
-      new_sheet = sheet_class.new(@excel.Activesheet)
+      new_sheet = worksheet_class.new(@excel.Activesheet)
       new_sheet.name = new_sheet_name if new_sheet_name
       new_sheet
     end    
 
     # copies a sheet to another position if a sheet is given, or adds an empty sheet
     # default: copied or empty sheet is appended, i.e. added behind the last sheet
-    # @param [Sheet] sheet a sheet that shall be copied (optional)
+    # @param [Worksheet] sheet a sheet that shall be copied (optional)
     # @param [Hash]  opts  the options
     # @option opts [Symbol] :as     new name of the copied or added sheet
     # @option opts [Symbol] :before a sheet before which the sheet shall be inserted
     # @option opts [Symbol] :after  a sheet after which the sheet shall be inserted
-    # @return [Sheet] the copied or added sheet
+    # @return [Worksheet] the copied or added sheet
     def add_or_copy_sheet(sheet = nil, opts = { })
       if sheet.is_a? Hash
         opts = sheet
@@ -762,11 +764,11 @@ module RobustExcelOle
     end 
 
     def last_sheet
-      sheet_class.new(@ole_workbook.Worksheets.Item(@ole_workbook.Worksheets.Count))
+      worksheet_class.new(@ole_workbook.Worksheets.Item(@ole_workbook.Worksheets.Count))
     end
 
     def first_sheet
-      sheet_class.new(@ole_workbook.Worksheets.Item(1))
+      worksheet_class.new(@ole_workbook.Worksheets.Item(1))
     end
 
     # returns the value of a range
@@ -870,7 +872,7 @@ module RobustExcelOle
 
     # @return [Boolean] true, if the full book names and excel Instances are identical, false otherwise  
     def == other_book
-      other_book.is_a?(Book) &&
+      other_book.is_a?(Workbook) &&
       @excel == other_book.excel &&
       self.filename == other_book.filename  
     end
@@ -892,7 +894,7 @@ module RobustExcelOle
     end
 
     def inspect    # :nodoc: #
-      "#<Book: " + "#{"not alive " unless alive?}" + "#{File.basename(self.filename) if alive?}" + " #{@ole_workbook} #{@excel}"  + ">"
+      "#<Workbook: " + "#{"not alive " unless alive?}" + "#{File.basename(self.filename) if alive?}" + " #{@ole_workbook} #{@excel}"  + ">"
     end
 
     def self.excel_class    # :nodoc: #
@@ -905,12 +907,12 @@ module RobustExcelOle
       end
     end
 
-    def self.sheet_class    # :nodoc: #
-      @sheet_class ||= begin
+    def self.worksheet_class    # :nodoc: #
+      @worksheet_class ||= begin
         module_name = self.parent_name
-        "#{module_name}::Sheet".constantize
+        "#{module_name}::Worksheet".constantize
       rescue NameError => e
-        Sheet
+        Worksheet
       end
     end
 
@@ -918,8 +920,8 @@ module RobustExcelOle
       self.class.excel_class
     end
 
-    def sheet_class        # :nodoc: #
-      self.class.sheet_class
+    def worksheet_class        # :nodoc: #
+      self.class.worksheet_class
     end
 
     include MethodHelpers
@@ -946,6 +948,6 @@ module RobustExcelOle
   
 public
 
-  Workbook = Book
+  Book = Workbook
 
 end

data/lib/robust_excel_ole/{sheet.rb → worksheet.rb}

@@ -2,7 +2,9 @@
 
 module RobustExcelOle
 
-  class Sheet < RangeOwners
+  # see https://docs.microsoft.com/en-us/office/vba/api/excel.worksheet#methods
+
+  class Worksheet < RangeOwners
 
     attr_reader :ole_worksheet
     attr_reader :workbook
@@ -18,7 +20,7 @@ module RobustExcelOle
         @end_row = last_row
         @end_column = last_column
       end
-      @workbook = book_class.new(self.Parent)
+      @workbook = workbook_class.new(self.Parent)
     end
 
     # sheet name
@@ -103,7 +105,7 @@ module RobustExcelOle
     end
 
     # sets the value of a cell, if row, column and color of the cell are given
-    # @params [Fixnum] x,y row and column
+    # @params [Integer] x,y row and column
     # @option opts [Symbol] :color the color of the cell when set 
     def set_cellval(x,y,value, opts = {:color => 0})
       begin
@@ -117,19 +119,17 @@ module RobustExcelOle
     end
 
     # creates a range.
-    # @params [Fixnum,Range] row or range of the rows 
-    # @params [Fixnum,Range] column or range of columns  
-    #                  row and column of the bottum right cell of a rectangur range 
+    # @params [Address] address  
     # @return [Range] a range
-    def range(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)
+    def range(address, address2 = :__not_provided)
+      address = [address,address2] unless address2 == :__not_provided
+      address = Address.new(address)
       begin
         RobustExcelOle::Range.new(@ole_worksheet.Range(
-          @ole_worksheet.Cells(int_range1.min, int_range2.min),
-          @ole_worksheet.Cells(int_range1.max, int_range2.max)))
+          @ole_worksheet.Cells(address.rows.min, address.columns.min),
+          @ole_worksheet.Cells(address.rows.max, address.columns.max)))
       rescue WIN32OLERuntimeError
-        raise RangeNotCreated, "cannot create range (#{int_range1.inspect},#{int_range2.inspect})"
+        raise RangeNotCreated, "cannot create range #{address.inspect}"
       end
     end
 
@@ -161,7 +161,7 @@ module RobustExcelOle
 
     def each_row_with_index(offset = 0)
       each_row(offset) do |row_range|
-        yield RobustExcelOle::Range.new(row_range), (row_range.row - 1 - offset)
+        yield RobustExcelOle::Range.new(row_range), (row_range.Row - 1 - offset)
       end
     end
 
@@ -175,7 +175,7 @@ module RobustExcelOle
 
     def each_column_with_index(offset = 0)
       each_column(offset) do |column_range|
-        yield RobustExcelOle::Range.new(column_range), (column_range.column - 1 - offset)
+        yield RobustExcelOle::Range.new(column_range), (column_range.Column - 1 - offset)
       end
     end
 
@@ -190,21 +190,21 @@ module RobustExcelOle
     end
 
 
-    def self.book_class   # :nodoc: #
-      @book_class ||= begin
+    def self.workbook_class   # :nodoc: #
+      @workbook_class ||= begin
         module_name = self.parent_name
-        "#{module_name}::Book".constantize
+        "#{module_name}::Workbook".constantize
       rescue NameError => e
-        book
+        Workbook
       end
     end
 
-    def book_class        # :nodoc: #
-      self.class.book_class
+    def workbook_class        # :nodoc: #
+      self.class.workbook_class
     end
 
     def to_s    # :nodoc: #
-      "#<Sheet: " + "#{"not alive " unless @workbook.alive?}" + "#{name}" + " #{File.basename(@workbook.stored_filename)} >"
+      "#<Worksheet: " + "#{"not alive " unless @workbook.alive?}" + "#{name}" + " #{File.basename(@workbook.stored_filename)} >"
     end
 
     def inspect    # :nodoc: #
@@ -247,7 +247,7 @@ module RobustExcelOle
 
 public
 
-  Worksheet = Sheet
+  Sheet = Worksheet
 
 end