This directory contains an example ANTLR grammar for a little
language called OGNL (pronounced OGG-null), which stands for
Object-Graph Navigation Language.  OGNL is an expression language for
setting and getting properties of Java objects, and can be used as is
or as a starting point for other projects.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*                                                                           *
*   Copyright (c) 2002, Drew Davidson and Luke Blanshard                    *
*   All rights reserved.                                                    *
*                                                                           *
*   Redistribution and use in source and binary forms, with or without      *
*   modification, are permitted provided that the following conditions are  *
*   met:                                                                    *
*                                                                           *
*   Redistributions of source code must retain the above copyright notice,  *
*   this list of conditions and the following disclaimer.                   *
*   Redistributions in binary form must reproduce the above copyright       *
*   notice, this list of conditions and the following disclaimer in the     *
*   documentation and/or other materials provided with the distribution.    *
*   Neither the name of the Drew Davidson nor the names of its contributors *
*   may be used to endorse or promote products derived from this software   *
*   without specific prior written permission.                              *
*                                                                           *
*   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS     *
*   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT       *
*   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS       *
*   FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
*   COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,     *
*   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,    *
*   BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS   *
*   OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED      *
*   AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,  *
*   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF   *
*   THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH    *
*   DAMAGE.                                                                 *
*                                                                           *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


1. Overview
===========

  As a tool and a code base, OGNL can be used as is or can be
cannibalized for its parts.  Its possible uses and features include:

  * OGNL was first conceived as a mechanism for associating parts of
    GUIs with model objects.  A single expression is used both to pull
    the appropriate value from the model for display by a widget, and
    to push the newly edited value back into the model when editing is
    complete.

  * OGNL's current syntax includes most of Java's operators and a few
    of its own.  It is probably close to powerful enough to be used by
    a debugger or other system that requires run-time interpretation
    of expressions.

  * OGNL has fully integrated support for arbitrary-precision math, as
    embodied by the classes of the java.math package, meaning that
    OGNL's arithmetic operators work on BigIntegers and BigDecimals as
    well as the primitive types.  While this is of marginal use (at
    best) to OGNL as a GUI hooker-upper, it could be valuable in other
    settings.


2. Building
===========

  OGNL was designed for JDK 1.2 (now known as Java 2).  It is possible
to modify the code to run under 1.1, though the extensive use of the
1.2 collections API makes this a bit painful.  If you have the JDK 1.1
version of the 1.2 collections, which was made available in the summer
of 1998 by the InfoBus group at Sun (and still available in June 1999
at http://java.sun.com/beans/infobus), the job will be easier.

  If you have GNU make, the GNUmakefile provided will build the OGNL
package, run the test program, and use javadoc to produce API
documentation; all on NT, Win98 or Unix systems.  Please see that
file for more information on what build targets are available.


3. Documentation
================

  OGNL is documented in the accompanying file "package.html", which is
used by javadoc as the ognl package description.  The best way to view
this is to generate javadoc (using "make doc" if you have GNU make),
and then open the generated file "index.html" in the javadoc-created
"doc" subdirectory, using your favorite HTML browser.  The package
description will be below the lists of interfaces and classes.

  The accompanying test program, Test.java, can be thought of as
"practical documentation."


4. Feedback
===========

  If you have any observations or complaints about OGNL or its
implementation or documentation, we would like to hear from you.  You
can reach Luke Blanshard by email at luke@quiq.com, or Drew Davidson at
drew@ognl.org.