Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 105 lines (63 sloc) 3.927 kb
5c0d742 @bspaulding Added README.md
authored
1 Sheets
2 ==========
3
a3242f7 @bspaulding Updated README.
authored
4 Sheets is a Facade on top of many spreadsheet formats, presenting them as simple, unified, native ruby arrays. It is intended to allow applications to easily import data from a wide variety of spreadsheet formats.
5c0d742 @bspaulding Added README.md
authored
5
6 With Sheets, all cell values are strings representing the final, evaluated value of the cell.
7
8 This does mean that, in some cases, you will be casting data back into its native format.
9
a3242f7 @bspaulding Updated README.
authored
10 However, this eliminates the need to deal with multiple spreadsheet formats and normalize data types in your application logic.
5c0d742 @bspaulding Added README.md
authored
11
12 Your application only needs to care about the layout of the spreadsheet, and the format *you* want the data in.
13
14 Usage
15 ----------
16
17121d1 @bspaulding Updated README.
authored
17 Install via Rubygems:
bbd022e @bspaulding Added gem install instructions to README.
authored
18
19 gem install sheets
20
14c3d81 @bspaulding Added test data. Added simple test for all Parseable Formats. Updated Sh...
authored
21 To retrieve a list of parseable spreadsheet formats at runtime:
5c0d742 @bspaulding Added README.md
authored
22
14c3d81 @bspaulding Added test data. Added simple test for all Parseable Formats. Updated Sh...
authored
23 Sheets::Base.parseable_formats # => ["csv", "xls", "xlsx", "ods"]
5c0d742 @bspaulding Added README.md
authored
24
290d6ad @bspaulding Updated README.
authored
25 To open a spreadsheet, pass initialize Sheets::Base.new either a file path:
5c0d742 @bspaulding Added README.md
authored
26
27 Sheets::Base.new( '/path/to/a/spreadsheet.(format)' )
28
29 or a file handle:
30
31 Sheets::Base.new( File.open('/path/to/a/spreadsheet.(format)') )
32
33 By default, Sheets will use the basename of the file to detect the spreadsheet type. You can override this by passing in the :format option:
34
42bd002 @bspaulding Updated README.
authored
35 *This is necessary if you pass Sheets an IO object, like StringIO, that doesn't have metadata like a filename/path.*
5c0d742 @bspaulding Added README.md
authored
36
c2ae117 @bspaulding Updated README.
authored
37 Sheets::Base.new( an_io_object_with_spreadsheet_data, :format => :xls )
38
290d6ad @bspaulding Updated README.
authored
39 Once you have imported a sheet, you can either grab the array:
5c0d742 @bspaulding Added README.md
authored
40
41 sheet = Sheets::Base.new( # ... )
42 sheet.to_array
43
44 or utilize any of the Enumerable functions on the sheet:
45
46 sheet = Sheets::Base.new( # ... )
47 sheet.collect {|row| puts row }
48
43a0e7d @bspaulding Updated README.
authored
49 Additionally, you may output the sheet in any of the renderable formats:
50
51 Sheets::Base.renderable_formats # => ['csv', 'xls']
52 sheet = Sheets::Base.new( file )
53 sheet.to_csv
54 sheet.to_xls
55
56 Sheets::Base will skip the parsing phase if initialized with an array, allowing you to render arrays to a native spreadsheet format:
57
58 my_awesome_data = [ ["Date", "Spent", "Earned"], ["2011-04-11", "$0.00", "$5,000.00"] ]
59 sheet = Sheets::Base.new( my_awesome_data )
60 sheet.to_csv
61 sheet.to_xls
62
5c0d742 @bspaulding Added README.md
authored
63 Adding Parsers
64 ------------
65
66 Parsers subclass Sheets::Parsers::Base, live in the Sheets::Parsers namespace and should respond to two methods:
67
68 * formats: returns an array of string format names (file extensions) that this parser class supports
69 * to_array: returns a simple array representation of the spreadsheet.
70
43a0e7d @bspaulding Updated README.
authored
71 Parsers have access to @data and @format in order to do their parsing. See lib/sheets/parsers/* for examples.
72
73 Adding Renderers
74 ------------
75
76 Renderers subclass Sheets::Renderers::Base, live in the Sheets::Renderers namespace and should respond to:
77
78 * formats: returns an array of string format names that this parser class supports
b3e65ec @bspaulding Updated README, added License
authored
79 * to\_#{format}: For each format that a renderer supports, it should respond to "to\_#{format}", returning the file data of that format.
43a0e7d @bspaulding Updated README.
authored
80
b3e65ec @bspaulding Updated README, added License
authored
81 Renderers are given access to the results of Sheets::Base#to_array as @data. See lib/sheets/renderers/* for examples.
82
c5fac0c @bspaulding Added testing rubies to README.
authored
83 Tests
84 -----
85
86 Test Suite passes on the following Rubies:
87
88 * ruby 1.9.2p136 (2010-12-25 revision 30365) [x86_64-darwin10.7.0]
89 * ruby 1.8.7 (2009-06-12 patchlevel 174) [universal-darwin10.0]
90 * ruby 1.8.7 (2010-04-19 patchlevel 253) [i686-darwin10.6.0], MBARI 0x6770, Ruby Enterprise Edition 2010.02
91
b3e65ec @bspaulding Updated README, added License
authored
92 License
93 ----------
94
95 Sheets is licensed under the [MIT License](http://www.opensource.org/licenses/mit-license.php).
96
97 Please note that Sheets is dependent upon the Spreadsheet gem, which is licensed under the [GPLv3](http://www.opensource.org/licenses/gpl-3.0.html).
98
99 Credits
100 ----------
101
102 Sheets takes full advantage of the great work done in these gems:
103
104 * [Spreadsheet](http://spreadsheet.rubyforge.org/) - mhatakeyama@ywesee.com, zdavatz@ywesee.com
105 * [Roo](http://roo.rubyforge.org/) - [Thomas Preymesser](mailto:thopre@gmail.com)
Something went wrong with that request. Please try again.