avik 2005/02/17 22:36:09
Modified: src/documentation skinconf.xml
src/documentation/content/xdocs book.xml
Added: src/documentation/content/xdocs poi-ruby.xml
Log:
docs for ruby bindings
Revision Changes Path
1.10 +1 -1 jakarta-poi/src/documentation/skinconf.xml
Index: skinconf.xml
===================================================================
RCS file: /home/cvs/jakarta-poi/src/documentation/skinconf.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- skinconf.xml 9 Apr 2004 13:05:14 -0000 1.9
+++ skinconf.xml 18 Feb 2005 06:36:09 -0000 1.10
@@ -99,7 +99,7 @@
<host-logo></host-logo>
<!-- The following are used to construct a copyright statement -->
- <year>2002-2003</year>
+ <year>2002-2005</year>
<vendor>The Apache Software Foundation.</vendor>
<!-- Some skins use this to form a 'breadcrumb trail' of links. If you
don't
1.18 +2 -0 jakarta-poi/src/documentation/content/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-poi/src/documentation/content/xdocs/book.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- book.xml 1 Jan 2005 06:59:32 -0000 1.17
+++ book.xml 18 Feb 2005 06:36:09 -0000 1.18
@@ -21,6 +21,7 @@
<menu-item label="HSSF" href="hssf/index.html"/>
<menu-item label="HWPF" href="hwpf/index.html"/>
<menu-item label="HPSF" href="hpsf/index.html"/>
+ <menu-item label="POI-Ruby" href="poi-ruby.html"/>
<menu-item label="POI-Utils" href="utils/index.html"/>
<menu-item label="Download" href="ext:download"/>
</menu>
@@ -51,6 +52,7 @@
<menu-item label="Guidelines" href="trans/guidelines.html"/>
<menu-item label="German (DE)" href="trans/de/index.html"/>
<menu-item label="Spanish (ES)" href="trans/es/index.html"/>
+ <menu-item label="French (FR)" href="trans/fr/index.html"/>
<menu-item label="Japanese (Web)"
href="http://jakarta.terra-intl.com/poi/"/>
<menu-item label="Korean (Web)"
href="http://jakarta.apache-korea.org/poi/"/>
</menu>
1.1 jakarta-poi/src/documentation/content/xdocs/poi-ruby.xml
Index: poi-ruby.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2005 The Apache Software Foundation. All rights reserved.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"./dtd/document-v11.dtd">
<document>
<header>
<title>POI Ruby Bindings</title>
<authors>
<person id="AS" name="Avik Sengupta" email="[EMAIL PROTECTED]"/>
</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>CVS</title>
<p>
The POI-Ruby module sits under the POI <link
href="http://jakarta.apache.org/site/cvsindex.html";>CVS</link> in the
<em>src/contrib/poi-ruby</em> directory. 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="hssf/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.
$Revision: 1.1 $ $Date: 2005/02/18 06:36:09 $
</legal>
</footer>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
Mailing List: http://jakarta.apache.org/site/mail2.html#poi
The Apache Jakarta POI Project: http://jakarta.apache.org/poi/
