[gnumeric] Introspection: deal with ranges

[Morten Welinder <mortenw src gnome org>]

commit af07a7daf3768081ac71abab9b480f4a5a1f0bcf
Author: Morten Welinder <terra gnome org>
Date:   Thu Apr 12 13:59:00 2018 -0400

    Introspection: deal with ranges

 README-introspection               |   90 +++++++++++++++++++++++++
 src/ranges.c                       |  127 +++++++++++++++++++++++++++++++----
 src/value.c                        |    7 ++
 src/value.h                        |    1 +
 test/t3001-introspection-simple.pl |    1 +
 test/t3001-introspection-simple.py |    1 +
 6 files changed, 212 insertions(+), 15 deletions(-)
---
diff --git a/README-introspection b/README-introspection
new file mode 100644
index 0000000..fd91e96
--- /dev/null
+++ b/README-introspection
@@ -0,0 +1,90 @@
+Today is 20180412.  If that seems a long time ago, this document might
+be outdated.
+
+test/t3001-introspection-simple.py shows a sample of using introspection
+to work with a spreadsheet.  Note: you must either "make install" first
+or else run it the corresponding *.pl file.
+
+The following is a list of types and the API that is expected to both
+be useful in this setting and actually work.
+
+This is incomplete.  In particular, I'll have to look at
+* Expressions other than via text
+* Style information
+* File i/o
+* Copy and paste
+
+-----------------------------------------------------------------------------
+
+Workbook: [GObject]
+  new_with_sheets(count)
+  sheet_by_index(no)
+  sheet_by_name(string)
+  props.name
+
+
+Sheet: [GObject]
+  get_size()
+  cell_set_value(col,row,value)      [1]
+  cell_set_text(col,row,string)      [1]
+  cell_get_value(col,row)
+  cell_get(col,row)
+  cell_fetch(col,row)
+  cells(range)
+  cells_count()
+  is_cell_empty(col,row)
+
+
+GnmCell: [Structure] [2]
+  name()
+  get_value()
+
+
+GnmSheetSize: [Simple structure]
+  max_cols
+  max_rows
+
+
+GnmValue: [Structure]
+  new_int(int)
+  new_bool(bool)
+  new_float(double)
+  new_string(string)
+  new_empty()
+  get_as_string()
+  get_as_int()
+  get_as_float()
+  type_of()
+
+
+ValueType: [Enum]
+  EMPTY
+  BOOLEAN
+  FLOAT
+  ERROR
+  STRING
+  CELLRANGE
+  ARRAY
+
+
+GnmRange: [Simple structure]
+  init(int,int,int,int)
+  init_full_sheet(sheet)
+  init_cols(sheet,int,int)
+  init_rows(sheet,int,int)
+  init_cellpos(sheet,cellpos)
+  as_string()
+  start
+  end
+
+
+GnmCellPos: [Simple structure]
+  col
+  row
+
+
+Footnotes:
+[1] This function is not calling the obvious C function, but uses
+    introspection's rename-to feature to present a better API.
+[2] Cells are owned by the sheet.  GnmCell's boxed type uses no-op
+    copying and freeing.
diff --git a/src/ranges.c b/src/ranges.c
index d15748b..926f4b1 100644
--- a/src/ranges.c
+++ b/src/ranges.c
@@ -34,6 +34,15 @@
 #undef RANGE_DEBUG
 #define UNICODE_ELLIPSIS "\xe2\x80\xa6"
 
+/**
+ * range_init_full_sheet:
+ * @r: #GnmRange
+ * @sheet: #Sheet
+ *
+ * Updates @r to fill @sheet in its entirety.
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init_full_sheet (GnmRange *r, Sheet const *sheet)
 {
@@ -44,6 +53,17 @@ range_init_full_sheet (GnmRange *r, Sheet const *sheet)
        return r;
 }
 
+/**
+ * range_init_cols:
+ * @r: #GnmRange
+ * @sheet: #Sheet
+ * @start_col: Starting column
+ * @end_col: Ending column
+ *
+ * Updates @r to span full columns @start_col through @end_col completely.
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init_cols (GnmRange *r, Sheet const *sheet, int start_col, int end_col)
 {
@@ -54,16 +74,17 @@ range_init_cols (GnmRange *r, Sheet const *sheet, int start_col, int end_col)
        return r;
 }
 
-GnmRange *
-range_init_invalid (GnmRange *r)
-{
-       r->start.col = -1;
-       r->start.row = -1;
-       r->end.col = -2;
-       r->end.row = -2;
-       return r;
-}
-
+/**
+ * range_init_rows:
+ * @r: #GnmRange
+ * @sheet: #Sheet
+ * @start_row: Starting row
+ * @end_row: Ending row
+ *
+ * Updates @r to span full rows @start_row through @end_row completely.
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init_rows (GnmRange *r, Sheet const *sheet, int start_row, int end_row)
 {
@@ -74,6 +95,33 @@ range_init_rows (GnmRange *r, Sheet const *sheet, int start_row, int end_row)
        return r;
 }
 
+/**
+ * range_init_invalid: (skip)
+ * @r: #GnmRange
+ *
+ * Updates @r to a meaningless range
+ *
+ * Returns: (transfer none): @r
+ */
+GnmRange *
+range_init_invalid (GnmRange *r)
+{
+       r->start.col = -1;
+       r->start.row = -1;
+       r->end.col = -2;
+       r->end.row = -2;
+       return r;
+}
+
+/**
+ * range_init_rangeref:
+ * @r: #GnmRange
+ * @rr: #GnmRangeRef
+ *
+ * Updates @r to be the same as the range part of @rr.
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init_rangeref (GnmRange *range, GnmRangeRef const *rr)
 {
@@ -87,6 +135,15 @@ range_init_rangeref (GnmRange *range, GnmRangeRef const *rr)
 }
 
 
+/**
+ * range_init_value:
+ * @r: A #GnmRange to change
+ * @v: A #GnmValue containing a cell range
+ *
+ * Updates @r to be the same as the cell range of @v.
+ *
+ * Returns: (transfer none) (nullable): @r
+ */
 GnmRange *
 range_init_value (GnmRange *range, GnmValue const *v)
 {
@@ -96,6 +153,15 @@ range_init_value (GnmRange *range, GnmValue const *v)
        return range_init_rangeref (range, &v->v_range.cell);
 }
 
