[Ogdl-core] New branch is ready

[didge <di...@fo...>]

Folks,

I've just committed a number of new files to the project on a new branch
called DIDGE_001.  As stated previously, the purpose of this branch is to
avoid confusion with the current public release, especially since the new
files represent experimental thinking that the whole team may not want as a
whole.

My main goals with this branch were as follows:
1. Learn OGDL.
2. Create a pull parser that could reproduce the input stream exactly.
3. Provide a serializer for convenient generation of OGDL streams.
4. Clarify some of the ambiguities in the grammar. 
5. Experiment with a simpler package structure.

To access these files, I suggest that you create a new working directory and
then perform a fresh checkout using:
	cvs checkout -r DIDGE_001 java

I've organized the files in this branch as an OGDL Java SDK.  Included are
ant build scripts, examples, documentation, and of course the source.  After
you check it out, you can use Ant to build it by simply executing 'ant' in
the new working directory which will build everything including javadocs.

I did not attempt to bring forward everything that currently exists for Java
into this new branch.  Please don't be alarmed by this.  

What's New and Different

1. Package names.
I've simplified the package names so as to place the most important classes
and interfaces at the top of the hierarchy.  I believe this is more natural
to Java programmers and is more similar to the organization of similar open
source projects.

2. Grammar
The grammar is mostly unchanged from a practical standpoint.  The grammar is
listed in doc/grammar.txt.

Changes include:
	1. Comments are not treated as data.
	2. Extraneous commas and parens are not allowed, but a single 
         trailing comma or empty group is.

3. Parsers
OgdlPullParser
This new class parses OGDL files using the pull style discussed in previous
posts.  There is a standard interface, org.ogdl.OgdlPullParser and a
reference implementation, org.ogdl.reference.OgdlPullParser.

The purpose of the separate interface is to encourage alternative but
interchangeable implementations.

org.ogdl.reference.OgdlPullParser is also executable.  It parses either
stdin or a list of OGDL files specified on the command line.  It then
outputs the result to stdout, stopping on the first syntax error.  If there
is a syntax error, it reports the line number, column number, cause, and the
current line with a pointer to the error.  For example,

$ java -cp lib/ogdl.jar org.ogdl.reference.OgdlPullParser
a\\
a
<stdin>: Unexpected token @ 0:3
a\\
  ^

OgdlPushParser
This class is similar to the existing OgdlParser, but is implemented using
the OgdlPullParser to ensure consistent behavior.  Like OgdlPullParser,
there is both a standard interface and reference implementation provided.

Like org.ogdl.reference.OgdlPullParser, org.ogdl.reference.OgdlPushParser is
also executable and behaves exactly the same.

4. Serializer
org.ogdl.reference.OgdlSerializer supports convenience methods for streaming
OGDL.

5. Not implemented
org.ogdl.reference.OgdlPullParser does not yet implement meta information or
references because I have a few questions about them.

Also not implemented is a flag to the parser to allow it to accept extra
punctuation as discussed in previous posts.

6. Documentation
There is an introduction to the SDK and the javadocs.

Next Steps:
1. I hope that this spurs plenty of discussion.  

2. I plan to start on a C# version shortly.

3. I need to ask some questions regarding meta information, references, and
quotes.


Regards,
  didge