Finish (more or less) to CQL-to-PQF translator.

[cql-java-moved-to-github.git] / README

diff --git a/README b/README
index ed5afc8..a508b3d 100644 (file)
--- a/README
+++ b/README
@@ -1,15 +1,22 @@
-$Id: README,v 1.7 2002-10-31 22:22:01 mike Exp $
+$Id: README,v 1.15 2002-11-06 20:13:45 mike Exp $

 
 

-cql-java -- a free CQL compiler for Java
+cql-java - a free CQL compiler, and other CQL tools, for Java

 
 
 
 

-This project provides a set of classes for representing a CQL parse
-tree (CQLBooleanNode, CQLTermNode, etc.) and a CQLCompiler class which
-builds a parse tree given a CQL query as input.  It also provides
-compiler back-ends to render out the parse tree as XCQL (the XML
-representation), as PQF (Yaz-style Prefix Query Format) and as CQL
-(i.e. decompiling the parse-tree).  Oh, and there's a random query
-generator, too.
+INTRODUCTION
+------------
+
+cql-java is a Free Software project that provides:
+
+* A set of classes for representing a CQL parse tree (a base CQLNode
+  class, CQLBooleanNode and its subclasses, CQLTermNode, etc.)
+* A CQLCompiler class (and its lexer) which builds a parse tree given
+  a CQL query as input.
+* A selection of compiler back-ends to render out the parse tree as:
+       * XCQL (the standard XML representation)
+       * CQL (i.e. decompiling the parse-tree)
+       * PQF (Yaz-style Prefix Query Format)
+* A random query generator, useful for testing.

 
 CQL is "Common Query Language", a new query language designed under
 the umbrella of the ZING initiative (Z39.59-International Next
 
 CQL is "Common Query Language", a new query language designed under
 the umbrella of the ZING initiative (Z39.59-International Next

@@ -24,52 +31,76 @@ which is supposed to be easier to parse.  More information at
 But if you didn't know that, why are you even reading this?  :-)
 
 
 But if you didn't know that, why are you even reading this?  :-)
 
 

+What's what in this distribution?
+
+       README  This file
+       VERSION The version-number of this distribution
+       src     Source-code for the cql-java library
+       lib     The compiled library file, "cql-java.jar"
+       bin     Simple shell-scripts to invoke the test-harnesses
+       docs    Documentation automatically generated by "javadoc"
+       test    Various testing and sanity-checking frameworks
+       etc     Other files: CQL Grammar, generator properties, etc.
+
+"Installation" of this package would consist of putting the bin
+directory on your PATH and the lib directory on your CLASSPATH.
+
+

 SYNOPSIS
 --------
 
 SYNOPSIS
 --------
 

-Test-harness:
+Using the test-harnesses:

 
 

-       $ echo "foo and (bar or baz)" | java org.z3950.zing.cql.CQLParser
+       $ CQLParser 'title=foo and author=(bar or baz)'
+       $ CQLLexer 'title=foo and author=(bar or baz)'
+               (not very interesting unless you're debugging)
+       $ CQLGenerator etc/generate.properties seed 18

 
 

-Library:
+Using the library in your own applications:

 
        import org.z3950.zing.cql.*
 
        // Building a parse-tree by hand
 
        import org.z3950.zing.cql.*
 
        // Building a parse-tree by hand

-       CQLNode n1 = new CQLTermNode("dc.author", "=", "kernighan");
-       CQLNode n2 = new CQLTermNode("dc.title", "all", "elements style");
+       CQLNode n1 = new CQLTermNode("dc.author", new CQLRelation("="),
+                                    "kernighan");
+       CQLNode n2 = new CQLTermNode("dc.title", new CQLRelation("all"),
+                                    "elements style");

        CQLNode root = new CQLAndNode(n1, n2);
        CQLNode root = new CQLAndNode(n1, n2);

-       System.out.println(root.toXCQL(3));
+       System.out.println(root.toXCQL(0));

 
        // Parsing a CQL query
        CQLParser parser = new CQLParser();
        CQLNode root = parser.parse("title=dinosaur");
 
        // Parsing a CQL query
        CQLParser parser = new CQLParser();
        CQLNode root = parser.parse("title=dinosaur");

-       System.out.println(root.toXCQL(0));
+       System.out.print(root.toXCQL(0));

        System.out.println(root.toCQL());
        System.out.println(root.toCQL());

-       System.out.println(root.toPQF(qualSet));
-       // ... where `qualSet' specifies CQL-qualfier => Z-attr mapping
+       System.out.println(root.toPQF(config));
+       // ... where `config' specifies CQL-qualfier => Z-attr mapping

 
 
 DESCRIPTION
 -----------
 
 See the automatically generated class documentation in the "doc"
 
 
 DESCRIPTION
 -----------
 
 See the automatically generated class documentation in the "doc"

-subdirectory.  (It's not all there yet, but it's coming.)
+subdirectory.

 
 
 AUTHOR
 ------
 
 
 
 AUTHOR
 ------
 

-Mike Taylor <mike@z3950.org>
-http://www.miketaylor.org.uk
+All code and documentation by Mike Taylor <mike@z3950.org>
+       http://www.miketaylor.org.uk
+Please email me with bug-reports, wishlist items, patches, deployment
+stories and, of course, large cash donations.

 
 
 LICENCE
 -------
 
 
 
 LICENCE
 -------
 

-This software is open source, but I've not yet decided exactly what
+This software is Open Source, but I've not yet decided exactly what

 licence to use.  Be good.  Assume I'm going with the GPL (most
 licence to use.  Be good.  Assume I'm going with the GPL (most

-restrictive) until I say otherwise.
+restrictive) until I say otherwise.  For what it's worth, I think the
+most likely licence is the LGPL (GNU's Lesser General Public Licence)
+which lets you deploy cql-java as a part of a non-free larger work.

 
 
 SEE ALSO
 
 
 SEE ALSO

@@ -80,45 +111,31 @@ Rob Sanderson's CQL compiler, written in Python.
 All the other free CQL compilers everyone's going to write  :-)
 
 
 All the other free CQL compilers everyone's going to write  :-)
 
 

-TO DO
------
-
-* Add proximity support to parser -- just the back-ends left to do.
+THINGS TO DO
+------------

 
 

-* Relation modifiers could be limited to known modifiers only.
+* ### Fix bug where "9x" is parsed as two tokens, a TT_NUMBER followed
+  by a TT_WORD.  The problem here is that I don't think it's actually
+  possible to fix this without throwing out StreakTokenizer and
+  rolling our own, which we absolutely _don't_ want to do.

 
 

-* Fix CQLParser and CQLLexer shell-script front-ends to elegantly
-  handle their classes' test harnesses' ability to read the query from
-  the command-line arguments, if any, falling back to stdin if there
-  are none.
+* Write javadoc comments for CQLRelation and ModifierSet.

 
 

-* Add CQLGenerate shell-script.  Allow CQLGenerate test-harness to
-  take some arguments on command-line as well as or instead of a
-  file.
+* Write "overview" file for the javadoc documentation.

 
 

-* Trivial CQLCanonicalise application, which renders out its source
-  tree in a canonical form, enabling queries to be diffed for
-  semantically significant differences only.  Tests can be run by
-  generating random trees, canonicalising them, then canonicalising
-  them _again_ and checking that the before-and-after results are the
-  same.
+* Allow keywords to be used unquoted as search terms.

 
 * Some niceties for the cql-decompiling back-end:
        * don't emit redundant parentheses.
        * don't put spaces around relations that don't need them.
 
 
 * Some niceties for the cql-decompiling back-end:
        * don't emit redundant parentheses.
        * don't put spaces around relations that don't need them.
 

-* Write pqn-generating back-end (will need to be driven from a
-  configuation file specifying how to represent the qualifiers,
-  relations, relation modifiers and wildcard characters as z39.50
-  attributes.)
-

 * Consider the utility of yet another back-end that translates a
 * Consider the utility of yet another back-end that translates a

-  cqlnode tree into a type-1 query tree using the jzkit data
+  CQLNode tree into a Type-1 query tree using the JZKit data

   structures.  That would be nice so that CQL could become a JZKit
   structures.  That would be nice so that CQL could become a JZKit

-  query-type, but you could achieve the same effect by generating PQN,
+  query-type; but you could achieve the same effect by generating PQN,

   and running that through JZKit's existing PQN-to-Type-1 compiler.
 
   and running that through JZKit's existing PQN-to-Type-1 compiler.
 

-* Refinements to random query generator:
+* Many refinements to the random query generator:

        * Generate relation modifiers
        * Proximity support
        * Don't always generate qualifier/relation for terms
        * Generate relation modifiers
        * Proximity support
        * Don't always generate qualifier/relation for terms

@@ -127,7 +144,3 @@ TO DO
        * Introduce wildcard characters into generated terms
        * Generate multi-word terms
 
        * Introduce wildcard characters into generated terms
        * Generate multi-word terms
 

-* Write fuller "javadoc" comments.
-
-* Write generic test suite.
-