octave_packages/io-1.0.19/odsread.m

   1 ## Copyright (C) 2009,2010,2011,2012 Philip Nienhuis <prnienhuis at users.sf.net>
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr},  @var{limits}] = odsread (@var{filename})
  18 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = odsread (@var{filename}, @var{wsh})
  19 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = odsread (@var{filename}, @var{wsh}, @var{range})
  20 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = odsread (@var{filename}, @var{wsh}, @var{range}, @var{reqintf})
  21 ##
  22 ## Read data contained from cell range @var{range} in worksheet @var{wsh}
  23 ## in OpenOffice_org Calc spreadsheet file @var{filename}.
  24 ##
  25 ## You need the octave-forge java package (> 1.2.6) and one or both of
  26 ## jopendocument-<version>.jar or preferrably: (odfdom.jar (versions
  27 ## 0.7.5 or 0.8.6+) & xercesImpl.jar v. 2.9.1) in your javaclasspath.
  28 ## There is also experimental support invoking OpenOffice.org or clones
  29 ## through Java/UNO bridge.
  30 ##
  31 ## Return argument @var{numarr} contains the numeric data, optional
  32 ## return arguments @var{txtarr} and @var{rawarr} contain text strings
  33 ## and the raw spreadsheet cell data, respectively, and @var{limits} is
  34 ##a struct containing the data origins of the various returned arrays.
  35 ##
  36 ## If @var{filename} does not contain any directory, the file is
  37 ## assumed to be in the current directory. @var{filename} should include
  38 ## the filename extension (.ods).
  39 ##
  40 ## @var{wsh} is either numerical or text, in the latter case it is
  41 ## case-sensitive and it should conform to OpenOffice.org Calc sheet
  42 ## name requirements.
  43 ## Note that in case of a numerical @var{wsh} this number refers to the
  44 ## position in the worksheet stack, counted from the left in a Calc
  45 ## window. The default is numerical 1, i.e. the leftmost worksheet
  46 ## in the Calc file.
  47 ##
  48 ## @var{range} is expected to be a regular spreadsheet range format,
  49 ## or "" (empty string, indicating all data in a worksheet).
  50 ## If no range is specified the occupied cell range will have to be
  51 ## determined behind the scenes first; this can take some time.
  52 ##
  53 ## If only the first argument is specified, odsread will try to read
  54 ## all contents from the first = leftmost (or the only) worksheet (as
  55 ## if a range of @'' (empty string) was specified).
  56 ##
  57 ## If only two arguments are specified, odsread assumes the second
  58 ## argument to be @var{wsh} and to refer to a worksheet. In that case
  59 ## odsread tries to read all data contained in that worksheet.
  60 ##
  61 ## The optional last argument @var{reqintf} can be used to override
  62 ## the automatic selection by odsread of one interface out of the
  63 ## supported ones: Java/ODFtoolkit ('OTK'), Java/jOpenDocument
  64 ## ('JOD') or Java/UNO bridge ('UNO').
  65 ##
  66 ## Erroneous data and empty cells are set to NaN in @var{numarr} and
  67 ## turn up empty in @var{txtarr} and @var{rawarr}. Date/time values
  68 ## in date/time formatted cells are returned as numerical values in
  69 ## @var{obj} with base 1-1-000. Note that OpenOfice.org and MS-Excel
  70 ## have different date base values (1/1/0000 & 1/1/1900, resp.) and
  71 ## internal representation so MS-Excel spreadsheets rewritten into
  72 ## .ods format by OpenOffice.org Calc may have different date base
  73 ## values.
  74 ##
  75 ## @var{numarr} and @var{txtarr} are trimmed from empty outer rows
  76 ## and columns, so any returned array may turn out to be smaller than
  77 ## requested in @var{range}.
  78 ##
  79 ## When reading from merged cells, all array elements NOT corresponding
  80 ## to the leftmost or upper Calc cell will be treated as if the
  81 ## "corresponding" Calc cells are empty.
  82 ##
  83 ## odsread is just a wrapper for a collection of scripts that find out
  84 ## the interface to be used and do the actual reading. For each call
  85 ## to odsread the interface must be started and the Calc file read into
  86 ## memory. When reading multiple ranges (in optionally multiple worksheets)
  87 ## a significant speed boost can be obtained by invoking those scripts
  88 ## directly (odsopen / ods2oct [/ parsecell] / ... / odsclose).
  89 ##
  90 ## Examples:
  91 ##
  92 ## @example
  93 ##   A = odsread ('test4.ods', '2nd_sheet', 'C3:AB40');
  94 ##   (which returns the numeric contents in range C3:AB40 in worksheet
  95 ##   '2nd_sheet' from file test4.ods into numeric array A)
  96 ## @end example
  97 ##
  98 ## @example
  99 ##   [An, Tn, Ra, limits] = odsread ('Sales2009.ods', 'Third_sheet');
 100 ##   (which returns all data in worksheet 'Third_sheet' in file test4.ods
 101 ##   into array An, the text data into array Tn, the raw cell data into
 102 ##   cell array Ra and the ranges from where the actual data came in limits)
 103 ## @end example
 104 ##
 105 ## @seealso {odsopen, ods2oct, oct2ods, odsclose, odswrite, odsfinfo, parsecell}
 106 ##
 107 ## @end deftypefn
 108
 109 ## Author: Philip Nienhuis <prnienhuis at users.sf.net>
 110 ## Created: 2009-12-12
 111 ## Updates:
 112 ## 2010-01-05 (....)
 113 ## 2010-03-04 Slight adaptations in texinfo
 114 ## 2010-05-31 Updated help text (delays i.c.o. empty range due to getusedrange call)
 115 ## 2010-11-10 Updated help text (filename extension req'd)
 116 ## 2010-11-13 Added some input validity checks
 117 ## 2011-09-08 Catch empty ods structs after failed odsopen attempts
 118 ## 2011-09-18 Return empty output arg in case of empty rawarr
 119 ## 2012-01-26 Fixed "seealso" help string
 120 ## 2012-03-07 Updated texinfo help text
 121 ## 2012-06-08 Tabs replaced by double space
 122
 123 function [ numarr, txtarr, rawarr, lim ] = odsread (filename, wsh=1, datrange=[], reqintf=[])
 124
 125   if (nargin < 1 || isempty (findstr ('.ods', tolower (filename))))
 126     usage ("odsread: at least a filename incl. suffix is needed");
 127   endif
 128   if (nargout < 1)
 129     usage ("odsread: no output argument(s) specified");
 130   endif
 131
 132   ods = odsopen (filename, 0, reqintf);
 133
 134   if (~isempty (ods))
 135
 136     [rawarr, ods, rstatus] = ods2oct (ods, wsh, datrange);
 137
 138     if (rstatus)
 139       [numarr, txtarr, lim] = parsecell (rawarr, ods.limits);
 140     else
 141       warning (sprintf ("No data read from %s.", filename));
 142       numarr = [];
 143     endif
 144
 145     ods = odsclose (ods);
 146
 147   endif
 148
 149 endfunction