winexcel 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in winexcel.gemspec
+gemspec

data/README.md

@@ -0,0 +1,156 @@
+winexcel
+========
+
+[WinExcel] Makes it possible to access MS Excel from Ruby via Excel COM/Win32OLE interface. Enables to read and write from/to Excel files with the use of Excel's API. Requires MS Excel application to be installed.
+
+Install
+=======
+
+    gem install winexcel
+	
+Usage
+=====
+
+Basic example script
+
+	require 'rubygems'
+	require 'winexcel'
+	include WinExcel
+
+	#
+	# Opening existing file and reading all data
+	file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "fixtures\\a.xls"))
+	xls = ExcelFile.new(file_full_path)
+	arrRecords = xls.get2DArray('A1')
+	puts arrRecords
+	#
+	# reading specified data
+	arrRecords = xls.get2DArray('A1:B2')
+	puts arrRecords
+	xls.close
+	#
+	# Writing some data to existing file
+	file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "my_basic_file.xls"))
+	xls = ExcelFile.new(file_full_path)
+	arrRecords = []
+	arrRecords << ['ID', 'NAME', 'NICKNAME']
+	arrRecords << ['001', 'Fredrick White', 'fred']
+	arrRecords << ['002', 'Robert Green', 'bob']
+	xls.write2DArray(arrRecords, 'A1')
+	xls.save
+	xls.close
+	#
+	# Creating a new file from template
+	file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "my_2nd_new_file.xls"))
+	template_full_path = File.expand_path(File.join(File.dirname(__FILE__), "fixtures\\template.xls"))
+	xls = ExcelFile.new(file_full_path, false, template_full_path)
+	arrRecords = []
+	arrRecords << ['Patrick Red', 'xyz', 'mail@xyz.com']
+	arrRecords << ['Martin Blue', 'abc']
+	xls.append2DArray(arrRecords)
+	xls.save
+	xls.close # not necessary as it would be handled by finalize
+	#
+	# Close any open file by calling finalize
+	ExcelFile.finalize # always call finalize at the end of a script
+
+Extended example script
+
+	require 'rubygems'
+	require 'winexcel'
+	include WinExcel
+
+	arrRecords = []
+
+	# path to already created empty Excel file that we will write to
+	file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "my_extended_file.xls"))
+
+	xls = ExcelFile.new(file_full_path)
+
+	begin
+
+	  #### writing data
+
+	  # writing array of arrays
+	  arrRecords << ['ID', 'NAME', 'NICKNAME']
+	  arrRecords << ['001', 'Fredrick White', 'fred']
+	  arrRecords << ['002', 'Robert Green', 'bob']
+	  xls.write2DArray(arrRecords, 'A1')
+
+	  # appending array of arrays
+	  arrRecords.clear
+	  arrRecords << ['003', 'Patrick Red', 'pati']
+	  arrRecords << ['004', 'Martin Blue', 'mati']
+	  xls.append2DArray(arrRecords)
+
+	  # lets delete the current sheet for now
+	  xls.addSheet('hashesSheet')
+
+	  # writing array of hashes
+	  arrRecords.clear
+	  arrRecords << {'ID'=>'001', 'NAME'=>'Fredrick White', 'NICKNAME'=>'fred'}
+	  arrRecords << {'ID'=>'002', 'NAME'=>'Robert Green', 'NICKNAME'=>'bob'}
+	  xls.writeArrayHash(arrRecords, 'A1')
+
+	  # appending array of hashes
+	  arrRecords.clear
+	  arrRecords << {'ID'=>'003', 'NAME'=>'Patrick Red', 'NICKNAME'=>'pati'}
+	  arrRecords << {'ID'=>'004', 'NAME'=>'Martin Blue', 'NICKNAME'=>'mati'}
+	  xls.appendArrayHash(arrRecords)
+
+	  # lets delete it to switch to the previous, default sheet
+	  xls.deleteSheet('hashesSheet')
+
+	  #### reading data
+
+	  # we can specify a range of data to retrieve
+	  arrRecords = xls.get2DArray('A1:C3')
+	  p arrRecords
+
+	  # if there is no range argument specified, then all occupied rows will be returned,
+	  # giving us the whole file contents
+	  arrRecords = xls.get2DArray()
+	  p arrRecords
+
+	ensure
+	  xls.save
+	  xls.close # not necessary as it would be handled by finalize
+	  # close any open file by calling finalize
+	  ExcelFile.finalize # finalize it at the end of a script
+	end
+	
+For more examples please look at Cucumber features.
+
+License
+=======
+
+Copyright (c) 2011 Kamil Sobieraj, ksob@dslowl.com
+
+(New BSD License)
+
+New BSD License claims:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+     this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of Zend Technologies USA, Inc. nor the names of its
+     contributors may be used to endorse or promote products derived from this
+     software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+Dir['tasks/**/*.rake'].each { |f| load f }
+
+desc "Run RSpec examples; Run cucumber:ok;"
+task :default => [:spec, :features]

