1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
<?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 V2.0//EN" "document-v20.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 <a href="https://gcc.gnu.org/java/">gcj</a>,
and generating the Ruby wrapper using <a href="https://www.swig.org">SWIG</a>. 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>Source Repository</title>
<p>
The POI-Ruby module sits under the POI <a href="https://github.com/apache/poi/tree/trunk/src/contrib/poi-ruby/">Git</a>.
Running <em>make</em> inside that directory will create a loadable ruby extension <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 across 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 <a href="https://www.apache.org/~avik/dist/poi4r.so">here</a> (broken 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 <a href="spreadsheet/quick-guide.html">quick guide </a> 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 <a href="site:javadocs">POI API documentation</a> 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 <a href="https://www.rubygems.org">gem</a>.</li>
</ul>
</section>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>
|
