ricardoo27-writeexcel 0.6.12.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (245) hide show
  1. data/.document +5 -0
  2. data/.gitattributes +1 -0
  3. data/README.rdoc +136 -0
  4. data/Rakefile +52 -0
  5. data/VERSION +1 -0
  6. data/charts/chartex.rb +316 -0
  7. data/charts/demo1.rb +46 -0
  8. data/charts/demo101.bin +0 -0
  9. data/charts/demo2.rb +65 -0
  10. data/charts/demo201.bin +0 -0
  11. data/charts/demo3.rb +117 -0
  12. data/charts/demo301.bin +0 -0
  13. data/charts/demo4.rb +119 -0
  14. data/charts/demo401.bin +0 -0
  15. data/charts/demo5.rb +48 -0
  16. data/charts/demo501.bin +0 -0
  17. data/examples/a_simple.rb +43 -0
  18. data/examples/autofilter.rb +265 -0
  19. data/examples/bigfile.rb +30 -0
  20. data/examples/chart_area.rb +121 -0
  21. data/examples/chart_bar.rb +120 -0
  22. data/examples/chart_column.rb +120 -0
  23. data/examples/chart_line.rb +120 -0
  24. data/examples/chart_pie.rb +108 -0
  25. data/examples/chart_scatter.rb +121 -0
  26. data/examples/chart_stock.rb +148 -0
  27. data/examples/chess.rb +142 -0
  28. data/examples/colors.rb +129 -0
  29. data/examples/comments1.rb +27 -0
  30. data/examples/comments2.rb +352 -0
  31. data/examples/copyformat.rb +52 -0
  32. data/examples/data_validate.rb +279 -0
  33. data/examples/date_time.rb +87 -0
  34. data/examples/defined_name.rb +32 -0
  35. data/examples/demo.rb +124 -0
  36. data/examples/diag_border.rb +36 -0
  37. data/examples/formats.rb +490 -0
  38. data/examples/formula_result.rb +30 -0
  39. data/examples/header.rb +137 -0
  40. data/examples/hide_sheet.rb +29 -0
  41. data/examples/hyperlink.rb +43 -0
  42. data/examples/images.rb +63 -0
  43. data/examples/indent.rb +31 -0
  44. data/examples/merge1.rb +40 -0
  45. data/examples/merge2.rb +45 -0
  46. data/examples/merge3.rb +66 -0
  47. data/examples/merge4.rb +83 -0
  48. data/examples/merge5.rb +80 -0
  49. data/examples/merge6.rb +67 -0
  50. data/examples/outline.rb +255 -0
  51. data/examples/outline_collapsed.rb +209 -0
  52. data/examples/panes.rb +113 -0
  53. data/examples/password_protection.rb +33 -0
  54. data/examples/properties.rb +34 -0
  55. data/examples/properties_jp.rb +33 -0
  56. data/examples/protection.rb +47 -0
  57. data/examples/regions.rb +53 -0
  58. data/examples/repeat.rb +43 -0
  59. data/examples/republic.png +0 -0
  60. data/examples/right_to_left.rb +27 -0
  61. data/examples/row_wrap.rb +53 -0
  62. data/examples/set_first_sheet.rb +14 -0
  63. data/examples/stats.rb +74 -0
  64. data/examples/stocks.rb +81 -0
  65. data/examples/store_formula.rb +15 -0
  66. data/examples/tab_colors.rb +31 -0
  67. data/examples/utf8.rb +15 -0
  68. data/examples/write_arrays.rb +83 -0
  69. data/html/en/doc_en.html +5946 -0
  70. data/html/images/a_simple.jpg +0 -0
  71. data/html/images/area1.jpg +0 -0
  72. data/html/images/bar1.jpg +0 -0
  73. data/html/images/chart_area.xls +0 -0
  74. data/html/images/column1.jpg +0 -0
  75. data/html/images/data_validation.jpg +0 -0
  76. data/html/images/line1.jpg +0 -0
  77. data/html/images/pie1.jpg +0 -0
  78. data/html/images/regions.jpg +0 -0
  79. data/html/images/scatter1.jpg +0 -0
  80. data/html/images/stats.jpg +0 -0
  81. data/html/images/stock1.jpg +0 -0
  82. data/html/images/stocks.jpg +0 -0
  83. data/html/index.html +16 -0
  84. data/html/style.css +433 -0
  85. data/lib/writeexcel.rb +1159 -0
  86. data/lib/writeexcel/biffwriter.rb +223 -0
  87. data/lib/writeexcel/caller_info.rb +12 -0
  88. data/lib/writeexcel/cell_range.rb +332 -0
  89. data/lib/writeexcel/chart.rb +1968 -0
  90. data/lib/writeexcel/charts/area.rb +154 -0
  91. data/lib/writeexcel/charts/bar.rb +177 -0
  92. data/lib/writeexcel/charts/column.rb +156 -0
  93. data/lib/writeexcel/charts/external.rb +66 -0
  94. data/lib/writeexcel/charts/line.rb +154 -0
  95. data/lib/writeexcel/charts/pie.rb +169 -0
  96. data/lib/writeexcel/charts/scatter.rb +192 -0
  97. data/lib/writeexcel/charts/stock.rb +213 -0
  98. data/lib/writeexcel/col_info.rb +87 -0
  99. data/lib/writeexcel/colors.rb +68 -0
  100. data/lib/writeexcel/comments.rb +460 -0
  101. data/lib/writeexcel/compatibility.rb +65 -0
  102. data/lib/writeexcel/convert_date_time.rb +117 -0
  103. data/lib/writeexcel/data_validations.rb +370 -0
  104. data/lib/writeexcel/debug_info.rb +41 -0
  105. data/lib/writeexcel/embedded_chart.rb +35 -0
  106. data/lib/writeexcel/excelformula.y +139 -0
  107. data/lib/writeexcel/excelformulaparser.rb +587 -0
  108. data/lib/writeexcel/format.rb +1575 -0
  109. data/lib/writeexcel/formula.rb +987 -0
  110. data/lib/writeexcel/helper.rb +78 -0
  111. data/lib/writeexcel/image.rb +218 -0
  112. data/lib/writeexcel/olewriter.rb +305 -0
  113. data/lib/writeexcel/outline.rb +24 -0
  114. data/lib/writeexcel/properties.rb +242 -0
  115. data/lib/writeexcel/shared_string_table.rb +153 -0
  116. data/lib/writeexcel/storage_lite.rb +984 -0
  117. data/lib/writeexcel/workbook.rb +2478 -0
  118. data/lib/writeexcel/worksheet.rb +6925 -0
  119. data/lib/writeexcel/worksheets.rb +25 -0
  120. data/lib/writeexcel/write_file.rb +63 -0
  121. data/test/excelfile/Chart1.xls +0 -0
  122. data/test/excelfile/Chart2.xls +0 -0
  123. data/test/excelfile/Chart3.xls +0 -0
  124. data/test/excelfile/Chart4.xls +0 -0
  125. data/test/excelfile/Chart5.xls +0 -0
  126. data/test/helper.rb +31 -0
  127. data/test/perl_output/Chart1.xls.data +0 -0
  128. data/test/perl_output/Chart2.xls.data +0 -0
  129. data/test/perl_output/Chart3.xls.data +0 -0
  130. data/test/perl_output/Chart4.xls.data +0 -0
  131. data/test/perl_output/Chart5.xls.data +0 -0
  132. data/test/perl_output/README +31 -0
  133. data/test/perl_output/a_simple.xls +0 -0
  134. data/test/perl_output/autofilter.xls +0 -0
  135. data/test/perl_output/biff_add_continue_testdata +0 -0
  136. data/test/perl_output/chart_area.xls +0 -0
  137. data/test/perl_output/chart_bar.xls +0 -0
  138. data/test/perl_output/chart_column.xls +0 -0
  139. data/test/perl_output/chart_line.xls +0 -0
  140. data/test/perl_output/chess.xls +0 -0
  141. data/test/perl_output/colors.xls +0 -0
  142. data/test/perl_output/comments0.xls +0 -0
  143. data/test/perl_output/comments1.xls +0 -0
  144. data/test/perl_output/comments2.xls +0 -0
  145. data/test/perl_output/data_validate.xls +0 -0
  146. data/test/perl_output/date_time.xls +0 -0
  147. data/test/perl_output/defined_name.xls +0 -0
  148. data/test/perl_output/demo.xls +0 -0
  149. data/test/perl_output/demo101.bin +0 -0
  150. data/test/perl_output/demo201.bin +0 -0
  151. data/test/perl_output/demo301.bin +0 -0
  152. data/test/perl_output/demo401.bin +0 -0
  153. data/test/perl_output/demo501.bin +0 -0
  154. data/test/perl_output/diag_border.xls +0 -0
  155. data/test/perl_output/f_font_biff +0 -0
  156. data/test/perl_output/f_font_key +1 -0
  157. data/test/perl_output/f_xf_biff +0 -0
  158. data/test/perl_output/file_font_biff +0 -0
  159. data/test/perl_output/file_font_key +1 -0
  160. data/test/perl_output/file_xf_biff +0 -0
  161. data/test/perl_output/formula_result.xls +0 -0
  162. data/test/perl_output/headers.xls +0 -0
  163. data/test/perl_output/hidden.xls +0 -0
  164. data/test/perl_output/hide_zero.xls +0 -0
  165. data/test/perl_output/hyperlink.xls +0 -0
  166. data/test/perl_output/images.xls +0 -0
  167. data/test/perl_output/indent.xls +0 -0
  168. data/test/perl_output/merge1.xls +0 -0
  169. data/test/perl_output/merge2.xls +0 -0
  170. data/test/perl_output/merge3.xls +0 -0
  171. data/test/perl_output/merge4.xls +0 -0
  172. data/test/perl_output/merge5.xls +0 -0
  173. data/test/perl_output/merge6.xls +0 -0
  174. data/test/perl_output/ole_write_header +0 -0
  175. data/test/perl_output/outline.xls +0 -0
  176. data/test/perl_output/outline_collapsed.xls +0 -0
  177. data/test/perl_output/panes.xls +0 -0
  178. data/test/perl_output/password_protection.xls +0 -0
  179. data/test/perl_output/protection.xls +0 -0
  180. data/test/perl_output/regions.xls +0 -0
  181. data/test/perl_output/right_to_left.xls +0 -0
  182. data/test/perl_output/set_first_sheet.xls +0 -0
  183. data/test/perl_output/stats.xls +0 -0
  184. data/test/perl_output/stocks.xls +0 -0
  185. data/test/perl_output/store_formula.xls +0 -0
  186. data/test/perl_output/tab_colors.xls +0 -0
  187. data/test/perl_output/unicode_cyrillic.xls +0 -0
  188. data/test/perl_output/utf8.xls +0 -0
  189. data/test/perl_output/workbook1.xls +0 -0
  190. data/test/perl_output/workbook2.xls +0 -0
  191. data/test/perl_output/ws_colinfo +1 -0
  192. data/test/perl_output/ws_store_colinfo +0 -0
  193. data/test/perl_output/ws_store_dimensions +0 -0
  194. data/test/perl_output/ws_store_filtermode +0 -0
  195. data/test/perl_output/ws_store_filtermode_off +0 -0
  196. data/test/perl_output/ws_store_filtermode_on +0 -0
  197. data/test/perl_output/ws_store_selection +0 -0
  198. data/test/perl_output/ws_store_window2 +1 -0
  199. data/test/republic.png +0 -0
  200. data/test/test_00_IEEE_double.rb +13 -0
  201. data/test/test_01_add_worksheet.rb +10 -0
  202. data/test/test_02_merge_formats.rb +49 -0
  203. data/test/test_04_dimensions.rb +388 -0
  204. data/test/test_05_rows.rb +175 -0
  205. data/test/test_06_extsst.rb +74 -0
  206. data/test/test_11_date_time.rb +475 -0
  207. data/test/test_12_date_only.rb +525 -0
  208. data/test/test_13_date_seconds.rb +477 -0
  209. data/test/test_21_escher.rb +624 -0
  210. data/test/test_22_mso_drawing_group.rb +741 -0
  211. data/test/test_23_note.rb +57 -0
  212. data/test/test_24_txo.rb +74 -0
  213. data/test/test_25_position_object.rb +80 -0
  214. data/test/test_26_autofilter.rb +309 -0
  215. data/test/test_27_autofilter.rb +126 -0
  216. data/test/test_28_autofilter.rb +156 -0
  217. data/test/test_29_process_jpg.rb +670 -0
  218. data/test/test_30_validation_dval.rb +74 -0
  219. data/test/test_31_validation_dv_strings.rb +123 -0
  220. data/test/test_32_validation_dv_formula.rb +203 -0
  221. data/test/test_40_property_types.rb +188 -0
  222. data/test/test_41_properties.rb +235 -0
  223. data/test/test_42_set_properties.rb +434 -0
  224. data/test/test_50_name_stored.rb +295 -0
  225. data/test/test_51_name_print_area.rb +353 -0
  226. data/test/test_52_name_print_titles.rb +450 -0
  227. data/test/test_53_autofilter.rb +199 -0
  228. data/test/test_60_chart_generic.rb +574 -0
  229. data/test/test_61_chart_subclasses.rb +84 -0
  230. data/test/test_62_chart_formats.rb +268 -0
  231. data/test/test_63_chart_area_formats.rb +645 -0
  232. data/test/test_biff.rb +71 -0
  233. data/test/test_big_workbook.rb +17 -0
  234. data/test/test_compatibility.rb +12 -0
  235. data/test/test_example_match.rb +3246 -0
  236. data/test/test_format.rb +1189 -0
  237. data/test/test_formula.rb +61 -0
  238. data/test/test_ole.rb +102 -0
  239. data/test/test_storage_lite.rb +116 -0
  240. data/test/test_workbook.rb +146 -0
  241. data/test/test_worksheet.rb +106 -0
  242. data/utils/add_magic_comment.rb +80 -0
  243. data/writeexcel.gemspec +278 -0
  244. data/writeexcel.rdoc +1425 -0
  245. metadata +292 -0
