From ef8bf574d5ea161a9b70e582f2b3e8bc7a8ea89a Mon Sep 17 00:00:00 2001 From: Phil Cohen Date: Tue, 20 Jan 2015 13:32:27 -0800 Subject: [PATCH] add GitHub Flavored Markdown to README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * this makes the example code easier to read, especially when perusing the docs on github --- README.markdown | 96 +++++++++++++++++++++++++------------------------ 1 file changed, 49 insertions(+), 47 deletions(-) diff --git a/README.markdown b/README.markdown index 2088dc5..658d69d 100644 --- a/README.markdown +++ b/README.markdown @@ -8,56 +8,58 @@ This little gem provides an alternative interface to the Apache POI java library INSTALL ======= -* gem install jruby-poi +``` +$ gem install jruby-poi +``` USAGE ===== -It's pretty simple really, create a POI::Workbook and access its sheets, rows, and cells. You can read from the spreadsheet, save it (as the filename with which you created or as a new spreadsheet via Workbook#save_as). - - require 'poi' - - # given an Excel spreadsheet whose first sheet (Sheet 1) has this data: - # A B C D E - # 1 4 A 2010-01-04 - # 2 3 B =DATE(YEAR($E$1), MONTH($E$1), A2) - # 3 2 C =DATE(YEAR($E$1), MONTH($E$1), A3) - # 4 1 D =DATE(YEAR($E$1), MONTH($E$1), A4) - - workbook = POI::Workbook.open('spreadsheet.xlsx') - sheet = workbook.worksheets["Sheet 1"] - rows = sheet.rows - - # get a cell's value -- returns the value as its proper type, evaluating formulas if need be - rows[0][0].value # => 4.0 - rows[0][1].value # => nil - rows[0][2].value # => 'A' - rows[0][3].value # => nil - rows[0][4].value # => 2010-01-04 as a Date instance - rows[1][4].value # => 2010-01-03 as a Date instance - rows[2][4].value # => 2010-01-02 as a Date instance - rows[3][4].value # => 2010-01-01 as a Date instance - - # you can access a cell in array style as well... these snippets are all equivalent - workbook.sheets[0][2][2] # => 'C' - workbook[0][2][2] # => 'C' - workbook.sheets['Sheet 1'][2][2] # => 'C' - workbook['Sheet 1'][2][2] # => 'C' - - # you can access a cell in 3D cell format too - workbook['Sheet 1!A1'] # => 4.0 - - # you can even refer to ranges of cells - workbook['Sheet 1!A1:A3'] # => [4.0, 3.0, 2.0] - - # if cells E1 - E4 were a named range, you could refer to those cells by its name - # eg. if the cells were named "dates"... - workbook['dates'] # => dates from E1 - E4 - - # to get the Cell instance, instead of its value, just use the Workbook#cell method - workbook.cell('dates') # => cells that contain dates from E1 to E4 - workbook['Sheet 1!A1:A3'] # => cells that contain 4.0, 3.0, and 2.0 - -There's a formatted version of this code [here](http://gist.github.com/557607), but Github doesn't allow embedding script tags in Markdown. Go figure! +It's pretty simple really, create an instance of `POI::Workbook` and access its sheets, rows, and cells. You can read from the spreadsheet, save it (as the filename with which you created or as a new spreadsheet via `Workbook#save_as`). + +```ruby +require 'poi' + +# given an Excel spreadsheet whose first sheet (Sheet 1) has this data: +# A B C D E +# 1 4 A 2010-01-04 +# 2 3 B =DATE(YEAR($E$1), MONTH($E$1), A2) +# 3 2 C =DATE(YEAR($E$1), MONTH($E$1), A3) +# 4 1 D =DATE(YEAR($E$1), MONTH($E$1), A4) + +workbook = POI::Workbook.open('spreadsheet.xlsx') +sheet = workbook.worksheets["Sheet 1"] +rows = sheet.rows + +# get a cell's value -- returns the value as its proper type, evaluating formulas if need be +rows[0][0].value # => 4.0 +rows[0][1].value # => nil +rows[0][2].value # => 'A' +rows[0][3].value # => nil +rows[0][4].value # => 2010-01-04 as a Date instance +rows[1][4].value # => 2010-01-03 as a Date instance +rows[2][4].value # => 2010-01-02 as a Date instance +rows[3][4].value # => 2010-01-01 as a Date instance + +# you can access a cell in array style as well... these snippets are all equivalent +workbook.sheets[0][2][2] # => 'C' +workbook[0][2][2] # => 'C' +workbook.sheets['Sheet 1'][2][2] # => 'C' +workbook['Sheet 1'][2][2] # => 'C' + +# you can access a cell in 3D cell format too +workbook['Sheet 1!A1'] # => 4.0 + +# you can even refer to ranges of cells +workbook['Sheet 1!A1:A3'] # => [4.0, 3.0, 2.0] + +# if cells E1 - E4 were a named range, you could refer to those cells by its name +# eg. if the cells were named "dates"... +workbook['dates'] # => dates from E1 - E4 + +# to get the Cell instance, instead of its value, just use the Workbook#cell method +workbook.cell('dates') # => cells that contain dates from E1 to E4 +workbook['Sheet 1!A1:A3'] # => cells that contain 4.0, 3.0, and 2.0 +``` TODO ====