Class: XlsxWriter::Workbook

Inherits:
Object
  • Object
show all
Defined in:
ext/xlsxwriter/workbook.c,
ext/xlsxwriter/chart.c,
ext/xlsxwriter/workbook.c

Overview

Workbook is the main class exposed by XlsxWriter. It represents the workbook (.xlsx) file.

Defined Under Namespace

Classes: Chart, Properties

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Object

:nodoc:



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'ext/xlsxwriter/workbook.c', line 58

VALUE
workbook_init(int argc, VALUE *argv, VALUE self) {
  struct workbook *ptr;
  lxw_workbook_options options = {
    .constant_memory = 0,
    .tmpdir = NULL
  };

  if (argc < 1 || argc > 2) {
    rb_raise(rb_eArgError, "wrong number of arguments");
    return self;
  } else if (argc == 2) {
    VALUE const_mem = rb_hash_aref(argv[1], ID2SYM(rb_intern("constant_memory")));
    if (!NIL_P(const_mem) && const_mem) {
      options.constant_memory = 1;
      VALUE tmpdir = rb_hash_aref(argv[1], ID2SYM(rb_intern("tmpdir")));
      if (!NIL_P(tmpdir))
        options.tmpdir = RSTRING_PTR(tmpdir);
    }
  }

  Data_Get_Struct(self, struct workbook, ptr);

  size_t len = RSTRING_LEN(argv[0]);
  ptr->path = malloc(len + 1);
  strncpy(ptr->path, RSTRING_PTR(argv[0]), len + 1);
  if (options.constant_memory) {
    ptr->workbook = workbook_new_opt(ptr->path, &options);
  } else {
    ptr->workbook = workbook_new(ptr->path);
  }
  ptr->properties = NULL;
  rb_iv_set(self, "@font_sizes", rb_hash_new());

  return self;
}

Instance Attribute Details

#font_sizes ⇒ Object (readonly)

This attribute contains effective font widths used for automatic column widths of workbook columns.

Class Method Details

.XlsxWriter::Workbook.new(path, constant_memory: false, tmpdir: nil) ⇒ Object .XlsxWriter::Workbook.new(path, constant_memory: false, tmpdir: nil) {|wb| ... } ⇒ nil .XlsxWriter::Workbook.open(path, constant_memory: false, tmpdir: nil) {|wb| ... } ⇒ nil

Creates a new Xlsx workbook in file path and returns a new Workbook object.

If constant_memory is set to true workbook data is stored in temporary files in tmpdir, considerably reducing memory consumption for large documents.

XlsxWriter::Workbook.open('/tmp/test.xlsx', constant_memory: true) do |wb|
  # ... populate the workbook with data ...
end

Overloads:

  • .XlsxWriter::Workbook.new(path, constant_memory: false, tmpdir: nil) {|wb| ... } ⇒ nil

    Yields:

    • (wb)

    Returns:

    • (nil)
  • .XlsxWriter::Workbook.open(path, constant_memory: false, tmpdir: nil) {|wb| ... } ⇒ nil

    Yields:

    • (wb)

    Returns:

    • (nil) 


46
47
48
49
50
51
52
53
54
55
 
# File 'ext/xlsxwriter/workbook.c', line 46

VALUE
workbook_new_(int argc, VALUE *argv, VALUE self) {
  VALUE workbook = rb_call_super(argc, argv);
  if (rb_block_given_p()) {
    rb_yield(workbook);
    workbook_release(workbook);
    return Qnil;
  }
  return workbook;
}

Instance Method Details

#add_chart(type) {|chart| ... } ⇒ Object #add_chert(type) ⇒ Object

Adds a chart of type type to the workbook.

