write_xlsx 1.09.5 → 1.10.1

data/examples/dynamic_arrays.rb

@@ -0,0 +1,247 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+
+#######################################################################
+#
+# An example of how to use the write_xlsx rubygem to write functions
+# that create dynamic arrays. These functions are new to Excel 365. The
+# examples mirror the examples in the Excel documentation on these functions.
+#
+# Copyright 2000-2021, John McNamara, jmcnamara@cpan.org
+# convert to ruby by Hideo NAKAMURA, nakamura.hideo@gmail.com
+#
+
+require 'write_xlsx'
+
+# Used from test_dynamic_arrays
+# Utility function to write the data some of the functions work on.
+def write_worksheet_data(worksheet, header)
+  worksheet.write('A1', 'Region',    header)
+  worksheet.write('B1', 'Sales Rep', header)
+  worksheet.write('C1', 'Product',   header)
+  worksheet.write('D1', 'Units',     header)
+
+  data = [
+    ['East',  'Tom',    'Apple',  6380],
+    ['West',  'Fred',   'Grape',  5619],
+    ['North', 'Amy',    'Pear',   4565],
+    ['South', 'Sal',    'Banana', 5323],
+    ['East',  'Fritz',  'Apple',  4394],
+    ['West',  'Sravan', 'Grape',  7195],
+    ['North', 'Xi',     'Pear',   5231],
+    ['South', 'Hector', 'Banana', 2427],
+    ['East',  'Tom',    'Banana', 4213],
+    ['West',  'Fred',   'Pear',   3239],
+    ['North', 'Amy',    'Grape',  6520],
+    ['South', 'Sal',    'Apple',  1310],
+    ['East',  'Fritz',  'Banana', 6274],
+    ['West',  'Sravan', 'Pear',   4894],
+    ['North', 'Xi',     'Grape',  7580],
+    ['South', 'Hector', 'Apple',  9814]
+  ]
+
+  row_num = 1
+  data.each do |row_data|
+    worksheet.write_row(row_num, 0, row_data)
+    row_num += 1
+  end
+end
+
+# Create a new workbook called simple.xls and add a worksheet
+workbook    = WriteXLSX.new('dynamic_arrays.xlsx')
+worksheet1  = workbook.add_worksheet('Filter')
+worksheet2  = workbook.add_worksheet('Unique')
+worksheet3  = workbook.add_worksheet('Sort')
+worksheet4  = workbook.add_worksheet('Sortby')
+worksheet5  = workbook.add_worksheet('Xlookup')
+worksheet6  = workbook.add_worksheet('Xmatch')
+worksheet7  = workbook.add_worksheet('Randarray')
+worksheet8  = workbook.add_worksheet('Sequence')
+worksheet9  = workbook.add_worksheet('Spill ranges')
+worksheet10 = workbook.add_worksheet('Older functions')
+header1     = workbook.add_format(fg_color: '#74AC4C', color: '#FFFFFF')
+header2     = workbook.add_format(fg_color: '#528FD3', color: '#FFFFFF')
+
+#
+# Example of using the FILTER() function.
+#
+worksheet1.write('F2', '=FILTER(A1:D17,C1:C17=K2)')
+
+# Write the data the function will work on.
+worksheet1.write('K1', 'Product',   header2)
+worksheet1.write('K2', 'Apple')
+worksheet1.write('F1', 'Region',    header2)
+worksheet1.write('G1', 'Sales Rep', header2)
+worksheet1.write('H1', 'Product',   header2)
+worksheet1.write('I1', 'Units',     header2)
+
+write_worksheet_data(worksheet1, header1)
+worksheet1.set_column_pixels('E:E', 20)
+worksheet1.set_column_pixels('J:J', 20)
+
+#
+# Example of using the UNIQUE() function.
+#
+worksheet2.write('F2', '=UNIQUE(B2:B17)')
+
+# A more complex example combining SORT and UNIQUE.
+worksheet2.write('H2', '=SORT(UNIQUE(B2:B17))')
+
+# Write the data the function will work on.
+worksheet2.write('F1', 'Sales Rep', header2)
+worksheet2.write('H1', 'Sales Rep', header2)
+
+write_worksheet_data(worksheet2, header1)
+worksheet2.set_column_pixels('E:E', 20)
+worksheet2.set_column_pixels('G:G', 20)
+
+#
+# Example of using the SORT() function.
+#
+worksheet3.write('F2', '=SORT(B2:B17)')
+
+# A more complex example combining SORT and FILTER.
+worksheet3.write('H2', '=SORT(FILTER(C2:D17,D2:D17>5000,""),2,1)')
+
+# Write the data the function will work on.
+worksheet3.write('F1', 'Sales Rep', header2)
+worksheet3.write('H1', 'Product',   header2)
+worksheet3.write('I1', 'Units',     header2)
+
+write_worksheet_data(worksheet3, header1)
+worksheet3.set_column_pixels('E:E', 20)
+worksheet3.set_column_pixels('G:G', 20)
+
+#
+# Example of using the SORTBY() function.
+#
+worksheet4.write('D2', '=SORTBY(A2:B9,B2:B9)')
+
+# Write the data the function will work on.
+worksheet4.write('A1', 'Name', header1)
+worksheet4.write('B1', 'Age',  header1)
+
+worksheet4.write('A2', 'Tom')
+worksheet4.write('A3', 'Fred')
+worksheet4.write('A4', 'Amy')
+worksheet4.write('A5', 'Sal')
+worksheet4.write('A6', 'Fritz')
+worksheet4.write('A7', 'Srivan')
+worksheet4.write('A8', 'Xi')
+worksheet4.write('A9', 'Hector')
+
+worksheet4.write('B2', 52)
+worksheet4.write('B3', 65)
+worksheet4.write('B4', 22)
+worksheet4.write('B5', 73)
+worksheet4.write('B6', 19)
+worksheet4.write('B7', 39)
+worksheet4.write('B8', 19)
+worksheet4.write('B9', 66)
+
+worksheet4.write('D1', 'Name', header2)
+worksheet4.write('E1', 'Age',  header2)
+
+worksheet4.set_column_pixels('C:C', 20)
+
+#
+# Example of using the XLOOKUP() function.
+#
+worksheet5.write('F1', '=XLOOKUP(E1,A2:A9,C2:C9)')
+
+# Write the data the function will work on.
+worksheet5.write('A1', 'Country', header1)
+worksheet5.write('B1', 'Abr',     header1)
+worksheet5.write('C1', 'Prefix',  header1)
+
+worksheet5.write('A2', 'China')
+worksheet5.write('A3', 'India')
+worksheet5.write('A4', 'United States')
+worksheet5.write('A5', 'Indonesia')
+worksheet5.write('A6', 'Brazil')
+worksheet5.write('A7', 'Pakistan')
+worksheet5.write('A8', 'Nigeria')
+worksheet5.write('A9', 'Bangladesh')
+
+worksheet5.write('B2', 'CN')
+worksheet5.write('B3', 'IN')
+worksheet5.write('B4', 'US')
+worksheet5.write('B5', 'ID')
+worksheet5.write('B6', 'BR')
+worksheet5.write('B7', 'PK')
+worksheet5.write('B8', 'NG')
+worksheet5.write('B9', 'BD')
+
+worksheet5.write('C2', 86)
+worksheet5.write('C3', 91)
+worksheet5.write('C4', 1)
+worksheet5.write('C5', 62)
+worksheet5.write('C6', 55)
+worksheet5.write('C7', 92)
+worksheet5.write('C8', 234)
+worksheet5.write('C9', 880)
+
+worksheet5.write('E1', 'Brazil', header2)
+
+worksheet5.set_column_pixels('A:A', 100)
+worksheet5.set_column_pixels('D:D', 20)
+
+#
+# Example of using the XMATCH() function.
+#
+worksheet6.write('D2', '=XMATCH(C2,A2:A6)')
+
+# Write the data the function will work on.
+worksheet6.write('A1', 'Product', header1)
+
+worksheet6.write('A2', 'Apple')
+worksheet6.write('A3', 'Grape')
+worksheet6.write('A4', 'Pear')
+worksheet6.write('A5', 'Banana')
+worksheet6.write('A6', 'Cherry')
+
+worksheet6.write('C1', 'Product', header2)
+worksheet6.write('D1', 'Position', header2)
+worksheet6.write('C2', 'Grape')
+
+worksheet6.set_column_pixels('B:B', 20)
+
+#
+# Example of using the RANDARRAY() function.
+#
+worksheet7.write('A1', '=RANDARRAY(5,3,1,100, TRUE)')
+
+#
+# Example of using the SEQUENCE() function.
+#
+worksheet8.write('A1', '=SEQUENCE(4,5)')
+
+#
+# Example of using the Spill range operator.
+#
+worksheet9.write('H2', '=ANCHORARRAY(F2)')
+
+worksheet9.write('J2', '=COUNTA(ANCHORARRAY(F2))')
+
+# Write the data the to work on.
+worksheet9.write('F2', '=UNIQUE(B2:B17)')
+worksheet9.write('F1', 'Unique', header2)
+worksheet9.write('H1', 'Spill', header2)
+worksheet9.write('J1', 'Spill', header2)
+
+write_worksheet_data(worksheet9, header1)
+worksheet9.set_column_pixels('E:E', 20)
+worksheet9.set_column_pixels('G:G', 20)
+worksheet9.set_column_pixels('I:I', 20)
+#
+# Example of using dynamic ranges with older Excel functions.
+#
+worksheet10.write_dynamic_array_formula('B1:B3', '=LEN(A1:A3)')
+
+# Write the data the to work on.
+worksheet10.write('A1', 'Foo')
+worksheet10.write('A2', 'Food')
+worksheet10.write('A3', 'Frood')
+
+# Close the workbook.
+workbook.close

