document xlsxreader functions

docs/Lua API.rst

@@ -4102,6 +4102,37 @@ Lua plugin classes
 - ``shuffle()``: shuffles the sequence of numbers
 - ``next()``: returns next number in the sequence
 
+xlsxreader
+==========
+
+Utility functions to facilitate reading .xlsx spreadsheets. It provides the
+following API methods:
+
+ - ``file_handle open_xlsx_file(filename)``
+ - ``close_xlsx_file(file_handle)``
+ - ``sheet_names list_sheets(file_handle)``
+ - ``sheet_handle open_sheet(file_handle, sheet_name)``
+ - ``close_sheet(sheet_handle)``
+ - ``cell_strings get_row(sheet_handle)``
+
+ Example::
+
+    local xlsxreader = require('plugins.xlsxreader')
+
+    local filepath = "path/to/some_file.xlsx"
+    local xlsx_file = xlsxreader.open_xlsx_file(filepath)
+    for _, sheet_name in ipairs(xlsxreader.list_sheets(xlsx_file)) do
+        print('reading sheet: '..sheet_name)
+        local xlsx_sheet = xlsxreader.open_sheet(xlsx_file, sheet_name)
+        local row_cells = xlsxreader.get_row(xlsx_sheet)
+        while row_cells do
+            printall(row_cells)
+            row_cells = xlsxreader.get_row(xlsx_sheet)
+        end
+        xlsxreader.close_sheet(xlsx_sheet)
+    end
+    xlsxreader.close_xlsx_file(xlsx_file)
+
 =======
 Scripts
 =======

docs/Plugins.rst

@@ -2939,10 +2939,11 @@ Lua API
 =======
 
 Some plugins consist solely of native libraries exposed to Lua. They are listed
-in the `lua-api` file under `lua-plugins`:
+in the `lua-api` file under `lua-plugins`::
 
 * `eventful`
 * `building-hacks`
 * `luasocket`
 * `map-render`
 * `cxxrandom`
+* `xlsxreader`

plugins/lua/xlsxreader.lua

@@ -12,6 +12,24 @@ local _ENV = mkmodule('plugins.xlsxreader')
  * close_sheet(sheet_handle)
  * cell_strings get_row(sheet_handle)
 
+Sample usage:
+
+    local xlsxreader = require('plugins.xlsxreader')
+
+    local filepath = "path/to/some_file.xlsx"
+    local xlsx_file = xlsxreader.open_xlsx_file(filepath)
+    for _, sheet_name in ipairs(xlsxreader.list_sheets(xlsx_file)) do
+        print('reading sheet: '..sheet_name)
+        local xlsx_sheet = xlsxreader.open_sheet(xlsx_file, sheet_name)
+        local row_cells = xlsxreader.get_row(xlsx_sheet)
+        while row_cells do
+            printall(row_cells)
+            row_cells = xlsxreader.get_row(xlsx_sheet)
+        end
+        xlsxreader.close_sheet(xlsx_sheet)
+    end
+    xlsxreader.close_xlsx_file(xlsx_file)
+
 --]]
 
 return _ENV