type is expected to be one of XlsxWriter::Workbook::Chart::{NONE, AREA, AREA_STACKED, AREA_STACKED_PERCENT, BAR, BAR_STACKED, BAR_STACKED_PERCENT, COLUMN, COLUMN_STACKED, COLUMN_STACKED_PERCENT, DOUGHNUT, LINE, PIE, SCATTER, SCATTER_STRAIGHT, SCATTER_STRAIGHT_WOTH_MARKERS, SCATTER_SMOOTH, SCATTER_SMOOTH_WITH_MARKERS, RADAR, RADAR_WITH_MARKERS, RADAR_FILLED}.

wb.add_chart(XlsxWriter::Workbook::Chart::PIE) do |chart|
  chart.add_series 'A1:A10', 'B1:B10'
  ws.insert_chart('D2', chart)
end

Overloads:

  • #add_chart(type) {|chart| ... } ⇒ Object

    Yields:

    • (chart)

    Returns:

    • (Object) 


266
267
268
269
270
271
272
273
274
 
# File 'ext/xlsxwriter/workbook.c', line 266

VALUE
workbook_add_chart_(VALUE self, VALUE type) {
  VALUE chart = rb_funcall(cChart, rb_intern("new"), 2, self, type);
  if (rb_block_given_p()) {
    VALUE res = rb_yield(chart);
    return res;
  }
  return chart;
}

#add_format(key, definition) ⇒ Object

Adds a format identified as key with parameters set from definition to the workbook.

definition should be an object and may contain the following options:

:font_name

Font family to be used to display the cell content (like Arial, Dejavu or Helvetica).

:font_size

Font size.

:font_color

Text color.

:bold, :italic, underline

Bold, italic, underlined text.

:font_strikeout

Striked out text.

:font_script

Superscript (XlsxWrtiter::Format::FONT_SUPERSCRIPT) or subscript (XlsxWriter::Format::FONT_SUBSCRIPT).

:num_format

Defines numerical format with mask, like 'd mmm yyyy' or '#,##0.00'.

:num_format_index

Defines numerical format from special pre-defined set.

:unlocked

Allows modifications of protected cells.

:hidden
:align, :vertical_align
:text_wrap
:rotation
:indent
:shrink
:pattern
:bg_color
:fg_color
:border
:bottom, :top, :left, :right
:border_color, :bottom_color, :top_color, :left_color, :right_color


222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'ext/xlsxwriter/workbook.c', line 222

VALUE
workbook_add_format_(VALUE self, VALUE key, VALUE opts) {
  struct workbook *ptr;
  lxw_format *format;
  Data_Get_Struct(self, struct workbook, ptr);

  if (!ptr->formats) {
    ptr->formats = st_init_numtable();
  }

  format = workbook_add_format(ptr->workbook);
  st_insert(ptr->formats, rb_to_id(key), (st_data_t)format);
  format_apply_opts(format, opts);

  VALUE font_size = rb_hash_aref(opts, ID2SYM(rb_intern("font_size")));
  if (!NIL_P(font_size)) {
    VALUE bold = rb_hash_aref(opts, ID2SYM(rb_intern("bold")));
    if (!NIL_P(bold) && bold) {
      rb_hash_aset(rb_iv_get(self, "@font_sizes"), key, rb_float_new(NUM2DBL(font_size) * 1.5));
    } else {
      rb_hash_aset(rb_iv_get(self, "@font_sizes"), key, font_size);
    }
  }

  return self;
}

#add_worksheet([name]) ⇒ Object #add_worksheet([name]) {|ws| ... } ⇒ Object

Adds a worksheet named name to the workbook.

If a block is passed, the last statement is returned.

wb.add_worksheet('Sheet1') do |ws|
  ws.add_row(['test'])
end

Overloads:

  • #add_worksheet([name]) {|ws| ... } ⇒ Object

    Yields:

    • (ws)

    Returns:

    • (Object) 


171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'ext/xlsxwriter/workbook.c', line 171

