src/documentation/content/xdocs/spreadsheet/formula.xml - poi - Git at Google

 <?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.1//EN" "../dtd/document-v11.dtd">

 <document>
     <header>
         <title>Formula Support</title>
         <authors>
             <person email="avik@apache.org" name="Avik Sengupta" id="AS"/>
         </authors>
     </header>
     <body>
         <section><title>Introduction</title>
             <p>
                 This document describes the current state of formula support in POI.
                 The information in this document currently applies to the 2.0 version of POI.
                 Since this area is a work in progress, this document will be updated with new features as and
                 when they are added.
             </p>

         </section>
         <section><title>The basics</title>
               <p>
                 In org.apache.poi.hssf.usermodel.HSSFCell
                     <strong> setCellFormula(&quot;formulaString&quot;) </strong> is used to add a formula to sheet and
                     <strong> getCellFormula() </strong> is used to retrieve the string representation of a formula.
                 </p>
             <p>
                 We aim to support the complete excel grammer for formulas. Thus, the string that you pass in
                 to the <em> setCellFormula </em> call should be what you expect to type into excel. Also, note
                 that you should NOT add a "=" to the front of the string.
             </p>
         </section>
         <section><title>Supported Features</title>
         <ul>
              <li>Cell References</li>
              <li>String, integer and floating point literals</li>
               <li>Area references</li>
               <li>Relative or absolute references</li>
               <li>Arithmetic and logical operators</li>
               <li>Sheet or Macro Functions (inlcuding logical functions)</li>
               <li>Sheet References</li>
               <li>Formual return values (number or string)</li>
         </ul>
         </section>
         <section><title>Partially supported</title>
             <ul>
                 <li>Formula tokens in Excel are stored in one of three possible <em> classes </em>:
                     Reference, Value and Array. Based on the location of a token, its class can change
                     in complicated and undocumented ways. While we have support for most cases, we
                     are not sure if we have covered all bases (since there is no documentation for this area.)
                     We would therefore like you to report any
                     occurence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that
                     typing the formula into Excel directly gives a valid result.)
             </li>

             </ul>
         </section>
         <section><title>Not yet supported</title>
             <ul>
                 <li>Array formulas</li>
                 <li>Unary Operators</li>
                 <li>3D References</li>
                 <li>Error Values (cells containing #REF's or #VALUE's)</li>
                 <li>Everything else :) </li>
             </ul>
         </section>

         <section><title>Internals</title>
             <p>
                 Formulas in Excel are stored as  sequences of tokens in Reverse Polish Notation order. The
                 <link href="http://sc.openoffice.org/excelfileformat.pdf">open office XLS spec</link> is the best
                 documentation you will find for the format.
             </p>

             <p>
                 The tokens used by excel are modelled as individual *Ptg classes in the <strong>
                 org.apache.poi.hssf.record.formula</strong> package.
             </p>
             <p>
                 The task of parsing a formula string into an array of RPN ordered tokens is done by the <strong>
                 org.apache.poi.hssf.record.formula.FormulaParser</strong> class. This class implements a hand
                 written recursive descent parser.
             </p>
             <p>Check out the <link href="http://poi.apache.org/apidocs/">javadocs </link> for details.
             </p>
         </section>

     </body>
 </document>
	<?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.1//EN" "../dtd/document-v11.dtd">

	<document>
	<header>
	<title>Formula Support</title>
	<authors>
	<person email="avik@apache.org" name="Avik Sengupta" id="AS"/>
	</authors>
	</header>
	<body>
	<section><title>Introduction</title>
	<p>
	This document describes the current state of formula support in POI.
	The information in this document currently applies to the 2.0 version of POI.
	Since this area is a work in progress, this document will be updated with new features as and
	when they are added.
	</p>

	</section>
	<section><title>The basics</title>
	<p>
	In org.apache.poi.hssf.usermodel.HSSFCell
	<strong> setCellFormula("formulaString") </strong> is used to add a formula to sheet and
	<strong> getCellFormula() </strong> is used to retrieve the string representation of a formula.
	</p>
	<p>
	We aim to support the complete excel grammer for formulas. Thus, the string that you pass in
	to the <em> setCellFormula </em> call should be what you expect to type into excel. Also, note
	that you should NOT add a "=" to the front of the string.
	</p>
	</section>
	<section><title>Supported Features</title>
	<ul>
	<li>Cell References</li>
	<li>String, integer and floating point literals</li>
	<li>Area references</li>
	<li>Relative or absolute references</li>
	<li>Arithmetic and logical operators</li>
	<li>Sheet or Macro Functions (inlcuding logical functions)</li>
	<li>Sheet References</li>
	<li>Formual return values (number or string)</li>
	</ul>
	</section>
	<section><title>Partially supported</title>
	<ul>
	<li>Formula tokens in Excel are stored in one of three possible <em> classes </em>:
	Reference, Value and Array. Based on the location of a token, its class can change
	in complicated and undocumented ways. While we have support for most cases, we
	are not sure if we have covered all bases (since there is no documentation for this area.)
	We would therefore like you to report any
	occurence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that
	typing the formula into Excel directly gives a valid result.)
	</li>

	</ul>
	</section>
	<section><title>Not yet supported</title>
	<ul>
	<li>Array formulas</li>
	<li>Unary Operators</li>
	<li>3D References</li>
	<li>Error Values (cells containing #REF's or #VALUE's)</li>
	<li>Everything else :) </li>
	</ul>
	</section>

	<section><title>Internals</title>
	<p>
	Formulas in Excel are stored as sequences of tokens in Reverse Polish Notation order. The
	<link href="http://sc.openoffice.org/excelfileformat.pdf">open office XLS spec</link> is the best
	documentation you will find for the format.
	</p>

	<p>
	The tokens used by excel are modelled as individual *Ptg classes in the <strong>
	org.apache.poi.hssf.record.formula</strong> package.
	</p>
	<p>
	The task of parsing a formula string into an array of RPN ordered tokens is done by the <strong>
	org.apache.poi.hssf.record.formula.FormulaParser</strong> class. This class implements a hand
	written recursive descent parser.
	</p>
	<p>Check out the <link href="http://poi.apache.org/apidocs/">javadocs </link> for details.
	</p>
	</section>

	</body>
	</document>