data/examples/basic.rb

@@ -0,0 +1,49 @@
+#
+# code created for testing purposes
+# and to demonstrate example usage
+#
+# Note: the library assumes that specified Excel file is already created
+#
+# For examples working out of the box please look at Cucumber/RSpec files
+#
+
+require 'rubygems'
+require 'winexcel'
+include WinExcel
+
+#
+# Opening existing file and reading all data
+file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "fixtures\\a.xls"))
+xls = ExcelFile.new(file_full_path)
+arrRecords = xls.get2DArray('A1')
+puts arrRecords
+#
+# reading specified data
+arrRecords = xls.get2DArray('A1:B2')
+puts arrRecords
+xls.close
+#
+# Writing some data to existing file
+file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "my_basic_file.xls"))
+xls = ExcelFile.new(file_full_path)
+arrRecords = []
+arrRecords << ['ID', 'NAME', 'NICKNAME']
+arrRecords << ['001', 'Fredrick White', 'fred']
+arrRecords << ['002', 'Robert Green', 'bob']
+xls.write2DArray(arrRecords, 'A1')
+xls.save
+xls.close
+#
+# Creating a new file from template
+file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "my_2nd_new_file.xls"))
+template_full_path = File.expand_path(File.join(File.dirname(__FILE__), "fixtures\\template.xls"))
+xls = ExcelFile.new(file_full_path, false, template_full_path)
+arrRecords = []
+arrRecords << ['Patrick Red', 'xyz', 'mail@xyz.com']
+arrRecords << ['Martin Blue', 'abc']
+xls.append2DArray(arrRecords)
+xls.save
+xls.close # not necessary as it would be handled by finalize
+#
+# Close any open file by calling finalize
+ExcelFile.finalize # always call finalize at the end of a script

data/examples/extended.rb

@@ -0,0 +1,73 @@
+#
+# code created for testing purposes
+# and to demonstrate example usage
+#
+# Note: the library assumes that specified Excel file is already created
+#
+# For examples working out of the box please look at Cucumber/RSpec files
+#
+
+require 'rubygems'
+require 'winexcel'
+include WinExcel
+
+arrRecords = []
+
+# path to already created empty Excel file that we will write to
+file_full_path = File.expand_path(File.join(File.dirname(__FILE__), "my_extended_file.xls"))
+
+xls = ExcelFile.new(file_full_path)
+
+begin
+
+  #### writing data
+
+  # writing array of arrays
+  arrRecords << ['ID', 'NAME', 'NICKNAME']
+  arrRecords << ['001', 'Fredrick White', 'fred']
+  arrRecords << ['002', 'Robert Green', 'bob']
+  xls.write2DArray(arrRecords, 'A1')
+
+  # appending array of arrays
+  arrRecords.clear
+  arrRecords << ['003', 'Patrick Red', 'pati']
+  arrRecords << ['004', 'Martin Blue', 'mati']
+  xls.append2DArray(arrRecords)
+
+  # lets delete the current sheet for now
+  xls.addSheet('hashesSheet')
+
+  # writing array of hashes
+  arrRecords.clear
+  arrRecords << {'ID'=>'001', 'NAME'=>'Fredrick White', 'NICKNAME'=>'fred'}
+  arrRecords << {'ID'=>'002', 'NAME'=>'Robert Green', 'NICKNAME'=>'bob'}
+  xls.writeArrayHash(arrRecords, 'A1')
+
+  # appending array of hashes
+  arrRecords.clear
+  arrRecords << {'ID'=>'003', 'NAME'=>'Patrick Red', 'NICKNAME'=>'pati'}
+  arrRecords << {'ID'=>'004', 'NAME'=>'Martin Blue', 'NICKNAME'=>'mati'}
+  xls.appendArrayHash(arrRecords)
+
+  # lets delete it to switch to the previous, default sheet
+  xls.deleteSheet('hashesSheet')
+
+  #### reading data
+
+  # we can specify a range of data to retrieve
+  arrRecords = xls.get2DArray('A1:C3')
+  p arrRecords
+
+  # if there is no range argument specified, then all occupied rows will be returned,
+  # giving us the whole file contents
+  arrRecords = xls.get2DArray()
+  p arrRecords
+
+ensure
+  xls.save
+  xls.close # not necessary as it would be handled by finalize
+  # close any open file by calling finalize
+  ExcelFile.finalize # finalize it at the end of a script
+end
+
+

