octave_packages/io-1.0.19/odswrite.m

   1 ## Copyright (C) 2009,2010,2011,2012 Philip Nienhuis <pr.nienhuis 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{rstatus} = odswrite (@var{filename}, @var{arr})
  18 ## @deftypefnx {Function File} @var{rstatus} = odswrite (@var{filename}, @var{arr}, @var{wsh})
  19 ## @deftypefnx {Function File} @var{rstatus} = odswrite (@var{filename}, @var{arr}, @var{wsh}, @var{range})
  20 ## @deftypefnx {Function File} @var{rstatus} = odswrite (@var{filename}, @var{arr}, @var{wsh}, @var{range}, @var{reqintf})
  21 ## Add data in 1D/2D array @var{arr} into sheet @var{wsh} in
  22 ## OpenOffice_org Calc spreadsheet file @var{filename} in cell range @var{range}.
  23 ##
  24 ## @var{rstatus} returns 1 if write succeeded, 0 otherwise.
  25 ##
  26 ## @var{filename} must be a valid .ods OpenOffice.org file name (including
  27 ## file name extension). If @var{filename} does not contain any directory
  28 ## path, the file is saved in the current directory.
  29 ##
  30 ## @var{arr} can be any 1D or 2D array containing numerical or character
  31 ## data (cellstr) except complex. Mixed numeric/text arrays can only be
  32 ## cell arrays.
  33 ##
  34 ## @var{wsh} can be a number or string. In case of a not yet existing
  35 ## OpenOffice.org spreadsheet, the first sheet will be used & named
  36 ## according to @var{wsh} - no extra empty sheets are created.
  37 ## In case of existing files, some checks are made for existing sheet
  38 ## names or numbers, or whether @var{wsh} refers to an existing sheet with
  39 ## a type other than sheet (e.g., chart).
  40 ## When new sheets are to be added to the spreadsheet file, they are
  41 ## inserted to the right of all existing sheets. The pointer to the
  42 ## "active" sheet (shown when OpenOffice.org Calc opens the file) remains
  43 ## untouched.
  44 ##
  45 ## @var{range} is expected to be a regular spreadsheet range.
  46 ## Data is added to the sheet; existing data in the requested
  47 ## range will be overwritten.
  48 ## Array @var{arr} will be clipped at the right and/or bottom if its size
  49 ## is bigger than can be accommodated in @var{range}.
  50 ## If @var{arr} is smaller than the @var{range} allows, it is placed
  51 ## in the top left rectangle of @var{range} and cell values outside that
  52 ## rectangle will be untouched.
  53 ##
  54 ## If @var{range} contains merged cells, only the elements of @var{arr}
  55 ## corresponding to the top or left Calc cells of those merged cells
  56 ## will be written, other array cells corresponding to that cell will be
  57 ## ignored.
  58 ##
  59 ## The optional last argument @var{reqintf} can be used to override
  60 ## the automatic selection by odswrite of one interface out of the
  61 ## supported ones: Java/ODFtooolkit ('OTK'), Java/jOpenDocument ('JOD'),
  62 ## or Java/OpenOffice.org ('UNO').
  63 ##
  64 ## odswrite is a mere wrapper for various scripts which find out what
  65 ## ODS interface to use (ODF toolkit or jOpenDocument) plus code to mimic
  66 ## the other brand's syntax. For each call to odswrite such an interface
  67 ## must be started and possibly an ODS file loaded. When writing to multiple
  68 ## ranges and/or worksheets in the same ODS file, a speed bonus can be
  69 ## obtained by invoking those scripts (odsopen / octods / .... / odsclose)
  70 ## directly.
  71 ##
  72 ## Example:
  73 ##
  74 ## @example
  75 ##   status = odswrite ('test4.ods', 'arr', 'Eight_sheet', 'C3:AB40');
  76 ##   (which adds the contents of array arr (any type) to range C3:AB40
  77 ##   in sheet 'Eight_sheet' in file test4.ods and returns a logical
  78 ##   True (= numerical 1) in status if al went well)
  79 ## @end example
  80 ##
  81 ## @seealso {odsread, oct2ods, ods2oct, odsopen, odsclose, odsfinfo}
  82 ##
  83 ## @end deftypefn
  84
  85 ## Author: Philip Nienhuis
  86 ## Created: 2009-12-14
  87 ## Updates:
  88 ## 2010-01-14 Finalized write support tru ODS toolkit
  89 ## 2010-01-15 Added texinfo help
  90 ## 2010-08-25 Removed text about 31 char limit for sheet names (invalid)
  91 ## 2010-11-13 Added note about required file extension in help text
  92 ## 2010-11-13 Added some input arg checks
  93 ## 2011-09-08 Minor filename error text adaptation
  94 ## 2012-01-26 Fixed "seealso" help string
  95 ## 2012-02-20 Fixed range parameter to be default empty string rather than empty numeral
  96 ## 2010-03-07 Updated texinfo help text
  97 ## 2012-06-08 Tabs replaced by double space
  98
  99 function [ rstatus ] = odswrite (filename, data, wsh=1, crange='', reqintf=[])
 100
 101   # Input validity checks
 102   if (nargin < 2)
 103     usage ("Insufficient arguments - see 'help odswrite'");
 104   elseif (~ischar (filename) || isempty (findstr ('.ods', tolower (filename))))
 105     error ("First argument must be a filename (incl. .ods suffix for OTK & JOD)");
 106   endif
 107
 108   ods = odsopen (filename, 1, reqintf);
 109
 110   if (~isempty (ods))
 111     [ods, rstatus] = oct2ods (data, ods, wsh, crange);
 112
 113     # If rstatus was not OK, reset change indicator in ods pointer
 114     if (~rstatus)
 115       ods.changed = rstatus;
 116       warning ("odswrite: data transfer errors, file not rewritten");
 117     endif
 118
 119     ods = odsclose (ods);
 120
 121   endif
 122
 123 endfunction