@@ -0,0 +1,1159 @@
1
+ # -*- coding: utf-8 -*-
2
+ ###############################################################################
3
+ #
4
+ # WriteExcel.
5
+ #
6
+ # WriteExcel - Write to a cross-platform Excel binary file.
7
+ #
8
+ # Copyright 2000-2010, John McNamara, jmcnamara@cpan.org
9
+ #
10
+ # original written in Perl by John McNamara
11
+ # converted to Ruby by Hideo Nakamura, cxn03651@msj.biglobe.ne.jp
12
+ #
13
+ require 'writeexcel/biffwriter'
14
+ require 'writeexcel/olewriter'
15
+ require 'writeexcel/formula'
16
+ require 'writeexcel/format'
17
+ require 'writeexcel/worksheet'
18
+ require "writeexcel/workbook"
19
+ require 'writeexcel/chart'
20
+ require 'writeexcel/charts/area'
21
+ require 'writeexcel/charts/bar'
22
+ require 'writeexcel/charts/column'
23
+ require 'writeexcel/charts/external'
24
+ require 'writeexcel/charts/line'
25
+ require 'writeexcel/charts/pie'
26
+ require 'writeexcel/charts/scatter'
27
+ require 'writeexcel/charts/stock'
28
+ require 'writeexcel/storage_lite'
29
+ require 'writeexcel/compatibility'
30
+ require 'writeexcel/debug_info'
31
+ #
32
+ # = WriteExcel - Write to a cross-platform Excel binary file.
33
+ #
34
+ # == Contents
35
+ # SYSNOPSYS
36
+ # DESCRIPTION
37
+ # QUICK START
38
+ # WORKBOOK METHODS
39
+ # WORKSHEET METHODS
40
+ # PAGE SET-UP METHODS
41
+ # CELL FORMATTING
42
+ # FORMAT METHODS
43
+ # COLOURS IN EXCEL
44
+ # DATE AND TIME IN EXCEL
45
+ # OUTLINES AND GROUPING IN EXCEL
46
+ # DATA VALIDATION IN EXCEL
47
+ # FORMULAS AND FUNCTIONS IN EXCEL
48
+ # CHART
49
+ #
50
+ # == Synopsis
51
+ #
52
+ # To write a string, a formatted string, a number and a formula to the first
53
+ # worksheet in an Excel workbook called ruby.xls:
54
+ #
55
+ # require 'WriteExcel'
56
+ #
57
+ # # Create a new Excel workbook
58
+ # workbook = WriteExcel.new('ruby.xls')
59
+ #
60
+ # # Add a worksheet
61
+ # worksheet = workbook.add_worksheet
62
+ #
63
+ # # Add and define a format
64
+ # format = workbook.add_format # Add a format
65
+ # format.set_bold()
66
+ # format.set_color('red')
67
+ # format.set_align('center')
68
+ #
69
+ # # Write a formatted and unformatted string, row and column notation.
70
+ # col = row = 0
71
+ # worksheet.write(row, col, 'Hi Excel!', format)
72
+ # worksheet.write(1, col, 'Hi Excel!')
73
+ #
74
+ # # Write a number and a formula using A1 notation
75
+ # worksheet.write('A3', 1.2345)
76
+ # worksheet.write('A4', '=SIN(PI()/4)')
77
+ #
78
+ # # Save to ruby.xls
79
+ # workbook.close
80
+ #
81
+ # == Description
82
+ #
83
+ # WriteExcel can be used to create a cross-platform Excel binary file.
84
+ # Multiple worksheets can be added to a workbook and formatting can be applied
85
+ # to cells. Text, numbers, formulas, hyperlinks and images can be written to
86
+ # the cells.
87
+ #
88
+ # The Excel file produced by this gem is compatible with 97, 2000, 2002, 2003
89
+ # and 2007.
90
+ #
91
+ # WriteExcel will work on the majority of Windows, UNIX and Mac platforms.
92
+ # Generated files are also compatible with the Linux/UNIX spreadsheet
93
+ # applications Gnumeric and OpenOffice.org.
94
+ #
95
+ # This module cannot be used to write to an existing Excel file
96
+ #
97
+ # This library is converted from Spreadsheet::WriteExcel module of Perl.
98
+ # http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel-2.37/
99
+ #
100
+ # == Quick Start
101
+ #
102
+ # WriteExcel tries to provide an interface to as many of Excel's features as
103
+ # possible. As a result there is a lot of documentation to accompany the
104
+ # interface and it can be difficult at first glance to see what it important
105
+ # and what is not. So for those of you who prefer to assemble Ikea furniture
106
+ # first and then read the instructions, here are four easy steps:
107
+ #
108
+ # 1. Create a new Excel workbook (i.e. file) using new().
109
+ #
110
+ # 2. Add a worksheet to the new workbook using add_worksheet().
111
+ #
112
+ # 3. Write to the worksheet using write().
113
+ #
114
+ # 4. Save to file.
115
+ #
116
+ # Like this:
117
+ #
118
+ # require 'WriteExcel' # Step 0
119
+ #
120
+ # workbook = WriteExcel.new('ruby.xls') # Step 1
121
+ # worksheet = workbook.add_worksheet # Step 2
122
+ # worksheet.write('A1', 'Hi Excel!') # Step 3
123
+ # workbook.close # Step 4
124
+ #
125
+ # This will create an Excel file called ruby.xls with a single worksheet and the
126
+ # text 'Hi Excel!' in the relevant cell. And that's it. Okay, so there is
127
+ # actually a zeroth step as well, but use WriteExcel goes without saying. There
128
+ # are also many examples that come with the distribution and which you can
129
+ # use to get you started. See EXAMPLES.
130
+ #
131
+ # = Workbook methods
132
+ #
133
+ # The WriteExcel module provides an object oriented interface
134
+ # to a new Excel workbook. The following methods are available through
135
+ # a new workbook.
136
+ #
137
+ # new()
138
+ # add_worksheet()
139
+ # add_format()
140
+ # add_chart()
141
+ # add_chart_ext()
142
+ # close()
143
+ # compatibility_mode()
144
+ # set_properties()
145
+ # define_name()
146
+ # set_tempdir()
147
+ # set_custom_color()
148
+ # sheets()
149
+ # set_1904()
150
+ # set_codepage()
151
+ #
152
+ # = Worksheet methods
153
+ #
154
+ # A new worksheet is created by calling the add_worksheet() method from
155
+ # a workbook object:
156
+ #
157
+ # worksheet1 = workbook.add_worksheet
158
+ # worksheet2 = workbook.add_worksheet
159
+ #
160
+ # The following methods are available through a new worksheet:
161
+ #
162
+ # write()
163
+ # write_number()
164
+ # write_string()
165
+ # write_utf16be_string()
166
+ # write_utf16le_string()
167
+ # keep_leading_zeros()
168
+ # write_blank()
169
+ # write_row()
170
+ # write_col()
171
+ # write_date_time()
172
+ # write_url()
173
+ # write_url_range()
174
+ # write_formula()
175
+ # store_formula()
176
+ # repeat_formula()
177
+ # write_comment()
178
+ # show_comments()
179
+ # add_write_handler() (* not implemented yet)
180
+ # insert_image()
181
+ # insert_chart()
182
+ # data_validation()
183
+ # get_name()
184
+ # activate()
185
+ # select()
186
+ # hide()
187
+ # set_first_sheet()
188
+ # protect()
189
+ # set_selection()
190
+ # set_row()
191
+ # set_column()
192
+ # outline_settings()
193
+ # freeze_panes()
194
+ # split_panes()
195
+ # merge_range()
196
+ # set_zoom()
197
+ # right_to_left()
198
+ # hide_zero()
199
+ # set_tab_color()
200
+ # autofilter()
201
+ #
202
+ # == Cell notation
203
+ # WriteExcel supports two forms of notation to designate the position of cells:
204
+ # Row-column notation and A1 notation.
205
+ #
206
+ # Row-column notation uses a zero based index for both row and column while A1
207
+ # notation uses the standard Excel alphanumeric sequence of column letter and
208
+ # 1-based row. For example:
209
+ #
210
+ # (0, 0) # The top left cell in row-column notation.
211
+ # ('A1') # The top left cell in A1 notation.
212
+ #
213
+ # (1999, 29) # Row-column notation.
214
+ # ('AD2000') # The same cell in A1 notation.
215
+ #
216
+ # Row-column notation is useful if you are referring to cells
217
+ # programmatically:
218
+ #
219
+ # (0 .. 10).each do |i|
220
+ # worksheet.write(i, 0, 'Hello') # Cells A1 to A10
221
+ # end
222
+ #
223
+ # A1 notation is useful for setting up a worksheet manually and for working
224
+ # with formulas:
225
+ #
226
+ # worksheet.write('H1', 200)
227
+ # worksheet.write('H2', '=H1+1')
228
+ #
229
+ # In formulas and applicable methods you can also use the A:A column notation:
230
+ #
231
+ # worksheet.write('A1', '=SUM(B:B)')
232
+ #
233
+ # For simplicity, the parameter lists for the worksheet method calls in the
234
+ # following sections are given in terms of row-column notation. In all cases
235
+ # it is also possible to use A1 notation.
236
+ #
237
+ # Note: in Excel it is also possible to use a R1C1 notation. This is not
238
+ # supported by WriteExcel.
239
+ #
240
+ # ==PAGE SET-UP METHODS
241
+ #
242
+ # Page set-up methods affect the way that a worksheet looks when it is printed.
243
+ # They control features such as page headers and footers and margins. These
244
+ # methods are really just standard worksheet methods. They are documented
245
+ # here in a separate section for the sake of clarity.
246
+ #
247
+ # The following methods are available for page set-up:
248
+ #
249
+ # set_landscape()
250
+ # set_portrait()
251
+ # set_page_view()
252
+ # set_paper()
253
+ # center_horizontally()
254
+ # center_vertically()
255
+ # set_margins()
256
+ # set_header()
257
+ # set_footer()
258
+ # repeat_rows()
259
+ # repeat_columns()
260
+ # hide_gridlines()
261
+ # print_row_col_headers()
262
+ # print_area()
263
+ # print_across()
264
+ # fit_to_pages()
265
+ # set_start_page()
266
+ # set_print_scale()
267
+ # set_h_pagebreaks()
268
+ # set_v_pagebreaks()
269
+ #
270
+ # A common requirement when working with WriteExcel is to apply the same page
271
+ # set-up features to all of the worksheets in a workbook. To do this you can use
272
+ # the sheets() method of the workbook class to access the array of worksheets
273
+ # in a workbook:
274
+ #
275
+ # workbook.sheets.each do |worksheet|
276
+ # worksheet.set_landscape
277
+ # end
278
+ #
279
+ # ==CELL FORMATTING
280
+ #
281
+ # This section describes the methods and properties that are available for
282
+ # formatting cells in Excel. The properties of a cell that can be formatted
283
+ # include: fonts, colours, patterns, borders, alignment and number formatting.
284
+ #
285
+ # ===Creating and using a Format object
286
+ #
287
+ # Cell formatting is defined through a Format object. Format objects are
288
+ # created by calling the workbook add_format() method as follows:
289
+ #
290
+ # format1 = workbook.add_format # Set properties later
291
+ # format2 = workbook.add_format(property hash..) # Set at creation
292
+ #
293
+ # The format object holds all the formatting properties that can be applied
294
+ # to a cell, a row or a column. The process of setting these properties is
295
+ # discussed in the next section.
296
+ #
297
+ # Once a Format object has been constructed and it properties have been set
298
+ # it can be passed as an argument to the worksheet write methods as follows:
299
+ #
300
+ # worksheet.write(0, 0, 'One', format)
301
+ # worksheet.write_string(1, 0, 'Two', format)
302
+ # worksheet.write_number(2, 0, 3, format)
303
+ # worksheet.write_blank(3, 0, format)
304
+ #
305
+ # Formats can also be passed to the worksheet set_row() and set_column()
306
+ # methods to define the default property for a row or column.
307
+ #
308
+ # worksheet.set_row(0, 15, format)
309
+ # worksheet.set_column(0, 0, 15, format)
310
+ #
311
+ # ===Format methods and Format properties
312
+ #
313
+ # The following table shows the Excel format categories, the formatting
314
+ # properties that can be applied and the equivalent object method:
315
+ #
316
+ # Category Description Property Method Name
317
+ # -------- ----------- -------- -----------
318
+ # Font Font type font set_font()
319
+ # Font size size set_size()
320
+ # Font color color set_color()
321
+ # Bold bold set_bold()
322
+ # Italic italic set_italic()
323
+ # Underline underline set_underline()
324
+ # Strikeout font_strikeout set_font_strikeout()
325
+ # Super/Subscript font_script set_font_script()
326
+ # Outline font_outline set_font_outline()
327
+ # Shadow font_shadow set_font_shadow()
328
+ #
329
+ # Number Numeric format num_format set_num_format()
330
+ #
331
+ # Protection Lock cells locked set_locked()
332
+ # Hide formulas hidden set_hidden()
333
+ #
334
+ # Alignment Horizontal align align set_align()
335
+ # Vertical align valign set_align()
336
+ # Rotation rotation set_rotation()
337
+ # Text wrap text_wrap set_text_wrap()
338
+ # Justify last text_justlast set_text_justlast()
339
+ # Center across center_across set_center_across()
340
+ # Indentation indent set_indent()
341
+ # Shrink to fit shrink set_shrink()
342
+ #
343
+ # Pattern Cell pattern pattern set_pattern()
344
+ # Background color bg_color set_bg_color()
345
+ # Foreground color fg_color set_fg_color()
346
+ #
347
+ # Border Cell border border set_border()
348
+ # Bottom border bottom set_bottom()
349
+ # Top border top set_top()
350
+ # Left border left set_left()
351
+ # Right border right set_right()
352
+ # Border color border_color set_border_color()
353
+ # Bottom color bottom_color set_bottom_color()
354
+ # Top color top_color set_top_color()
355
+ # Left color left_color set_left_color()
356
+ # Right color right_color set_right_color()
357
+ #
358
+ # There are two ways of setting Format properties: by using the object method
359
+ # interface or by setting the property directly. For example, a typical use of
360
+ # the method interface would be as follows:
361
+ #
362
+ # format = workbook.add_format
363
+ # format.set_bold
364
+ # format.set_color('red')
365
+ #
366
+ # By comparison the properties can be set directly by passing a hash of
367
+ # properties to the Format constructor:
368
+ #
369
+ # format = workbook.add_format(:bold => 1, :color => 'red')
370
+ #
371
+ # or after the Format has been constructed by means of the
372
+ # set_format_properties() method as follows:
373
+ #
374
+ # format = workbook.add_format
375
+ # format.set_format_properties(:bold => 1, :color => 'red')
376
+ #
377
+ # You can also store the properties in one or more named hashes and pass them
378
+ # to the required method:
379
+ #
380
+ # font = {
381
+ # :font => 'Arial',
382
+ # :size => 12,
383
+ # :color => 'blue',
384
+ # :bold => 1
385
+ # }
386
+ #
387
+ # shading = {
388
+ # :bg_color => 'green',
389
+ # :pattern => 1
390
+ # }
391
+ #
392
+ # format1 = workbook.add_format(font) # Font only
393
+ # format2 = workbook.add_format(font, shading) # Font and shading
394
+ #
395
+ # The provision of two ways of setting properties might lead you to wonder
396
+ # which is the best way. The method mechanism may be better is you prefer
397
+ # setting properties via method calls (which the author did when they were
398
+ # code was first written) otherwise passing properties to the constructor has
399
+ # proved to be a little more flexible and self documenting in practice. An
400
+ # additional advantage of working with property hashes is that it allows you to
401
+ # share formatting between workbook objects as shown in the example above.
402
+ #
403
+ #--
404
+ #
405
+ # did not converted ???
406
+ #
407
+ # The Perl/Tk style of adding properties is also supported:
408
+ #
409
+ # %font = (
410
+ # -font => 'Arial',
411
+ # -size => 12,
412
+ # -color => 'blue',
413
+ # -bold => 1,
414
+ # )
415
+ #++
416
+ #
417
+ # ===Working with formats
418
+ #
419
+ # The default format is Arial 10 with all other properties off.
420
+ #
421
+ # Each unique format in WriteExcel must have a corresponding
422
+ # Format object. It isn't possible to use a Format with a write() method and
423
+ # then redefine the Format for use at a later stage. This is because a Format
424
+ # is applied to a cell not in its current state but in its final state.
425
+ # Consider the following example:
426
+ #
427
+ # format = workbook.add_format
428
+ # format.set_bold
429
+ # format.set_color('red')
430
+ # worksheet.write('A1', 'Cell A1', format)
431
+ # format.set_color('green')
432
+ # worksheet.write('B1', 'Cell B1', format)
433
+ #
434
+ # Cell A1 is assigned the Format _format_ which is initially set to the colour
435
+ # red. However, the colour is subsequently set to green. When Excel displays
436
+ # Cell A1 it will display the final state of the Format which in this case
437
+ # will be the colour green.
438
+ #
439
+ # In general a method call without an argument will turn a property on,
440
+ # for example:
441
+ #
442
+ # format1 = workbook.add_format
443
+ # format1.set_bold # Turns bold on
444
+ # format1.set_bold(1) # Also turns bold on
445
+ # format1.set_bold(0) # Turns bold off
446
+ #
447
+ # ==FORMAT METHODS
448
+ #
449
+ # The Format object methods are described in more detail in the following
450
+ # sections. In addition, there is a Ruby program called formats.rb in the
451
+ # examples directory of the WriteExcel distribution. This program creates an
452
+ # Excel workbook called formats.xls which contains examples of almost all
453
+ # the format types.
454
+ #
455
+ # The following Format methods are available:
456
+ #
457
+ # set_font()
458
+ # set_size()
459
+ # set_color()
460
+ # set_bold()
461
+ # set_italic()
462
+ # set_underline()
463
+ # set_font_strikeout()
464
+ # set_font_script()
465
+ # set_font_outline()
466
+ # set_font_shadow()
467
+ # set_num_format()
468
+ # set_locked()
469
+ # set_hidden()
470
+ # set_align()
471
+ # set_rotation()
472
+ # set_text_wrap()
473
+ # set_text_justlast()
474
+ # set_center_across()
475
+ # set_indent()
476
+ # set_shrink()
477
+ # set_pattern()
478
+ # set_bg_color()
479
+ # set_fg_color()
480
+ # set_border()
481
+ # set_bottom()
482
+ # set_top()
483
+ # set_left()
484
+ # set_right()
485
+ # set_border_color()
486
+ # set_bottom_color()
487
+ # set_top_color()
488
+ # set_left_color()
489
+ # set_right_color()
490
+ #
491
+ # The above methods can also be applied directly as properties. For example
492
+ # format.set_bold is equivalent to workbook.add_format(:bold => 1).
493
+ #
494
+ # ==COLOURS IN EXCEL
495
+ #
496
+ # Excel provides a colour palette of 56 colours. In WriteExcel these colours
497
+ # are accessed via their palette index in the range 8..63. This index is used
498
+ # to set the colour of fonts, cell patterns and cell borders. For example:
499
+ #
500
+ # format = workbook.add_format(
501
+ # :color => 12, # index for blue
502
+ # :font => 'Arial',
503
+ # :size => 12,
504
+ # :bold => 1
505
+ # )
506
+ #
507
+ # The most commonly used colours can also be accessed by name. The name acts
508
+ # as a simple alias for the colour index:
509
+ #
510
+ # black => 8
511
+ # blue => 12
512
+ # brown => 16
513
+ # cyan => 15
514
+ # gray => 23
515
+ # green => 17
516
+ # lime => 11
517
+ # magenta => 14
518
+ # navy => 18
519
+ # orange => 53
520
+ # pink => 33
521
+ # purple => 20
522
+ # red => 10
523
+ # silver => 22
524
+ # white => 9
525
+ # yellow => 13
526
+ #
527
+ # For example:
528
+ #
529
+ # font = workbook.add_format(:color => 'red')
530
+ #
531
+ # Users of VBA in Excel should note that the equivalent colour indices are in
532
+ # the range 1..56 instead of 8..63.
533
+ #
534
+ # If the default palette does not provide a required colour you can override
535
+ # one of the built-in values. This is achieved by using the set_custom_color()
536
+ # workbook method to adjust the RGB (red green blue) components of the colour:
537
+ #
538
+ # ferrari = workbook.set_custom_color(40, 216, 12, 12)
539
+ #
540
+ # format = workbook.add_format(
541
+ # :bg_color => ferrari,
542
+ # :pattern => 1,
543
+ # :border => 1
544
+ # )
545
+ #
546
+ # worksheet.write_blank('A1', format)
547
+ #
548
+ # You may also find the following links helpful:
549
+ #
550
+ # A detailed look at Excel's colour palette:
551
+ # http://www.mvps.org/dmcritchie/excel/colors.htm
552
+ #
553
+ # A decimal RGB chart: http://www.hypersolutions.org/pages/rgbdec.html
554
+ #
555
+ # A hex RGB chart: : http://www.hypersolutions.org/pages/rgbhex.html
556
+ #
557
+ # ==DATES AND TIME IN EXCEL
558
+ #
559
+ # There are two important things to understand about dates and times in Excel:
560
+ #
561
+ # 1. A date/time in Excel is a real number plus an Excel number format.
562
+ #
563
+ # 2. WriteExcel doesn't automatically convert date/time strings in write() to
564
+ # an Excel date/time.
565
+ #
566
+ # These two points are explained in more detail below along with some
567
+ # suggestions on how to convert times and dates to the required format.
568
+ #
569
+ # ===An Excel date/time is a number plus a format
570
+ #
571
+ # If you write a date string with write() then all you will get is a string:
572
+ #
573
+ # worksheet.write('A1', '02/03/04') # !! Writes a string not a date. !!
574
+ #
575
+ # Dates and times in Excel are represented by real numbers, for example
576
+ # "Jan 1 2001 12:30 AM" is represented by the number 36892.521.
577
+ #
578
+ # The integer part of the number stores the number of days since the epoch
579
+ # and the fractional part stores the percentage of the day.
580
+ #
581
+ # A date or time in Excel is just like any other number. To have the number
582
+ # display as a date you must apply an Excel number format to it. Here are
583
+ # some examples.
584
+ #
585
+ # #!/usr/bin/ruby -w
586
+ #
587
+ # require 'writeexcel'
588
+ #
589
+ # workbook = WriteExcel.new('date_examples.xls')
590
+ # worksheet = workbook.add_worksheet
591
+ #
592
+ # worksheet.set_column('A:A', 30) # For extra visibility.
593
+ #
594
+ # number = 39506.5
595
+ #
596
+ # worksheet.write('A1', number) # 39506.5
597
+ #
598
+ # format2 = workbook.add_format(:num_format => 'dd/mm/yy')
599
+ # worksheet.write('A2', number , format2); # 28/02/08
600
+ #
601
+ # format3 = workbook.add_format(:num_format => 'mm/dd/yy')
602
+ # worksheet.write('A3', number , format3); # 02/28/08
603
+ #
604
+ # format4 = workbook.add_format(:num_format => 'd-m-yyyy')
605
+ # worksheet.write('A4', .number , format4) # 28-2-2008
606
+ #
607
+ # format5 = workbook.add_format(:num_format => 'dd/mm/yy hh:mm')
608
+ # worksheet.write('A5', number , format5) # 28/02/08 12:00
609
+ #
610
+ # format6 = workbook.add_format(:num_format => 'd mmm yyyy')
611
+ # worksheet.write('A6', number , format6) # 28 Feb 2008
612
+ #
613
+ # format7 = workbook.add_format(:num_format => 'mmm d yyyy hh:mm AM/PM')
614
+ # worksheet.write('A7', number , format7) # Feb 28 2008 12:00 PM
615
+ #
616
+ # ===WriteExcel doesn't automatically convert date/time strings
617
+ #
618
+ # WriteExcel doesn't automatically convert input date strings into Excel's
619
+ # formatted date numbers due to the large number of possible date formats
620
+ # and also due to the possibility of misinterpretation.
621
+ #
622
+ # For example, does 02/03/04 mean March 2 2004, February 3 2004 or even March
623
+ # 4 2002.
624
+ #
625
+ # Therefore, in order to handle dates you will have to convert them to numbers
626
+ # and apply an Excel format. Some methods for converting dates are listed in
627
+ # the next section.
628
+ #
629
+ # The most direct way is to convert your dates to the ISO8601
630
+ # yyyy-mm-ddThh:mm:ss.sss date format and use the write_date_time() worksheet
631
+ # method:
632
+ #
633
+ # worksheet.write_date_time('A2', '2001-01-01T12:20', format)
634
+ #
635
+ # See the write_date_time() section of the documentation for more details.
636
+ #
637
+ # A general methodology for handling date strings with write_date_time() is:
638
+ #
639
+ # 1. Identify incoming date/time strings with a regex.
640
+ # 2. Extract the component parts of the date/time using the same regex.
641
+ # 3. Convert the date/time to the ISO8601 format.
642
+ # 4. Write the date/time using write_date_time() and a number format.
643
+ #
644
+ # Here is an example:
645
+ #
646
+ # #!/usr/bin/ruby -w
647
+ #
648
+ # require 'writeexcel'
649
+ #
650
+ # workbook = WriteExcel.new('example.xls')
651
+ # worksheet = workbook.add_worksheet
652
+ #
653
+ # # Set the default format for dates.
654
+ # date_format = workbook.add_format(:num_format => 'mmm d yyyy')
655
+ #
656
+ # # Increase column width to improve visibility of data.
657
+ # worksheet.set_column('A:C', 20)
658
+ #
659
+ # data = [
660
+ # %w(Item Cost Date),
661
+ # %w(Book 10 1/9/2007),
662
+ # %w(Beer 4 12/9/2007),
663
+ # %w(Bed 500 5/10/2007)
664
+ # ]
665
+ #
666
+ # # Simulate reading from a data source.
667
+ # row = 0
668
+ #
669
+ # data.each do |row_data|
670
+ # col = 0
671
+ # row_data.each do |item|
672
+ #
673
+ # # Match dates in the following formats: d/m/yy, d/m/yyyy
674
+ # if item =~ %r[^(\d{1,2})/(\d{1,2})/(\d{4})$]
675
+ # # Change to the date format required by write_date_time().
676
+ # date = sprintf "%4d-%02d-%02dT", $3, $2, $1
677
+ # worksheet.write_date_time(row, col, date, date_format)
678
+ # else
679
+ # # Just plain data
680
+ # worksheet.write(row, col, item)
681
+ # end
682
+ # col += 1
683
+ # end
684
+ # row += 1
685
+ # end
686
+ #
687
+ #--
688
+ # For a slightly more advanced solution you can modify the write() method to
689
+ # handle date formats of your choice via the add_write_handler() method. See
690
+ # the add_write_handler() section of the docs and the write_handler3.rb and
691
+ # write_handler4.rb programs in the examples directory of the distro.
692
+ #++
693
+ #
694
+ # ==OUTLINES AND GROUPING IN EXCEL
695
+ #
696
+ # Excel allows you to group rows or columns so that they can be hidden or
697
+ # displayed with a single mouse click. This feature is referred to as outlines.
698
+ #
699
+ # Outlines can reduce complex data down to a few salient sub-totals or
700
+ # summaries.
701
+ #
702
+ # This feature is best viewed in Excel but the following is an ASCII
703
+ # representation of what a worksheet with three outlines might look like. Rows
704
+ # 3-4 and rows 7-8 are grouped at level 2. Rows 2-9 are grouped at level 1.
705
+ # The lines at the left hand side are called outline level bars.
706
+ #
707
+ # ------------------------------------------
708
+ # 1 2 3 | | A | B | C | D | ...
709
+ # ------------------------------------------
710
+ # _ | 1 | A | | | | ...
711
+ # | _ | 2 | B | | | | ...
712
+ # | | | 3 | (C) | | | | ...
713
+ # | | | 4 | (D) | | | | ...
714
+ # | - | 5 | E | | | | ...
715
+ # | _ | 6 | F | | | | ...
716
+ # | | | 7 | (G) | | | | ...
717
+ # | | | 8 | (H) | | | | ...
718
+ # | - | 9 | I | | | | ...
719
+ # - | . | ... | ... | ... | ... | ...
720
+ #
721
+ # Clicking the minus sign on each of the level 2 outlines will collapse and
722
+ # hide the data as shown in the next figure. The minus sign changes to a plus
723
+ # sign to indicate that the data in the outline is hidden.
724
+ #
725
+ # ------------------------------------------
726
+ # 1 2 3 | | A | B | C | D | ...
727
+ # ------------------------------------------
728
+ # _ | 1 | A | | | | ...
729
+ # | | 2 | B | | | | ...
730
+ # | + | 5 | E | | | | ...
731
+ # | | 6 | F | | | | ...
732
+ # | + | 9 | I | | | | ...
733
+ # - | . | ... | ... | ... | ... | ...
734
+ #
735
+ # Clicking on the minus sign on the level 1 outline will collapse the
736
+ # remaining rows as follows:
737
+ #
738
+ # ------------------------------------------
739
+ # 1 2 3 | | A | B | C | D | ...
740
+ # ------------------------------------------
741
+ # | 1 | A | | | | ...
742
+ # + | . | ... | ... | ... | ... | ...
743
+ #
744
+ # Grouping in WriteExcel is achieved by setting the outline level via the
745
+ # set_row() and set_column() worksheet methods:
746
+ #
747
+ # set_row(row, height, format, hidden, level, collapsed)
748
+ # set_column(first_col, last_col, width, format, hidden, level, collapsed)
749
+ #
750
+ # The following example sets an outline level of 1 for rows 1 and 2
751
+ # (zero-indexed) and columns B to G. The parameters _height_ and _format_ are
752
+ # assigned default values since they are undefined:
753
+ #
754
+ # worksheet.set_row(1, nil, nil, 0, 1)
755
+ # worksheet.set_row(2, nil, nil, 0, 1)
756
+ # worksheet.set_column('B:G', nil, nil, 0, 1)
757
+ #
758
+ # Excel allows up to 7 outline levels. Therefore the _level_ parameter should
759
+ # be in the range 0 <= _level_ <= 7.
760
+ #
761
+ # Rows and columns can be collapsed by setting the _hidden_ flag for the hidden
762
+ # rows/columns and setting the _collapsed_ flag for the row/column that has
763
+ # the collapsed + symbol:
764
+ #
765
+ # worksheet.set_row(1, nil, nil, 1, 1)
766
+ # worksheet.set_row(2, nil, nil, 1, 1)
767
+ # worksheet.set_row(3, nil, nil, 0, 0, 1) # Collapsed flag.
768
+ #
769
+ # worksheet.set_column('B:G', nil, nil, 1, 1)
770
+ # worksheet.set_column('H:H', nil, nil, 0, 0, 1) # Collapsed flag.
771
+ #
772
+ # Note: Setting the _collapsed_ flag is particularly important for
773
+ # compatibility with OpenOffice.org and Gnumeric.
774
+ #
775
+ # For a more complete example see the outline.rb
776
+ # and outline_collapsed.rb
777
+ # programs in the examples directory of the distro.
778
+ #
779
+ # Some additional outline properties can be set via the outline_settings()
780
+ # worksheet method, see above.
781
+ #
782
+ # ==DATA VALIDATION IN EXCEL
783
+ #
784
+ # Data validation is a feature of Excel which allows you to restrict the data
785
+ # that a users enters in a cell and to display help and warning messages. It
786
+ # also allows you to restrict input to values in a drop down list.
787
+ #
788
+ # A typical use case might be to restrict data in a cell to integer values in
789
+ # a certain range, to provide a help message to indicate the required value and
790
+ # to issue a warning if the input data doesn't meet the stated criteria.
791
+ # In WriteExcel we could do that as follows:
792
+ #
793
+ # worksheet.data_validation('B3',
794
+ # {
795
+ # :validate => 'integer',
796
+ # :criteria => 'between',
797
+ # :minimum => 1,
798
+ # :maximum => 100,
799
+ # :input_title => 'Input an integer:',
800
+ # :input_message => 'Between 1 and 100',
801
+ # :error_message => 'Sorry, try again.'
802
+ # })
803
+ #
804
+ # The above example would look like this in Excel:
805
+ # http://homepage.eircom.net/~jmcnamara/perl/data_validation.jpg.
806
+ #
807
+ # For more information on data validation see the following Microsoft
808
+ # support article "Description and examples of data validation in Excel":
809
+ # http://support.microsoft.com/kb/211485.
810
+ #
811
+ # ==FORMULAS AND FUNCTIONS IN EXCEL
812
+ #
813
+ # ===Caveats
814
+ #
815
+ # The first thing to note is that there are still some outstanding issues
816
+ # with the implementation of formulas and functions:
817
+ #
818
+ # 1. Writing a formula is much slower than writing the equivalent string.
819
+ # 2. You cannot use array constants, i.e. {1;2;3}, in functions.
820
+ # 3. Unary minus isn't supported.
821
+ # 4. Whitespace is not preserved around operators.
822
+ # 5. Named ranges are not supported.
823
+ # 6. Array formulas are not supported.
824
+ #
825
+ # However, these constraints will be removed in future versions. They are
826
+ # here because of a trade-off between features and time. Also, it is possible
827
+ # to work around issue 1 using the store_formula() and repeat_formula()
828
+ # methods as described later in this section.
829
+ #
830
+ # ===Introduction
831
+ #
832
+ # The following is a brief introduction to formulas and functions in Excel
833
+ # and WriteExcel.
834
+ #
835
+ # A formula is a string that begins with an equals sign:
836
+ #
837
+ # '=A1+B1'
838
+ # '=AVERAGE(1, 2, 3)'
839
+ #
840
+ # The formula can contain numbers, strings, boolean values, cell references,
841
+ # cell ranges and functions. Named ranges are not supported. Formulas should
842
+ # be written as they appear in Excel, that is cells and functions must be
843
+ # in uppercase.
844
+ #
845
+ # Cells in Excel are referenced using the A1 notation system where the
846
+ # column is designated by a letter and the row by a number. Columns
847
+ # range from A to IV i.e. 0 to 255, rows range from 1 to 65536.
848
+ #--
849
+ # The WriteExcel::Utility module that is included in the distro
850
+ # contains helper functions for dealing with A1 notation, for example:
851
+ #
852
+ # use Spreadsheet::WriteExcel::Utility;
853
+ #
854
+ # ($row, $col) = xl_cell_to_rowcol('C2'); # (1, 2)
855
+ # $str = xl_rowcol_to_cell(1, 2); # C2
856
+ #++
857
+ #
858
+ # The Excel $ notation in cell references is also supported. This allows you
859
+ # to specify whether a row or column is relative or absolute. This only has
860
+ # an effect if the cell is copied. The following examples show relative and
861
+ # absolute values.
862
+ #
863
+ # '=A1' # Column and row are relative
864
+ # '=$A1' # Column is absolute and row is relative
865
+ # '=A$1' # Column is relative and row is absolute
866
+ # '=$A$1' # Column and row are absolute
867
+ #
868
+ # Formulas can also refer to cells in other worksheets of the current
869
+ # workbook. For example:
870
+ #
871
+ # '=Sheet2!A1'
872
+ # '=Sheet2!A1:A5'
873
+ # '=Sheet2:Sheet3!A1'
874
+ # '=Sheet2:Sheet3!A1:A5'
875
+ # q{='Test Data'!A1}
876
+ # q{='Test Data1:Test Data2'!A1}
877
+ #
878
+ # The sheet reference and the cell reference are separated by ! the exclamation
879
+ # mark symbol. If worksheet names contain spaces, commas o parentheses then Excel
880
+ # requires that the name is enclosed in single quotes as shown in the last two
881
+ # examples above. In order to avoid using a lot of escape characters you can
882
+ # use the quote operator %q{} to protect the quotes. Only valid sheet names that
883
+ # have been added using the add_worksheet() method can be used in formulas.
884
+ # You cannot reference external workbooks.
885
+ #
886
+ # The following table lists the operators that are available in Excel's formulas.
887
+ # The majority of the operators are the same as Perl's, differences are indicated:
888
+ #
889
+ # Arithmetic operators:
890
+ # =====================
891
+ # Operator Meaning Example
892
+ # + Addition 1+2
893
+ # - Subtraction 2-1
894
+ # * Multiplication 2*3
895
+ # / Division 1/4
896
+ # ^ Exponentiation 2^3 # Equivalent to **
897
+ # - Unary minus -(1+2) # Not yet supported
898
+ # % Percent (Not modulus) 13% # Not supported, [1]
899
+ #
900
+ # Comparison operators:
901
+ # =====================
902
+ # Operator Meaning Example
903
+ # = Equal to A1 = B1 # Equivalent to ==
904
+ # <> Not equal to A1 <> B1 # Equivalent to !=
905
+ # > Greater than A1 > B1
906
+ # < Less than A1 < B1
907
+ # >= Greater than or equal to A1 >= B1
908
+ # <= Less than or equal to A1 <= B1
909
+ #
910
+ # String operator:
911
+ # ================
912
+ # Operator Meaning Example
913
+ # & Concatenation "Hello " & "World!" # [2]
914
+ #
915
+ # Reference operators:
916
+ # ====================
917
+ # Operator Meaning Example
918
+ # : Range operator A1:A4 # [3]
919
+ # , Union operator SUM(1, 2+2, B3) # [4]
920
+ #
921
+ # Notes:
922
+ # [1]: You can get a percentage with formatting and modulus with MOD().
923
+ # [2]: Equivalent to ("Hello " . "World!") in Perl.
924
+ # [3]: This range is equivalent to cells A1, A2, A3 and A4.
925
+ # [4]: The comma behaves like the list separator in Perl.
926
+ #
927
+ # The range and comma operators can have different symbols in non-English
928
+ # versions of Excel. These will be supported in a later version of WriteExcel.
929
+ # European users of Excel take note:
930
+ #
931
+ # worksheet.write('A1', '=SUM(1; 2; 3)') # Wrong!!
932
+ # worksheet.write('A1', '=SUM(1, 2, 3)') # Okay
933
+ #
934
+ # The following table lists all of the core functions supported by
935
+ # Excel 5 and WriteExcel. Any additional functions that are available through
936
+ # the "Analysis ToolPak" or other add-ins are not supported. These functions
937
+ # have all been tested to verify that they work.
938
+ #
939
+ # ABS DB INDIRECT NORMINV SLN
940
+ # ACOS DCOUNT INFO NORMSDIST SLOPE
941
+ # ACOSH DCOUNTA INT NORMSINV SMALL
942
+ # ADDRESS DDB INTERCEPT NOT SQRT
943
+ # AND DEGREES IPMT NOW STANDARDIZE
944
+ # AREAS DEVSQ IRR NPER STDEV
945
+ # ASIN DGET ISBLANK NPV STDEVP
946
+ # ASINH DMAX ISERR ODD STEYX
947
+ # ATAN DMIN ISERROR OFFSET SUBSTITUTE
948
+ # ATAN2 DOLLAR ISLOGICAL OR SUBTOTAL
949
+ # ATANH DPRODUCT ISNA PEARSON SUM
950
+ # AVEDEV DSTDEV ISNONTEXT PERCENTILE SUMIF
951
+ # AVERAGE DSTDEVP ISNUMBER PERCENTRANK SUMPRODUCT
952
+ # BETADIST DSUM ISREF PERMUT SUMSQ
953
+ # BETAINV DVAR ISTEXT PI SUMX2MY2
954
+ # BINOMDIST DVARP KURT PMT SUMX2PY2
955
+ # CALL ERROR.TYPE LARGE POISSON SUMXMY2
956
+ # CEILING EVEN LEFT POWER SYD
957
+ # CELL EXACT LEN PPMT T
958
+ # CHAR EXP LINEST PROB TAN
959
+ # CHIDIST EXPONDIST LN PRODUCT TANH
960
+ # CHIINV FACT LOG PROPER TDIST
961
+ # CHITEST FALSE LOG10 PV TEXT
962
+ # CHOOSE FDIST LOGEST QUARTILE TIME
963
+ # CLEAN FIND LOGINV RADIANS TIMEVALUE
964
+ # CODE FINV LOGNORMDIST RAND TINV
965
+ # COLUMN FISHER LOOKUP RANK TODAY
966
+ # COLUMNS FISHERINV LOWER RATE TRANSPOSE
967
+ # COMBIN FIXED MATCH REGISTER.ID TREND
968
+ # CONCATENATE FLOOR MAX REPLACE TRIM
969
+ # CONFIDENCE FORECAST MDETERM REPT TRIMMEAN
970
+ # CORREL FREQUENCY MEDIAN RIGHT TRUE
971
+ # COS FTEST MID ROMAN TRUNC
972
+ # COSH FV MIN ROUND TTEST
973
+ # COUNT GAMMADIST MINUTE ROUNDDOWN TYPE
974
+ # COUNTA GAMMAINV MINVERSE ROUNDUP UPPER
975
+ # COUNTBLANK GAMMALN MIRR ROW VALUE
976
+ # COUNTIF GEOMEAN MMULT ROWS VAR
977
+ # COVAR GROWTH MOD RSQ VARP
978
+ # CRITBINOM HARMEAN MODE SEARCH VDB
979
+ # DATE HLOOKUP MONTH SECOND VLOOKUP
980
+ # DATEVALUE HOUR N SIGN WEEKDAY
981
+ # DAVERAGE HYPGEOMDIST NA SIN WEIBULL
982
+ # DAY IF NEGBINOMDIST SINH YEAR
983
+ # DAYS360 INDEX NORMDIST SKEW ZTEST
984
+ #
985
+ #--
986
+ # You can also modify the module to support function names in the following
987
+ # languages: German, French, Spanish, Portuguese, Dutch, Finnish, Italian and
988
+ # Swedish. See the function_locale.pl program in the examples directory of the distro.
989
+ #++
990
+ #
991
+ # For a general introduction to Excel's formulas and an explanation of the
992
+ # syntax of the function refer to the Excel help files or the following:
993
+ # http://office.microsoft.com/en-us/assistance/CH062528031033.aspx.
994
+ #
995
+ # If your formula doesn't work in WriteExcel try the following:
996
+ #
997
+ # 1. Verify that the formula works in Excel (or Gnumeric or OpenOffice.org).
998
+ # 2. Ensure that it isn't on the Caveats list shown above.
999
+ # 3. Ensure that cell references and formula names are in uppercase.
1000
+ # 4. Ensure that you are using ':' as the range operator, A1:A4.
1001
+ # 5. Ensure that you are using ',' as the union operator, SUM(1,2,3).
1002
+ # 6. Ensure that the function is in the above table.
1003
+ #
1004
+ # If you go through steps 1-6 and you still have a problem, mail me.
1005
+ #
1006
+ # ===Improving performance when working with formulas
1007
+ #
1008
+ # Writing a large number of formulas with WriteExcel can be slow.
1009
+ # This is due to the fact that each formula has to be parsed and with the
1010
+ # current implementation this is computationally expensive.
1011
+ #
1012
+ # However, in a lot of cases the formulas that you write will be quite
1013
+ # similar, for example:
1014
+ #
1015
+ # worksheet.write_formula('B1', '=A1 * 3 + 50', format)
1016
+ # worksheet.write_formula('B2', '=A2 * 3 + 50', format)
1017
+ # ...
1018
+ # ...
1019
+ # worksheet.write_formula('B99', '=A999 * 3 + 50', format)
1020
+ # worksheet.write_formula('B1000', '=A1000 * 3 + 50', format)
1021
+ #
1022
+ # In this example the cell reference changes in iterations from A1 to A1000.
1023
+ # The parser treats this variable as a token and arranges it according to
1024
+ # predefined rules. However, since the parser is oblivious to the value of
1025
+ # the token, it is essentially performing the same calculation 1000 times.
1026
+ # This is inefficient.
1027
+ #
1028
+ # The way to avoid this inefficiency and thereby speed up the writing of
1029
+ # formulas is to parse the formula once and then repeatedly substitute
1030
+ # similar tokens.
1031
+ #
1032
+ # A formula can be parsed and stored via the store_formula() worksheet method.
1033
+ # You can then use the repeat_formula() method to substitute _pattern_,
1034
+ # _replace_ pairs in the stored formula:
1035
+ #
1036
+ # formula = worksheet.store_formula('=A1 * 3 + 50')
1037
+ #
1038
+ # (0...1000).each do |row|
1039
+ # worksheet.repeat_formula(row, 1, formula, format, 'A1', 'A' + (row +1).to_s)
1040
+ # end
1041
+ #
1042
+ # On an arbitrary test machine this method was 10 times faster than the
1043
+ # brute force method shown above.
1044
+ #
1045
+ # It should be noted however that the overall speed of direct formula parsing
1046
+ # will be improved in a future version.
1047
+ #
1048
+ # ==Chart
1049
+ #
1050
+ # ===Synopsis(Chart)
1051
+ #
1052
+ # To create a simple Excel file with a chart using WriteExcel:
1053
+ #
1054
+ # #!/usr/bin/ruby -w
1055
+ #
1056
+ # require 'writeexcel'
1057
+ #
1058
+ # workbook = WriteExcel.new('chart.xls')
1059
+ # worksheet = workbook.add_worksheet
1060
+ #
1061
+ # chart = workbook.add_chart(:type => 'Chart::Column')
1062
+ #
1063
+ # # Configure the chart.
1064
+ # chart.add_series(
1065
+ # :categories => '=Sheet1!$A$2:$A$7',
1066
+ # :values => '=Sheet1!$B$2:$B$7'
1067
+ # )
1068
+ #
1069
+ # # Add the data to the worksheet the chart refers to.
1070
+ # data = [
1071
+ # [ 'Category', 2, 3, 4, 5, 6, 7 ],
1072
+ # [ 'Value', 1, 4, 5, 2, 1, 5 ]
1073
+ # ]
1074
+ #
1075
+ # worksheet.write('A1', data)
1076
+ #
1077
+ # workbook.close
1078
+ #
1079
+ # ===DESCRIPTION(Chart)
1080
+ #
1081
+ # The Chart module is an abstract base class for modules that implement charts
1082
+ # in WriteExcel. The information below is applicable to all of the available
1083
+ # subclasses.
1084
+ #
1085
+ # The Chart module isn't used directly, a chart object is created via the
1086
+ # Workbook add_chart() method where the chart type is specified:
1087
+ #
1088
+ # chart = workbook.add_chart(:type => 'Chart::Column')
1089
+ #
1090
+ # Currently the supported chart types are:
1091
+ #
1092
+ # * 'Chart::Column': Creates a column style (histogram) chart. See Column.
1093
+ # * 'Chart::Bar': Creates a Bar style (transposed histogram) chart. See Bar.
1094
+ # * 'Chart::Line': Creates a Line style chart. See Line.
1095
+ # * 'Chart::Area': Creates an Area (filled line) style chart. See Area.
1096
+ # * 'Chart::Scatter': Creates an Scatter style chart. See Scatter.
1097
+ # * 'Chart::Stock': Creates an Stock style chart. See Stock.
1098
+ #
1099
+ # More chart types will be supported in time. See the "TODO" section.
1100
+ #
1101
+ # === Chart names and links
1102
+ #
1103
+ # The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
1104
+ # support a name property. In general these names can be either a static
1105
+ # string or a link to a worksheet cell. If you choose to use the name_formula
1106
+ # property to specify a link then you should also the name property.
1107
+ # This isn't strictly required by Excel but some third party applications
1108
+ # expect it to be present.
1109
+ #
1110
+ # chartl.set_title(
1111
+ # :name => 'Year End Results',
1112
+ # :name_formula => '=Sheet1!$C$1'
1113
+ # )
1114
+ #
1115
+ # These links should be used sparingly since they aren't commonly
1116
+ # used in Excel charts.
1117
+ #
1118
+ # === Chart names and Unicode
1119
+ #
1120
+ # The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
1121
+ # support a name property. These names can be UTF8 strings.
1122
+ #
1123
+ # This methodology is explained in the "UNICODE IN EXCEL" section of WriteExcel
1124
+ # but is semi-deprecated. If you are using Unicode the easiest option is to
1125
+ # just use UTF8.
1126
+ #
1127
+ # === TODO(Chart)
1128
+ #
1129
+ # Charts in WriteExcel are a work in progress. More chart types and
1130
+ # features will be added in time. Please be patient. Even a small feature
1131
+ # can take a week or more to implement, test and document.
1132
+ #
1133
+ # Features that are on the TODO list and will be added are:
1134
+ #
1135
+ # * Additional chart types. Stock, Pie and Scatter charts are next in line.
1136
+ # Send an email if you are interested in other types and they will be
1137
+ # added to the queue.
1138
+ # * Colours and formatting options. For now you will have to make do
1139
+ # with the default Excel colours and formats.
1140
+ # * Axis controls, gridlines.
1141
+ # * Embedded data in charts for third party application support.
1142
+ #
1143
+ # == KNOWN ISSUES(Chart)
1144
+ #
1145
+ # * Currently charts don't contain embedded data from which the charts
1146
+ # can be rendered. Excel and most other third party applications ignore
1147
+ # this and read the data via the links that have been specified. However,
1148
+ # some applications may complain or not render charts correctly. The
1149
+ # preview option in Mac OS X is an known example. This will be fixed
1150
+ # in a later release.
1151
+ # * When there are several charts with titles set in a workbook some of
1152
+ # the titles may display at a font size of 10 instead of the default
1153
+ # 12 until another chart with the title set is viewed.
1154
+ #
1155
+ class WriteExcel < Workbook
1156
+ if RUBY_VERSION < '1.9'
1157
+ $KCODE = 'u'
1158
+ end
1159
+ end