xlsxwriter 0.0.2 → 0.0.3

data/ext/xlsxwriter/chart.h

@@ -8,20 +8,22 @@ struct chart {
   lxw_chart *chart;
 };
 
+struct chart_axis {
+  lxw_chart_axis *axis;
+};
+
 struct chart_series {
   lxw_chart_series *series;
 };
 
-VALUE chart_alloc(VALUE klass);
-VALUE chart_init(VALUE self, VALUE worksheet, VALUE type);
-VALUE chart_series_alloc(VALUE klass);
-VALUE chart_series_init(int argc, VALUE *argv, VALUE self);
+lxw_chart_fill val_to_lxw_chart_fill(VALUE opts);
+lxw_chart_font val_to_lxw_chart_font(VALUE opts);
+lxw_chart_line val_to_lxw_chart_line(VALUE opts);
 
-VALUE chart_add_series_(int argc, VALUE *argv, VALUE self);
+void init_xlsxwriter_chart();
 
-VALUE chart_get_axis_id_1_(VALUE self);
-VALUE chart_set_axis_id_1_(VALUE self, VALUE val);
-VALUE chart_get_axis_id_2_(VALUE self);
-VALUE chart_set_axis_id_2_(VALUE self, VALUE val);
+extern VALUE cChart;
+extern VALUE cChartSeries;
+extern VALUE cChartAxis;
 
 #endif // __CHART__

data/ext/xlsxwriter/format.c

@@ -1,4 +1,7 @@
 #include "format.h"
+#include "workbook.h"
+
+VALUE mXlsxFormat;
 
 #define STR2SYM(x) ID2SYM(rb_intern(x))
 
@@ -14,7 +17,8 @@
       format_set_##fmt_name(format);                \
 }
 
