| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| ==================================================================== |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| ==================================================================== |
| --> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd"> |
| |
| <document> |
| <header> |
| <title>POI Ruby Bindings</title> |
| <authors> |
| <person id="AS" name="Avik Sengupta" email="avik@apache.org"/> |
| </authors> |
| </header> |
| |
| <body> |
| <section><title>Intro</title> |
| <p>The POI library can now be compiled as a Ruby extension, allowing the API to be called from |
| Ruby language programs. Ruby users can therefore read and write OLE2 documents, such as Excel files |
| with ease |
| </p> |
| <p>The bindings are generated by compiling POI with <link href="http://gcc.gnu.org/java/">gcj</link>, |
| and generating the Ruby wrapper using <link href="http://www.swig.org">SWIG</link>. The aim is the keep |
| the POI api as-is. However, where java standard library objects are used, an effort is made to transform them smoothly |
| into Ruby objects. Therefore, where the POI API takes an OutputStream, you can pass an IO object. Where the POI works |
| java.util.Date or java.util.Calendar object, you can work with a Ruby Time object. </p> |
| </section> |
| |
| |
| <section><title>Getting Started</title> |
| <section><title>Pre-Requisites</title> |
| <p>The bindings have been developed with GCC 3.4.3 and Ruby 1.8.2. You are unlikely to get correct results with |
| versions of GCC prior to 3.4 or versions of Ruby prior to 1.8. To compile the Ruby extension, you must have |
| GCC (compiled with java language support), Ruby development headers, and SWIG. To run, you will need Ruby (obviously!) and |
| <em>libgcj </em>, presumably from the same version of GCC with which you compiled. |
| </p> |
| </section> |
| <section><title>Subversion</title> |
| <p> |
| The POI-Ruby module sits under the POI <link href="http://svn.apache.org/repos/asf/poi/trunk/src/contrib/poi-ruby/">Subversion</link>. Running <em>make</em> |
| inside that directory will create a loadable ruby extention <em>poi4r.so</em> in the release subdirectory. Tests |
| 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. |
| </p> |
| <p>Note that the makefile, though designed to work accross Linux/OS X/Cygwin, has been tested only on linux. |
| There are likely to be issues on other platform; fixes gratefully accepted! </p> |
| </section> |
| <section><title>Binary</title> |
| <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 |
| with GCC 3.4.3 and Ruby 1.8.2. It dynamically links to libgcj. No guarantees about working on any other box. </p> |
| </section> |
| </section> |
| |
| |
| |
| |
| <section> |
| <title>Usage</title> |
| <p>The following ruby code shows some of the things you can do with POI in Ruby</p> |
| <source> |
| h=Poi4r::HSSFWorkbook.new |
| #Test Sheet Creation |
| s=h.createSheet("Sheet1") |
| |
| #Test setting cell values |
| s=h.getSheetAt(0) |
| r=s.createRow(0) |
| c=r.createCell(0) |
| c.setCellValue(1.5) |
| |
| c=r.createCell(1) |
| c.setCellValue("Ruby") |
| |
| #Test styles |
| st = h.createCellStyle() |
| c=r.createCell(2) |
| st.setAlignment(Poi4r::HSSFCellStyle.ALIGN_CENTER) |
| c.setCellStyle(st) |
| c.setCellValue("centr'd") |
| |
| #Date handling |
| c=r.createCell(3) |
| t1=Time.now |
| c.setCellValue(Time.now) |
| t2= c.getDateCellValue().gmtime |
| |
| st=h.createCellStyle(); |
| st.setDataFormat(Poi4r::HSSFDataFormat.getBuiltinFormat("m/d/yy h:mm")) |
| c.setCellStyle(st) |
| |
| #Formulas |
| c=r.createCell(4) |
| c.setCellFormula("A1*2") |
| c.getCellFormula() |
| |
| #Writing |
| h.write(File.new("test.xls","w")) |
| </source> |
| <p> The <em>tc_base_tests.rb</em> file in the <em>tests</em> sub directory of the source distribution |
| contains examples of simple uses of the API. The <link href="spreadsheet/quick-guide.html">quick quide </link> is the best |
| place to learn HSSF API use. (Note however that none of the Drawing features are implemented in the Ruby binding.) |
| See also the <link href="apidocs/overview-summary.html">POI API documentation</link> for more details. |
| </p> |
| </section> |
| |
| <section> |
| <title>Future Directions</title> |
| <section><title>TODO's</title> |
| <ul> |
| <li>Implement support for reading Excel files (easy)</li> |
| <li>Expose POIFS API to read raw OLE2 files from Ruby</li> |
| <li>Expose HPSF API to read property streams </li> |
| <li>Tests... Tests... Tests...</li> |
| </ul> |
| </section> |
| <section><title>Limitations</title> |
| <ul> |
| <li>Check operations in 64bit machines - Java primitive types are fixed irrespective of machine type, unlike C/C++ types. The wrapping code |
| that converts C/C++ primitive types to/from Java types is making assumptions on type sizes that MAY be incorrect on wide architectures. </li> |
| <li>The current implementation is with the POI 2.0 release. The 2.5 release adds support for Excel drawing primitives, and |
| 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> |
| <li>Packaging - The current make file makes no effort to install the extension into the standard ruby directories. This should probably be |
| packaged as a <link href="http://www.rubygems.org">gem</link>.</li> |
| </ul> |
| </section> |
| |
| </section> |
| |
| </body> |
| <footer> |
| <legal> |
| Copyright 2005 The Apache Software Foundation or its licensors, as applicable. |
| </legal> |
| </footer> |
| </document> |