1 $Id: README,v 1.13 2002-11-05 17:20:30 mike Exp $
3 cql-java - a free CQL compiler, and other CQL tools, for Java
9 cql-java is a Free Software project that provides:
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
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.
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
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)
31 But if you didn't know that, why are you even reading this? :-)
34 What's what in this distribution?
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.
45 "Installation" of this package would consist of putting the bin
46 directory on your PATH and the lib directory on your CLASSPATH.
52 Using the test-harnesses:
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
59 Using the library in your own applications:
61 import org.z3950.zing.cql.*
63 // Building a parse-tree by hand
64 CQLNode n1 = new CQLTermNode("dc.author", new CQLRelation("="),
66 CQLNode n2 = new CQLTermNode("dc.title", new CQLRelation("all"),
68 CQLNode root = new CQLAndNode(n1, n2);
69 System.out.println(root.toXCQL(0));
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
83 See the automatically generated class documentation in the "doc"
84 subdirectory. (It's not all there yet, but it's coming.)
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.
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.
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 :-)
117 * ### Make necessary parts of CQLNode etc. public.
119 * ### Fix bug where "9x" is parsed as two tokens, a TT_NUMBER followed
120 by a TT_WORD. The problem here is that I don't think it's actually
121 possible to fix this without throwing out StreakTokenizer and
122 rolling our own, which we absolutely _don't_ want to do.
124 * Allow keywords to be used unquoted as search terms.
126 * Some niceties for the cql-decompiling back-end:
127 * don't emit redundant parentheses.
128 * don't put spaces around relations that don't need them.
130 * Write the PQN-generating back-end. This will need to be driven from
131 a configuation file specifying how to represent the qualifiers,
132 relations, relation modifiers and wildcard characters as z39.50
133 attributes. I think Ray has such a thing, though perhaps not yet in
134 a form sufficiently rigorous to be computer-readable.
136 * Consider the utility of yet another back-end that translates a
137 CQLNode tree into a Type-1 query tree using the JZKit data
138 structures. That would be nice so that CQL could become a JZKit
139 query-type; but you could achieve the same effect by generating PQN,
140 and running that through JZKit's existing PQN-to-Type-1 compiler.
142 * Many refinements to the random query generator:
143 * Generate relation modifiers
145 * Don't always generate qualifier/relation for terms
146 * Better selection of qualifier (configurable?)
147 * Better selection of terms (from a dictionary file?)
148 * Introduce wildcard characters into generated terms
149 * Generate multi-word terms
151 * Write fuller "javadoc" comments.