1 $Id: README,v 1.15 2002-11-06 20:13:45 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)
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(config));
77 // ... where `config' specifies CQL-qualfier => Z-attr mapping
83 See the automatically generated class documentation in the "doc"
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 * ### 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.
122 * Write javadoc comments for CQLRelation and ModifierSet.
124 * Write "overview" file for the javadoc documentation.
126 * Allow keywords to be used unquoted as search terms.
128 * Some niceties for the cql-decompiling back-end:
129 * don't emit redundant parentheses.
130 * don't put spaces around relations that don't need them.
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.
138 * Many refinements to the random query generator:
139 * Generate relation modifiers
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