[R] Updates for xlsReadWrite (1.5.3) and xlsReadWritePro (1.6.1/3)

[Hans-Peter Suter]

The xlsReadWrite[Pro] packages allow to natively read/write Excel files (.xls)
on the Win 32-bit platform.

About a week ago new package versions have been released:
* xlsReadWrite 1.5.3 is available at CRAN (for R2.11/2.12) and from
www.swissr.org/download (binary builds for R2.9 - R2.12)
* xlsReadWritePro 1.6.3 is available from www.swissr.org/download
(binary builds for R2.9 - R2.12)
* (the full download listing is here:
http://dl.dropbox.com/u/2602516/swissrpkg/index.html)

###### Changes in xlsReadWrite 1.5.3 (0b78c1) ######

  - *important*: fix AV when reading large data (issue #110: in a subroutine a
    pointer (pSExp) had been 'riUnprotect'ed (Rf_unprotect) too early, the total
    protect/unprotect count was correct (of course) but when 'anyDuplicated' got
    called in the subroutine, the control flow switched to R and R then had the
    possibility to free 'my' pointer. Not good).
    Thanks to the (anonymous) user which submitted the nice bug report!
  - NaN values will be written as 'NaN' and behaviour (e.g. coercion) better
    accounts R (see read.xls.Rd, write.xls.Rd and unitTests/runitNaNaN.R).
  - 'dateTimeAs' argument in read.xls has been renamed to 'dateTime'. When using
    the default (which should be fine in most cases) this change won't
affect you.
  - fix startup message scrambling in R2.12.0 (LF instead of CRLF -
reported to Rdevel)
  - simplified file (unitTests/execManually.R) to run RUnit tests
  - misc. small/cosmetic changes (see github commits)
  - (internal) update makefile: support R2.12, much simplify targets, set/modify
    Windows System Path from within the makefile


###### Changes in xlsReadWritePro 1.6.3 (93a6d7) ######

  - fix for startup message scrambling (use LF instead of CRLF -
reported to Rdevel)
  - some more RUnit tests, cosmetic changes (typos, formatting, etc.)
  - (internal) update makefile: also support R2.12/2.9, much simplify targets,
    set/modify Windows System Path from within the makefile

###### Changes in xlsReadWritePro version 1.6.1 ######

This is a significant update and may require some small adjustments in
your code.

    * Precompiled binary packages for R2.10 and R2.11 (see downloads)
    * While the package runs on R2.9 and R2.12, we have some issues
with our automated 'binary-package-building-and-releasing' makefile.
This will be fixed later. Please send us an email if you need the pkg
for these versions now and we try to help.
    * Note: works with existing keys (even when already 4 years old;)

Changes:

--- 'meta' ---

o test/ensure functionality with RUnit tests (>180)
o improve consistency and add examples
o issue tracking is public now and a forum has been added

--- important ---

o 'KEEP' argument/functionality DROPPED
  - reason: redundant, differences between the so-called 'keep-obj'
and 'xls-obj'
    are confusing, complicates lowlevel code and hinders future enhancements
  - resolution: use xls.open, xls.new, xls.save, xls.cancel and
xls.close instead

o area-related arguments (from, rows, cells, ...) in read.xls/write.xls
  - CELLS argument SPLITTED into 'CELLS' and 'RANGE':
    - cells: pick single cell values and give them back as a vector or as a
      data.frame (the latter is new, type will be determined for each
cell individually)
    - range: read ranges either by name or by a numeric 4-elem-vector
(R1,C1,R2,C2)
      (A1 style, i.e. 'A1:C3', 'Sheet2!B42' could eventually be added here).

o xls.sheet, NAMEORINDEX argument renamed
  - 'nameOrIndex' becomes 'sheet' and the default is the first/active sheet
    (depends if file is a physical file or an xls-obj)
  - 'copyAndInsert' action copies from the active sheet

o xls.image, SHEET argument is needed! In light of this obligatory change the
  arguments have been reworked. Here are the current and older declaration:
  - curr.: xls.image(file, action, sheet = NA|NULL, img = NA, range =
NA, target = NA)
  - beta:  xls.image(file, action, img = NA, range = NA, name = NA)
  - old:   xls.image(file = NA, action, nameOrIdx = NA, miscData = NA,
keep = NA)

o xls.range, NAMEORINDEX argument renamed
  - 'nameorindex' becomes 'range'

o template location moved
  - new: R_HOME/library/xlsReadWrite/template/TemplateNew.xls
  - (old/erronous: R_HOME/library/xlsReadWrite/libs/template,
     reported by B. Ripley for free version)
  - (the template location in APPDATA remains unaffected)

--- normal ---

o read.xls
  - colClasses: recognizes boolean strings as logical, recognizes isodatetime
    formatted strings, isodatetime/isotime/isodate work for double and character
    string values. ??? todo: re-read formula values when one or more
formulas have
    been modified: gives back 0 (instead of #NULL!).
  - rownames for data.frames are integers (when not read from Excel)
  - NEW ARGUMENT 'checkNames' to optionally treat colnames with 'make.names'
  - NEW ARGUMENT 'strictArea'
    - background: when the library opens an Excel file it determines
the area which
      is containing data (see variables sheet.nrow and sheet.ncol from
xls.info)).
    - arguments:
      - NA (default): rows/cols must be inside Excel data area,
to/from can be outside
      - TRUE: rows/cols/to/from must all be inside Excel data area
      - FALSE: rows/cols/to/from are allowed to be outside the Excel data area
  - values which cannot be converted become NA (for double it was NaN before)
o write.xls
  - naStrings the DEFAULT CHANGES from NA to '', i.e. cells will be cleared
o read.xls/write.xls
  - rows/cols arguments can be used together. This is kind of subsetting Excel:
    'ExcelSheet[<rows>, <cols>]', i.e. 'ExcelSheet[c(3, 4, 6), c(2, 4)]'
  - colNames
    - supports scalar number to denote row to be used for column names
    - several default related changes 'X', 'X.1', 'V1' (see ?read.xls)
  - rowNames: character scalars do no longer select a column (use
numbers instead)
  - colnames/rowNames: number value may be a double (and not only integer)
  - NaN will be written as 'NaN' (instead of 2.69653970229347E+308)
and can be re-read
  - support empty objects (without data but with column names)
  - area-arguments (except 'cell') always include rowname/colnames
(slightly inconsistent before)
o xls.image:
  - support for vector images (wmf, emf)
  - new 'export' action to save an Excel pictures to a file
o xls.close always attempts to save a modified Excel object (use xls.cancel to
  discard changes and close object)
o xls.cancel: 'what' argument removed (use 'obj = NA' to cancel all objects)
o xls.info
  - 'onlyFileInfo', 'what' arguments dropped (always provide full info)
  - SOME LIST ELEMENT names have been RENAMED/ADDED
  - some double types have become integers
o date time helper functions:
  - properly initialize format settings (with GetUserDefaultLangID, it probably
    incorrectly defaulted to US settings on some systems before)
  - isodatetime format: some time formats added
  - yesterday() and tomorrow() give back dates instead of oledatetimes
o misc. other bugfixes (writing RUnit tests exposes glitches, ahem...)

--- 'technical' ---

o move from Subversion to git
o quite substancial code refactoring


Cheers,
Hans-Peter