aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorAvik Sengupta <avik@apache.org>2005-02-18 06:36:09 +0000
committerAvik Sengupta <avik@apache.org>2005-02-18 06:36:09 +0000
commit70ff7397d31f6af164802af6f6f74d32e2af8442 (patch)
tree35522ac937fd6494e93bef905739590de3c56a46 /src
parent1b82f818a6b8dd1832ecef5e15ae979090bfe2a8 (diff)
downloadpoi-70ff7397d31f6af164802af6f6f74d32e2af8442.tar.gz
poi-70ff7397d31f6af164802af6f6f74d32e2af8442.zip
docs for ruby bindings
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353632 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src')
-rw-r--r--src/documentation/content/xdocs/book.xml2
-rw-r--r--src/documentation/content/xdocs/poi-ruby.xml132
-rw-r--r--src/documentation/skinconf.xml2
3 files changed, 135 insertions, 1 deletions
diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml
index fc21386ab1..30f51987ed 100644
--- a/src/documentation/content/xdocs/book.xml
+++ b/src/documentation/content/xdocs/book.xml
@@ -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>
diff --git a/src/documentation/content/xdocs/poi-ruby.xml b/src/documentation/content/xdocs/poi-ruby.xml
new file mode 100644
index 0000000000..4b7d00e9ea
--- /dev/null
+++ b/src/documentation/content/xdocs/poi-ruby.xml
@@ -0,0 +1,132 @@
+<?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="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>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$ $Date$
+ </legal>
+ </footer>
+</document>
diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml
index 1057befdc1..0ad82534fb 100644
--- a/src/documentation/skinconf.xml
+++ b/src/documentation/skinconf.xml
@@ -99,7 +99,7 @@ be used to configure the chosen Forrest skin.
<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
generated by cgit v1.2.3 (git 2.39.1) at 2025-03-15 21:42:49 +0000