poi-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a...@apache.org
Subject cvs commit: jakarta-poi/src/documentation/content/xdocs poi-ruby.xml book.xml
Date Fri, 18 Feb 2005 06:36:09 GMT
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="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: 1.1 $ $Date: 2005/02/18 06:36:09 $
      </legal>
    </footer>
  </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: poi-dev-unsubscribe@jakarta.apache.org
Mailing List:    http://jakarta.apache.org/site/mail2.html#poi
The Apache Jakarta POI Project: http://jakarta.apache.org/poi/


Mime
View raw message