VALUE
workbook_add_worksheet_(int argc, VALUE *argv, VALUE self) {
  VALUE worksheet = Qnil;

  rb_check_arity(argc, 0, 1);

  struct workbook *ptr;
  Data_Get_Struct(self, struct workbook, ptr);
  if (ptr->workbook) {
    worksheet = rb_funcall(cWorksheet, rb_intern("new"), argc + 1, self, argv[0]);
  }

  if (rb_block_given_p()) {
    VALUE res = rb_yield(worksheet);
    return res;
  }

  return worksheet;
}

#close ⇒ nil

Dumps the workbook content to the file and closes the worksheet. To be used only for workbooks opened with XlsxWriter::Workbook.new without block.

No methods should be called on the worksheet after it is colsed.

wb = XlsxWriter::Workbook.new('/tmp/test.xlsx')
wb.close

Returns:

  • (nil) 


107
108
109
110
111
112
113
114
 
# File 'ext/xlsxwriter/workbook.c', line 107

VALUE
workbook_release(VALUE self) {
  struct workbook *ptr;
  Data_Get_Struct(self, struct workbook, ptr);

  workbook_free(ptr);
  return self;
}

#define_name(name, formula) ⇒ Object

Create a defined name in the workbook to use as a variable defined in formula.

wb.define_name 'Sales', '=Sheet1!$G$1:$H$10'



304
305
306
307
308
309
310
 
# File 'ext/xlsxwriter/workbook.c', line 304

VALUE
workbook_define_name_(VALUE self, VALUE name, VALUE formula) {
  struct workbook *ptr;
  Data_Get_Struct(self, struct workbook, ptr);
  workbook_define_name(ptr->workbook, StringValueCStr(name), StringValueCStr(formula));
  return self;
}

#properties ⇒ Object

Returns worbook properties accessor object.

wb.properties.title = 'My awesome sheet'



291
292
293
294
295
296
 
# File 'ext/xlsxwriter/workbook.c', line 291

VALUE
workbook_properties_(VALUE self) {
  VALUE props = rb_obj_alloc(cWorkbookProperties);
  rb_obj_call_init(props, 1, &self);
  return props;
}

#set_default_xf_indices ⇒ Object

:nodoc:



277
278
279
280
281
282
283
 
# File 'ext/xlsxwriter/workbook.c', line 277

VALUE
workbook_set_default_xf_indices_(VALUE self) {
  struct workbook *ptr;
  Data_Get_Struct(self, struct workbook, ptr);
  lxw_workbook_set_default_xf_indices(ptr->workbook);
  return self;
}

#validate_sheet_name(name) ⇒ true #validate_worksheet_name(name) ⇒ true

Validates a worksheet name. Returns true or raises an exception (not implemented yet).

Overloads:

  • #validate_sheet_name(name) ⇒ true

    Returns:

    • (true)
  • #validate_worksheet_name(name) ⇒ true

    Returns:

    • (true) 


320
321
322
323
324
325
326
327
328
 
# File 'ext/xlsxwriter/workbook.c', line 320

VALUE
workbook_validate_sheet_name_(VALUE self, VALUE name) {
  struct workbook *ptr;
  lxw_error err;
  Data_Get_Struct(self, struct workbook, ptr);
  err = workbook_validate_sheet_name(ptr->workbook, StringValueCStr(name));
  handle_lxw_error(err);
  return Qtrue;
}

#validate_sheet_name(name) ⇒ true #validate_worksheet_name(name) ⇒ true

Validates a worksheet name. Returns true or raises an exception (not implemented yet).

Overloads:

  • #validate_sheet_name(name) ⇒ true

    Returns:

    • (true)
  • #validate_worksheet_name(name) ⇒ true

    Returns:

    • (true) 


320
321
322
323
324
325
326
327
328
 
# File 'ext/xlsxwriter/workbook.c', line 320

VALUE
workbook_validate_sheet_name_(VALUE self, VALUE name) {
  struct workbook *ptr;
  lxw_error err;
  Data_Get_Struct(self, struct workbook, ptr);
  err = workbook_validate_sheet_name(ptr->workbook, StringValueCStr(name));
  handle_lxw_error(err);
  return Qtrue;
}