-void format_apply_opts(lxw_format *format, VALUE opts) {
+void
+format_apply_opts(lxw_format *format, VALUE opts) {
   VALUE value;
 
   MAP_FORMAT(font_name, StringValueCStr(value));
@@ -65,3 +69,87 @@ void format_apply_opts(lxw_format *format, VALUE opts) {
   MAP_FORMAT(reading_order, NUM2INT(value));
   MAP_FORMAT(theme, NUM2INT(value));
 }
+
+void
+init_xlsxwriter_format() {
+  /* :nodoc: */
+  mXlsxFormat = rb_define_module_under(mXlsxWriter, "Format");
+
+#define MAP_LXW_FMT_CONST(name) rb_define_const(mXlsxFormat, #name, INT2NUM(LXW_##name))
+  MAP_LXW_FMT_CONST(COLOR_BLACK);
+  MAP_LXW_FMT_CONST(COLOR_BLUE);
+  MAP_LXW_FMT_CONST(COLOR_BROWN);
+  MAP_LXW_FMT_CONST(COLOR_CYAN);
+  MAP_LXW_FMT_CONST(COLOR_GRAY);
+  MAP_LXW_FMT_CONST(COLOR_GREEN);
+  MAP_LXW_FMT_CONST(COLOR_LIME);
+  MAP_LXW_FMT_CONST(COLOR_MAGENTA);
+  MAP_LXW_FMT_CONST(COLOR_NAVY);
+  MAP_LXW_FMT_CONST(COLOR_ORANGE);
+  MAP_LXW_FMT_CONST(COLOR_PINK);
+  MAP_LXW_FMT_CONST(COLOR_PURPLE);
+  MAP_LXW_FMT_CONST(COLOR_RED);
+  MAP_LXW_FMT_CONST(COLOR_SILVER);
+  MAP_LXW_FMT_CONST(COLOR_WHITE);
+  MAP_LXW_FMT_CONST(COLOR_YELLOW);
+
+  MAP_LXW_FMT_CONST(UNDERLINE_SINGLE);
+  MAP_LXW_FMT_CONST(UNDERLINE_DOUBLE);
+  MAP_LXW_FMT_CONST(UNDERLINE_SINGLE_ACCOUNTING);
+  MAP_LXW_FMT_CONST(UNDERLINE_DOUBLE_ACCOUNTING);
+
+  MAP_LXW_FMT_CONST(FONT_SUPERSCRIPT);
+  MAP_LXW_FMT_CONST(FONT_SUBSCRIPT);
+
+  MAP_LXW_FMT_CONST(ALIGN_LEFT);
+  MAP_LXW_FMT_CONST(ALIGN_CENTER);
+  MAP_LXW_FMT_CONST(ALIGN_RIGHT);
+  MAP_LXW_FMT_CONST(ALIGN_FILL);
+  MAP_LXW_FMT_CONST(ALIGN_JUSTIFY);
+  MAP_LXW_FMT_CONST(ALIGN_CENTER_ACROSS);
+  MAP_LXW_FMT_CONST(ALIGN_DISTRIBUTED);
+
+  MAP_LXW_FMT_CONST(ALIGN_VERTICAL_TOP);
+  MAP_LXW_FMT_CONST(ALIGN_VERTICAL_BOTTOM);
+  MAP_LXW_FMT_CONST(ALIGN_VERTICAL_CENTER);
+  MAP_LXW_FMT_CONST(ALIGN_VERTICAL_JUSTIFY);
+  MAP_LXW_FMT_CONST(ALIGN_VERTICAL_DISTRIBUTED);
+
+  MAP_LXW_FMT_CONST(PATTERN_SOLID);
+  MAP_LXW_FMT_CONST(PATTERN_MEDIUM_GRAY);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_GRAY);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_GRAY);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_HORIZONTAL);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_VERTICAL);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_DOWN);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_UP);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_GRID);
+  MAP_LXW_FMT_CONST(PATTERN_DARK_TRELLIS);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_HORIZONTAL);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_VERTICAL);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_DOWN);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_UP);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_GRID);
+  MAP_LXW_FMT_CONST(PATTERN_LIGHT_TRELLIS);
+  MAP_LXW_FMT_CONST(PATTERN_GRAY_125);
+  MAP_LXW_FMT_CONST(PATTERN_GRAY_0625);
+
+  MAP_LXW_FMT_CONST(BORDER_THIN);
+  MAP_LXW_FMT_CONST(BORDER_MEDIUM);
+  MAP_LXW_FMT_CONST(BORDER_DASHED);
+  MAP_LXW_FMT_CONST(BORDER_DOTTED);
+  MAP_LXW_FMT_CONST(BORDER_THICK);
+  MAP_LXW_FMT_CONST(BORDER_DOUBLE);
+  MAP_LXW_FMT_CONST(BORDER_HAIR);
+  MAP_LXW_FMT_CONST(BORDER_MEDIUM_DASHED);
+  MAP_LXW_FMT_CONST(BORDER_DASH_DOT);
+  MAP_LXW_FMT_CONST(BORDER_MEDIUM_DASH_DOT);
+  MAP_LXW_FMT_CONST(BORDER_DASH_DOT_DOT);
+  MAP_LXW_FMT_CONST(BORDER_MEDIUM_DASH_DOT_DOT);
+  MAP_LXW_FMT_CONST(BORDER_SLANT_DASH_DOT);
+
+  MAP_LXW_FMT_CONST(DIAGONAL_BORDER_UP);
+  MAP_LXW_FMT_CONST(DIAGONAL_BORDER_DOWN);
+  MAP_LXW_FMT_CONST(DIAGONAL_BORDER_UP_DOWN);
+#undef MAP_LXW_FMT_CONST
+}

data/ext/xlsxwriter/format.h

@@ -6,4 +6,8 @@
 
 void format_apply_opts(lxw_format *format, VALUE opts);
 
+void init_xlsxwriter_format();
+
+extern VALUE mXlsxFormat;
+
 #endif // __FORMAT__

data/ext/xlsxwriter/workbook.c

@@ -1,7 +1,16 @@
 #include <string.h>
 #include "xlsxwriter.h"
+#include "chart.h"
 #include "format.h"
 #include "workbook.h"
+#include "workbook_properties.h"
+#include "worksheet.h"
+
+VALUE cWorkbook;
+
+void workbook_free(void *p);
+VALUE workbook_release(VALUE self);
+
 
 VALUE
 workbook_alloc(VALUE klass)
@@ -19,6 +28,20 @@ workbook_alloc(VALUE klass)
   return obj;
 }
 
