src/documentation/content/xdocs/poi-ruby.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    ====================================================================
   4    Licensed to the Apache Software Foundation (ASF) under one or more
   5    contributor license agreements.  See the NOTICE file distributed with
   6    this work for additional information regarding copyright ownership.
   7    The ASF licenses this file to You under the Apache License, Version 2.0
   8    (the "License"); you may not use this file except in compliance with
   9    the License.  You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18    ====================================================================
  19 -->
  20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
  21
  22 <document>
  23   <header>
  24     <title>POI Ruby Bindings</title>
  25     <authors>
  26       <person id="AS" name="Avik Sengupta" email="avik@apache.org"/>
  27     </authors>
  28   </header>
  29
  30   <body>
  31     <section><title>Intro</title>
  32       <p>The POI library can now be compiled as a Ruby extension, allowing the API to be called from
  33       Ruby language programs. Ruby users can therefore read and write OLE2 documents, such as Excel files
  34       with ease
  35       </p>
  36       <p>The bindings are generated by compiling POI with <link href="http://gcc.gnu.org/java/">gcj</link>,
  37       and generating the Ruby wrapper using <link href="http://www.swig.org">SWIG</link>.  The aim is the keep
  38       the POI api as-is. However, where java standard library objects are used, an effort is made to transform them smoothly
  39       into  Ruby objects. Therefore, where the POI API takes an OutputStream, you can pass an IO object. Where the POI works
  40       java.util.Date or java.util.Calendar object, you can work with a Ruby Time object. </p>
  41     </section>
  42
  43
  44       <section><title>Getting Started</title>
  45         <section><title>Pre-Requisites</title>
  46         <p>The bindings have been developed with GCC 3.4.3 and Ruby 1.8.2. You are unlikely to get correct results with
  47         versions of GCC prior to 3.4 or versions of Ruby prior to 1.8. To compile the Ruby extension, you must have
  48         GCC (compiled with java language support), Ruby development headers, and SWIG. To run, you will need Ruby (obviously!) and
  49         <em>libgcj </em>, presumably from the same version of GCC with which you compiled.
  50         </p>
  51         </section>
  52         <section><title>Subversion</title>
  53         <p>
  54         The POI-Ruby module sits under the POI <link href="http://jakarta.apache.org/site/cvsindex.html">Subversion</link> in the <em>src/contrib/poi-ruby</em> directory. Running <em>make</em>
  55         inside that directory will create a loadable ruby extention <em>poi4r.so</em> in the release subdirectory. Tests
  56         are in the <em>tests/</em> subdirectory, and should be run from the <em>poi-ruby</em> directory. Please read the tests to figure out the usage.
  57         </p>
  58         <p>Note that the makefile, though designed to work accross Linux/OS X/Cygwin, has been tested only on linux.
  59         There are likely to be issues on other platform; fixes gratefully accepted! </p>
  60       </section>
  61       <section><title>Binary</title>
  62         <p>A version of poi4r.so is available <link href="http://www.apache.org/~avik/dist/poi4r.so">here</link>. Its been compiled on a linux box
  63         with GCC 3.4.3 and Ruby 1.8.2. It dynamically links to libgcj. No guarantees about working on any other box.  </p>
  64         </section>
  65       </section>
  66
  67
  68
  69
  70     <section>
  71       <title>Usage</title>
  72       <p>The following ruby code shows some of the things you can do with POI in Ruby</p>
  73         <source>
  74         h=Poi4r::HSSFWorkbook.new
  75         #Test Sheet Creation
  76         s=h.createSheet("Sheet1")
  77
  78         #Test setting cell values
  79         s=h.getSheetAt(0)
  80         r=s.createRow(0)
  81         c=r.createCell(0)
  82         c.setCellValue(1.5)
  83
  84         c=r.createCell(1)
  85         c.setCellValue("Ruby")
  86
  87         #Test styles
  88         st = h.createCellStyle()
  89         c=r.createCell(2)
  90         st.setAlignment(Poi4r::HSSFCellStyle.ALIGN_CENTER)
  91         c.setCellStyle(st)
  92         c.setCellValue("centr'd")
  93
  94         #Date handling
  95         c=r.createCell(3)
  96         t1=Time.now
  97         c.setCellValue(Time.now)
  98         t2= c.getDateCellValue().gmtime
  99
 100         st=h.createCellStyle();
 101         st.setDataFormat(Poi4r::HSSFDataFormat.getBuiltinFormat("m/d/yy h:mm"))
 102         c.setCellStyle(st)
 103
 104         #Formulas
 105         c=r.createCell(4)
 106         c.setCellFormula("A1*2")
 107         c.getCellFormula()
 108
 109         #Writing
 110         h.write(File.new("test.xls","w"))
 111       </source>
 112       <p>  The <em>tc_base_tests.rb</em> file in the <em>tests</em> sub directory of the source distribution
 113       contains examples of simple uses of the API. The <link href="hssf/quick-guide.html">quick quide </link> is the best
 114       place to learn HSSF API use. (Note however that none of the Drawing features are implemented in the Ruby binding.)
 115        See also the <link href="apidocs/overview-summary.html">POI API documentation</link>  for more details.
 116        </p>
 117     </section>
 118
 119     <section>
 120       <title>Future Directions</title>
 121         <section><title>TODO's</title>
 122         <ul>
 123         <li>Implement support for reading Excel files (easy)</li>
 124         <li>Expose POIFS API to read raw OLE2 files from Ruby</li>
 125         <li>Expose HPSF API to read property streams </li>
 126         <li>Tests... Tests... Tests...</li>
 127         </ul>
 128         </section>
 129         <section><title>Limitations</title>
 130         <ul>
 131         <li>Check operations in 64bit machines - Java primitive types are fixed irrespective of machine type, unlike C/C++ types. The wrapping code
 132         that converts C/C++ primitive types to/from Java types is making assumptions on type sizes that MAY be incorrect on wide architectures. </li>
 133         <li>The current implementation is with the POI 2.0 release. The 2.5 release adds support for Excel drawing primitives, and
 134       thus has a dependency on java AWT. Since AWT is not very mature in gcj, leaving it out seemed to be the safer option.</li>
 135       <li>Packaging - The current make file makes no effort to install the extension into the standard ruby directories. This should probably be
 136       packaged as a <link href="http://www.rubygems.org">gem</link>.</li>
 137         </ul>
 138         </section>
 139
 140       </section>
 141
 142   </body>
 143   <footer>
 144     <legal>
 145       Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
 146       $Revision$ $Date$
 147     </legal>
 148   </footer>
 149 </document>