workbook 0.4.13 → 0.4.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +2 -1
  3. data/lib/workbook/modules/cell.rb +14 -0
  4. data/lib/workbook/version.rb +1 -1
  5. data/test/test_modules_cache.rb +14 -14
  6. data/test/test_modules_cell.rb +9 -2
  7. data/test/test_readers_xls_reader.rb +1 -1
  8. metadata +4 -46
  9. data/doc/RubyXL/Cell.html +0 -201
  10. data/doc/RubyXL/Workbook.html +0 -449
  11. data/doc/RubyXL.html +0 -128
  12. data/doc/Workbook/Book.html +0 -1852
  13. data/doc/Workbook/Cell.html +0 -1553
  14. data/doc/Workbook/Format.html +0 -1168
  15. data/doc/Workbook/Modules/RawObjectsStorage.html +0 -502
  16. data/doc/Workbook/Modules/TableDiffSort.html +0 -758
  17. data/doc/Workbook/Modules/TypeParser.html +0 -1063
  18. data/doc/Workbook/Modules.html +0 -117
  19. data/doc/Workbook/NilValue.html +0 -434
  20. data/doc/Workbook/Readers/CsvReader.html +0 -324
  21. data/doc/Workbook/Readers/OdsReader.html +0 -1066
  22. data/doc/Workbook/Readers/TxtReader.html +0 -236
  23. data/doc/Workbook/Readers/XlsReader.html +0 -378
  24. data/doc/Workbook/Readers/XlsShared.html +0 -188
  25. data/doc/Workbook/Readers/XlsxReader.html +0 -302
  26. data/doc/Workbook/Readers.html +0 -117
  27. data/doc/Workbook/Row.html +0 -2392
  28. data/doc/Workbook/Sheet.html +0 -875
  29. data/doc/Workbook/Table.html +0 -1732
  30. data/doc/Workbook/Template.html +0 -634
  31. data/doc/Workbook/Writers/CsvTableWriter.html +0 -200
  32. data/doc/Workbook/Writers/HtmlWriter.html +0 -407
  33. data/doc/Workbook/Writers/XlsWriter.html +0 -905
  34. data/doc/Workbook/Writers.html +0 -117
  35. data/doc/Workbook.html +0 -142
  36. data/doc/_index.html +0 -381
  37. data/doc/class_list.html +0 -53
  38. data/doc/css/common.css +0 -1
  39. data/doc/css/full_list.css +0 -57
  40. data/doc/css/style.css +0 -338
  41. data/doc/file.README.html +0 -245
  42. data/doc/file_list.html +0 -55
  43. data/doc/frames.html +0 -28
  44. data/doc/index.html +0 -245
  45. data/doc/js/app.js +0 -214
  46. data/doc/js/full_list.js +0 -173
  47. data/doc/js/jquery.js +0 -4
  48. data/doc/method_list.html +0 -1308
  49. data/doc/top-level-namespace.html +0 -112
  50. data/test/artifacts/floats_problem.xls +0 -0