+/*  call-seq:
+ *     XlsxWriter::Workbook.new(path, constant_memory: false, tmpdir: nil) -> workbook
+ *     XlsxWriter::Workbook.new(path, constant_memory: false, tmpdir: nil) { |wb| block } -> nil
+ *     XlsxWriter::Workbook.open(path, constant_memory: false, tmpdir: nil) { |wb| block } -> 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
+ */
 VALUE
 workbook_new_(int argc, VALUE *argv, VALUE self) {
   VALUE workbook = rb_call_super(argc, argv);
@@ -30,6 +53,7 @@ workbook_new_(int argc, VALUE *argv, VALUE self) {
   return workbook;
 }
 
+/* :nodoc: */
 VALUE
 workbook_init(int argc, VALUE *argv, VALUE self) {
   struct workbook *ptr;
@@ -67,6 +91,18 @@ workbook_init(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
+/*  call-seq:
+ *     wb.close -> nil
+ *
+ *  Dumps the workbook content to the file and closes the worksheet.
+ *  To be used only for workbooks opened with <code>XlsxWriter::Workbook.new</code>
+ *  without block.
+ *
+ *  No methods should be called on the worksheet after it is colsed.
+ *
+ *    wb = XlsxWriter::Workbook.new('/tmp/test.xlsx')
+ *    wb.close
+ */
 VALUE
 workbook_release(VALUE self) {
   struct workbook *ptr;
@@ -119,20 +155,27 @@ workbook_free(void *p) {
   }
 }
 
+/* call-seq:
+ *    wb.add_worksheet([name]) -> ws
+ *    wb.add_worksheet([name]) { |ws| block } -> obj
+ *
+ * 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
+ */
 VALUE
 workbook_add_worksheet_(int argc, VALUE *argv, VALUE self) {
   VALUE worksheet = Qnil;
 
-  if (argc > 1) {
-    rb_raise(rb_eArgError, "wrong number of arguments");
-    return Qnil;
-  }
+  rb_check_arity(argc, 0, 1);
 
   struct workbook *ptr;
   Data_Get_Struct(self, struct workbook, ptr);
   if (ptr->workbook) {
-    VALUE mXlsxWriter = rb_const_get(rb_cObject, rb_intern("XlsxWriter"));
-    VALUE cWorksheet = rb_const_get(mXlsxWriter, rb_intern("Worksheet"));
     worksheet = rb_funcall(cWorksheet, rb_intern("new"), argc + 1, self, argv[0]);
   }
 
@@ -144,6 +187,37 @@ workbook_add_worksheet_(int argc, VALUE *argv, VALUE self) {
   return worksheet;
 }
 
+/* call-seq:
+ *    wb.add_format(key, definition) -> wb
+ *
+ * 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 <code>'d mmm yyyy'</code>
+ *               or <code>'#,##0.00'</code>.
+ * :num_format_index:: Defines numerical format from special {pre-defined set}[https://libxlsxwriter.github.io/format_8h.html#a688aa42bcc703d17e125d9a34c721872].
+ * :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::
+ */
 VALUE
 workbook_add_format_(VALUE self, VALUE key, VALUE opts) {
   struct workbook *ptr;
@@ -171,6 +245,23 @@ workbook_add_format_(VALUE self, VALUE key, VALUE opts) {
   return self;
 }
 
+/*  call-seq:
+ *     wb.add_chart(type) { |chart| block } -> obj
+ *     wb.add_chert(type) -> chart
+ *
+ *  Adds a chart of type +type+ to the workbook.
+ *
+ *  +type+ is expected to be one of <code>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}</code>.
+ *
+ *    wb.add_chart(XlsxWriter::Workbook::Chart::PIE) do |chart|
+ *      chart.add_series 'A1:A10', 'B1:B10'
+ *      ws.insert_chart('D2', chart)
+ *    end
+ */
 VALUE
 workbook_add_chart_(VALUE self, VALUE type) {
   VALUE chart = rb_funcall(cChart, rb_intern("new"), 2, self, type);
@@ -181,6 +272,7 @@ workbook_add_chart_(VALUE self, VALUE type) {
   return chart;
 }
 
+/* :nodoc: */
 VALUE
 workbook_set_default_xf_indices_(VALUE self) {
   struct workbook *ptr;
@@ -189,6 +281,12 @@ workbook_set_default_xf_indices_(VALUE self) {
   return self;
 }
 
+/*  call-seq: wb.properties -> wb_properties
+ *
+ *  Returns worbook properties accessor object.
+ *
+ *    wb.properties.title = 'My awesome sheet'
+ */
 VALUE
 workbook_properties_(VALUE self) {
   VALUE props = rb_obj_alloc(cWorkbookProperties);
@@ -196,6 +294,12 @@ workbook_properties_(VALUE self) {
   return props;
 }
 
+/*  call-seq: wb.define_name(name, formula) -> wb
+ *
+ *  Create a defined +name+ in the workbook to use as a variable defined in +formula+.
+ *
+ *    wb.define_name 'Sales', '=Sheet1!$G$1:$H$10'
+ */
 VALUE
 workbook_define_name_(VALUE self, VALUE name, VALUE formula) {
   struct workbook *ptr;
@@ -204,6 +308,11 @@ workbook_define_name_(VALUE self, VALUE name, VALUE formula) {
   return self;
 }
 
+/*  call-seq: wb.validate_worksheet_name(name) -> true
+ *
+ *  Validates a worksheet +name+. Returns +true+ or raises an exception (not
+ *  implemented yet).
+ */
 VALUE
 workbook_validate_worksheet_name_(VALUE self, VALUE name) {
   struct workbook *ptr;
@@ -255,3 +364,33 @@ void
 handle_lxw_error(lxw_error err) {
   return;
 }
+
+
+/*  Document-class: XlsxWriter::Workbook
+ *
+ *  +Workbook+ is the main class exposed by +XlsxWriter+. It represents the
+ *  workbook (.xlsx) file.
+ */
+void
+init_xlsxwriter_workbook() {
+  cWorkbook = rb_define_class_under(mXlsxWriter, "Workbook", rb_cObject);
+
+  rb_define_alloc_func(cWorkbook, workbook_alloc);
+  rb_define_singleton_method(cWorkbook, "new", workbook_new_, -1);
+  rb_define_alias(rb_singleton_class(cWorkbook), "open", "new");
+  rb_define_method(cWorkbook, "initialize", workbook_init, -1);
+  rb_define_method(cWorkbook, "close", workbook_release, 0);
+  rb_define_method(cWorkbook, "add_worksheet", workbook_add_worksheet_, -1);
+  rb_define_method(cWorkbook, "add_format", workbook_add_format_, 2);
+  rb_define_method(cWorkbook, "add_chart", workbook_add_chart_, 1);
+  rb_define_method(cWorkbook, "set_default_xf_indices", workbook_set_default_xf_indices_, 0);
+  rb_define_method(cWorkbook, "properties", workbook_properties_, 0);
+  rb_define_method(cWorkbook, "define_name", workbook_define_name_, 2);
+  rb_define_method(cWorkbook, "validate_worksheet_name", workbook_validate_worksheet_name_, 1);
+
+  /*
+   * This attribute contains effective font widths used for automatic column
+   * widths of workbook columns.
+   */
+  rb_define_attr(cWorkbook, "font_sizes", 1, 0);
+}

data/ext/xlsxwriter/workbook.h

@@ -10,33 +10,13 @@ struct workbook {
   st_table *formats;
 };
 
-
-VALUE workbook_alloc(VALUE klass);
-VALUE workbook_new_(int argc, VALUE *argv, VALUE self);
-VALUE workbook_init(int argc, VALUE *argv, VALUE self);
-VALUE workbook_release(VALUE self);
-void workbook_free(void *);
-
-VALUE workbook_add_worksheet_(int argc, VALUE *argv, VALUE self);
-VALUE workbook_add_format_(VALUE self, VALUE key, VALUE opts);
-VALUE workbook_add_chart_(VALUE self, VALUE type);
-VALUE workbook_set_default_xf_indices_(VALUE self);
-VALUE workbook_properties_(VALUE self);
-VALUE workbook_define_name_(VALUE self, VALUE name, VALUE formula);
-VALUE workbook_validate_worksheet_name_(VALUE self, VALUE name);
-
-
 lxw_format *workbook_get_format(VALUE self, VALUE key);
 lxw_datetime value_to_lxw_datetime(VALUE val);
 void handle_lxw_error(lxw_error err);
 
+void init_xlsxwriter_workbook();
+
 extern VALUE mXlsxWriter;
 extern VALUE cWorkbook;
-extern VALUE cWorksheet;
-extern VALUE mXlsxFormat;
-extern VALUE cWorkbookProperties;
-extern VALUE cChart;
-extern VALUE cChartSeries;
-extern VALUE cChartAxis;
 
 #endif // __WORKBOOK__

data/ext/xlsxwriter/workbook_properties.c

@@ -4,6 +4,9 @@
 #include "workbook.h"
 #include "workbook_properties.h"
 
+VALUE cWorkbookProperties;
+
+/* :nodoc: */
 VALUE
 workbook_properties_init_(VALUE self, VALUE workbook) {
   struct workbook *wb_ptr;
@@ -18,20 +21,11 @@ workbook_properties_init_(VALUE self, VALUE workbook) {
   return self;
 }
 
-VALUE
-workbook_properties_set_dir_(VALUE self, VALUE value) {
-  VALUE key = rb_id2str(rb_frame_callee());
-  char *key_str = ruby_strdup(RSTRING_PTR(key));
-  size_t last_pos = RSTRING_LEN(key) - 1;
-  if (last_pos > 0 && key_str[last_pos] == '=') {
-    key_str[last_pos] = '\0';
-  }
-  key = rb_str_new_cstr(key_str);
-  workbook_properties_set_(self, key, value);
-  xfree(key_str);
-  return value;
-}
-
+/*  call-seq: wb_properies[property]= value
+ *
+ *  Sets a document +property+ (both custom and standard).
+ *  Property type is automatically deduced from the +value+.
+ */
 VALUE
 workbook_properties_set_(VALUE self, VALUE key, VALUE value) {
   char *key_cstr = NULL;
@@ -101,3 +95,56 @@ workbook_properties_set_(VALUE self, VALUE key, VALUE value) {
   }
   return value;
 }
+
+VALUE
+workbook_properties_set_dir_(VALUE self, VALUE value) {
+  VALUE key = rb_id2str(rb_frame_callee());
+  char *key_str = ruby_strdup(RSTRING_PTR(key));
+  size_t last_pos = RSTRING_LEN(key) - 1;
+  if (last_pos > 0 && key_str[last_pos] == '=') {
+    key_str[last_pos] = '\0';
+  }
+  key = rb_str_new_cstr(key_str);
+  workbook_properties_set_(self, key, value);
+  xfree(key_str);
+  return value;
+}
+
+/*  Document-class: XlsxWriter::Workbook::Properties
+ *
+ *  The class defines accessors for workbook properties.
+ *
+ *  Setting standard workbook text properties:
+ *
+ *     wb_properties.title = title
+ *     wb_properties.subject = subjet
+ *     wb_properties.author = author
+ *     wb_properties.manager = manager
+ *     wb_properties.company = company
+ *     wb_properties.category = category
+ *     wb_properties.keywords = keywords
+ *     wb_properties.comments = comments
+ *     wb_properties.status = status
+ *
+ *  You can see the properties under Office Button -> Prepare -> Properties
+ *  in Excel.
+ */
+void
+init_xlsxwriter_workbook_properties() {
+  cWorkbookProperties = rb_define_class_under(cWorkbook, "Properties", rb_cObject);
+
+  rb_define_method(cWorkbookProperties, "initialize", workbook_properties_init_, 1);
+  rb_define_method(cWorkbookProperties, "[]=", workbook_properties_set_, 2);
+#define DEF_PROP_HANDLER(prop) rb_define_method(cWorkbookProperties, #prop "=", workbook_properties_set_dir_, 1);
+  DEF_PROP_HANDLER(title);
+  DEF_PROP_HANDLER(subject);
+  DEF_PROP_HANDLER(author);
+  DEF_PROP_HANDLER(manager);
+  DEF_PROP_HANDLER(company);
+  DEF_PROP_HANDLER(category);
+  DEF_PROP_HANDLER(keywords);
+  DEF_PROP_HANDLER(comments);
+  DEF_PROP_HANDLER(status);
+  DEF_PROP_HANDLER(hyperlink_base);
+#undef DEF_PROP_HANDLER
+}