+/**
+ * range_init_cellpos:
+ * @r: A #GnmRange to change
+ * @pos: A #GnmCellPos
+ *
+ * Updates @r to be the singleton range of @pos
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init_cellpos (GnmRange *r, GnmCellPos const *pos)
 {
@@ -104,6 +170,18 @@ range_init_cellpos (GnmRange *r, GnmCellPos const *pos)
 
        return r;
 }
+
+/**
+ * range_init_cellpos_size:
+ * @r: A #GnmRange to change
+ * @start: A #GnmCellPos for the upper left corner of the desired range
+ * @cols: number of columns
+ * @rows: number of rows
+ *
+ * Updates @r to start at @start and spanning @cols columns and @rows rows.
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init_cellpos_size (GnmRange *r,
                         GnmCellPos const *start, int cols, int rows)
@@ -115,6 +193,19 @@ range_init_cellpos_size (GnmRange *r,
        return r;
 }
 
+/**
+ * range_init:
+ * @r: A #GnmRange to change
+ * @start_col: Column
+ * @start_row: Row
+ * @end_col: Column
+ * @end_row: Row
+ *
+ * Updates @r to start at (@start_col,@start_row) and end
+ * at (@end_col,@end_row).
+ *
+ * Returns: (transfer none): @r
+ */
 GnmRange *
 range_init (GnmRange *r, int start_col, int start_row,
            int end_col, int end_row)
@@ -179,19 +270,25 @@ range_list_destroy (GSList *ranges)
 }
 
 
+/**
+ * range_as_string:
+ * @r: A #GnmRange
+ *
+ * Returns: (transfer none): a string repesentation of @src
+ **/
 char const *
-range_as_string (GnmRange const *src)
+range_as_string (GnmRange const *r)
 {
        static char buffer[(6 + 4 * sizeof (long)) * 2 + 1];
 
-       g_return_val_if_fail (src != NULL, "");
+       g_return_val_if_fail (r != NULL, "");
 
        sprintf (buffer, "%s%s",
-                col_name (src->start.col), row_name (src->start.row));
+                col_name (r->start.col), row_name (r->start.row));
 
-       if (src->start.col != src->end.col || src->start.row != src->end.row)
+       if (r->start.col != r->end.col || r->start.row != r->end.row)
                sprintf (buffer + strlen(buffer), ":%s%s",
-                        col_name (src->end.col), row_name (src->end.row));
+                        col_name (r->end.col), row_name (r->end.row));
 
        return buffer;
 }
diff --git a/src/value.c b/src/value.c
index 8aec956..90d43fb 100644
--- a/src/value.c
+++ b/src/value.c
@@ -826,6 +826,13 @@ value_hash (GnmValue const *v)
 }
 
 
+GnmValueType
+value_type_of (const GnmValue *v)
+{
+       return v->v_any.type;
+}
+
+
 gboolean
 value_get_as_bool (GnmValue const *v, gboolean *err)
 {
diff --git a/src/value.h b/src/value.h
index e7582b9..1475572 100644
--- a/src/value.h
+++ b/src/value.h
@@ -150,6 +150,7 @@ char       *value_get_as_string        (GnmValue const *v);
 void        value_get_as_gstring   (GnmValue const *v, GString *target,
                                    GnmConventions const *conv);
 
+GnmValueType value_type_of         (GnmValue const *v);
 int         value_get_as_int      (GnmValue const *v);
 gnm_float   value_get_as_float    (GnmValue const *v);
 gboolean    value_is_zero         (GnmValue const *v);
diff --git a/test/t3001-introspection-simple.pl b/test/t3001-introspection-simple.pl
index 8c1bcac..de56494 100755
--- a/test/t3001-introspection-simple.pl
+++ b/test/t3001-introspection-simple.pl
@@ -14,6 +14,7 @@ my $ref = join("",<DATA>);
               sub { $_ eq $ref });
 
 __DATA__
+Name: Sheet1
 Number of columns: 256
 Number of rows: 65536
 
diff --git a/test/t3001-introspection-simple.py b/test/t3001-introspection-simple.py
index e6c2204..299303b 100755
--- a/test/t3001-introspection-simple.py
+++ b/test/t3001-introspection-simple.py
@@ -11,6 +11,7 @@ wb = Gnm.Workbook.new_with_sheets(1)
 
 # Get sheet.  Index starts at 0
 sheet = wb.sheet_by_index(0)
+print "Name:",sheet.props.name
 print "Number of columns:", sheet.get_size().max_cols
 print "Number of rows:", sheet.get_size().max_rows