README

   1 $Id: README,v 1.11 2002-11-03 17:37:14 mike Exp $
   2
   3 cql-java - a free CQL compiler, and other CQL tools, for Java
   4
   5
   6 INTRODUCTION
   7 ------------
   8
   9 cql-java is a Free Software project that provides:
  10
  11 * A set of classes for representing a CQL parse tree (a base CQLNode
  12   class, CQLBooleanNode and its subclasses, CQLTermNode, etc.)
  13 * A CQLCompiler class (and its lexer) which builds a parse tree given
  14   a CQL query as input.
  15 * A selection of compiler back-ends to render out the parse tree as:
  16         * XCQL (the standard XML representation)
  17         * CQL (i.e. decompiling the parse-tree)
  18         * PQF (Yaz-style Prefix Query Format) [### NOT YET]
  19 * A random query generator, useful for testing.
  20
  21 CQL is "Common Query Language", a new query language designed under
  22 the umbrella of the ZING initiative (Z39.59-International Next
  23 Generation).  More information at
  24         http://zing.z3950.org/cql/index.html
  25
  26 XCQL is "XML CQL", a representation of CQL-equivalent queries in XML
  27 which is supposed to be easier to parse.  More information at
  28         http://www.loc.gov/z3950/agency/zing/srwu/xcql.html
  29 (not much more, though)
  30
  31 But if you didn't know that, why are you even reading this?  :-)
  32
  33
  34 What's what in this distribution?
  35
  36         README  This file
  37         VERSION The version-number of this distribution
  38         src     Source-code for the cql-java library
  39         lib     The compiled library file, "cql-java.jar"
  40         bin     Simple shell-scripts to invoke the test-harnesses
  41         docs    Documentation automatically generated by "javadoc"
  42         test    Various testing and sanity-checking frameworks
  43         etc     Other files: CQL Grammar, generator properties, etc.
  44
  45 "Installation" of this package would consist of putting the bin
  46 directory on your PATH and the lib directory on your CLASSPATH.
  47
  48
  49 SYNOPSIS
  50 --------
  51
  52 Using the test-harnesses:
  53
  54         $ CQLParser 'title=foo and author=(bar or baz)'
  55         $ CQLLexer 'title=foo and author=(bar or baz)'
  56                 (not very interesting unless you're debugging)
  57         $ CQLGenerator etc/generate.properties seed 18
  58
  59 Using the library in your own applications:
  60
  61         import org.z3950.zing.cql.*
  62
  63         // Building a parse-tree by hand
  64         CQLNode n1 = new CQLTermNode("dc.author", new CQLRelation("="),
  65                                      "kernighan");
  66         CQLNode n2 = new CQLTermNode("dc.title", new CQLRelation("all"),
  67                                      "elements style");
  68         CQLNode root = new CQLAndNode(n1, n2);
  69         System.out.println(root.toXCQL(0));
  70
  71         // Parsing a CQL query
  72         CQLParser parser = new CQLParser();
  73         CQLNode root = parser.parse("title=dinosaur");
  74         System.out.print(root.toXCQL(0));
  75         System.out.println(root.toCQL());
  76         System.out.println(root.toPQF(qualSet));
  77         // ... where `qualSet' specifies CQL-qualfier => Z-attr mapping
  78
  79
  80 DESCRIPTION
  81 -----------
  82
  83 See the automatically generated class documentation in the "doc"
  84 subdirectory.  (It's not all there yet, but it's coming.)
  85
  86
  87 AUTHOR
  88 ------
  89
  90 All code and documentation by Mike Taylor <mike@z3950.org>
  91         http://www.miketaylor.org.uk
  92 Please email me with bug-reports, wishlist items, patches, deployment
  93 stories and, of course, large cash donations.
  94
  95
  96 LICENCE
  97 -------
  98
  99 This software is Open Source, but I've not yet decided exactly what
 100 licence to use.  Be good.  Assume I'm going with the GPL (most
 101 restrictive) until I say otherwise.  For what it's worth, I think the
 102 most likely licence is the LGPL (GNU's Lesser General Public Licence)
 103 which lets you deploy cql-java as a part of a non-free larger work.
 104
 105
 106 SEE ALSO
 107 --------
 108
 109 Adam Dickmeiss's CQL compiler, written in C.
 110 Rob Sanderson's CQL compiler, written in Python.
 111 All the other free CQL compilers everyone's going to write  :-)
 112
 113
 114 THINGS TO DO
 115 ------------
 116
 117 * ### Fix bug where "9x" is parsed as two tokens, a TT_NUMBER followed
 118   by a TT_WORD.  The problem here is that I don't think it's actually
 119   possible to fix this without throwing out StreakTokenizer and
 120   rolling our own, which we absolutely _don't_ want to do.
 121
 122 * Some niceties for the cql-decompiling back-end:
 123         * don't emit redundant parentheses.
 124         * don't put spaces around relations that don't need them.
 125
 126 * Write the PQN-generating back-end.  This will need to be driven from
 127   a configuation file specifying how to represent the qualifiers,
 128   relations, relation modifiers and wildcard characters as z39.50
 129   attributes.  I think Ray has such a thing, though perhaps not yet in
 130   a form sufficiently rigorous to be computer-readable.
 131
 132 * Consider the utility of yet another back-end that translates a
 133   CQLNode tree into a Type-1 query tree using the JZKit data
 134   structures.  That would be nice so that CQL could become a JZKit
 135   query-type; but you could achieve the same effect by generating PQN,
 136   and running that through JZKit's existing PQN-to-Type-1 compiler.
 137
 138 * Many refinements to the random query generator:
 139         * Generate relation modifiers
 140         * Proximity support
 141         * Don't always generate qualifier/relation for terms
 142         * Better selection of qualifier (configurable?)
 143         * Better selection of terms (from a dictionary file?)
 144         * Introduce wildcard characters into generated terms
 145         * Generate multi-word terms
 146
 147 * Write fuller "javadoc" comments.