data/doc/file.README.html DELETED
@@ -1,245 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
- <head>
5
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
- <title>
7
- File: README
8
-
9
- &mdash; Documentation by YARD 0.8.5.2
10
-
11
- </title>
12
-
13
- <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
14
-
15
- <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
16
-
17
- <script type="text/javascript" charset="utf-8">
18
- hasFrames = window.top.frames.main ? true : false;
19
- relpath = '';
20
- framesUrl = "frames.html#!" + escape(window.location.href);
21
- </script>
22
-
23
-
24
- <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
-
26
- <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
-
28
-
29
- </head>
30
- <body>
31
- <div id="header">
32
- <div id="menu">
33
-
34
- <a href="_index.html">Index</a> &raquo;
35
- <span class="title">File: README</span>
36
-
37
-
38
- <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
39
- </div>
40
-
41
- <div id="search">
42
-
43
- <a class="full_list_link" id="class_list_link"
44
- href="class_list.html">
45
- Class List
46
- </a>
47
-
48
- <a class="full_list_link" id="method_list_link"
49
- href="method_list.html">
50
- Method List
51
- </a>
52
-
53
- <a class="full_list_link" id="file_list_link"
54
- href="file_list.html">
55
- File List
56
- </a>
57
-
58
- </div>
59
- <div class="clear"></div>
60
- </div>
61
-
62
- <iframe id="search_frame"></iframe>
63
-
64
- <div id="content"><div id='filecontents'><h1 id="workbook">Workbook</h1>
65
-
66
- <p>Goal of this gem is to make working with workbooks (spreadsheets) as programmer friendly as possible. Not reinventing a totally new DSL or all kinds of new methodnames, but just borrowing from known concepts such as hashes and arrays (much like (Faster)CSV does)). Workbook is a gem that mimicks a typical spreadsheet, a bundle of sheets, bundled in a <em>workbook</em>. A sheet may contain one or more tables (which might the multi table sheets of Apple Numbers or Excel ranges). Basically:</p>
67
-
68
- <ul>
69
- <li>Book
70
- <ul>
71
- <li>Sheet (one or more)
72
- <ul>
73
- <li>Table (one or more)</li>
74
- </ul>
75
- </li>
76
- </ul>
77
- </li>
78
- </ul>
79
-
80
- <p>Subsequently a table consists of:</p>
81
-
82
- <ul>
83
- <li>Table
84
- <ul>
85
- <li>Row (one or more)
86
- <ul>
87
- <li>Cell ( wich has may have a (shared) Format )</li>
88
- </ul>
89
- </li>
90
- </ul>
91
- </li>
92
- </ul>
93
-
94
- <p>Book, Sheet, Table and Row inherit from the base Array class, and hence walks and quacks as such. The row is extended with hashlike lookups (<code>row[:id]</code>) and writers (<code>row[:id]=</code>). Values are converted to ruby native types, and optional parsers can be added to improve recognition. </p>
95
-
96
- <p>In addition to offering you this plain structure it allows for importing .xls, .csv, .xlsx, .txt files (more to come), writing .xls, and .csv (more to come) and includes several utilities to easily create an overview of the differences between two tables and output basic cell-styling properties as css.</p>
97
-
98
- <h2 id="the-basics">The Basics</h2>
99
-
100
- <p>Simply initialize a simple spreadsheet using:</p>
101
-
102
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
103
- </code></pre>
104
-
105
- <p>or</p>
106
-
107
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span> <span class='id identifier rubyid_filename'>filename</span>
108
- </code></pre>
109
-
110
- <p>Calling</p>
111
-
112
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_s'>s</span> <span class='op'>=</span> <span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_sheet'>sheet</span>
113
- <span class='id identifier rubyid_t'>t</span> <span class='op'>=</span> <span class='id identifier rubyid_s'>s</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
114
- </code></pre>
115
-
116
- <p>will give you an the first Sheet and Table (if one doesn’t exist it is created on the fly).</p>
117
-
118
- <p>You can initialize with simple 2-d array like this:</p>
119
-
120
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='lbracket'>[</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>a</span><span class='tstring_end'>'</span></span><span class='comma'>,</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>b</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span><span class='lbracket'>[</span><span class='int'>1</span><span class='comma'>,</span><span class='int'>2</span><span class='rbracket'>]</span><span class='comma'>,</span><span class='lbracket'>[</span><span class='int'>3</span><span class='comma'>,</span><span class='int'>4</span><span class='rbracket'>]</span><span class='comma'>,</span><span class='lbracket'>[</span><span class='int'>5</span><span class='comma'>,</span><span class='int'>6</span><span class='rbracket'>]</span><span class='rbracket'>]</span>
121
- <span class='id identifier rubyid_t'>t</span> <span class='op'>=</span> <span class='id identifier rubyid_s'>s</span><span class='period'>.</span><span class='id identifier rubyid_sheet'>sheet</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
122
- </code></pre>
123
-
124
- <p>Subsequently you look up values in the table like this:</p>
125
-
126
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span>
127
- <span class='comment'># returns &lt;Workbook::Cel @value=2&gt;
128
- </span></code></pre>
129
-
130
- <p>which is equivalent to</p>
131
-
132
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span>
133
- </code></pre>
134
-
135
- <p>Of course you’ll be able to write a new value back to it. If you just enter a value, formatting of the original cell will be maintained.</p>
136
-
137
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='int'>5</span>
138
- </code></pre>
139
-
140
- <p>Alternatively (more spreadsheet like) you can read cells like this (writing to be supported, not implemented yet)</p>
141
-
142
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>A2</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span>
143
- </code></pre>
144
-
145
- <p>If you want to use an existing file as a template (which you can create in Excel to create nice looking templates),
146
- simply clone the row, and add it back:</p>
147
-
148
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>template.xls</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
149
- <span class='id identifier rubyid_table'>table</span> <span class='op'>=</span> <span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_sheet'>sheet</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
150
- <span class='id identifier rubyid_template_row'>template_row</span> <span class='op'>=</span> <span class='id identifier rubyid_table'>table</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span> <span class='comment'># can be any, but I typically have a well
151
- </span> <span class='comment'># formatted header row + an example template
152
- </span> <span class='comment'># row for the data
153
- </span><span class='lbracket'>[</span><span class='int'>1</span><span class='comma'>,</span><span class='int'>2</span><span class='comma'>,</span><span class='int'>3</span><span class='comma'>,</span><span class='int'>4</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_v'>v</span><span class='op'>|</span>
154
- <span class='id identifier rubyid_new_row'>new_row</span> <span class='op'>=</span> <span class='id identifier rubyid_template_row'>template_row</span><span class='period'>.</span><span class='id identifier rubyid_clone'>clone</span>
155
- <span class='id identifier rubyid_table'>table</span> <span class='op'>&lt;&lt;</span> <span class='id identifier rubyid_new_row'>new_row</span> <span class='comment'># to use the symbol style header references,
156
- </span> <span class='comment'># the row first needs to be added back to the
157
- </span> <span class='comment'># table
158
- </span> <span class='id identifier rubyid_new_row'>new_row</span><span class='lbracket'>[</span><span class='symbol'>:a</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='id identifier rubyid_v'>v</span>
159
- <span class='kw'>end</span>
160
- <span class='id identifier rubyid_table'>table</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='lparen'>(</span><span class='id identifier rubyid_template_row'>template_row</span><span class='rparen'>)</span> <span class='comment'># you don't want the template to show up
161
- </span> <span class='comment'># in the endresult
162
- </span><span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_write'>write</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>result.xls</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='comment'># write it!
163
- </span></code></pre>
164
-
165
- <p>&lt;!– Feature <em>to implement</em>: </p>
166
-
167
- <p>Feature <em>to implement</em>, get a single column:</p>
168
-
169
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span>
170
- <span class='comment'># returns [&lt;Workbook::Cel @value=2&gt;,&lt;Workbook::Cel @value=4&gt;,&lt;Workbook::Cel @value=6&gt;]
171
- </span></code></pre>
172
-
173
- <p>On my wishlist: In the future I hope to return the cell value directly, without the intermediate Workbook::Cel class in between.</p>
174
-
175
- <pre class="code ruby"><code class="ruby">--&gt;
176
- </code></pre>
177
-
178
- <h2 id="utilities">Utilities</h2>
179
-
180
- <h3 id="sorting">Sorting</h3>
181
-
182
- <p>Sorting leaves the header alone, if it exists, and doesn’t complain about comparing strings with dates with floats (Ever found OpenOffice Calc or Excel complainging about its inability to compare integers and strings? We’re talking spreadsheet here). When classes are different the following (default) order is used: Numbers, Strings, Dates and Times, Booleans and Nils (empty values).</p>
183
-
184
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_sort'>sort</span>
185
- </code></pre>
186
-
187
- <p><em>To implement</em>:</p>
188
-
189
- <p>To some extent, sort_by works, it doesn’t, however, adhere to the header settings… </p>
190
-
191
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_sort_by'>sort_by</span> <span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_r'>r</span><span class='op'>|</span> <span class='id identifier rubyid_r'>r</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span><span class='rbrace'>}</span>
192
- </code></pre>
193
-
194
- <h3 id="comparing-tables">Comparing tables</h3>
195
-
196
- <p>Simply call on a Workbook::Table</p>
197
-
198
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t1'>t1</span><span class='period'>.</span><span class='id identifier rubyid_diff'>diff</span> <span class='id identifier rubyid_t2'>t2</span>
199
- </code></pre>
200
-
201
- <p>And a new book with a new sheet/table will be returned containing the differences between the two tables.</p>
202
-
203
- <h2 id="writing">Writing</h2>
204
-
205
- <p>Currently writing is limited to the following formats. Templating support is still limited.</p>
206
-
207
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_to_xls'>to_xls</span> <span class='comment'># returns a spreadsheet workbook
208
- </span><span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_write_to_xls'>write_to_xls</span> <span class='id identifier rubyid_filename'>filename</span> <span class='comment'># writes to filename
209
- </span><span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_to_csv'>to_csv</span> <span class='comment'># returns a csv-string (called on tables)
210
- </span></code></pre>
211
-
212
- <p>In case you want to display the table in HTML, some conversion is offered to convert text/background properties to css-entities. Internally the hash storing style elements tries to map to CSS where possible.</p>
213
-
214
- <h2 id="compatibility">Compatibility</h2>
215
-
216
- <p>Workbook should be compatible with ruby 1.8.7 and 1.9.3. Check <a href="https://travis-ci.org/murb/workbook">Travis for Workbook’s current build status</a> <a href="https://travis-ci.org/murb/workbook"><img src="https://travis-ci.org/murb/workbook.png?branch=master" alt="Build Status" /></a>. </p>
217
-
218
- <h2 id="alternatives">Alternatives</h2>
219
-
220
- <p>The <a href="https://www.ruby-toolbox.com/search?utf8=%E2%9C%93&amp;q=spreadsheet">ruby toolbox lists plenty of alternatives</a>, that just didn’t suit my needs.</p>
221
-
222
- <h2 id="license">License</h2>
223
-
224
- <p>This code MIT (but see below) (c) murb / Maarten Brouwers, 2011-2013</p>
225
-
226
- <p>Workbook uses the following gems:</p>
227
-
228
- <ul>
229
- <li><a href="https://github.com/zdavatz/spreadsheet">Spreadsheet</a> Used for reading and writing old style .xls files (Copyright © 2010 ywesee GmbH (mhatakeyama@ywesee.com, zdavatz@ywesee.com); GPL3 (License required for closed implementations))</li>
230
- <li><a href="http://code.google.com/p/ruby-ole/">ruby-ole</a> Used in the Spreadsheet Gem (Copyright © 2007-2010 Charles Lowe; MIT)</li>
231
- <li><a href="http://fastercsv.rubyforge.org/">FasterCSV</a> Used for reading CSV (comma separated text) and TXT (tab separated text) files (Copyright © James Edward Gray II; GPL2 &amp; Ruby License)</li>
232
- <li><a href="http://rubyforge.org/projects/rchardet">rchardet</a> Used for detecting encoding in CSV and TXT importers (Copyright © JMHodges; LGPL)</li>
233
- <li><a href="https://github.com/gilt/rubyXL">RubyXL</a> Used for reading the newer .xlsx files (Copyright © 2011 Vivek Bhagwat; MIT-Licensed)</li>
234
- <li><a href="http://nokogiri.org/">Nokogiri</a> Used for reading ODS documents (Copyright © 2008 - 2012 Aaron Patterson, Mike Dalessio, Charles Nutter, Sergio Arbeo, Patrick Mahoney, Yoko Harada; MIT Licensed)</li>
235
- </ul>
236
- </div></div>
237
-
238
- <div id="footer">
239
- Generated on Sun May 19 23:16:28 2013 by
240
- <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
241
- 0.8.5.2 (ruby-1.9.3).
242
- </div>
243
-
244
- </body>
245
- </html>
data/doc/file_list.html DELETED
@@ -1,55 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html>
4
- <head>
5
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
-
7
- <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
8
-
9
- <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
10
-
11
-
12
-
13
- <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
-
15
- <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
-
17
-
18
- <base id="base_target" target="_parent" />
19
- </head>
20
- <body>
21
- <script type="text/javascript" charset="utf-8">
22
- if (window.top.frames.main) {
23
- document.getElementById('base_target').target = 'main';
24
- document.body.className = 'frames';
25
- }
26
- </script>
27
- <div id="content">
28
- <h1 id="full_list_header">File List</h1>
29
- <div id="nav">
30
-
31
- <span><a target="_self" href="class_list.html">
32
- Classes
33
- </a></span>
34
-
35
- <span><a target="_self" href="method_list.html">
36
- Methods
37
- </a></span>
38
-
39
- <span><a target="_self" href="file_list.html">
40
- Files
41
- </a></span>
42
-
43
- </div>
44
- <div id="search">Search: <input type="text" /></div>
45
-
46
- <ul id="full_list" class="file">
47
-
48
-
49
- <li class="r1"><a href="index.html" title="README">README</a></li>
50
-
51
-
52
- </ul>
53
- </div>
54
- </body>
55
- </html>
data/doc/frames.html DELETED
@@ -1,28 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
2
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
3
-
4
- <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
- <head>
6
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
7
- <title>Documentation by YARD 0.8.5.2</title>
8
- </head>
9
- <script type="text/javascript" charset="utf-8">
10
- window.onload = function() {
11
- var match = window.location.hash.match(/^#!(.+)/);
12
- var name = 'index.html';
13
- if (match) {
14
- name = unescape(match[1]);
15
- }
16
- document.writeln('<frameset cols="20%,*">' +
17
- '<frame name="list" src="class_list.html" />' +
18
- '<frame name="main" src="' + name + '" />' +
19
- '</frameset>');
20
- }
21
- </script>
22
- <noscript>
23
- <frameset cols="20%,*">
24
- <frame name="list" src="class_list.html" />
25
- <frame name="main" src="index.html" />
26
- </frameset>
27
- </noscript>
28
- </html>
data/doc/index.html DELETED
@@ -1,245 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
- <head>
5
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
- <title>
7
- File: README
8
-
9
- &mdash; Documentation by YARD 0.8.5.2
10
-
11
- </title>
12
-
13
- <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
14
-
15
- <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
16
-
17
- <script type="text/javascript" charset="utf-8">
18
- hasFrames = window.top.frames.main ? true : false;
19
- relpath = '';
20
- framesUrl = "frames.html#!" + escape(window.location.href);
21
- </script>
22
-
23
-
24
- <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
-
26
- <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
-
28
-
29
- </head>
30
- <body>
31
- <div id="header">
32
- <div id="menu">
33
-
34
- <a href="_index.html">Index</a> &raquo;
35
- <span class="title">File: README</span>
36
-
37
-
38
- <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
39
- </div>
40
-
41
- <div id="search">
42
-
43
- <a class="full_list_link" id="class_list_link"
44
- href="class_list.html">
45
- Class List
46
- </a>
47
-
48
- <a class="full_list_link" id="method_list_link"
49
- href="method_list.html">
50
- Method List
51
- </a>
52
-
53
- <a class="full_list_link" id="file_list_link"
54
- href="file_list.html">
55
- File List
56
- </a>
57
-
58
- </div>
59
- <div class="clear"></div>
60
- </div>
61
-
62
- <iframe id="search_frame"></iframe>
63
-
64
- <div id="content"><div id='filecontents'><h1 id="workbook">Workbook</h1>
65
-
66
- <p>Goal of this gem is to make working with workbooks (spreadsheets) as programmer friendly as possible. Not reinventing a totally new DSL or all kinds of new methodnames, but just borrowing from known concepts such as hashes and arrays (much like (Faster)CSV does)). Workbook is a gem that mimicks a typical spreadsheet, a bundle of sheets, bundled in a <em>workbook</em>. A sheet may contain one or more tables (which might the multi table sheets of Apple Numbers or Excel ranges). Basically:</p>
67
-
68
- <ul>
69
- <li>Book
70
- <ul>
71
- <li>Sheet (one or more)
72
- <ul>
73
- <li>Table (one or more)</li>
74
- </ul>
75
- </li>
76
- </ul>
77
- </li>
78
- </ul>
79
-
80
- <p>Subsequently a table consists of:</p>
81
-
82
- <ul>
83
- <li>Table
84
- <ul>
85
- <li>Row (one or more)
86
- <ul>
87
- <li>Cell ( wich has may have a (shared) Format )</li>
88
- </ul>
89
- </li>
90
- </ul>
91
- </li>
92
- </ul>
93
-
94
- <p>Book, Sheet, Table and Row inherit from the base Array class, and hence walks and quacks as such. The row is extended with hashlike lookups (<code>row[:id]</code>) and writers (<code>row[:id]=</code>). Values are converted to ruby native types, and optional parsers can be added to improve recognition. </p>
95
-
96
- <p>In addition to offering you this plain structure it allows for importing .xls, .csv, .xlsx, .txt files (more to come), writing .xls, and .csv (more to come) and includes several utilities to easily create an overview of the differences between two tables and output basic cell-styling properties as css.</p>
97
-
98
- <h2 id="the-basics">The Basics</h2>
99
-
100
- <p>Simply initialize a simple spreadsheet using:</p>
101
-
102
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
103
- </code></pre>
104
-
105
- <p>or</p>
106
-
107
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span> <span class='id identifier rubyid_filename'>filename</span>
108
- </code></pre>
109
-
110
- <p>Calling</p>
111
-
112
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_s'>s</span> <span class='op'>=</span> <span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_sheet'>sheet</span>
113
- <span class='id identifier rubyid_t'>t</span> <span class='op'>=</span> <span class='id identifier rubyid_s'>s</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
114
- </code></pre>
115
-
116
- <p>will give you an the first Sheet and Table (if one doesn’t exist it is created on the fly).</p>
117
-
118
- <p>You can initialize with simple 2-d array like this:</p>
119
-
120
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='lbracket'>[</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>a</span><span class='tstring_end'>'</span></span><span class='comma'>,</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>b</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span><span class='lbracket'>[</span><span class='int'>1</span><span class='comma'>,</span><span class='int'>2</span><span class='rbracket'>]</span><span class='comma'>,</span><span class='lbracket'>[</span><span class='int'>3</span><span class='comma'>,</span><span class='int'>4</span><span class='rbracket'>]</span><span class='comma'>,</span><span class='lbracket'>[</span><span class='int'>5</span><span class='comma'>,</span><span class='int'>6</span><span class='rbracket'>]</span><span class='rbracket'>]</span>
121
- <span class='id identifier rubyid_t'>t</span> <span class='op'>=</span> <span class='id identifier rubyid_s'>s</span><span class='period'>.</span><span class='id identifier rubyid_sheet'>sheet</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
122
- </code></pre>
123
-
124
- <p>Subsequently you look up values in the table like this:</p>
125
-
126
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span>
127
- <span class='comment'># returns &lt;Workbook::Cel @value=2&gt;
128
- </span></code></pre>
129
-
130
- <p>which is equivalent to</p>
131
-
132
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span>
133
- </code></pre>
134
-
135
- <p>Of course you’ll be able to write a new value back to it. If you just enter a value, formatting of the original cell will be maintained.</p>
136
-
137
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='int'>5</span>
138
- </code></pre>
139
-
140
- <p>Alternatively (more spreadsheet like) you can read cells like this (writing to be supported, not implemented yet)</p>
141
-
142
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>A2</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span>
143
- </code></pre>
144
-
145
- <p>If you want to use an existing file as a template (which you can create in Excel to create nice looking templates),
146
- simply clone the row, and add it back:</p>
147
-
148
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='const'>Workbook</span><span class='op'>::</span><span class='const'>Book</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>template.xls</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
149
- <span class='id identifier rubyid_table'>table</span> <span class='op'>=</span> <span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_sheet'>sheet</span><span class='period'>.</span><span class='id identifier rubyid_table'>table</span>
150
- <span class='id identifier rubyid_template_row'>template_row</span> <span class='op'>=</span> <span class='id identifier rubyid_table'>table</span><span class='lbracket'>[</span><span class='int'>1</span><span class='rbracket'>]</span> <span class='comment'># can be any, but I typically have a well
151
- </span> <span class='comment'># formatted header row + an example template
152
- </span> <span class='comment'># row for the data
153
- </span><span class='lbracket'>[</span><span class='int'>1</span><span class='comma'>,</span><span class='int'>2</span><span class='comma'>,</span><span class='int'>3</span><span class='comma'>,</span><span class='int'>4</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_v'>v</span><span class='op'>|</span>
154
- <span class='id identifier rubyid_new_row'>new_row</span> <span class='op'>=</span> <span class='id identifier rubyid_template_row'>template_row</span><span class='period'>.</span><span class='id identifier rubyid_clone'>clone</span>
155
- <span class='id identifier rubyid_table'>table</span> <span class='op'>&lt;&lt;</span> <span class='id identifier rubyid_new_row'>new_row</span> <span class='comment'># to use the symbol style header references,
156
- </span> <span class='comment'># the row first needs to be added back to the
157
- </span> <span class='comment'># table
158
- </span> <span class='id identifier rubyid_new_row'>new_row</span><span class='lbracket'>[</span><span class='symbol'>:a</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='id identifier rubyid_v'>v</span>
159
- <span class='kw'>end</span>
160
- <span class='id identifier rubyid_table'>table</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='lparen'>(</span><span class='id identifier rubyid_template_row'>template_row</span><span class='rparen'>)</span> <span class='comment'># you don't want the template to show up
161
- </span> <span class='comment'># in the endresult
162
- </span><span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_write'>write</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>result.xls</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='comment'># write it!
163
- </span></code></pre>
164
-
165
- <p>&lt;!– Feature <em>to implement</em>: </p>
166
-
167
- <p>Feature <em>to implement</em>, get a single column:</p>
168
-
169
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span>
170
- <span class='comment'># returns [&lt;Workbook::Cel @value=2&gt;,&lt;Workbook::Cel @value=4&gt;,&lt;Workbook::Cel @value=6&gt;]
171
- </span></code></pre>
172
-
173
- <p>On my wishlist: In the future I hope to return the cell value directly, without the intermediate Workbook::Cel class in between.</p>
174
-
175
- <pre class="code ruby"><code class="ruby">--&gt;
176
- </code></pre>
177
-
178
- <h2 id="utilities">Utilities</h2>
179
-
180
- <h3 id="sorting">Sorting</h3>
181
-
182
- <p>Sorting leaves the header alone, if it exists, and doesn’t complain about comparing strings with dates with floats (Ever found OpenOffice Calc or Excel complainging about its inability to compare integers and strings? We’re talking spreadsheet here). When classes are different the following (default) order is used: Numbers, Strings, Dates and Times, Booleans and Nils (empty values).</p>
183
-
184
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_sort'>sort</span>
185
- </code></pre>
186
-
187
- <p><em>To implement</em>:</p>
188
-
189
- <p>To some extent, sort_by works, it doesn’t, however, adhere to the header settings… </p>
190
-
191
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_sort_by'>sort_by</span> <span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_r'>r</span><span class='op'>|</span> <span class='id identifier rubyid_r'>r</span><span class='lbracket'>[</span><span class='symbol'>:b</span><span class='rbracket'>]</span><span class='rbrace'>}</span>
192
- </code></pre>
193
-
194
- <h3 id="comparing-tables">Comparing tables</h3>
195
-
196
- <p>Simply call on a Workbook::Table</p>
197
-
198
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_t1'>t1</span><span class='period'>.</span><span class='id identifier rubyid_diff'>diff</span> <span class='id identifier rubyid_t2'>t2</span>
199
- </code></pre>
200
-
201
- <p>And a new book with a new sheet/table will be returned containing the differences between the two tables.</p>
202
-
203
- <h2 id="writing">Writing</h2>
204
-
205
- <p>Currently writing is limited to the following formats. Templating support is still limited.</p>
206
-
207
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_to_xls'>to_xls</span> <span class='comment'># returns a spreadsheet workbook
208
- </span><span class='id identifier rubyid_b'>b</span><span class='period'>.</span><span class='id identifier rubyid_write_to_xls'>write_to_xls</span> <span class='id identifier rubyid_filename'>filename</span> <span class='comment'># writes to filename
209
- </span><span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_to_csv'>to_csv</span> <span class='comment'># returns a csv-string (called on tables)
210
- </span></code></pre>
211
-
212
- <p>In case you want to display the table in HTML, some conversion is offered to convert text/background properties to css-entities. Internally the hash storing style elements tries to map to CSS where possible.</p>
213
-
214
- <h2 id="compatibility">Compatibility</h2>
215
-
216
- <p>Workbook should be compatible with ruby 1.8.7 and 1.9.3. Check <a href="https://travis-ci.org/murb/workbook">Travis for Workbook’s current build status</a> <a href="https://travis-ci.org/murb/workbook"><img src="https://travis-ci.org/murb/workbook.png?branch=master" alt="Build Status" /></a>. </p>
217
-
218
- <h2 id="alternatives">Alternatives</h2>
219
-
220
- <p>The <a href="https://www.ruby-toolbox.com/search?utf8=%E2%9C%93&amp;q=spreadsheet">ruby toolbox lists plenty of alternatives</a>, that just didn’t suit my needs.</p>
221
-
222
- <h2 id="license">License</h2>
223
-
224
- <p>This code MIT (but see below) (c) murb / Maarten Brouwers, 2011-2013</p>
225
-
226
- <p>Workbook uses the following gems:</p>
227
-
228
- <ul>
229
- <li><a href="https://github.com/zdavatz/spreadsheet">Spreadsheet</a> Used for reading and writing old style .xls files (Copyright © 2010 ywesee GmbH (mhatakeyama@ywesee.com, zdavatz@ywesee.com); GPL3 (License required for closed implementations))</li>
230
- <li><a href="http://code.google.com/p/ruby-ole/">ruby-ole</a> Used in the Spreadsheet Gem (Copyright © 2007-2010 Charles Lowe; MIT)</li>
231
- <li><a href="http://fastercsv.rubyforge.org/">FasterCSV</a> Used for reading CSV (comma separated text) and TXT (tab separated text) files (Copyright © James Edward Gray II; GPL2 &amp; Ruby License)</li>
232
- <li><a href="http://rubyforge.org/projects/rchardet">rchardet</a> Used for detecting encoding in CSV and TXT importers (Copyright © JMHodges; LGPL)</li>
233
- <li><a href="https://github.com/gilt/rubyXL">RubyXL</a> Used for reading the newer .xlsx files (Copyright © 2011 Vivek Bhagwat; MIT-Licensed)</li>
234
- <li><a href="http://nokogiri.org/">Nokogiri</a> Used for reading ODS documents (Copyright © 2008 - 2012 Aaron Patterson, Mike Dalessio, Charles Nutter, Sergio Arbeo, Patrick Mahoney, Yoko Harada; MIT Licensed)</li>
235
- </ul>
236
- </div></div>
237
-
238
- <div id="footer">
239
- Generated on Sun May 19 23:16:28 2013 by
240
- <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
241
- 0.8.5.2 (ruby-1.9.3).
242
- </div>
243
-
244
- </body>
245
- </html>