data/examples/formats.rb

@@ -18,8 +18,8 @@ require 'write_xlsx'
 workbook = WriteXLSX.new('formats.xlsx')
 
 # Some common formats
-center = workbook.add_format(:align => 'center')
-heading = workbook.add_format(:align => 'center', :bold => 1)
+center = workbook.add_format(align: 'center')
+heading = workbook.add_format(align: 'center', bold: 1)
 
 # The named colors
 colors = {
@@ -61,8 +61,8 @@ def intro(workbook, _center, _heading, _colors)
   format2.set_color('blue')
 
   format3 = workbook.add_format(
-    :color     => 'blue',
-    :underline => 1
+    color:     'blue',
+    underline: 1
   )
 
   worksheet.write(2, 0, 'This workbook demonstrates some of', format)
@@ -113,9 +113,9 @@ def named_colors(workbook, center, heading, colors)
   [33, 11, 53, 17, 22, 18, 13, 16, 23, 9, 12, 15, 14, 20, 8, 10].each do |index|
     color = colors[index]
     format = workbook.add_format(
-      :bg_color => color,
-      :pattern  => 1,
-      :border   => 1
+      bg_color: color,
+      pattern:  1,
+      border:   1
     )
 
     worksheet.write(i + 1, 0, index, center)
@@ -142,9 +142,9 @@ def standard_colors(workbook, center, heading, colors)
 
   (8..63).each do |i|
     format = workbook.add_format(
-      :bg_color => i,
-      :pattern  => 1,
-      :border   => 1
+      bg_color: i,
+      pattern:  1,
+      border:   1
     )
 
     worksheet.write((i - 7), 0, i, center)

data/examples/hyperlink1.rb

@@ -24,10 +24,10 @@ worksheet.set_selection('B1')
 
 # Add a sample format.
 red_format = workbook.add_format(
-  :color     => 'red',
-  :bold      => 1,
-  :underline => 1,
-  :size      => 12
+  color:     'red',
+  bold:      1,
+  underline: 1,
+  size:      12
 )
 
 # Add an alternate description string to the URL.

data/examples/ignore_errors.rb

@@ -25,8 +25,8 @@ worksheet.write_formula('C6', '=1/0')
 
 # Turn off some of the warnings:
 worksheet.ignore_errors(
-  :number_stored_as_text => 'C3',
-  :eval_error            => 'C6'
+  number_stored_as_text: 'C3',
+  eval_error:            'C6'
 )
 
 # Write some descriptions for the cells and make the column wider for clarity.

data/examples/indent.rb

@@ -16,8 +16,8 @@ require 'write_xlsx'
 workbook = WriteXLSX.new('indent.xlsx')
 
 worksheet = workbook.add_worksheet
-indent1   = workbook.add_format(:indent => 1)
-indent2   = workbook.add_format(:indent => 2)
+indent1   = workbook.add_format(indent: 1)
+indent2   = workbook.add_format(indent: 2)
 
 worksheet.set_column('A:A', 40)
 

data/examples/lambda.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# -*- coding: utf-8 -*-
+
+#######################################################################
+#
+# An example of using the new Excel LAMBDA() function with the
+# WriteXLSX rubygem. Note, this function is only currently available
+# if you are subscribed to the Microsoft Office Beta program.
+#
+# Copyright 2000-2021, John McNamara, jmcnamara@cpan.org
+# convert to ruby by Hideo NAKAMURA, nakamura.hideo@gmail.com
+#
+
+require 'write_xlsx'
+
+workbook = WriteXLSX.new('lambda.xlsx')
+worksheet = workbook.add_worksheet
+
+worksheet.write(
+  'A1',
+  'Note: Lambda functions currently only work with the Beta Channel versions of Excel 365'
+)
+
+# Write a Lambda function to convert Fahrenheit to Celsius to a cell.
+#
+# Note that the lambda function parameters must be prefixed with
+# "_xlpm.". These prefixes won't show up in Excel.
+worksheet.write('A2', '=LAMBDA(_xlpm.temp, (5/9) * (_xlpm.temp-32))(32)')
+
+# Create the same formula (without an argument) as a defined name and use that
+# to calculate a value.
+#
+# Note that the formula name is prefixed with "_xlfn." (this is normally
+# converted automatically by write_formula but isn't for defined names)
+# and note that the lambda function parameters are prefixed with
+# "_xlpm.". These prefixes won't show up in Excel.
+workbook.define_name(
+  'ToCelsius',
+  '=_xlfn.LAMBDA(_xlpm.temp, (5/9) * (_xlpm.temp-32))'
+)
+worksheet.write_dynamic_array_formula('A3', '=ToCelsius(212)')
+
+workbook.close

data/examples/macros.rb

@@ -32,10 +32,10 @@ worksheet.write('A3', 'Press the button to say hello.')
 # Add a button tied to a macro in the VBA project.
 worksheet.insert_button(
   'B3',
-  :macro   => 'say_hello',
-  :caption => 'Press Me',
-  :width   => 80,
-  :height  => 30
+  macro:   'say_hello',
+  caption: 'Press Me',
+  width:   80,
+  height:  30
 )
 
 workbook.close

data/examples/merge1.rb

@@ -24,7 +24,7 @@ worksheet.set_column('B:D', 20)
 worksheet.set_row(2, 30)
 
 # Create a merge format
-format = workbook.add_format(:center_across => 1)
+format = workbook.add_format(center_across: 1)
 
 # Only one cell should contain text, the others should be blank.
 worksheet.write(2, 1, "Center across selection", format)

data/examples/merge2.rb

@@ -26,15 +26,15 @@ worksheet.set_row(2, 40)
 
 # Create a merged format
 format = workbook.add_format(
-  :center_across => 1,
-  :bold          => 1,
-  :size          => 15,
-  :pattern       => 1,
-  :border        => 6,
-  :color         => 'white',
-  :fg_color      => 'green',
-  :border_color  => 'yellow',
-  :align         => 'vcenter'
+  center_across: 1,
+  bold:          1,
+  size:          15,
+  pattern:       1,
+  border:        6,
+  color:         'white',
+  fg_color:      'green',
+  border_color:  'yellow',
+  align:         'vcenter'
 )
 
 # Only one cell should contain text, the others should be blank.

data/examples/merge3.rb

@@ -25,11 +25,11 @@ worksheet.set_column('B:D', 20)
 # Example: Merge cells containing a hyperlink using merge_range().
 #
 format = workbook.add_format(
-  :border    => 1,
-  :underline => 1,
-  :color     => 'blue',
-  :align     => 'center',
-  :valign    => 'vcenter'
+  border:    1,
+  underline: 1,
+  color:     'blue',
+  align:     'center',
+  valign:    'vcenter'
 )
 
 # Merge 3 cells

data/examples/merge4.rb

@@ -25,11 +25,11 @@ worksheet.set_column('B:D', 20)
 # Example 1: Text centered vertically and horizontally
 #
 format1 = workbook.add_format(
-  :border => 6,
-  :bold   => 1,
-  :color  => 'red',
-  :valign => 'vcenter',
-  :align  => 'center'
+  border: 6,
+  bold:   1,
+  color:  'red',
+  valign: 'vcenter',
+  align:  'center'
 )
 
 worksheet.merge_range('B2:D3', 'Vertical and horizontal', format1)
@@ -39,11 +39,11 @@ worksheet.merge_range('B2:D3', 'Vertical and horizontal', format1)
 # Example 2: Text aligned to the top and left
 #
 format2 = workbook.add_format(
-  :border => 6,
-  :bold   => 1,
-  :color  => 'red',
-  :valign => 'top',
-  :align  => 'left'
+  border: 6,
+  bold:   1,
+  color:  'red',
+  valign: 'top',
+  align:  'left'
 )
 
 worksheet.merge_range('B5:D6', 'Aligned to the top and left', format2)
@@ -53,11 +53,11 @@ worksheet.merge_range('B5:D6', 'Aligned to the top and left', format2)
 # Example 3:  Text aligned to the bottom and right
 #
 format3 = workbook.add_format(
-  :border => 6,
-  :bold   => 1,
-  :color  => 'red',
-  :valign => 'bottom',
-  :align  => 'right'
+  border: 6,
+  bold:   1,
+  color:  'red',
+  valign: 'bottom',
+  align:  'right'
 )
 
 worksheet.merge_range('B8:D9', 'Aligned to the bottom and right', format3)
@@ -67,11 +67,11 @@ worksheet.merge_range('B8:D9', 'Aligned to the bottom and right', format3)
 # Example 4:  Text justified (i.e. wrapped) in the cell
 #
 format4 = workbook.add_format(
-  :border => 6,
-  :bold   => 1,
-  :color  => 'red',
-  :valign => 'top',
-  :align  => 'justify'
+  border: 6,
+  bold:   1,
+  color:  'red',
+  valign: 'top',
+  align:  'justify'
 )
 
 worksheet.merge_range('B11:D12', 'Justified: ' << ('so on and ' * 18), format4)

data/examples/merge5.rb

@@ -26,12 +26,12 @@ worksheet = workbook.add_worksheet
 # Rotation 1, letters run from top to bottom
 #
 format1 = workbook.add_format(
-  :border   => 6,
-  :bold     => 1,
-  :color    => 'red',
-  :valign   => 'vcentre',
-  :align    => 'centre',
-  :rotation => 270
+  border:   6,
+  bold:     1,
+  color:    'red',
+  valign:   'vcentre',
+  align:    'centre',
+  rotation: 270
 )
 
 worksheet.merge_range('B4:B9', 'Rotation 270', format1)
@@ -41,12 +41,12 @@ worksheet.merge_range('B4:B9', 'Rotation 270', format1)
 # Rotation 2, 90ｰ anticlockwise
 #
 format2 = workbook.add_format(
-  :border   => 6,
-  :bold     => 1,
-  :color    => 'red',
-  :valign   => 'vcentre',
-  :align    => 'centre',
-  :rotation => 90
+  border:   6,
+  bold:     1,
+  color:    'red',
+  valign:   'vcentre',
+  align:    'centre',
+  rotation: 90
 )
 
 worksheet.merge_range('D4:D9', 'Rotation 90', format2)
@@ -56,12 +56,12 @@ worksheet.merge_range('D4:D9', 'Rotation 90', format2)
 # Rotation 3, 90ｰ clockwise
 #
 format3 = workbook.add_format(
-  :border   => 6,
-  :bold     => 1,
-  :color    => 'red',
-  :valign   => 'vcentre',
-  :align    => 'centre',
-  :rotation => -90
+  border:   6,
+  bold:     1,
+  color:    'red',
+  valign:   'vcentre',
+  align:    'centre',
+  rotation: -90
 )
 
 worksheet.merge_range('F4:F9', 'Rotation -90', format3)

data/examples/merge6.rb

@@ -22,13 +22,13 @@ worksheet.set_column('B:D', 25)
 
 # Format for the merged cells.
 format = workbook.add_format(
-  :border => 6,
-  :bold   => 1,
-  :color  => 'red',
-  :size   => 20,
-  :valign => 'vcentre',
-  :align  => 'left',
-  :indent => 1
+  border: 6,
+  bold:   1,
+  color:  'red',
+  size:   20,
+  valign: 'vcentre',
+  align:  'left',
+  indent: 1
 )
 
 ###############################################################################

data/examples/outline.rb

@@ -74,7 +74,7 @@ worksheet3 = workbook.add_worksheet('Outline Columns')
 worksheet4 = workbook.add_worksheet('Outline levels')
 
 # Add a general format
-bold = workbook.add_format(:bold => 1)
+bold = workbook.add_format(bold: 1)
 
 ###############################################################################
 #

data/examples/outline_collapsed.rb

@@ -24,7 +24,7 @@ worksheet5 = workbook.add_worksheet('Outline Columns')
 worksheet6 = workbook.add_worksheet('Collapsed Columns')
 
 # Add a general format
-bold = workbook.add_format(:bold => 1)
+bold = workbook.add_format(bold: 1)
 
 ###############################################################################
 #

data/examples/panes.rb

@@ -37,12 +37,12 @@ worksheet4.split_panes(15, 8.43)    # 1 row and column
 #
 
 header = workbook.add_format(
-  :align    => 'center',
-  :valign   => 'vcenter',
-  :fg_color => '#C3FFC0'
+  align:    'center',
+  valign:   'vcenter',
+  fg_color: '#C3FFC0'
 )
 
-center = workbook.add_format(:align => 'center')
+center = workbook.add_format(align: 'center')
 
 #######################################################################
 #

data/examples/properties.rb

@@ -15,15 +15,15 @@ workbook  = WriteXLSX.new('properties.xlsx')
 worksheet = workbook.add_worksheet
 
 workbook.set_properties(
-  :title    => 'This is an example spreadsheet',
-  :subject  => 'With document properties',
-  :author   => 'John McNamara',
-  :manager  => 'Dr. Heinz Doofenshmirtz',
-  :company  => 'of Wolves',
-  :category => 'Example spreadsheets',
-  :keywords => 'Sample, Example, Properties',
-  :comments => 'Created with Perl and Excel::Writer::XLSX',
-  :status   => 'Quo'
+  title:    'This is an example spreadsheet',
+  subject:  'With document properties',
+  author:   'John McNamara',
+  manager:  'Dr. Heinz Doofenshmirtz',
+  company:  'of Wolves',
+  category: 'Example spreadsheets',
+  keywords: 'Sample, Example, Properties',
+  comments: 'Created with Perl and Excel::Writer::XLSX',
+  status:   'Quo'
 )
 
 worksheet.set_column('A:A', 70)

data/examples/protection.rb

@@ -7,8 +7,8 @@ workbook  = WriteXLSX.new('protection.xlsx')
 worksheet = workbook.add_worksheet
 
 # Create some format objects
-unlocked = workbook.add_format(:locked => 0)
-hidden   = workbook.add_format(:hidden => 1)
+unlocked = workbook.add_format(locked: 0)
+hidden   = workbook.add_format(hidden: 1)
 
 # Format the columns
 worksheet.set_column('A:A', 45)