149 lines
6.2 KiB
XML
149 lines
6.2 KiB
XML
<?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>
|