README

   1 $Id: README,v 1.10 2002-11-03 16:49:37 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         src     Source-code for the cql-java library
  38         lib     The compiled library file, "cql-java.jar"
  39         bin     Simple shell-scripts to invoke the test-harnesses
  40         docs    Documentation automatically generated by "javadoc"
  41         test    Various testing and sanity-checking frameworks
  42         etc     Other files: CQL Grammar, generator properties, etc.
  43
  44 "Installation" of this package would consist of putting the bin
  45 directory on your PATH and the lib directory on your CLASSPATH.
  46
  47
  48 SYNOPSIS
  49 --------
  50
  51 Using the test-harnesses:
  52
  53         $ CQLParser 'title=foo and author=(bar or baz)'
  54         $ CQLLexer 'title=foo and author=(bar or baz)'
  55                 (not very interesting unless you're debugging)
  56         $ CQLGenerator etc/generate.properties seed 18
  57
  58 Using the library in your own applications:
  59
  60         import org.z3950.zing.cql.*
  61
  62         // Building a parse-tree by hand
  63         CQLNode n1 = new CQLTermNode("dc.author", new CQLRelation("="),
  64                                      "kernighan");
  65         CQLNode n2 = new CQLTermNode("dc.title", new CQLRelation("all"),
  66                                      "elements style");
  67         CQLNode root = new CQLAndNode(n1, n2);
  68         System.out.println(root.toXCQL(0));
  69
  70         // Parsing a CQL query
  71         CQLParser parser = new CQLParser();
  72         CQLNode root = parser.parse("title=dinosaur");
  73         System.out.print(root.toXCQL(0));
  74         System.out.println(root.toCQL());
  75         System.out.println(root.toPQF(qualSet));
  76         // ... where `qualSet' specifies CQL-qualfier => Z-attr mapping
  77
  78
  79 DESCRIPTION
  80 -----------
  81
  82 See the automatically generated class documentation in the "doc"
  83 subdirectory.  (It's not all there yet, but it's coming.)
  84
  85
  86 AUTHOR
  87 ------
  88
  89 All code and documentation by Mike Taylor <mike@z3950.org>
  90         http://www.miketaylor.org.uk
  91 Please email me with bug-reports, wishlist items, patches, deployment
  92 stories and, of course, large cash donations.
  93
  94
  95 LICENCE
  96 -------
  97
  98 This software is Open Source, but I've not yet decided exactly what
  99 licence to use.  Be good.  Assume I'm going with the GPL (most
 100 restrictive) until I say otherwise.  For what it's worth, I think the
 101 most likely licence is the LGPL (GNU's Lesser General Public Licence)
 102 which lets you deploy cql-java as a part of a non-free larger work.
 103
 104
 105 SEE ALSO
 106 --------
 107
 108 Adam Dickmeiss's CQL compiler, written in C.
 109 Rob Sanderson's CQL compiler, written in Python.
 110 All the other free CQL compilers everyone's going to write  :-)
 111
 112
 113 THINGS TO DO
 114 ------------
 115
 116 * ### Fix bug where "9x" is parsed as two tokens, a TT_NUMBER followed
 117   by a TT_WORD.  The problem here is that I don't think it's actually
 118   possible to fix this without throwing out StreakTokenizer and
 119   rolling our own, which we absolutely _don't_ want to do.
 120
 121 * Some niceties for the cql-decompiling back-end:
 122         * don't emit redundant parentheses.
 123         * don't put spaces around relations that don't need them.
 124
 125 * Write the PQN-generating back-end.  This will need to be driven from
 126   a configuation file specifying how to represent the qualifiers,
 127   relations, relation modifiers and wildcard characters as z39.50
 128   attributes.  I think Ray has such a thing, though perhaps not yet in
 129   a form sufficiently rigorous to be computer-readable.
 130
 131 * Consider the utility of yet another back-end that translates a
 132   CQLNode tree into a Type-1 query tree using the JZKit data
 133   structures.  That would be nice so that CQL could become a JZKit
 134   query-type; but you could achieve the same effect by generating PQN,
 135   and running that through JZKit's existing PQN-to-Type-1 compiler.
 136
 137 * Many refinements to the random query generator:
 138         * Generate relation modifiers
 139         * Proximity support
 140         * Don't always generate qualifier/relation for terms
 141         * Better selection of qualifier (configurable?)
 142         * Better selection of terms (from a dictionary file?)
 143         * Introduce wildcard characters into generated terms
 144         * Generate multi-word terms
 145
 146 * Write fuller "javadoc" comments.