Read and write Excel files

Description:

       1. Overview

       2. CRAN/pro versions

       3. RUnit tests

       4. Future plans

       5. Download and compilation

       6. Links and contact

1. Overview:

     'xlsReadWrite' is a packages which allows to read and write Excel
     files.  Currently supported is the .xls (BIFF8) file format.

     *Getting started*

        * check out 'read.xls', 'write.xls' and 'xls.getshlib'

        * type: 'help(package = "xlsReadWrite")' for more information

     *Why xlsReadWrite?*

        * it is fast

        * well documented and (RUnit) tested

        * the package does _not_ have any external dependencies

        * it has a nice simple interface and _just works fine_ since ~4
          years

     On the less rosy side: xlsReadWrite still is windows only and uses
     proprietary 3rd party code (which means only our own code is, and
     can be, free). The package is written in Pascal, a very nice but
     rather obscure language in the R world.
     *Other solutions*

     xlsReadWrite is not the only game in town, we know of the
     following packages (brackets indicate dependencies): _RODBC_
     (drivers), _gdata_ (Perl), _RExcel_ or _COM_ (Excel),
     _dataframes2xls_ (Python), _xlsx_ (Apache POI, Java). Last but not
     least, you may use plain old _.csv_ files (none) or consider our
     own _xlsReadWritePro_ (none) shareware package.

2. CRAN/pro versions:

     Besides the regular xlsReadWrite package there is a special 'CRAN'
     version.
     Reason (as copied from the startup message):
     _BACKGROUND: Our own xlsReadWrite code is free, but we also use
     proprietary code_
     _(Flexcel, tmssoftware.com) which can only be distributed legally
     in precompiled,_
     _i.e. binary form. As CRAN 'generally does not accept submissions
     of precompiled_
     _binaries due to security reasons' we only provide a placeholder
     and you can_
     _download the binary shlib separately._
     The 'xlsReadWritePro' version is our second attempt and goes
     further than the free version:

        * append data to existing files

        * work with in-memory Excel 'files' (called xls-obj)

        * manage sheets (select, insert, copy, rename, delete, hide,
          info, list)

        * support images (add, delete, count, list, export, info)

        * address confined data areas (rows, cols, from, to, (named)
          ranges, cells)

        * read and write formula values

        * get file and sheet related info

        * more date time helper functions

        * formal support

     By purchasing the 'xlsReadWritePro' shareware version you help
     support our development and maintenance effort. We are grateful
     that quite some people and companies did and both, the free and
     the pro version shall benefit. The trial (http://www.swissr.org)
     is free and the two versions do coexist just fine.  So, why not
     check out 'xlsReadWritePro' now and see for yourself?

3. RUnit tests:

     There are more than 50 unit tests which should cover every aspect
     of the package and ensure and maintain code quality. The tests
     also serve as an extended reference going beyond the examples.

     You can easily run the tests on your system, the RUnit test files
     are located at:

        * 'R_HOME/library/xlsReadWrite/unitTest/runit*.R'

        * 'R_HOME/library/xlsReadWrite/unitTest/execManually.R' (exec
          details)

4. Future plans:

     xlsReadWrite is mature and no big changes are planned. Certainly
     some internal refactoring would be beneficial and some features
     could be backported from the pro version.

     In 2011 Delphi should be released for Mac, Linux and Win64, and we
     plan to support these platforms eventually. The underlying library
     is being developed for .xlsx and we are looking forward to it
     (probably as a separate package).

5. Download and compilation:

       Current version:    <URL: http://www.swissr.org/download>                                 
         All resources:    <URL: http://dl.dropbox.com/u/2602516/swissrpkg/index.html>           
           Github repo:    <URL: http://github.com/swissr/xlsReadWrite>                          
                  CRAN:    <URL: http://cran.r-project.org/web/packages/xlsReadWrite/index.html> 
      
     *Compilation*

     Prerequisites for compiling: Delphi 2007 and Flexcel
     (http://www.tmssoftware.com, the core library doing the
     Excel-work). Then follow these steps:

       1. Clone the github repo and initialize the RPascal submodule

       2. Adapt paths in 'include.mk'

       3. Regarding Flexcel code:

            * in FLXCOMPILER.INC: disable the FLEXCEL define'

            * 'src/pas/vFlexcelCommits.txt' has the currently used
              Flexcel version

       4. Run 'make <target>' in cmd.exe (system path will be modified
          temporarily)

       5. Alternatively compile/run project in the Delphi IDE.

6. Links and contact:

       General info:    <URL: http://www.swissr.org>                              
         Bugtracker:    <URL: http://dev.swissr.org/projects/xlsReadWrite>        
              Forum:    <URL: http://dev.swissr.org/projects/xlsReadWrite/boards> 
              Email:    support at swissr.org                                     
      
     November 21, 2010 / Hans-Peter