data/features/connect_to_open_excel_file.feature

@@ -0,0 +1,32 @@
+# scenarios in this file are meant to be used by developers that want to use excel_file.rb functionality
+
+Feature: connect_to_open_excel_file
+  As a developer
+  I want to connect to open Excel file
+  So that I can read and write to it
+
+# this initial background processing try to simulate state of end-user system
+
+  Background: let say that the user executed some script using a button supplied in "../fixtures/temp/a.xls"
+  so we are sure the Excel workbook is open while that script is processing
+  and so we will open it here in background processing and read one cell to ensure the file is
+  open correctly before testing scenario that assume it is open correctly
+    Given I copy file "../fixtures/a.xls" to "../fixtures/temp" directory
+    And I open the "../fixtures/temp/a.xls" file manually
+    And I open the same file via script passing "../fixtures/temp/a.xls" as a parameter to ExcelFile.new
+    And I call get2DArray method of the returned object passing "A1" as a cell parameter
+    And I get [["aaa"]] back
+
+  Scenario: opening an existing file that has already been opened by the user before
+  and reading some data, then finalizing but NOT closing the file
+  since it was opened by user
+    Given I pass file="../fixtures/temp/a.xls" as parameter to ExcelFile.new
+    Then I should see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    When I call get2DArray method of the returned object passing "A1" as a cell parameter
+    Then I should get [["aaa"]] back
+    When I call ExcelFile.finalize
+    Then I should still see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+	
+	
+	
+	

data/features/create_excel_file_from_template_and_open.feature

@@ -0,0 +1,35 @@
+# scenarios in this file are meant to be used by developers that want to use excel_file.rb functionality
+
+Feature: create_excel_file_from_template_and_open
+  As a developer
+  I want to create Excel file from template and open it
+  So that I can read and write to it
+
+# this initial background processing try to simulate state of end-user system
+
+  Background:
+    Given I close "../fixtures/temp/a.xls" Excel file if it exists and is open
+    And I do not see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    And I delete "../fixtures/temp/a.xls" Excel file if it exists
+    And I close "../fixtures/temp/b.xls" Excel file if it exists and is open
+    And I do not see file "../fixtures/temp/b.xls" in RunningObjectTable (ROT)
+    And I delete "../fixtures/temp/b.xls" Excel file if it exists
+    And I copy files "../fixtures/a.xls" and "../fixtures/b.xlsx" to "../fixtures/temp" directory
+    And I open the "../fixtures/temp/a.xls" file manually
+    And I open the same file via script passing "../fixtures/temp/a.xls" as a parameter to ExcelFile.new
+    And I call get2DArray method of the returned object passing "A1" as a cell parameter
+    And I get [["aaa"]] back
+
+  Scenario: creating (and then opening) a new file from template when file with the same name exists there already and is open
+    Given I pass file="../fixtures/temp/a.xls", debug="false" and template="../fixtures/temp/b.xlsx" as parameters to ExcelFile.new
+    Then I should see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    When I call get2DArray method of the returned object passing "A1" as a cell parameter
+    Then I should get [["bbb"]] back
+    When I call ExcelFile.finalize
+    Then I should not see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+
+
+	
+	
+	
+	

data/features/open_excel_file.feature

@@ -0,0 +1,41 @@
+# scenarios in this file are meant to be used by developers that want to use excel_file.rb functionality
+
+Feature: open_excel_file
+  As a developer
+  I want to open Excel file
+  So that I can read and write to it
+
+# this initial background processing try to simulate state of end-user system
+
+  Background: let say that the user did NOT opened "../fixtures/temp/a.xls" but he executed
+  some script that will use this file
+    Given I close "../fixtures/temp/a.xls" Excel file if it exists and is open
+    And I do not see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    And I delete "../fixtures/temp/a.xls" Excel file if it exists
+    And I copy file "../fixtures/a.xls" to "../fixtures/temp" directory
+
+  Scenario: opening an existing file that has NOT already been opened by the user before
+  and reading some data, then we DO call close method and then finalize
+  to release automationInstance (Excel application)
+    Given I pass file="../fixtures/temp/a.xls" as parameter to ExcelFile.new
+    Then I should see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    When I call get2DArray method of the returned object passing "A1" as a cell parameter
+    Then I should get [["aaa"]] back
+    When I call close method
+    Then I should not see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    And I call ExcelFile.finalize
+
+  Scenario: opening an existing file that has NOT already been opened by the user before
+  and reading some data, then we DO NOT call close method but finalize method
+  to close that for us and release automationInstance (Excel application)
+    Given I pass file="../fixtures/temp/a.xls" as parameter to ExcelFile.new
+    Then I should see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+    When I call get2DArray method of the returned object passing "A1" as a cell parameter
+    Then I should get [["aaa"]] back
+    When I call ExcelFile.finalize
+    Then I should not see file "../fixtures/temp/a.xls" in RunningObjectTable (ROT)
+
+	
+	
+	
+	

data/features/step_definitions/excel_file_steps.rb

@@ -0,0 +1,71 @@
+xls = nil
+res = nil
+rot = WIN32OLE::RunningObjectTable.new
+if rot.nil? then
+  throw 'Cannot access WIN32OLE::RunningObjectTable'
+end
+
+Given /^I copy files "([^\"]*)" and "([^\"]*)" to "([^\"]*)" directory$/ do |file1, file2, dir|
+  FileUtils.createDirIfMissing File.expand_path(File.join(File.dirname(__FILE__), dir))
+  FileUtils.cp(File.expand_path(File.join(File.dirname(__FILE__), file1)), File.join(File.expand_path(File.join(File.dirname(__FILE__), dir)), File.basename(file1)))
+  FileUtils.cp(File.expand_path(File.join(File.dirname(__FILE__), file2)), File.join(File.expand_path(File.join(File.dirname(__FILE__), dir)), File.basename(file2)))
+end
+Given /^I copy file "([^\"]*)" to "([^\"]*)" directory$/ do |file1, dir|
+  FileUtils.createDirIfMissing File.expand_path(File.join(File.dirname(__FILE__), dir))
+  FileUtils.cp(File.expand_path(File.join(File.dirname(__FILE__), file1)), File.join(File.expand_path(File.join(File.dirname(__FILE__), dir)), File.basename(file1)))
+end
+When /^I open the "([^\"]*)" file manually$/ do |path|
+  full_path = File.expand_path(File.join(File.dirname(__FILE__), path))
+  system("start #{full_path}")
+  sleep 5
+end
+When /^I open the same file via script passing "([^\"]*)" as a parameter to ExcelFile\.new$/ do |path|
+  full_path = File.expand_path(File.join(File.dirname(__FILE__), path))
+  xls = WinExcel::ExcelFile.new(full_path)
+end
+When /^I call get2DArray method of the returned object passing "([^\"]*)" as a cell parameter$/ do |cell|
+  res = xls.get2DArray(cell)
+end
+When /^I get \[\["([^\"]*)"\]\] back$/ do |value|
+  res[0][0].should == value
+end
+res = nil
+Given /^I pass file="([^\"]*)", debug="([^\"]*)" and template="([^\"]*)" as parameters to ExcelFile\.new$/ do |path, debug, template|
+  full_path = File.expand_path(File.join(File.dirname(__FILE__), path))
+  template_full_path = File.expand_path(File.join(File.dirname(__FILE__), template))
+  xls = WinExcel::ExcelFile.new(full_path, debug, template_full_path)
+end
+Given /^I pass file="([^\"]*)" as parameter to ExcelFile\.new$/ do |path|
+  full_path = File.expand_path(File.join(File.dirname(__FILE__), path))
+  xls = WinExcel::ExcelFile.new(full_path)
+end
+Then /^I (?:should|do)(?: still)? see file "([^\"]*)" in RunningObjectTable \(ROT\)$/ do |file|
+  rot.is_running?(File.expand_path(File.join(File.dirname(__FILE__), file))).should == true
+end
+Then /^I (?:should|do) not see file "([^\"]*)" in RunningObjectTable \(ROT\)$/ do |file|
+  rot.is_running?(File.expand_path(File.join(File.dirname(__FILE__), file))).should == false
+end
+Then /^I should get \[\["([^\"]*)"\]\] back$/ do |value|
+  res[0][0].should == value
+end
+When /^I call ExcelFile\.finalize$/ do
+  WinExcel::ExcelFile.finalize
+end
+When /^I call close method$/ do
+  xls.close
+end
+Given /^I close "([^\"]*)" Excel file if it exists and is open$/ do |file|
+  full_path = File.expand_path(File.join(File.dirname(__FILE__), file))
+  if File.exists?(full_path) and rot.is_running?(full_path)
+    xls = WinExcel::ExcelFile.new(full_path)
+    xls.close(forceClose=true)
+    WinExcel::ExcelFile.finalize
+  end
+end
+When /^I delete "([^\"]*)" Excel file if it exists$/ do |file|
+  full_path = File.expand_path(File.join(File.dirname(__FILE__), file))
+  begin
+    FileUtils.rm_rf(full_path)
+  rescue
+  end
+end